Creating a Kafka service

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

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

Before you begin

Before you can use Kafka services in your workflow automations, you must enable the Kafka services capability in your authoring and runtime container environments, as follows.
Enabling Kafka services in Business Automation Workflow Authoring and Workflow Process Service Authoring
Add kafka to sc_optional_components in the ICP4ACluster custom resource: 
shared_configuration:
  # The following ensures that Kafka is installed and Kafka services is enabled
  sc_optional_components: kafka
Enabling Kafka services in Business Automation Workflow Runtime
If you want to enable Kafka, add kafka to sc_optional_components in the ICP4A Cluster custom resource. For example:
shared_configuration:
  # The following ensures that Kafka is installed and Kafka services is enabled
  sc_optional_components: kafka
If you do not want to enable Kafka on all of your runtime instances, you need to disable it on each instance by adding:
kafka_services: 
  enable: false
For example, the following shows a situation where Kafka is disabled for bawinst2 and enabled for bawinst1:
shared_configuration: 
  # The following ensures that Kafka is installed and Kafka services is enabled
  sc_optional_components: kafka
baw_configuration:
- name: bawinst1
- name: bawinst2
   kafka_services:
     enable: false
Enabling Kafka services in Workflow Process Service Runtime
Enable Kafka services in the WfPSRuntime custom resource by adding the following:
spec:
  kafka_services:
    enable: true

Procedure

To create and model your Kafka service:

  1. Open the designer.
  2. Click the plus sign next to Exposed Automation Services and then select Kafka Service from the list.
  3. Name the Kafka service.
    The Kafka service editor opens.
  4. To add operations to your Kafka service that your Kafka 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 Kafka service and its interface.

  5. Click Save or Finish Editing.
  6. To check that the AsyncAPI definition for the Kafka service exists and is available in the development environment, click the AsyncAPI definition URL in the Behavior section of the Kafka service editor.
    Note:
    • Kafka services are only supported in workflow automations, but are not supported in toolkits.
    • When you create a new version of your existing Kafka service, ensure that your changes keep the service compatible with existing clients.
    • After you created, imported, or installed a version that contains Kafka services, it can take up to 5 minutes until message events sent to the Kafka topics are being processed.
    • Messages are deleted after 7 days regardless of being processed or not.

Results

Using the Kafka services
The AsyncAPI definition of a Kafka service describes the operations and their expected message event schemas and the name of the Kafka topic. You use this information in the Kafka client of your choice to send message events to the respective topic. For each message event, the corresponding service flow or process of your default workflow automation version is triggered.
You can get the AsyncAPI definition for your Kafka service from the following URL:
 http://host_name:port/[custom_prefix/]automationservices/kafka/workflow_automation_acronym/kafka_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, and kafka_service_name is the name of the Kafka 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.

In the development environment, before you can send message events to a topic, you must create a version.

Kafka services can be triggered with the credentials specified in the kafka-service-external-client-user secret. The secret also specifies the certificate of the Kafka server that you must add to your trust store of your Kafka client application.