> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/tutorials/external-api-task-workflow.md).

# 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](https://app.gitbook.com/s/AeKwSsP1BP6lDDArkTO2/designing-workflows/processes/shape-repository/external-api-task.md).
* 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:

```groovy
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:

```json
{
  "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.

{% hint style="info" %}
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.
{% endhint %}

## 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:

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

The request body must include the decision variable:

```json
{
  "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**.

{% hint style="info" %}
To change an asset status from a service task, use the **Change status** delegate. For details, see the shape repository reference.
{% endhint %}

## Testing and verification

{% stepper %}
{% step %}
Publish the workflow to your Collibra environment.
{% endstep %}

{% step %}
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.
   {% endstep %}

{% step %}
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.
   {% endstep %}
   {% endstepper %}

## 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](https://app.gitbook.com/s/AeKwSsP1BP6lDDArkTO2/designing-workflows/processes/shape-repository/external-api-task.md): Full reference for the task's attributes and configuration options.
* [Collibra API Task workflow](/tutorials/collibra-api-task-workflow.md): A similar tutorial for calling Collibra REST APIs from a workflow.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.collibra.com/tutorials/external-api-task-workflow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.