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 Products icon → Cogwheel icon 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:

    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.

    FieldDescriptionRequired
    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
    DescriptionA description for the connection. No
    VaultThe vault where you store your credentials. No
    Client IDThe unique identifier assigned to each client application by the authorization server when the application is registered. Yes
    Client secretThe 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 URIThe 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
    ScopesA list of space delimited specific permissions that the client application is requesting, for example read_data read_pii_data No
    HostThe 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

    Connect to an external REST API using basic access authentication.

    FieldDescriptionRequired
    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
    DescriptionA description for the connection. No
    VaultThe vault where you store your credentials. No
    UsernameThe username for this connection or the vault parameters for the username. Yes
    PasswordThe password for this connection or the vault parameters for the password. Yes
    HostThe 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

    Connect to an external REST API that does not require authentication.

    FieldDescriptionRequired
    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
    DescriptionA description for the connection. No
    Vault The vault where you store your connection details. No
    HostThe protocol and domain name of the server, for example https://api.example.com or the vault parameters for the host. Yes
    Test connection path

    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.

    		 No
  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.
See all variables
  • ResponseReason
  • RequestUrl
  • RequestHeaders
  • RequestMethod
  • DisallowRedirects
  • ResponseProtocol
  • ResponseStatusCode
  • SaveResponseParameters
  • RequestBodyEncoding
  • RequestTimeout
  • FailStatusCodes
  • HandleStatusCodes
  • SaveRequestVariables
  • ResponseHeaders
  • RequestBody
  • IgnoreException
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.