Connectors

Connectors are used to handle interactions between external systems and a process.

Connectors execute their logic outside of the application runtime bundle with values being passed between a connector and a process as inputs and outputs. Service tasks are used in a process definition to implement connectors.

Examples of what connectors can be used for include:

• Sending an email using values from a process to populate the fields
• Interacting with an installation of Slack to post messages
• Calling a custom REST API and passing the response back to a process

A set of out of the box connectors are provided with Activiti Enterprise or custom connectors can be created.

Modeling connectors

Connectors are created with two separate elements:

• A connector definition that can contain actions and events.
• A connector image that is deployed with an application and contains the logic of the connector.

Connector definitions

Connector definitions are the templates for modeling a connector. The definitions are where the input and output parameters are set for the connector to send and receive variables from an external system.

Connector definitions are stored as JSON files in the format <connector-name>.json and can be modeled in the GUI or the JSON Editor.

The basic properties for connector definitions are:

Connector definitions can contain actions, events and configuration parameters.

Actions

Actions are the operations a connector can take. Connector definitions can have multiple actions, however only one action can be executed by each service task. Connector actions are attached to service tasks using the implementation attribute with a value in the format <connector-name>.<action-name>, for example:

<bpmn2:serviceTask id="ServiceTask_3xcd7zp" implementation="slackConnector.SEND_MESSAGE" />

The basic properties for actions are:

Each action has a set of input parameters and output parameters. Input parameters are the values sent from a process to the connector and output parameters are the ones returned to the process after the connector has executed its logic. Values are defined in a service task using process variables.

The properties for input and output parameters are:

Actions are stored in the actions section of the connector JSON, for example in an excerpt of the Slack connector SEND_MESSAGE event:

    "actions": {
        "88296a50-f6cf-496e-b433-5d794788fc8f": {
            "id": "88296a50-f6cf-496e-b433-5d794788fc8f",
            "name": "SEND_MESSAGE",
            "description": "Sends a standalone message to a Slack conversation. Conversations can be public or private channels, or direct messages.",
            "inputs": [
                {
                    "id": "f7435a5c-20bd-46e4-9d26-901a9dabb87c",
                    "name": "userId",
                    "description": "Internal Slack user id. If present, the message will be sent as a direct message.",
                    "type": "string"
                },
...
            ],
            "outputs": [
                {
                    "id": "c9daca61-6ecd-4dd2-b8b0-f1f99589cd52",
                    "name": "slackError",
                    "description": "If present, it describes the error occurred trying to send the message.",
                    "type": "string"
                },
...
            ]
        },

Events

Events are used by triggers to configure a connector event that can be listened for and published by a trigger.

The basic properties for events are:

Events contain input and output parameters that define the properties used by a trigger. Input parameters are used to set the criteria for event publishing and any notification of matches. Output parameters are variables that can be used in the payload of trigger actions.

The properties for input and output parameters are:

Events are stored in the events section of the connector JSON, for example in an excerpt of the email connector EMAIL_RECEIVED event:

"events": {
        "62bfa43e-a495-4786-9495-1e24eedf1a1f": {
            "id": "62bfa43e-a495-4786-9495-1e24eedf1a1f",
            "name": "EMAIL_RECEIVED",
            "description": "Event that is dispatched when an email is received",
            "inputs": [
                {
                    "id": "3dbe2c22-dfc2-41c6-a576-7797f9fbeb62",
                    "name": "pattern",
                    "description": "Regular expression that any incoming message shall match in order to be published as events. Regular expressions can contain matching groups delimited by '(' and ')'. Matching groups can be used in variables and the echo message.",
                    "type": "string"
                },
...
            ],
            "outputs": [
                {
                    "id": "fa6b0f2a-ca79-476b-ba4e-f0f082eff47c",
                    "name": "matchGroups",
                    "description": "Matching groups between pattern and message. They can be used in variables and the echo messages.",
                    "type": "json"
                },
...
            ]
        }
    },

Configuration parameters

Configuration parameters are the environment variables specific to each connector instance that are used at deployment time. They set values such as the SMTP host and port the email connector will use.

Note Additional configuration parameters can be specified at deployment time and existing parameters set during the modeling experience can be overridden.

The basic properties for configuration parameters are:

Configuration parameters are stored in the config section of the connector JSON, for example in an excerpt of the Slack connector:

    "config": [
        {
            "name": "SLACK_XOXB",
            "description": "Slack bot user token",
            "value": "",
            "required": true
            
        },
        {
            "name": "SLACK_XOXP",
            "description": "Slack admin user token",
            "value": "",
            "required": true
        }
    ],

Connector images

Connectors are deployed as separate Docker images with an application. The communication between the connector and the application runtime bundle uses the message broker, by default Rabbit MQ.

The images for the out of the box connectors supplied with Activiti Enterprise are pulled from Quay.io. Custom connectors can be hosted on another Docker registry as long as a secret is created in the Activiti Enterprise infrastructure namespace. Alternatively custom images can be hosted on a publicly hosted container repository such as Docker Hub.