Extension points and handlers

Introduction

Manhattan Active® Platform provides a flexible extensible model for customizing the business workflows via Extension Points. Extension points allow the customer or the Manhattan Professional Services organization to extend the base functionality with little to no code, while supports variety of internal and external integration options for invoking, consuming, and orchestrating custom workflows that meet your needs.

Two key constructs that are embedded in the system design of integrating and executing custom workflows as part of the base flows of Manhattan Active® Solutions:

Extension Points: Manhattan Active® application components have built-in extension points for functional customizations. Callouts to custom services can be configured at these extension points such that the custom services are invoked as part of a base workflow. The custom extension points are available throughout the base application functionality for a powerful extension model. Manhattan also evaluates the need for new extension points frequently and continues to insert them as part of application updates every few weeks. Extension points are designed to handle synchronous and asynchronous call-outs from the base flow, respectively

REST API: Every Manhattan Active® Solution microservices publishes a REST API that handles virtually every business function and “CRUD” operation. Collectively, Manhattan Active® Platform exposes thousands of REST API endpoints which can be used as an instrument for integrating 3rd party systems with Manhattan Active® Platform. The REST API supports the same degree of access control that the Manhattan Active® Platform user interface provides. The REST API comes with Swagger documentation that outline the usage and references.

Extension Point

An Extension Point is a pre-defined hook placed in the base application code at specific places where there’s a potential for customization. Extension Points can be configured to invoke custom services, which are instrumented in - and are invoked as part of - the base code flow at runtime.

• Customizations can be configured at these points as necessary.
• Extension points allows for a powerful execution model to support provides a powerful extension model to support customizations while keeping them external to the base code.
• Requirements for the new extension points are considered and evaluated as part of the development process of the base application, and upon approval, they are delivered as part of the routine code delivery. Once added, extension points are never modified or deleted to preserve the compatibility with the potential implementations of these extension points.
• The configuration that implements the extension point resides in entity called Extension Handler. An extension point can have zero or more extension handlers.

An extension point can be of two types:

Synchronous call-out (User Exit)

• Produces a synchronous call-out at the given extension point. The call-out waits for a response before continuing the base flow.
• While a synchronous call-out (user exit) can be configured with multiple extension handlers, only the first matching handler is executed (see more detailed explanation of how the “matching” is performed in the section below)
• Synchronous call-outs (user exits) are typically added at points in the base code where there is an expectation that a response containing a new or modified payload will be received in response to the call-out.

Asynchronous call-out (Event)

• Produces an asynchronous call-out at the given extension point. Unlike the synchronous call-outs, the call-out does not wait for a response before continuing the base flow.
• Unlike synchronous call-outs (user exits), if multiple extension handlers are configured for an event, all matching extension handlers are executed (see more detailed explanation of how the “matching” is performed in the section below)
• Additionally, base code may also send messages to queue(s) through ExtPointToMessageType, which are processed after the configured extension handlers are executed. This allows the base application code to execute logic after all potential customizations are executed. This is base functionality and not expected to be customized.

The type of extension point to be introduced in the base code is determined by Manhattan engineering based on the functional and technical requirements, behavior expectations, and throughput calculations.

Extension Handler

Implementation of extension point customization is configured using an entity called Extension Handler. The execution of extension handler is performed as part of the base flow when the base code encounters the extension point. When an extension point is evaluated by the base code, it performs two steps:

1. Determines the extension handler(s) to be invoked as configured for that extension point
2. Serializes the business objects and the contextual metadata from the current transaction as a JSON object and passes it to the extension handlers. See the extension point documentation to learn more about what business objects and contextual metadata is passed to the extension handlers.

The extension handler, when executed, utilizes the JSON payload sent from the extension point, and performs the custom flows. When the extension handler completes the custom flow, it responds back with a “return” payload - the returned payload may contain modifications based on the customization requirements. The returned payload is only relevant for the synchronous call-outs (http); for asynchronous call-outs, the returned payload is not relevant.

Extension handlers can be added and managed via a REST API for the ExtensionHandler entity. However, it is recommended that the Configurator UI is used to configure extension handlers for a more intuitive graphical experience, detailed validations, and to avoid human errors. See below for an example screen-shot of the Configurator UI.

Extension Handler Configuration

As described below, an extension handler can be configured for a variety of customization operations:

ENTRY CONDITION

• Every extension handler can be configured for an Entry Condition to determine if it is the right handler to execute that call-out. Since multiple extension handlers can be configured at a given extension point, the entry condition serves as a selection criterion to choose the appropriate extension handler for the given business flow.
• Entry conditions can be defined using JSONPath or MVEL expression. Environment variables available in the runtime can also be used in the MVEL expressions using the {:env_variable_name} format.

PRIORITY

• Priority is an integer number that can be assigned to an extension handler to determine the order in which the extension handlers are sorted for execution of the given extension point. The priority numbers are in ascending order of priority (higher the number, higher the priority).
• Extension handlers with the most stringent entry condition should be given the least priority (the smallest number) to ensure these handlers are executed at the very end.

SERVICE DEFINITION

• Service definition are configured for extension points to invoke internal or external APIs as part of the execution of an extension handler. An extension handler can be configured to use one or more service definitions.
• Service definition are configured via the ServiceDefinition entity and are configured and managed separately from the extension handler configuration. The extension handler configuration simply “points” to a service definition created previously.
• A service definition can be configured to be of several types:
  • URL: calls an HTTP URL. For example, "Url" : "example.com/some/api?k=v".
  • RequestMappingUrl: partial URL of the same component in which the extension handler is configured. For example, "RequestMappingUrl": "/api/ServiceDefinition/inBoundMessageType/search" provides an output similar to an HTTP call, but invokes the underlying Spring bean without making an actual HTTP call.
  • CompositeService: points to an extension handler and executes it. Do note, that entry conditions of an extension handlers are ignored when it is invoked as a composite service configuration.

Example of a URL Service configuration in the Configurator UI:

SERVICE CHAINING

An extension handler can invoke a chain of service definitions as described above. The chaining is created by feeding the output of a service execution call as the input to the next service invocation.

CONDITIONAL SERVICE CHAINING

Conditional service chains are service chains that include conditions between execution of two services. The condition is defined using the same format as the Entry Condition described above.

Example of conditionally chained service configuration in the Configurator UI:

INPUT TRANSFORMATION

While chaining services, the input to the next service can be transformed using Velocity or Freemarker templates. This is useful for services whose payload structures are not directly compatible. Functionality supports both inline and pre-saved templates.

Example of input transformation with Freemarker template:

OUTPUT AUGMENTATION

When services are chained, it replaces the whole full payload with the output of a service. In addition, you can also preserve the input payload and augment the new output to it by using the Augment key. An augment key can be any string key in the input JSON payload where the new output payload will be added.

OUTPUT TEMPLATES

A service may produce larger payload than necessary, which could lead to performance concerns. Such payloads can be reduced using response templates. Functionality supports both inline and pre-saved response templates.

OUTPUT QUEUES

Outputs of the services can be posted to a queue at individual services level for further asynchronous processing. Output of the entire extension handler can also be posted to a queue.

SAMPLING

Sampling provides clean visibility into the intermediate results of the services and payloads sent to the queues. As an extension handler can comprise multiple service calls, this feature can be very useful for visualizing payloads and debug at different levels of the chain.

Example of the sampling output:

Learn More

• Concept Guides
• Quick Starts

Author

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