Collibra API task

The Collibra API task allows you to automate workflow actions by leveraging Collibra REST APIs, even without dedicated Java APIs. This task handles authentication for seamless API integration.

The Collibra API task BPMN element in Collibra Workflow Designer

Supported APIs

You can use the Collibra API task to interact with all endpoints of Collibra APIs that have a request and response format which is XML, JSON, or plain text. You can only use this task to call APIs on the same environment and not, for example, to trigger an update from your production environment to a non-production environment. You cannot interact with Data Quality APIs or the Console Management API.

The following Collibra APIs are currently supported:

  • Core REST API
  • Import REST API
  • Search REST API
  • Catalog Data Classification REST API (v1)
  • Catalog Data Classification REST API (v2)
  • Catalog Database Registration REST API
  • Data Class Management REST API
  • Data Class Import REST API
  • Catalog Sampling REST API
  • Catalog Cloud Ingestions REST API
  • Catalog External Profiling Upload REST API
  • Protect REST API
  • Job REST API
  • OAuth 2.0 Client Management REST API
  • OAuth 2.0 Authorization REST API

Execution and response handling

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.

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

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

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.

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.