ResponseBody`, for example `HttpTask_1ResponseBody`, if you have not specified a **Response variable name**.
* The **Response variable name** defined in the external API task configuration.
### Execution and response handling
The external API task treats all HTTP responses as successful, including `4xx` and `5xx` status codes. The workflow always continues to the next task, regardless of the response status code. To act on a specific status code, you must explicitly inspect the response in your workflow design.
The API tasks are always executed as [asynchronous activities](/workflows/designing-workflows/processes/process-execution.md). As a result, any changes made in activities before these tasks are committed to Collibra, including any preparation of the input for the API task.
The API task component treats all response status codes as successful, including `4xx` and `5xx`. To handle a particular response status code, use the **Handle status codes** attribute and place an **ErrorBoundaryEvent** with the appropriate error code, such as *HTTP400* on the API task component. This approach provides flexibility to define an error handling pathway, which may include actions such as:
* Ending the workflow.
* Logging relevant information.
* Assigning a task to a system administrator for further investigation.
Using the **Fail status codes** property causes the workflow to enter an error state as it attempts to revert to the last successful state. Due to the asynchronous execution of the API task, the workflow is unable to progress further, effectively halting its execution.
### Workflow exceptions
The workflow stops with an error at the instance level in case of an exception such as:
* Pre-validation:
* Unsupported Request Format
* Edge HTTP Connection Not Provided
* Edge HTTP Connection Not Found
* Request Sending Error
* Request Timeout
* Response Size Exceeded
### Important considerations
* The request timeout is limited to 10 seconds.
* The external API task runs in asynchronous mode only.
* The maximum allowed response size is 100KB.
* The supported request and response formats are XML, JSON, and plain text.
* Retry is limited to 3 times, only if the HTTP request fails to be sent, since `4xx` and `5xx` response codes are also considered successful.
* Any `Authorization` header defined in the **Headers** configuration of the task is removed. You must configure authentication through the Edge HTTP connection.
* The Edge vault stores credentials for Edge capabilities only and is not accessible from workflow HTTP tasks.
### Troubleshooting null response from a valid endpoint
If an external API task consistently returns a `null` response even though the same request succeeds in a REST client such as Postman, the target API may not support HTTP response streaming. By default, the Edge Session Manager streams responses. To disable streaming, a Collibra or Edge administrator can run the following [Edge CLI](https://productresources.collibra.com/docs/collibra/latest/Content/Edge/EdgeSiteManagement/co_edge-cli.htm) command:
|
|---|
edgecli update --set edgeSessionManager.sessionManager.externalApiTask.useRequestStreaming=false
|
{% hint style="info" %}
Disabling streaming affects all external API tasks on the Edge Site. APIs that send real-time updates, perform long-running queries, or send data that arrives in chunks may experience degraded functionality or performance. Instead of sending incremental updates or streamed data, these APIs would need to wait until they have the full response before any data is returned.
{% endhint %}
## Prerequisites
You have created an **HTTP connection** on an Edge or Collibra Cloud site in Collibra.
Show me how
### Prerequisites
* You either created and installed an Edge site or were granted a Collibra Cloud site.
* You have a global role that has the **System administration** or **Manage connections and capabilities** global permission.
### Steps
{% stepper %}
{% step %}
Open a site.
1. On the main toolbar, click 
→ 
**Settings**.\ :chevrons-right: The **Settings** page opens.
2. In the tab pane, click **Edge**.\ :chevrons-right: The **Sites** tab opens and shows a table with an overview of your sites.
3. In the site overview, click the name of a site.\ :chevrons-right: The site page appears.
{% endstep %}
{% step %}
In the **Connections** section, click **Create connection**.\ :chevrons-right: The **Create connection** page appears.
{% endstep %}
{% step %}
Select the **HTTP connection**:
{% tabs %}
{% tab title="OAuth 2.0" %}
Connect to an external REST API using OAuth 2.0 authentication with a [Client Credentials grant](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/).
{% hint style="info" %}
Only the Client Credentials grant type is supported. Credentials are sent in the **Authorization** header using the Basic method. Sending credentials in the request body (`client_secret_post`) is not supported.
{% endhint %}
| Field | Description | Required |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Name | The name of the Edge HTTP connection.
Use this value in the external API task as the Edge HTTP connection name property to identify the connection.
Yes |
| Description | A description for the connection. | 
No |
| Vault | The vault where you store your credentials. | No |
| Client ID | The unique identifier assigned to each client application by the authorization server when the application is registered. | Yes |
| Client secret | The confidential string of characters used to authenticate the identity of the client application on the authorization server.
If your client secret contains special characters such as +, =, or &, some identity providers may reject the token request. This occurs when the identity provider does not decode the percent-encoded secret that Collibra sends per RFC 6749. If token requests fail with a 401 error and your credentials are correct, regenerate the client secret in your identity provider until you obtain an alphanumeric-only value.
The path for testing this connection with a GET call, for example /v1/health.
You can only test a connection after saving the connection details.
The name of the Edge HTTP connection.
Use this value in the external API task as the Edge HTTP connection name property to identify the connection.
The path for testing this connection with a GET call, for example /v1/health.
You can only test a connection after saving the connection details.
The name of the Edge HTTP connection.
Use this value in the external API task as the Edge HTTP connection name property to identify the connection.
The path for testing this connection with a GET call, for example /v1/health or the vault parameters for the path.
You can only test a connection after saving the connection details.
## General properties
| Property | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Model ID | The unique identifier of the element within the process model. |
| Name | The name of the element displayed in the diagram. |
| Documentation | A description and any additional information about this element. |
| Edge HTTP connection name | The name of the Edge HTTP connection that contains the connection details and credentials. |
| Request method | The method of the request: GET, POST, PUT, DELETE, or PATCH.
Values are case sensitive and must not contain leading or trailing spaces.
Line-separated HTTP request headers, such as Content-Type:application/json.
The following headers are not supported and are removed:
Access-Control-Request-MethodAuthorizationConnectionUpgradeViaContent-LengthHostOriginTrailerTransfer-EncodingContent-Transfer-EncodingKeep-Alive
The relative path of the API endpoint.
You can use expressions such as ${requestPath} or /api/endpoint/${expression}.
You can add query parameters in key=value format by appending them after a ? to the path and separating multiple parameters by &, for example /api/endpoint?limit=10\&status=${expression}.
Values are case sensitive.
The body of the request, such as a JSON file which can also contain expressions, for example: {'clientId': ${clientId}, 'name': ${name}}.
The supported formats are: XML, JSON, and plain text.
To avoid unexpected behavior, do not send a body with GET or DELETE requests.
A list of HTTP response status codes to fail the request and throw a runtime exception. You can set code ranges with an X, for example 400, 404, 5XX.
- The API task component treats all response status codes as successful, including
4xx and 5xx. - Use Handle status codes to provide an error handling pathway and prevent the workflow from being stuck.
A list of status codes for which the task will throw a BPMN error, which can be caught by a boundary error event. You can set code ranges with an X, for example 400, 404, 5XX.
Status codes defined here take precedence if the same status codes are defined in the Fail status codes attribute.
The name of the process variable to store the HTTP response.
If not specified, the response is stored in the default variable \ResponseBody, for example httpTask1ResponseBody.
The supported response formats are XML, JSON, and plain text.
An expression which is evaluated before executing the task. If it evaluates to true, the task is skipped.
You must opt-in to enable this feature by setting a process variable \_FLOWABLE\_SKIP\_EXPRESSION\_ENABLED with the Boolean value true.
Allows you to invoke Java logic after certain events:
- Start: Executes after the activity has been started.
- End: Executes after the activity was completed.
- Transition: When defined on a sequence flow, executes once the flow is transition is taken.
|
## Visual properties
| Property | Description |
| ---------------- | --------------------------------------------------- |
| Font size | The font size of the element in the diagram. |
| Font weight | The font weight of the element in the diagram. |
| Font style | The font style of the element in the diagram. |
| Font color | The font color of the element in the diagram. |
| Background color | The background color of the element in the diagram. |
| Border color | The border color of the element in the diagram. |
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.collibra.com/workflows/designing-workflows/processes/shape-repository/external-api-task.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.