3.2.13 TX EventQ Publish Task

Use the TX EventQ Publish task to publish a message to a queue in Oracle Database, which serves as a message broker.

This task uses Transactional Event Queues (TxEventQ) and Advanced Queuing (AQ), message queuing systems integrated with Oracle Database. This robust and feature-rich message queuing system leverages the functions of Oracle Database so that producers and consumers can exchange messages with high throughput, by storing messages persistently and propagating messages between queues on different databases. Producers create messages and publish them to a specific topic. This action enqueues the message into the topic's queue within the database. Consumers subscribe to topics to receive messages. When a message is published to a topic, all subscribed consumers are notified and can dequeue the message for processing. For more information, see Introduction to Transactional Event Queues and Advanced Queuing in Transactional Event Queues and Advanced Queuing User's Guide.

Prerequisites

Before you begin, ensure that you have completed the following tasks.

• Create a database profile to define the connection parameters to the Oracle Database where you want to publish messages. This task supports only Oracle AI Database 26ai and Oracle Database 19c as the database engine and does not support other databases, such as PostgreSQL database. See Create a Database Profile. MicroTx Workflows uses the credentials provided in the database profile to push the provided message to a topic in Oracle Database.
• Create a topic or event queue in Oracle Database. In Oracle Database 19c, use the CREATE_SHARDED_QUEUE procedure. See CREATE_SHARDED_QUEUE Procedure in Oracle AI Database PL/SQL Packages and Types Reference. To create a topic or event queue in Oracle AI Database 26ai use Java or PL/SQL code. See Java Message Service for Transactional Event Queues and Advanced Queuing or Oracle Database Advanced Queuing Operations Using PL/SQL in Oracle AI Database Transactional Event Queues and Advanced Queuing User's Guide.

  Note down the name of the topic as you will need to provide it later.

• Enable event handlers for the message brokers. See Event Handler Configuration Properties in MicroTx Installation and Configuration Guide.

To add a TX EventQ Publish Task

1. Navigate to the Task tab in a workflow and view all the tasks that you can add using the Workflow Builder. See Access the Task Tab in Workflow Builder.

2. In the More Tasks dialog box, click TX EventQ Publish Task to add it to the workflow.

3. Click the task that you have added in the left pane. The Task tab in the right pane displays details about the task, such as its name and parameters. Next, let's provide details for the task.

4. In the Task Details group, enter the following information.

   • Task Name: Mandatory. Enter a unique name for the task. The name must be between 1 to 128 alphanumeric characters in length and cannot contain spaces or any special characters. Optionally, you can use underscore (_) and hyphen (-).
   • Task Reference: Mandatory. Enter a value to refer to the task within a workflow definition. This value must be unique within a workflow. The task reference value must be between 1 to 128 alphanumeric characters in length and cannot contain spaces or any special characters. Optionally, you can use underscore (_) and hyphen (-).
5. In the TXEventQ_PUBLISH Parameters group, provide the following information.
   • Database Profile: Mandatory. Specify the name of the database profile which contains the connection parameters to connect to the Oracle Database instance where you want to publish the events.
   • Topic: Mandatory. Enter the name of the destination queue or topic in Oracle Database where messages are published.
   • Value: Mandatory. Enter the message that you want to send to the topic.
   • Publisher Agent Name: Mandatory. Enter the name or identifier of a publisher agent, producer application, entity, or task that enqueues messages into a topic.
   • Enable Idempotency: Optional. Enable this option when you want the TX EventQ Publish task to avoid duplicate execution for the same workflow idempotency key and task idempotency key. If you enable idempotency, you may also provide values for the following fields:
     • Idempotency Table Name: Optional. Enter the table name used to store task idempotency lock information. If you do not provide a value, MicroTx Workflows uses fenced_task_idempotency_lock.
     • Idempotency Timeout: Optional. Specifies how long MicroTx Workflows holds the task-level idempotency lock for this task. The lock prevents duplicate concurrent execution during retries or replays. The default is 600000 milliseconds, or 10 minutes.

6. Click Save to save the changes to the workflow.

   MicroTx Workflows displays the changes in JSON code.

7. Review all the changes, and then click Confirm Save to save the changes.

   If you do not want to save the changes, click Cancel, and then click Reset to undo all the changes that you have made since the workflow was last saved.

Example

When you enter information in the Task tab, the corresponding code of the task is updated in the JSON tab. The following example displays the JSON code for a TX EventQ Publish task with sample values.

{
  "name": "txeventq_publish_1234",
  "taskReferenceName": "txeventq_publish_sample",
  "inputParameters": {
    "databaseProfile": "sample_db_profile_name",
    "topic": "sample_queue",
    "value": "This is the message I want to send. A simple hello.",
    "publisherAgentName": "Workflow_Publisher_sampleName",
    "enableIdempotency": true,
    "idempotentTableName": "fenced_task_idempotency_lock"
  },
  "type": "TXEVENTQ_PUBLISH"
}