Configure a Callback Workflow Agent

Configure a callback workflow agent to receive completion details for asynchronous data extracts. When an extract is complete, Data Extraction sends a signal to the workflow agent for further processing.

For example, the workflow can send an email notification or send the completion details to an external REST service.

Before You Start

Ensure that you have access to AI Studio.

Verify that the following signal is available:

Signal

Code	Description
ORA_DATA_EXTRACT_SIGNAL	AI Agent Studio Signal to notify completion of a data extraction job

Create a Callback Workflow Agent

1. Open AI Studio, and then open Workflows.

2. Select Create.

3. Enter the workflow details, including a name, code, pillar, family, and description.

   If you are unsure of the pillar and family, select Common and Others.

   Don't enable Expose to Agentic Apps.

4. Create the workflow.

5. Open the workflow settings, and then select Triggers > Signals.

6. Add the Oracle Data Extract Signal, and then select Apply.

7. Add the node required by the client’s callback requirement. Configure a Send Email node, an External REST node, or another workflow node based on the selected destination.

   An External REST node requires an external REST tool to be configured in AI Studio. Map the required parameters to the signal payload. For example:

   Required Parameters

   Parameter	Value
   requestId	{{$context.$triggers.EVENTS.$input.eventPayload.requestId}}
   summaryStatus	{{$context.$triggers.EVENTS.$input.eventPayload.summaryStatus}}
   extractDefinitionName	{{$context.$triggers.EVENTS.$input.eventPayload.extractDefinitionName}}
   totalExtracts	{{$context.$triggers.EVENTS.$input.eventPayload.totalExtracts}}

8. Save and activate the workflow.

Enable the Callback

When you create or edit an extract definition that uses standard views or an asynchronous user-defined query, enable the Enable Callback switch to send extract-completion details to the configured callback workflow agent.

For instructions about creating the extract definition, see Create an Extract Definition Using User-Defined Queries.

Callback Payload

The callback workflow agent receives a payload that contains the extract request ID, overall status, storage location, output file URL when available, and details for each extract.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "integer"
    },
    "summaryStatus": {
      "type": "string"
    },
    "extractDefinitionName": {
      "type": "string"
    },
    "storage": {
      "type": "string"
    },
    "outputFilesUrl": {
      "type": "string"
    },
    "totalExtracts": {
      "type": "integer"
    },
    "successfulExtracts": {
      "type": "integer"
    },
    "failedExtracts": {
      "type": "integer"
    },
    "extractionDetails": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "extractName": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "extractName",
          "status"
        ]
      }
    }
  },
  "required": [
    "requestId",
    "summaryStatus",
    "storage"
  ]
}

The following example shows a successful extract:

{
  "requestId": 10001,
  "summaryStatus": "Succeeded",
  "extractDefinitionName": "SalesExtract",
  "storage": "ObjectStorage",
  "outputFilesUrl": "https://example.oraclecloud.com/api/saas-batch/jobfilemanager/v1/jobRequests/95428/outputFiles",
  "totalExtracts": 2,
  "successfulExtracts": 2,
  "failedExtracts": 0,
  "extractionDetails": [
    {
      "extractName": "OrderExtract",
      "status": "Succeeded"
    },
    {
      "extractName": "PaymentExtract",
      "status": "Succeeded"
    }
  ]
}

Validate the Callback Configuration

1. In AI Studio, select Resources > Signals > Signal Control Tower.

2. Review the Live Signal Feed to verify that Data Extraction sent the signal.

3. Review the Response Network Trace to verify that the workflow agent subscribed to the signal was resolved.

4. Review Signal Outcomes. Select View All Deliveries to view the delivery details.

Troubleshoot Callback Delivery

If the workflow agent does not receive a callback:

• Verify that the workflow is active.
• Verify that the workflow subscribes to ORA_DATA_EXTRACT_SIGNAL.

• Verify the configuration of the destination node, such as the email recipient or external REST tool.

• Review the signal delivery details in Signal Control Tower.