Skip to main content

Integrating NATS Messaging with Orkes Conductor

This developer guide includes the steps to integrate NATS Messaging with Orkes Conductor. This integration lets you connect your NATS server to Conductor to publish and receive messages from queues.

Get Configuration Credentials from NATS Messaging

Pre-Requisites

You must set up NATS messaging before integrating with Orkes Conductor. Refer to the NATS Messaging official documentation for more details.

Get the following parameters from the NATS server:

  • Server name
  • Username & password if you prefer to authenticate with credentials.
  • Stream name & consumer name if the connection mechanism is using consumer.

Integrating with NATS Messaging as a Message Broker

Once you have the required configuration parameters from NATS Messaging, let’s integrate with Orkes Conductor.

  1. Navigate to Integrations from the left menu on the Orkes Conductor cluster.
  2. Click + New integration from the top-right corner.
  3. Under the Message Broker section, choose NATS Messaging.
  4. Click +Add and provide the following parameters:

Integration configuration for NATS Messaging

ParemetersDescription
Integration NameA name to identify your integration.
ServerThe NATS server name to be integrated with Orkes Conductor.
Connection TypeChoose the required connection type for the integration. Supported values:
  • Default - Standard NATS connection.
  • Jetstream - Advanced NATS connection with streaming capabilities.
Connection MechanismChoose the required connection mechanism for the Jetstream connection. Supported values:
  • With stream - This is the regular approach in a Jetstream connection, where each stream defines how the messages are stored and the retention limits.
  • With consumer - This mechanism acts as an interface for clients to consume a subset of messages stored in a stream.
This field is applicable only if the Connection Type is chosen as Jetstream.
Stream nameThe name of the stream for Jetstream connection.

This field is applicable only if the Connection Type is chosen as Jetstream and the Connection Mechanism is chosen as With consumer.
Consumer nameThe name of the consumer for Jetstream connection.

This field is applicable only if the Connection Type is chosen as Jetstream and the Connection Mechanism is chosen as With consumer.
Consumer typeThe type of consumer for Jetstream connection. Supported values:
  • Push - The server actively delivers messages to the client.
  • Pull - The client requests messages from the server when ready.
This field is applicable only if the Connection Type is chosen as Jetstream and the Connection Mechanism is chosen as With consumer.
Batch Poll Consumers CountThe number of consumers to be polled per batch when using the Pull consumer type.

This field is applicable only if the Connection Type is chosen as Jetstream and the Connection Mechanism is chosen as With consumer.
Select security protocolChoose the security protocol for authenticating the connection. It can take values:
  • NONE
  • JWT - If JWT is opted, upload the JWT credentials file.
  • TOKEN_BASED_AUTHENTICATION - Obtain the JWT token from your NATS server using an API.
Transport Layer SecurityChoose the TLS security mechanism. Supported values:
  • NONE - No TLS security.
  • PEM - Use PEM files for TLS security. If PEM is opted for, upload the CA certificate PEM file.
  • JKS - Use Java KeyStore for TLS security. If JKS is opted for, upload the CA certificate JKS file.
Trust Store AuthenticationChoose the required trust store authentication type. Supported values:
  • NONE - No TLS authentication.
  • usingPassword - If opted, provide the trust store password.
This field is applicable only if TLS is chosen as JKS.
Authentication TypeChoose the required authentication type. You can opt for With Credentials or Without Credentials.
UsernameThe username for authentication. This field is applicable only if the Authentication Type is chosen as With Credentials.
PasswordThe password for authentication. This field is applicable only if the Authentication Type is chosen as With Credentials.
DescriptionA description of the integration.
  1. You can toggle on the Active button to activate the integration instantly.
  2. Click Save.

Creating Event Handlers in Orkes Conductor

The integration is created successfully now. The next step is to create an event handler in Orkes Conductor.

To do this:

  1. Navigate to Definitions > Event Handler from the left menu on your Orkes Conductor cluster.
  2. Click the + Define event handler option from the top-right corner.
  3. Create an event handler with the following configurations:

Configuring Event Handler for NATS Messaging Integration

Event Handler ParametersDescription
NameA name to identify your event handler definition.
EventThe event integration you have created in the following format:

Type : Config Name : Queue Name

Example: nats:nats-test:queue-name

Notes: The drop-down automatically lists the integration you’ve added to the Conductor cluster. You can choose that and add the queue name you want to publish/receive messages.
ConditionThe ECMAScript to control the message processing if required. Check out the event handler documentation for more details.
ActionsChoose the required actions to be carried out on sending/receiving the events from NATS. It can take the following values:
  • Complete Task
  • Terminate Workflow
  • Update Variables
  • Fail Task
  • Start Workflow
Each type of action requires and supports a certain set of input parameters. Check out the event handler documentation for more details.
ActiveSet this to true or false. It determines if the event handler is running or not.

A sample JSON for the event handler is as follows:

{
"name": "nats-userpass",
"event": "nats:natstest:events-test-1.test",
"condition": "true",
"actions": [
{
"action": "start_workflow",
"start_workflow": {
"name": "event-handler-test",
"version": 1,
"correlationId": "",
"input": {
"payload": "${$}"
}
},
"expandInlineJSON": false
}
],
"active": true,
"evaluatorType": "javascript"
}

RBAC - Governance on who can use Integrations

Once the integration is added, the next step is determining who can access these integrations.

The permissions can be granted to applications/groups within the Orkes Conductor cluster.

To provide explicit permission to Groups:

  1. From the left menu on your Orkes Conductor cluster, navigate to Access Control > Groups.
  2. Create a new group or choose an existing group.
  3. Under the Permissions section, click +Add Permission.
  4. From the Integrations sub-tab, choose the integration with required permissions.
  5. Click Add Permissions. This ensures that all the group members can access these integration models in their workflows.

Configuring RBAC for Nats Messaging Integration

Similarly, you can also provide permissions to applications.

Creating Workflow in Orkes Conductor

This step involves creating a workflow with an event task in Orkes Conductor. Here, we are utilizing the NATS queue as a sink for the event.

You can quickly build a workflow from UI in Orkes Conductor.

For this,

  1. Navigate to Definitions > Workflow, and click the + Define Workflow button.
  2. Create a workflow and add an event task at the required point with the Sink in the format nats:Nats-integration-test:queue-name, where “Nats-integration-test” is the integration name and “queue-name” is the queue to which Conductor should send/receive messages.

Event task for NATS Integration in Orkes Conductor

Executing Workflow in Orkes Conductor

The workflow can be run using different methods. You can use the Run Workflow button for quick testing, as shown in the image below:

Running workflow from Orkes Conductor UI

Upon successful execution, you can verify the message's delivery through the NATS server.

Check out the official NATS documentation on enabling monitoring & how to monitor the NATS messaging system.

The action added in the event handler definition was to start the workflow event-handler-test. You can verify the same from the Executions > Workflow page.

Starting workflow on sending events