External API task

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

When the workflow reaches an external API task, the CollibraEdge Session Manager sends the request defined in the task to the external API. The Session Manager handles the API call using the configured connection details and authentication together with the external API task details.

The response is captured and stored in a process variable. The name of the variable is:

  • <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.

The workflow continues to the next task even if an error response code is returned.

The external 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 external API task component.

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
  • 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.

Prerequisites

You have created an HTTP connection on an Edge site in Collibra.

Show me how

Prerequisites

  • You have created and installed an Edge 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 Collibra 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
    • Basic Auth
    • No Auth

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

    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. 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 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.
Request headers Line-separated HTTP request headers, such as Content-Type:application/json.
Some headers are not supported and are removed.
See the list of unsupported headers
  • Access-Control-Request-Method
  • Authorization
  • Connection
  • Upgrade
  • Via
  • Content-Length
  • Host
  • Origin
  • Trailer
  • Transfer-Encoding
  • Content-Transfer-Encoding
  • Keep-Alive
Request path The path of the API endpoint. You can use expressions such as ${requestPath} or /api/endpoint/${expression}.
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 external API task component treats all response status codes as successful, including 4xx and 5xx.
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 external API tasks.

Advanced properties

Property Description
Exclusive Whether the asynchronous activity or process runs as an exclusive job. An exclusive job ensures that no other asynchronous exclusive activities within the same process are performed at the same time. This helps prevent failing jobs in concurrent scenarios.
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.