Request settings
This module defines request properties, such as the type of HTTP request, request headers, and payload. It handles the response and allows mapping of response values to predefined custom fields. Please follow our step-by-step guide below or watch our video to find out more.
The Request Settings tab structures “HTTP” requests and handles responses from third party APIs. Please follow our step-by-step guide below or watch our video to find out more.
Request Type
Request type options “POST,“ “PUT,“ “PATCH“, “DELETE” or “GET“.
- When POST, PUT, or PATCH is selected, 'Request headers' and 'Outbound payload' settings are displayed.
- When GET or DELETE is selected, 'Request headers' and 'Request parameters' settings are displayed.
URL
Enter the URL of the request e.g. https://<your-domain>.atlassian.net/rest/api/[insert latest API version]/issue)
Note: The URL field can use variables in order to customize the endpoint. Please see the Variable endpoints section at the end of this page for further information about this.
Execution mode
When firing the integration (e.g. “On Task Start“), a request is made to the location defined in either '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 section below.
Response handling
When the execution method is 'HTTP' and the execution mode is 'Response mapping', the 'Response handling' setting is displayed.
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,“ 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/Request parameters
These settings customize headers, payload, or 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: 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 none are provided. Make sure to set the value as “application/json“ as this is the format for the submitted content.
Request parameters: The parameters sent along with an 'HTTP' execution method of type 'GET' or 'DELETE'. 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 requests of type 'POST', 'PATCH', and 'PUT'.
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}}"}
Here is an example with custom fields:
{"Job_name":"{{CustomField['Job name']}}","Build_parameters":"{{CustomField['Build parameters']}}"}
Custom Integration variables
The following table describes the available variables.
| Variable | Lookup | Description |
|---|---|---|
| Task | Any task property such as id, internal_id, or name | Returns the property value for the task. |
| Runbook | Any runbook property such as id, name, or description | Returns 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. |
| IntegrationAction | finish_integration_callback _url | Returns the callback URL for the finish integration endpoint. |
| IntegrationAction | update_polling_response _mapping_callback_url | Returns the callback URL for the polling response mapping endpoint. This endpoint is used by the Custom Integration integration. |
| IntegrationAction | update_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. |
| User | Any 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 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']}}"}
XML to JSON conversion
Convert XML Response to JSON: Mark this checkbox if the expected response from the third party service is provided in XML format. The response will be converted to JSON format so it can be used in response mappings.
“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', and the associated 'Target Custom Field'. For example, let's say that your external service will return 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.
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.“
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, 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.
Note: Variable endpoints are generated by dynamic fields. You can read more about Dynamic fields in our help center here.
Consider the following scenario. You are making a GET HTTP call to an API that requires some 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, 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 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 described previously can be interpolated in the URL fields.
