Glossary of key terminology

Become familiar with the key terminology utilized throughout this documentation.

Manhattan Active® Platform, or simply the “Platform” is the underlying runtime that houses the Manhattan Active® applications’ components, and manages them. For an overview of the Platform, see Manhattan Active® Platform Overview. The Platform is informally called the “Cloud Platform”, “CP” or simply, “Active”.

Manhattan Active® Omni

Part of the Platform, Manhattan Active® Omni provides the business functions for Omni-channel commerce and retail. MAO, as it is known in short, includes several business applications including the Order Management, Customer Engagement, Store Inventory & Fulfillment and Point of Sale. For an overview of MAO, see MA Active® Omni Overview

Manhattan Active® Supply Chain

Part of the Platform, Manhattan Active® Supply Chain provides the business functions for Warehouse and Distribution, and Transportation ecosystem. MASC, as it is known in short, includes several business applications including the Warehouse Management, Labor Management, Yard Management, and Transportation Management. For an overview of MASC, see MA Active® Supply Chain Overview

Environment

An Environment is an isolated “slice” the Manhattan Active® applications as used by a customer, or a tenant. An environment is a logical “container” of the business workflows, custom extensions and business configuration of the application for the given customer. And hence, it is also sometimes referred to as the customer’s environment. Do note, that while an environment may have a one-to-one relationship with underlying compute runtime in certain cases, an environment in many cases may also share compute resources with other environments stood up for that customer or other customers. However, what the term environment does ensure is the isolation of data and business workflows of a customer from other customers - at rest and in transit. Manhattan Active® Platform deployments also ensure that one environment is not impacted adversely – functionally or in performance – because of a neighboring environment if the compute resources are shared among these environments.

Stack

A Stack is a network-isolated collection of compute and physical or virtual resources of the underlying cloud infrastructure. A stack hosts one or more environments depending on the tenancy definition of the stack. Every stack consists of a Kubernetes cluster, a database, a set of essential services, the application microservices, application configuration, and zero or more custom extension components. In other words, a stack is the physical runtime that hosts one or more logical environments. A stack is accessed and managed by the Manhattan Active® Cloud Operations team.

Microservice

A Microservice is a self-contained, immutable, and portable process that can be built, delivered, deployed, run, and managed in isolation from other processes. In Manhattan Active® Platform, most microservices are written in Java, though some microservices use different implementation technologies and programming languages. All microservices in Manhattan Active® Platform are built as Linux containers, orchestrated via Kubernetes, and are accessible via a REST API.

Component

A “Component” is a term used interchangeably with a “microservice”.

Essential Service

Essential Services are specialized microservices, including 3rd party software such as Rabbit MQ or Elasticsearch, that provide runtime support and system services (such as caching, indexing, messaging, time series storage, configuration management etc.) to the application microservices. Without the essential services, the application microservices may not function or perform properly. And hence the term “essential”.

Application Configuration

Application configuration consists of a set of properties files that are maintained in a Key-Value store (Consul), and are injected into the microservice process’s runtime using native configuration instrumentation techniques (such as Spring Cloud Config). Application configuration is managed and delivered just like the way the application code binaries are delivered to the target runtime. Changes to the application configuration are tracked via the built-in change detection & audit mechanisms.

Auth Server

Auth Server is a microservice deployed as part of Manhattan Active® Platform. It performs the role of intercepting the inbound authentication calls, and processes them by redirecting them to the target identity or authentication system (it could be an external system such as a 3rd party identity provider, or could be Manhattan Active® Platform’s native authentication). Upon successful authentication, Auth Server constructs the necessary service context and OAuth access token, and redirects the invocation to the target application (such as Manhattan Active® Omni, Supply Chain or Inventory). All user interface and REST API invocations must authenticate with Auth Server first before they can reach to the application. Unauthenticated requests are returned with HTTP 401 UNAUTHORIZED status code.

Zuul Server

Zuul Server is a microservice deployed as part of Manhattan Active® Platform. It performs the role of a gateway and a router: all user interface and REST API invocations first reach Zuul Server immediately after authentication, and dispatched to the target application microservice based on statically defined routing configuration. Additionally, Zuul Server also performs the resource grants for the requested resource by the user (or system) submitting the request. Zuul Server will only dispatch the invocation downstream if the requester has the grants to access the requested resource. Unauthorized requests are returned with HTTP 403 FORBIDDEN status code.

Organization

Organization is a microservice deployed as part of Manhattan Active® Platform. It performs the role of the bookkeeping of organization hierarchy, application users, user roles and resource grants, locations (such as warehouses or stores), business units of organizations, and authentication information (usernames, passwords, and PINs) applicable to Manhattan Active® Platform’s native authentication mechanism. Organization provides a user interfaces and API to retrieve and manage this configuration, and is used by many other downstream microservices to utilize organization hierarchy and other configuration in business workflows.

User

A User is someone who uses a Manhattan Active® application. Examples of users include employees in a store or a warehouse, or customer service representatives in a call center, or a corporate executive retrieving the operational report. The users are typically the employees, temporary staff, or contractors of the customer of the Manhattan Active® application.

Robot

Robots are specialized user accounts designated to invoke the Manhattan Active® Platform APIs. Robots can be assigned roles and grants just like the “human” users, except that the Robot users can only access the REST API, and not the user interface of the applications.

Resource

Every “function” (such as an API, user interface, or any other URLs that a user may access) is defined as a resource. Every resource is controlled by one or more permission. A user can only access a resource if they have the permission for that resource. A user can only perform a certain action to a resource based on the permissions given to that resource.

Permission

A Permission is a predefined entity for governing access control. A permission defines the type of access (“read”, “write”, “admin”) a specific resource such as a user interface, or an API of the Manhattan Active® Platform. Permissions are static values that must be added to a role, and granted to a user.

Role

A Role is a collection of permissions such that the permissions can be grouped based on business requirements. Roles may be defined as “corporate administrator”, “user administrator”, “store user”, “CSR”, “cashier” etc. When a role is assigned to a user, the user inherits the permissions defined in the role. Roles can also be hierarchical. Roles are typically defined statically as part of business configuration of the application, but can also be modified as part of the routine operation of the applications. Roles can be managed via the Organization user interface, or API.

Grant

A Grant is the assignment of a role to a user. A grant states what resources a user has, and what a user can do with that resource. Grants are typically added, modified or deleted dynamically as users are onboarded, change their responsibilities or when they are removed from the application. Grants can be managed via the Organization user interface, or API.

Stereotype

In a typical deployment, a microservice could have multiple instances running at any given time. We assign specific responsibilities to every instance by setting a stereotype to that instance. During the runtime, the instance can detect the stereotype value, and behave in a certain way, throughout its life cycle. Stereotype values are predefined such as REST that designate certain instances to process the REST API workload including all HTTP invocations from the user interfaces or external systems, QUEUE_PROCESSOR to process asynchronous messages from queuing systems, and ALL to process both REST/HTTP and asynchronous workload.

Extensibility

Extensibility is Manhattan Active® Platform’s ability to extend or modify the default behavior of an application function. Extensibility is a mechanism using which customers can develop additional business functionality to meet their functional requirements, or can adjust them to work within the existing IT landscape. Such changes to out-of-the-box (“base”) functionality is called a Custom Extension.

Extension Point

Manhattan Active® Platform exposes “hooks” in certain places in the base functional flows where a custom extension is plugged in. These hooks are well documented similar to the APIs, and continue to grow in numbers as Manhattan identifies new requirements. These hooks are also known as the extension points.

Extension Handler

In order to use an extension point, it needs to be attached to some handling configuration such as invoking one or more service, or intercepting the incoming payload and modifying it when that extension point is invoked. The handling configuration is defined as an Extension Handler. The handler can utilize the base API, 3rd party APIs, or other custom extensions. If an extension handler is defined for an extension point, the base code will invoke the configured custom flow at that point. Subsequent execution of base code will make use of the modified payload returned from the extension handler’s response. Extension points with extension handlers could cause performance problems. Performance tests should be performed when implementing extension handlers that may cause execution latency.

Synchronous Extension Handler

Synchronous extensions handlers are a type of extension handler that execute the extension flows synchronously. If a synchronous call-out (user exit) is defined for an extension point, the base flow waits for the response from the handler before proceeding to the next step. If the extension handler modified the payload in transit, the subsequent workflow execution will use the modified payload returned from the extension handler for further execution.

Asynchronous Extension Handler

Asynchronous extension handlers are a type of extension handler that execute the extension flows asynchronously. Events are typically used for “fire and forget” workflows (such as notifications of certain milestones), though they can be modeled to orchestrate a workflow that can handle asynchronous invocations. For example, when a new order is placed, the system can send a message to a queue to notify the recipient about the order creation event. The receiving system (the target that subscribes to the asynchronous message) can in turn invoke additional steps in the workflow with or without modifying the payload.

Custom Extension Components

Custom extension components are microservices developed and deployed in the SaaS environment for meeting a customer’s business requirement. A custom extension component runs custom (Java) code as part of the Manhattan Active® Platform’s cloud runtime, and integrates with the base microservices via REST API or messaging. Do note, that only the Manhattan’s professional services team is authorized to develop and deploy the custom extension components as they require internal knowledge of how the system works and depend on restricted resources that are only accessible to Manhattan employees.

AWPF

AWPF stands for Asynchronous Workload Processing Framework. AWPF is Manhattan’s proprietary framework for abstracting the management of asynchronous communication for individual microservices.

Message

A Message is an asynchronous payload either received by, or sent by, a microservice, and is sent or received using a queuing mechanism such as Rabbit MQ. A message has a producer, and usually, zero or more consumers. A message provides an ability for microservices to communicate to one another asynchronously in one of one-to-one, one-to-many or broadcast fashion. A message has two parts: The metadata about the message, or the header, and the actual message content, or the body. The header contains the envelope information (sender and receiver information, metadata about the message and timestamps). The body contains the business contents of the message.

Message Types

Message Types are configuration entities meant to provide an easy-to-use abstraction for queue naming and other connection details. From a microservice’s perspective, it can either produce some messages or consume some messages. Messages produced by a microservice, are called outbound messages, and messages consumed are called inbound messages. These message types are defined technically as OutBoundMessageType and InBoundMessageType, and are available in the runtime of every microservice.

Message Brokers

Message Brokers are the message queueing services or systems that a microservice can integrate with. Manhattan Active® Platform supports Rabbit MQ and Kafka for internal messaging (messaging between microservices), and Google Pub/Sub or Amazon SQS for external messaging (messaging to- and from- the microservices and external systems).

Transactional Messaging

If there is a need to send a message only when the parent transaction succeeds, we can use the Transactional Messaging. The parent transaction can perform different database updates along with sending the message. There are primarily two resources involved in such transactions: the database and messaging. As the transaction does not span both resources (not JTA), Manhattan Active® Platform has its own way of handling such requirement by first writing the message to a database and then sending it to the messaging service.

Non-transactional Messaging

Unlike the transaction messaging, if a message can be sent irrespective of the presence or completion of a parent transaction, Manhattan Active® Platform also supports Non-transactional Messaging. It does not have the overhead of tracking transactionality of a message.

Message Persistence, or TranLog

Manhattan Active® Platform has a way of storing messages in Elasticsearch for future reference and reconciliation. It is recommended to enable message persistence for only external messages as there could be need for reconciliation later. For message types that do not require reconciliation later, or for other replayable messages, message persistence should be disabled as it could lead to over-utilization of resources and performance issues.

Learn More

Author

  • Kartik Pandya: Vice President, Manhattan Active® Platform, R&D.
  • Subhajit Maiti: Director, Manhattan Active® Platform, R&D.
  • Shanthosh Govindaraj: Director, Manhattan Active® Platform, R&D.