Creating an MQ service

You can create an MQ service to expose a message-based interface to external clients, which can interact asynchronously with workflow automations.

MQ services enable message-driven interactions with workflow automations. An MQ service exposes a message-based interface to external clients, which can send IBM® MQ messages, for example, to trigger processes or service flows asynchronously. This enables loosely coupled, asynchronous interactions between clients and workflow automations.

Messages are read transactionally from the queue to guarantee their delivery and integrity. If a transaction is rolled back, the message is returned to the queue.

IBM MQ is not part of IBM Cloud Pak for Business Automation and needs to be installed and configured externally.

Before you begin

Before you can use MQ services in your workflow automations, you must configure IBM MQ and enable the MQ services capability in your authoring or runtime container environments, as follows.

Set up and configure IBM MQ: Set up and configure IBM MQ, and create a queue manager. See the IBM MQ documentation for instructions.; The IBM MQ resource adapter is provided by IBM Cloud Pak for Business Automation,
Create an input queue for your workflow automations: To enable MQ services, create a new queue on IBM MQ to be used as the input queue for all automation. See Working with local queues .; It is a good idea to configure a dead-letter queue for your queue. See Working with dead-letter queues . Messages that cannot be processed are put on that queue and can be repaired and replayed.; Configure the BOQNAME(queue-name) parameter to specify the queue and the BOTHRESH(integer) parameter to specify the backout threshold for your queue. The message is retried for the specified number of times until it is backed out to the dead-letter queue. See BOTHRESH(integer) .; Create a user for Workflow to read messages from the queue. When you also expose an MQ service as an automation service, the user also needs write access to the queue.

Enabling MQ services in Business Automation Workflow Authoring and Workflow Process Service Authoring

Enable MQ by customizing the Liberty custom XML file that is set in the bastudio_configuration.custom_xml parameter. Sensitive information can be added to a secret that is referenced in the bastudio_configuration.custom_secret_name. The settings are merged into the Liberty settings for the component in the custom resource (CR).

Create a secret for the Liberty server configuration. See Creating secrets to protect sensitive configuration data. Add variables for the user and password to the secret.

<server>
  <variable name="mq_service_user_consumer" value="<user>" />
  <variable name="mq_service_user_consumer_password" value="<password>" />      
</server>

If you have the content in a file named cutom.xml, you can create the secret with the followig command.

kubectl create secret generic secret-name --from-
file=sensitiveCustomConfig=./custom.xml

Add the connection details of your MQ queue to the Liberty configuration. Also add the name of the secret that you created.

bastudio_configuration:
	…
  custom_xml: |
      <server>
          <!-- In-bound MQ service configurations -->
          <variable name="mq_service_auto_start" value="true" />
          <variable name="mq_service_channel" value="<service channel name" />
          <variable name="mq_service_queue_manager" value="<queue manager name>" />
          <variable name="mq_service_host" value="<queue manager host name>" />
          <variable name="mq_service_port" value="="<queue manager port>"/>
          <variable name="mq_service_base_queue_name" value="<queue name>" />
          <variable name="mq_service_ssl_cipher_suite" value="" />
      </server>
  custom_secret_name: <name of the secret>

The Business Automation Workflow configuration contains a predefined jmsQueue (id="jndi/MDBQ") and a predefined jmsActivationSpec ("id=Teamworks/twcore-ejb/MQServiceConsumerMessageListener"). If you need to specify additional MQ specific properties, you can add a jmsQueue orjmsActivationSpec with the same ID to the Liberty configuration and provide the required properties.

Enabling MQ services in Business Automation Workflow Runtime

To enable MQ services in Business Automation Workflow Runtime, use baw_configuration[x].liberty_custom_xml and baw_configuration[x].custom_xml_secret_name.

Enabling MQ services in Workflow Process Service Authoring

To enable MQ services in Workflow Process Service Authoring, use workflow_authoring_configuration.liberty_custom_xml and workflow_authoring_configuration.custom_xml_secret_name.

Procedure

To create and model your MQ service:

Open the designer.
Click the plus sign next to Exposed Automation Services and then select MQ Service from the list.
Name the MQ service.
The MQ service editor opens.
To add the operations that your MQ service should support:
1. Click Add.
2. In the operation details, name the operation and specify the implementation for the operation.
3. As implementation, you can either create or select an existing service flow or process. For more information, see Creating a service flow or Creating a process.
  Operations are one-way, asynchronous, without a response.
  You can use service flows and processes that expose inputs and outputs that use out-of-the-box basic simple types, such as String, Integer, Boolean, Decimal, Date, Time from the System Data toolkit, or custom business objects. Other out-of-the-box types from the system toolkits are not supported. Make sure there are no multiple business objects with the same name in the dependency chain of your MQ service and its interface.
4. Click Save or Finish Editing.
5. To check that the AsyncAPI definition for the MQ service exists and is available in the development environment, click the AsyncAPI definition URL in the Behavior section of the MQ service editor.
  Note:
  - For MQ services, an AsyncAPI v3 defintion with an ibmmq is created. The headers in the AsyncAPI v3 definition are mapped to user properties in the IBM MQ message.
  - MQ services are only supported in workflow automations, but are not supported in toolkits.
  - When you create a new version of your existing MQ service, ensure that your changes keep the service compatible with existing clients.

Results

Using the MQ services

The AsyncAPI definition of a MQ service describes the operations and their expected message schemas and the name of the MQ queue. You use this information in the MQ client of your choice to send messages to the respective queue. For each message, the corresponding service flow or process of your workflow automation is triggered. The default version is used if you do not specify the version header.

You can get the AsyncAPI definition for your MQ service from the following URL:

 http://host_name:port/[custom_prefix/]automationservices/MQ/workflow_automation_acronym/[snapshot_acronym/]mq_service_name/docs

where host_name is the host name, port is the port number, custom_prefix is an optional custom prefix, workflow_automation_acronym is the acronym of the workflow automation, snapshot_acronym is an optional snapshot acronym which, if not specified, resolves to either the tip of the default branch in the development environment, or to the default snapshot in a runtime environment, and mq_service_name is the name of the MQ service.

In a runtime environment, the URL retrieves the AsyncAPI definition from the default version of the workflow automation. In a development environment, the URL retrieves the AsyncAPI definition from the tip of the default branch.