External API task workflow

This tutorial explains how to use the External API task in a workflow to route asset approval through an external system. You learn how to send asset details to an external REST API, pause the workflow while the external system processes the request, receive its decision through a message event callback, and update the asset status in Collibra.

Learning objectives

• Configure an External API task to call a third-party REST endpoint.

• Build a dynamic JSON request body that includes the workflow instance ID so the external system can send its decision back.

• Use an Intermediate Catching Message Event to pause the workflow and wait for an external callback.

• Route the workflow based on the external system's decision and update the asset status in Collibra.

Prerequisites

• Access to a Collibra environment with Workflow Designer.

• Familiarity with creating and publishing workflows.

• Basic understanding of Groovy scripting and JSON.

• An HTTP connection configured on a Collibra Edge Site, pointing to the host of the external approval system. For instructions, see External API task.

• The external approval system must be able to send an HTTP POST request to the Collibra Workflow API to deliver its decision back to the workflow.

Workflow overview

This sample workflow routes asset approval to an external system. A user selects an asset for approval, and the workflow sends its details to an external REST API. The workflow then waits for the external system to respond with its decision. Based on the response, the workflow either approves or rejects the asset in Collibra.

The workflow includes the following main components:

• User task - Select asset for approval: Lets the user select the asset to send for external approval.

• Script task - Build approval request: Builds the JSON payload containing the asset ID and the workflow instance ID for the callback.

• External API task - Send approval request: Sends the payload to the external system via the configured Edge HTTP connection.

• Intermediate Catching Message Event - Wait for decision: Pauses the workflow until the external system sends its decision back via the Collibra Workflow API.

• Exclusive Gateway: Routes the workflow based on the value of the externalSystemStatus process variable.

• Service task - Approve asset / Reject asset: Changes the asset status in Collibra.

Create a user task for asset selection

Start the workflow with a user task that lets the user select the asset to send for external approval:

1. Add a User task to your workflow and name it Select asset for approval.

2. Configure the task form with the following field:

   • Asset - Asset for approval: Map this to an assetId variable.

Build the API request body

After the user selects an asset, use a script task to build the JSON payload for the external system. Include the workflow instance ID so the external system can reference it when sending its decision back:

1. Add a Script task after the Select asset for approval user task and name it Build approval request.

2. Enter the following Groovy code:

import groovy.json.JsonBuilder

JsonBuilder json = new JsonBuilder()
json {
  assetId execution.getVariable("assetId")
  workflowInstanceId execution.getProcessInstanceId()
}

execution.setVariable("approvalRequest", json.toPrettyString())

Explanation:

• assetId: The ID of the asset selected by the user in the previous task.

• workflowInstanceId: The ID of the running workflow instance, retrieved using execution.getProcessInstanceId(). The external system uses this ID to address its callback to the correct workflow instance.

• The resulting JSON string is stored in the approvalRequest process variable.

The JSON output

The approvalRequest variable will contain a JSON object similar to the following:

{
  "assetId": "00000000-0000-0000-0000-000000000001",
  "workflowInstanceId": "9e5b4c3a-1d2e-4f5a-8b7c-6d9e0f1a2b3c"
}

Configure the external API task

Use an External API task to POST the approval request to the external system:

1. Add an External API task after the Build approval request script task and name it Send approval request.

2. Configure the task properties:

   • Edge HTTP connection name: Enter the name of the HTTP connection you created on the Collibra Edge Site. This name must match exactly.

   • Request method: POST.

   • Path: Enter the path of the endpoint on the external system, for example /approvals/requests. The host defined in the Edge HTTP connection is prepended automatically.

   • Request body: Enter the approvalRequest process variable.

   • Handle status codes: 500. This allows an error boundary event on this task to catch HTTP 500 errors and redirect to an error-handling path.

The external API task always runs asynchronously. Every change made to process variables before this task is committed to Collibra before the external call is made.

Wait for the external decision

After sending the request, the workflow must pause and wait for the external system to send its decision. Use an Intermediate Catching Message Event for this:

1. Add an Intermediate Catching Message Event after the Send approval request external API task and name it Wait for decision.

2. Set the Message name to externalApprovalDecision. The external system uses this name when addressing its callback.

How the external system sends its decision

While the workflow waits at the Wait for decision event, the external system processes the approval request. When ready, it resumes the workflow by sending an HTTP POST request to the Collibra Workflow API. It uses the workflowInstanceId received in the original request as the processInstanceId, and the message name defined in the workflow as the messageName path parameter:

POST /rest/2.0/workflowInstances/{processInstanceId}/messageEvents/{messageName}

The request body must include the decision variable:

{
  "variables": {
    "externalSystemStatus": "approved"
  }
}

When Collibra receives this request, it resumes the workflow and makes the externalSystemStatus variable available to subsequent tasks.

Route and handle the decision

After the workflow resumes, use an exclusive gateway to route it based on the external system decision:

1. Add an Exclusive Gateway after the Wait for decision event.

2. Configure two outgoing sequence flows:

   • Approve: Set the condition expression to ${externalSystemStatus == 'approved'}.

   • Reject: Set this as the default flow, or set the condition expression to ${externalSystemStatus != 'approved'}.

3. Connect the Approve flow to a service task named Approve asset and configure it to change the asset status to the approved status in your operating model.

4. Connect the Reject flow to a service task named Reject asset and configure it to change the asset status to the rejected status in your operating model.

5. Connect both service tasks to an End Event.

To change an asset status from a service task, use the Change status delegate. For details, see the shape repository reference.

Testing and verification

1

Publish the workflow to your Collibra environment.

2

Test the approval path:

1. Start the workflow and select an asset.

2. Verify that the external system receives the request containing the assetId and workflowInstanceId.

3. Send a callback to the workflow with externalSystemStatus set to approved.

4. Verify that the workflow completes and the asset status is updated to approved.

3

Test the rejection path:

1. Start the workflow and select an asset.

2. Send a callback with externalSystemStatus set to rejected.

3. Verify that the asset status is updated to rejected.

Summary

You have built a workflow that uses the External API task to delegate approval to an external system and apply the decision in Collibra. The same pattern applies to any integration that requires a workflow to call a third-party REST API, pause for an asynchronous response, and act on the result.

Additional resources

• External API task: Full reference for the task's attributes and configuration options.

• Collibra API Task workflow: A similar tutorial for calling Collibra REST APIs from a workflow.