HTTP task (beta)

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

When the workflow reaches an HTTP 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 HTTP task details.

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

  • <HTTP_Task_Model_ID>ResponseBody, for example httpTask1ResponseBody, if you have not specified a Response variable name.
  • The Response variable name defined in the HTTP task configuration.

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

The HTTP 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 HTTP 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 HTTP 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 an Edge site.
    1. On the main toolbar, click Products icon, and then click 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 the Edge sites.
    3. In the Edge site overview, click the name of an Edge site.
      The Edge site page appears.
  2. In the Connections section, click Create connection.
    The Create connection page appears.
  3. Select the HTTP connection:
    • Basic Auth
    • No Auth

    Connect to an external REST API using basic access authentication.

    FieldDescriptionRequired
    Name

    The name of the Edge HTTP connection.

    Use this value in the HTTP 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 HTTP 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.

Attributes: General

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

Attributes: Details

Attribute Description
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.

If you provide an Auth header and the Edge HTTP connection is Basic, the Edge connection authentication takes precedence. If the Edge HTTP connection is No Auth, the Auth header provided here is used.
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 HTTP 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.
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 HTTP tasks.
Save response as a transient variable

Determines whether the response variables should be stored as transient.

If you used the Response variable name to store the response as a process instance variable and these responses tend to become large, you have the option to store this variable transiently.

The transient variable is no longer available through execution.getVariable("<Response_variable_name>"); and you can only access it directly as <Response_variable_name> through a synchronous script task placed immediately after the HTTP task.

Attributes: Execution

Attribute Description
Exclusive Determines whether the activity or process is run 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 to prevent failing jobs in concurrent scenarios.
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.
Skip expression

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

Attributes: Visual

Attribute Description
Font color The font color of the element in the diagram.
Font size The font size of the element in the diagram.
Font style The font style of the element in the diagram.
Font weight The font weight 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.