External API task

The external API task allows your workflows to securely interact with external REST APIs.

The external API task BPMN element in Collibra Workflow Designer

This task cannot connect to Collibra APIs. Use the Collibra API task instead.

How the external API task works

When the workflow reaches an external API task, the Collibra Edge Session Manager sends the request defined in the task to the external API. The Session Manager processes the request using the configured connection details, authentication, and task-specific details.

The final request URL is constructed by concatenating the Host defined in the Edge HTTP connection with the Path defined in the external API task. For example, a host of https://api.example.com and a path of /v1/resource result in a request to https://api.example.com/v1/resource.

Because the request originates from the Edge Site, the Edge Site must have network access to the target host, not Collibra. If the connection fails, verify that the Edge Site can reach the external endpoint.

The response from the external API is captured and stored in a process variable. The variable name is determined as follows:

• <Model_ID>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. 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 command:

edgecli update --set edgeSessionManager.sessionManager.externalApiTask.useRequestStreaming=false

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.

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

1

Open a site.

1. On the main toolbar, click → Settings. The Settings page opens.

2. In the tab pane, click Edge. 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. The site page appears.

2

In the Connections section, click Create connection. The Create connection page appears.

3

Select the HTTP connection:

OAuth 2.0

Connect to an external REST API using OAuth 2.0 authentication with a Client Credentials grant.

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.

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.	Yes
Access token URI	The endpoint on the authorization server where the client application can exchange an authorization grant for an access token, for example https://api.example.com/oauth/token.	Yes
Scopes	A list of space delimited specific permissions that the client application is requesting, for example read_data read_pii_data	No
Host	The protocol and domain name of the server, for example https://api.example.com.	Yes
Test connection path	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.	No

Basic Auth

No Auth

4

Click Create. The connection is added to the Edge or Collibra Cloud site.

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.
Request headers	Line-separated HTTP request headers, such as Content-Type:application/json. The following headers are not supported and are removed: Access-Control-Request-Method Authorization Connection Upgrade Via Content-Length Host Origin Trailer Transfer-Encoding Content-Transfer-Encoding Keep-Alive
Request path	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.
Request body	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.
Fail status codes	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.
Handle status codes	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.
Response variable name	The name of the process variable to store the HTTP response. If not specified, the response is stored in the default variable <HTTP_Task_Model_ID>ResponseBody, for example httpTask1ResponseBody. The supported response formats are XML, JSON, and plain text.

Detail properties

Property	Description
Save request variables	Determines whether all the runtime fields related to the request should be stored as process variables, such as header, path, encoding, or body. By default, only fields related to the response are stored as variables.
Save response details	Determines whether all the fields related to the response that are not the actual response in the body should be stored as process variables, including HTTP status, headers, and so on. By default, only the response body is stored as a variable.
Result variable prefix	A prefix that should be prepended to all the variables for easier grouping, which is useful when there are different API tasks.

Advanced properties

Property	Description
Skip expression	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.
Execution listeners	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.