2.4.1 Create an Event Handler

Create event handlers in MicroTx Workflows to listen to messages sent by Transactional Event Queues (TxEventQ) within MicroTx Workflows or to listen to external message brokers, such as Kafka.

When the message broker receives a message, event handlers can perform one or more of the following actions based on the specified conditions.
  • Start running a workflow
  • Terminate a workflow
  • Complete a task
  • Fail a task

Prerequisites

Depending on the type of message broker, you must set txeventq.enabled or kafka.enabled to true in the values.yaml file. This enables event handlers to listen to the message brokers. For Kafka message broker, specify a comma-separated list of addresses of bootstrap servers to access Kafka brokers. See Event Handler Configuration in MicroTx Installation and Configuration Guide.

To create an event handler:
  1. Open the navigation menu and click Definitions.
  2. Click the Event Handlers tab.

    The Event Handlers list page opens. All the event handlers that you have defined are displayed in a table.

  3. Click add (Add Event Handler).
    The New Event Handler dialog box is displayed.
  4. Enter the following information to create an event handler.
    • Name: Mandatory. Enter a unique name to identify the event handler. The name can be up to 128-characters long. Use only letters, numbers, underscores (_), and hyphens (-). Spaces and other special characters are not supported. You cannot change this name later.
    • Queue Type: Select txeventq if the event handler listens to messages sent by Transactional Event Queues (TxEventQ) within MicroTx Workflows or kafka to listen to external Kafka events.
    • Queue Name: The name of the queue or topic to which the message is pushed.
    • Condition: Define an expression that determines what triggers the event handler. The expression must return a boolean value. The actions specified in the event handler are triggered only when the result of the condition expression is true. Enter the expression in a JavaScript-like syntax which evaluates the result of the condition based on the payload.
    • Evaluator Type: Enter JavaScript as the type of evaluator for the condition. This is the only supported value.
    • Active: Select this option to enable the event handler.
  5. If you select txeventq as the Queue Type, provide the following additional information.
    • Publisher Name: Enter the name or identifier of a publisher agent, producer application, entity, or task that enqueues messages.
    • DB Profile: Select the database profile which contains the connection details of the Oracle Database, to which you want to publish messages.
  6. Add one or more of the following types of actions in the Actions group to determine the activities performed by the event handler when it is triggered.
    • Start Workflow. Starts the specified workflow. Provide information for the following fields.
      • Workflow Name: Select a workflow.
      • Workflow Version: Select a version of the workflow.
      • Correlation ID: Enter an ID to logically group and monitor several related workflow executions.
      • Input (JSON): Provide input parameters for the workflow, if any, in JSON format.
      • Task to Domain (JSON): Enter the names of the domains in which you want to run a task.
    • Complete Task to complete executing a task or Fail Task to fail the task execution. This changes the status of a task from in progress to completed or failed based on your selection. Provide information for the following fields.
      • Workflow ID: Enter the workflow execution ID. This ID is unique to a workflow execution.
      • Task Ref Name: Enter the unique reference name for the task. This is used to reference the task within a workflow.
      • Task ID: Enter a unique identifier to retrieve details of a specific task.
      • Output (JSON): Enter the message that you want to display in JSON format.
    • Terminate Workflow: Terminates the specified workflow. Provide information for the following fields.
      • Workflow ID: Enter the workflow execution ID. This ID is unique to a workflow execution.
      • Termination Reason: Enter the cause for terminating the workflow execution.
  7. Optional. Click Add Action to add another action that the event handler performs when it is triggered.
  8. Click Submit to save the changes.
Details of the event handler that you have created are displayed on the Event Handlers list page.

Parent topic: Manage Event Handlers