Cutover API
>
Integrations
>
Custom Integration

Custom Integration

The Custom Integration toolkit is a suite of tools that can be used to build flexible integrations with third-party services. It handles a variety of HTTP request methods that conform to API standards, captures and stores response data within Cutover, handles authentication, and polls API endpoints for certain conditions.

Advanced features allow for the customization of request payloads, definition of variable endpoints, and the inspection of nested API responses to retrieve the values you need.

Note: The Custom Integration toolkit is geared for users who have, at minimum, a basic understanding of RESTful APIs and a knowledge of Cutover's custom fields. For less technical, higher-level guidance, see our Custom Integration user guide in our Help Center.

Modules

The following modules are available in the Custom Integration toolkit:

General

This module defines general integration properties, such as a custom name, the trigger that fires the integration and additional settings that modify the integration's behavior.

See 'General settings' below for a more detailed explanation.

Authorization

This module defines authorization properties to be used by integration requests, including oAuth, bearer token and different AWS authorization types.

See 'Authorization settings' below for a more detailed explanation.

Request

This module defines request properties, such as the type of HTTP request, request headers and payload. It handles the response and allows for the mapping of response values to predefined custom fields.

See 'Request settings' below for a more detailed explanation.

Polling

This module defines a scheduled polling to a different endpoint than the initial request. It handles the response and maps response values to a custom field. You can determine the conditions to end the polling scheduler by defining a set of response values that will tell the integration to complete.

See 'Polling settings' below for a more detailed explanation.

General settings

The following common integration properties are defined in the General settings tab:

  • Name: A custom name for the integration. The name must be unique.
  • Image URL: The icon that is associated and displayed with the integration. If this is not defined, a default icon will be added.
  • Trigger: Determines when the integration is fired. Available triggers are:
    - On Task Start - fired when a runbook task is started.
    - On Runbook Update - fired when the runbook is updated via either the Runbook Details panel or the Pages tab. Alternatively, a runbook-level integration can be fired manually when its Run Integration button is clicked (runbook-level integrations are located in a runbook’s Runbook Integrations side panel).
  • Visibility: The Cutover workspace that the integration is restricted to, or Global for general use.

Additional settings

The following additional settings provide further customisation:

  • Auto start: The task will automatically start upon the task's predecessor completing, without requiring manual intervention to get it underway If the trigger is “On Task Start“ this also means that the integration will fire automatically.
  • Enable fixed start time: It will be possible to add a fixed start time in a runbook’s editing panel for the task; this means the task can only be started at the day and time that has been set.
  • Cancellable: It will be possible to cancel a task during its execution.
  • Notify Webhook on Cancel: On task cancellation, an HTTP request will send an abort/cancel message to the specified URL.

    Warning:
    Aborting an integration prevents any further integration actions from being executed but will not stop any process that the integration has initiated when invoking the third-party API.
  • Finish task on success: The task will finish when the integration’s status is set to success.
  • Include context in Request: The outbound payload request will contain information about the runbook and task.
  • Execute in Rehearsal: The task can be executed when the runbook is in rehearsal mode.

Authorization settings

The Custom Integration authorization settings tab allows you to define the type of authorization used by integration requests (in both request and polling phases). The following options are available in the authorization type dropdown which are:

No Auth 

Using this option means there is no authorization required by requests. 

Token Auth

This option defines an authorization token to be sent with the request. 

Enter the following information into the appropriate fields:

  • Token type: specify the type of token e.g. Bearer.
  • Token: the token string

OAuth

OAuth is an open industry standard for access delegation and can be used by the Cutover application to access information in any OAuth compliant service.

Following a standard process, a user must first provide authorization by signing into the third party service with the user’s credentials. With this authorization, Cutover will then obtain and store an access token that is subsequently used to perform API calls on the user’s behalf. There are numerous resources on the web about OAuth. 

The Custom Integration OAuth tab provides the necessary fields to enable OAuth for a compliant service.

The following settings are defined by an OAuth provider. To find the appropriate settings for the service you would like to access, visit the OAuth documentation for that service.

First select the OAuth Flow type:

  • Authorization Code: A commonly used OAuth flow where an authorization code is exchanged for a token.
  • Client Credentials: Involves an application exchanging its application credentials, such as client ID and client secret, for an access token. This flow will display a subset of the configuration settings described below.

Now inform the OAuth settings:

  • Requires Client Assertion: Toggle if your OAuth provider requires a client assertion before requesting an access token. Only relevant to “Authorization Code“ flow.
  • Client ID: The ID provided by the third party OAuth provider.
  • Client Secret: The secret associated with the client ID.
  • OAuth2 provider host: This is the base URL for the OAuth provider (e.g. https://login.microsoftonline.com)
  • Authorization endpoint: The endpoint defined by the OAuth provider to perform authorization (e.g. /common/oauth2/v2.0/authorize). Only relevant if you selected the “Authorization Code“ flow type.
  • Token endpoint: The endpoint defined by the OAuth provider to exchange the authorization token for an access token (e.g. /common/oauth2/v2.0/token)
  • Scopes: The types of operations that Cutover will be allowed to perform on behalf of an authorized user. Scopes are defined by the OAuth provider and usually allow restricted permissions to certain functions (e.g. read, write, profileAccess, etc.)

The last setting is the only one defined by Cutover:

  • Redirect URI: The URI that the OAuth provider must redirect to after the authorization step, where [instance] is the base URL for your Cutover instance. Only relevant to “Authorization Code“ flow.

[instance]/api/integrations/oauth/authentications/payload_transformer/callback

Authenticating as a functional user

Once all settings are filled, it is now possible to authenticate with the OAuth provider in order to perform the API calls defined by the integration. There are two kinds of authentication: as a functional user or individually at the task level.

When authenticating as a functional user, the user’s credentials are supplied for all instances of the integration. To authenticate as a functional user, click on the “Authenticate“ button in the OAuth tab of the Custom Integration. If the functional user is not defined, the integration will request that the authentication be done at the task level.

Authenticating as a task user

The second form of authentication is in every instance of the integration, for example, in the task edit panel of a runbook with an OAuth enabled Custom Integration. When a functional user has not been defined, the “Authenticate“ button is displayed in the task edit sidebar panel. Click this button to authenticate with the OAuth provider. The integration will use these credentials to perform API calls.

AWS STS SigV4

The “AWS STS SigV4“ type uses AWS STS (Secure Token Service) to perform authorization.

Enter the following information into the appropriate fields:

  • AWS Service Code: The STS service code.
  • External ID: The AWS external ID.
  • Role ARN: The AWS role ARN.
  • Region: The AWS region.

Cutover Connect

The “Cutover Connect“ authorization type routes requests to an AWS SQS (Simple Queue Service) according to the values defined in these settings.

Enter the following information into the appropriate fields:

  • SQS URL: The URL of the SQS queue.
  • External ID: The AWS external ID.
  • Role ARN: The AWS role ARN.
  • Region: The AWS region.

Note: The SQS URL field can use variables in order to customize the endpoint.

Request settings

The Request settings tab structures HTTP or Cutover Connect requests and handles responses from third-party APIs.

A screenshot showing the Request settings tab

Execution method

  • HTTP: Make a request to the endpoint defined in the URL field.
  • Use Cutover Connect: Send a message to an SQS defined in the Connect tab.
HTTP execution method

When the HTTP method is selected, the following fields are displayed:

  • URL: The URL of the request.
  • Request type options: POST, PUT, PATCH or GET (defaults to POST).
    - When POST, PUT or PATCH is selected, Request headers and Outbound payload settings are displayed.
    - When GET is selected, Request headers and GET parameters settings are displayed.
Use Cutover Connect execution method

When the Use Cutover Connect method is selected, the Request type and URL fields are hidden. Requests are routed according to the SQS URL field defined in the
Connect tab.

Note: Both HTTP URL and SQS URL fields can use variables in order to customize the endpoint. See 'Variable endpoints' below for more information.

Execution mode

When firing the integration (for example, On Task Start), a request is made to the location defined in either the URL or SQS URL fields. The settings defined in Request headers, Outbound payload or GET parameters are used in this outbound request.

What happens next depends on the execution mode:

  • Fire and forget: When this option is selected, the request is made and the integration is successful if the response is in the 200 range, otherwise it fails. No further action is performed.
  • Response mapping: When this setting is selected, the request is made and the integration expects to handle an inbound response. The response can be handled synchronously or from a callback invoked by an external service. This is defined in the Response handling setting, which is explained next.

Response handling

When the execution method is HTTP and the execution mode is Response mapping, the Response handling setting is displayed. This field is not displayed when the execution method is Use Cutover Connect, since it is assumed the integration will always wait for a callback. In either case, the response mapping settings On success and On error are provided to map response data to a custom field in Cutover.

  • Synchronous: This setting assumes that the desired response will be returned immediately in reply to the outbound request. In other words, the external service provides the information required for response mapping in its response to the POST, PUT, PATCH or GET request.
  • Wait for callback: This setting assumes that the response to the initial request is ignored and the integration waits for a request from an external service to a callback URL provided by Cutover. This callback URL is automatically generated when provided in the Outbound payload setting, described further below. The integration is set to a running state. This behavior is mostly associated with integrations that are handled by a lambda, which receives information from a downstream service and then forwards this information to Cutover via the callback URL.

Request headers, outbound payload and GET parameters

These settings customize the headers, the payload or the parameters sent with the initial request and must be formatted as JSON objects. The code editor checks that the JSON is correctly formatted and displays error markers if there are any mistakes.

  • Request headers: This allows specification of request headers. Here you can specify a bearer token in the header for authentication with external services.
    For instance:
{
    "Content-Type": "application/json",
    "Authorization": "my-bearer-token"
}

Note: Most APIs require “Content-Type“ to be defined and will error if nothing is provided. Make sure to set the value as “application/json“ as this is the format for the submitted content.

  • GET parameters: The parameters sent with an HTTP execution method of type GET. These parameters are defined by the external API and can include, for instance, variables for searching, pagination or sorting.
  • Outbound payload: The payload that is sent with the request body, applicable to the HTTP execution method of type POST, PATCH or PUT, or to the Use Cutover Connect execution method.

Here is an example of a simple payload:

{
    "my_key": "my_value"
}

The JSON can include variables that are processed in the backend. For instance, if you would like to pass the task ID in the payload, you can add the Task.id variable inside double curly braces, as follows:

{
    "my_task_id": "{{Task.id}}"
}

The following table describes the available variables. More variables can be built for the Custom Integration toolkit to address new use cases as they are identified.

Custom Integration variables

Variable LookupDescription
Task 
Any task property such as id, internal_id, or name
Returns the property value for the task.
RunbookAny runbook property such as id, name, or descriptionReturns the property value for the runbook.
IntegrationAction
Any integration action item property such as id or name unless the lookup is one of callback_url specified below.
Returns the property value for the integration action item.
IntegrationActionfinish_integration_callback
_url
Returns the callback URL for the finish integration endpoint.
IntegrationActionupdate_polling_response
_mapping_callback_url
Returns the callback URL for the polling response mapping endpoint. This endpoint is used by the Custom Integration integration.
IntegrationActionupdate_response_mapping
_callback_url
Returns the callback URL for the response mapping endpoint. This endpoint is used by the Custom Integration integration.
CustomField

['custom field name']

Example: CustomField['My custom field name']

Returns the value of a custom field associated with a task. Note that custom fields not accessible by the task will be ignored. Also, custom fields must match their name, including case and spaces.
UserAny user property such as email or first_name.

Returns the property value for the user that started the integration task or a

global admin in case of an auto-start task.

The following is an example of an outbound payload:

{
    "some_key": "my_static_value",
    "callback_url":
"{{IntegrationAction.update_response_mapping_callback_url}}",
    "integration_action_id": "{{IntegrationAction.id}}",
    "task_internal_id": "{{Task.internal_id}}",
    "some_custom_field": "{{CustomField['My custom field name']}}"
}
Using JSONPath lookups

In addition to the variables described above, you can use the special JSON variable to pass in a JSONPath lookup. When the JSON variable is found, the underlying transformer will serialize the following objects as JSON.

{
    runbook: [current runbook],
    runbook_type: [runbook type for the current runbook],
    streams: [current runbook streams],
    task: [current task]
    task_custom_field_values: [task level custom fields and values in current runbook]
}

You can then use JSONPath to find values in the above JSON, as in the following examples:

{
    "runbook": "{{JSON['$.runbook.name']}}",
    "streams": "{{JSON['$.streams[*].name']}}"
}
On success and On error response mappings

These settings provide a means to map a response from the external service to custom fields associated with the integration. Each setting is an array of mappings.
To add a mapping, click on Add New Row. To remove the mapping, click on the X next to it.

A mapping is the combination of a Response Path, written in JSONPath notation, and the associated Target Custom Field.

For example, let's say that your external service returns the following payload:

"foo": {
   "bar": "foo.bar value",
    "baz": "foo.baz value"
    },
    "error": "error value"
}

You could then map the value at key foo.bar to a custom field named "Response foo", as demonstrated in the image below.

A screenshot showing an "On success" response mapping

You could do the same for foo.baz and point it to a custom field named "Response baz."

Then, in On error mappings, you could point the response path error to a custom field named “Response error“.

Custom field handling on integration execution

When the custom integration is executed in a runbook, the mapping will populate the custom field with the value from the response. Our “Response foo“ will now have a
value of “foo.bar value“.

Shared custom field value

An important feature of the Custom Integration toolkit is the ability to provide values for custom fields associated with other integrations or tasks in the same runbook.

If a custom field defined by the mapper is shared between tasks or integrations, either because it is “Global“ or has been associated through “constraints", the values of all instances of the custom field in the runbook are updated.

For instance, you could retrieve the ID of a job launched by an external service and then use that ID in a subsequent integration.

Routing to success or error mappings

If the Response handling setting is Synchronous, the integration will use success mappings if the response status is in the 200 range, otherwise it will use error mappings.

If the Response handling setting is Wait for callback, success and error mappings are handled by a query parameter appended to the callback URL. When the response from the external service is processed by Cutover Connect or a lambda, you can append a status query parameter to the callback URL. If the status is 200, the On success response mapping is used. If the status is 400, the On error response mapping is used.

For instance, given a callback URL provided by the outbound payload, the following would route the response to On success:

[outbound payload callback URL]&status=200

And the following would route the response to On error:

[outbound payload callback URL]&status=400

Variable endpoints

A recurring integration pattern is to make a call to an endpoint that is dependent on a variable, such as the value of a custom field.

For instance, consider a scenario in which you are making a GET HTTP call to an API that requires an object ID to be passed in the endpoint (URL), for instance https://third-party-api/object/11. You might wish to define the object ID at the task level, in order to reuse the integration to access similar endpoints but with different object IDs, instead of creating a new integration for every object endpoint.

This can be done by storing the object ID in a custom field that is defined at the task level. To illustrate this, let us say the ID is stored in a custom field named “Object ID.“ Your endpoint would then take the following form:

https://third-party-api/object/{{CustomField['Object ID']}}

In this manner, the value stored in the task's custom field “Object ID“ will be substituted/interpolated in the endpoint when the integration is fired. Every task can define its own value for the custom field so that the same integration has the flexibility of accessing different objects in the external API.

In fact, any variable from the 'Custom integrations variables' table (see above) can be interpolated in the URL fields.

Polling settings

The polling settings tab defines repeated HTTP requests to an endpoint. If the Use Polling checkbox is selected, consecutive polling requests are performed after the initial request defined in Request settings is completed. The endpoint defined in the URL field, or in the SQS URL field of Connect settings, is polled at defined intervals until a certain condition is met.

A screenshot showing the Polling settings tab

Execution method

  • HTTP: Make a polling request to the endpoint defined in the URL field.
  • Use Cutover Connect: Send a message to an SQS defined in the Connect tab.

HTTP polling execution method

  • Request type: GET or POST (defaults to GET).
  • URL: The URL to be called with each polling request.

Note: The polling URL can also use variables to customize the endpoint. See the 'Request settings' section's 'Variable endpoints' subsection above for more detail.

Cutover Connect polling execution method

When the Use Cutover Connect method is selected, the Request type field is hidden. Requests are routed according to the SQS URL field defined in the Connect
tab.

Request headers, outbound payload and GET parameters

These settings customize headers, payload or parameters sent with each polling request and must be formatted as JSON objects.

Note: The behavior of these settings is the same as described in the 'Request settings' section above. Please refer to the corresponding section, as well as the description of how to use custom integration variables (see the 'Custom integration variables' table above) in these fields.

  • Request headers: Specifies request headers for the polling request.
  • Outbound payload: Specifies the payload to be sent with a polling request of type POST or when the execution method is Use Cutover Connect.
  • GET parameters: Specifies parameters to be sent with a polling request of type GET.

Polling response handling

When the polling execution method is HTTP, the Response handling setting is displayed. This field is not displayed when the execution method is Use Cutover Connect since it is assumed that polling will always wait for a callback.

  • Synchronous: This setting assumes that the desired response will be returned immediately in reply to the outbound polling request. In other words, the external service provides the information required for the Stop polling conditions mapping in its response to the POST or GET request.
  • Wait for callback: This setting assumes that the response to the initial request is ignored and the integration waits for a request from an external service to the polling callback URL provided by Cutover. This callback URL is automatically generated when provided in the Outbound payload as described above in the 'Request settings' section's 'Custom Integration variables' table.

Polling interval

  • Polling interval in seconds: Defines the number of seconds elapsed between each execution of the polling request. The default is set to 10 seconds (although this can be longer), and it cannot be set to under one second.

Stop polling conditions

Once polling requests are initiated, they will continue to be scheduled and executed until certain conditions are met. These conditions are specified through an array of
custom field mappings and expected values at the user’s discretion.


Click on Add New Row to enter a condition line. The condition is composed of the following:

  • Response Path: The path of a property in the API response, retrieved from the polling request synchronously or through a callback. This field can use JSONPath to inspect complex responses. The path retrieves the value at the specified location of the response.
  • Target Custom Field: A custom field defined in Cutover that stores the value obtained from the response path lookup.
  • Condition Value: The value to consider as a stop polling condition if it matches the value at the response path lookup.

For instance, let us imagine that we are making a polling request to an endpoint and expecting that a status property with a value of “successful“ or “failed“ will signal polling to stop.

A screenshot showing how to add conditions to stop polling

The response from the API would look something like the following:

{
    status: "continue"
}

The status value “continue“ will be stored with the custom field “Mock Job Status.“ New polling requests will be scheduled until the status response matches either “successful“ or “failed,“ at which point the integration will stop polling and finish successfully.

Thank you for using our integration. If you have any feedback or suggestions for improving this documentation, please send it to docs@cutover.com.