Asynchronous (Messaging) Outbound Resources

Last modified 22 Apr 2021 17:31 +02:00
EXPERIMENTAL
This feature is experimental. It means that it is not intended for production use. The feature is not finished. It is not stable. The implementation may contain bugs, the configuration may change at any moment without any warning and it may not work at all. Use at your own risk. This feature is not covered by midPoint support. In case that you are interested in supporting development of this feature, please consider purchasing midPoint Platform subscription.
Since 4.3
This functionality is available since version 4.3.

There are situations where a target resource is not accessible in a direct, synchronous, CRUD-like way. Such a resource can receive commands to add, modify, or delete accounts and other objects, but processes them asynchronously - in an unspecified time.

Support for such resource was planned for a longer time. Starting with 4.3, it becomes a reality.

Overview

Asynchronous provisioning

The idea of asynchronous provisioning is very similar to the one of manual provisioning. Generally, when midPoint has something to do on a resource (like creating, updating, or deleting an account), the provisioning module asks a connector to do that. For synchronous resources, the connector ensures the execution of the operation, and informs provisioning module about the result. But not in the case of asynchronous provisioning connector. Here the connector sends a request (e.g. a JMS message containing JSON-encoded data about the requested operation) to specified target (e.g. JMS queue), where it will wait until the real target system retrieves and processes it. And because midPoint has no access to the target system to know about the current state of the account, the provisioning keeps all the account attributes in the repository using a mechanism called attribute caching.

Configuration overview

When configuring an asynchronous resource, two basic questions have to be answered:

  1. Where we should send requests to?

  2. How should these requests look like?

The answer to the first question is usually an address (URL, JNDI name, …​) of a messaging broker, plus specification of an address (e.g. JMS queue) within it.

The answer to the second one is a specification of message format, or a custom transformation script.

Let us illustrate it. In the above picture, orange components are standard midPoint parts: provisioning module, asynchronous connector, and repository. The blue box is typically a part of standard messaging infrastructure, like ActiveMQ or RabbitMQ broker. And the green box is a custom application. In a similar way, orange "documents" are ones that are defined by midPoint: operations requested, and shadows in the repository. Green documents are custom ones: messages carrying the requests from midPoint to the application.

The answer to the first question, i.e. specification of the target "address", is the blue part of the resource definition. It points to the blue-colored provisioning target.

The answer to the second question, i.e. specification of message transformation, is the green part of the resource definition. It describes how orange documents (operations requested) are transformed into green ones (messages carrying requests).

An example

<connectorConfiguration>
    <conf:targets>
        <jms>
            <connectionFactory>mainBrokerConnectionFactory</connectionFactory>
            <destination>FileServerRequestsQueue</destination>
        </jms>
    </conf:targets>
    <conf:predefinedTransformation>simplifiedJson</conf:predefinedTransformation>
</connectorConfiguration>

This configuration snippet is a part of an asynchronous resource definition. It says that:

  1. There is a single JMS target we will send messages to. It resides on a broker reachable via mainBrokerConnectionFactory (a JNDI name to be resolved), and the specific queue is obtained by resolving FileSystemRequestsQueue name.

  2. When transforming operations into requests, the simplifiedJson predefined transformation will be used.

Configuration details

See Asynchronous Resource Configuration (Outbound) page for configuration details.

Current state of the implementation

The design of this feature is highly modular. In theory, the communication with the asynchronous target can use any transport: various kinds of message queuing technologies, REST, SOAP web services, and so on. But the current implementation was created and tested with a particular target in mind:

  • Apache ActiveMQ Artemis 2.x;

  • using JMS 2.0 to connect to it.

Other JMS 2.0 providers should be pluggable. JMS 1.1 might work as well but there can be some classloading issues. It looks like some engineering effort will be needed to be able to use them with midPoint.