Polling settings
Last updated: May 15th, 2024
The Polling settings tab defines repeated HTTP requests to an endpoint. Please follow our step-by-step guide below or watch our video to find out more.
The endpoint defined in the “URL“ field of this tab is polled at defined intervals until a certain condition is met.
If the “Use Polling” checkbox is selected, consecutive polling requests are performed after the initial request defined in the “Request“ tab is completed.
Request type
Please select either 'GET' or 'POST'.
URL
The URL to be called with each polling request e.g ‘https://<your-domain>.atlassian.net/rest/api/issue/[issue id or key]’
Note: The polling URL can also use variables to customize the endpoint. Please see the “Variable endpoints“ section on the Request page for further information about this.
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 page tab. Please refer to the corresponding section, as well as the description of how to use “Custom integration variables“ 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.
GET parameters: specifies parameters to be sent with a polling request type of GET.
Polling Response handling
The following options are displayed:
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 in the “Custom Integration variables“ section of the Request page.
Polling interval and retries
Polling interval in seconds: Defines the number of seconds elapsed between each execution of the polling request. The default is set to 30 seconds (although this can be longer), however it cannot be under 1 second. This option displays if you selected Synchronous as a Response handling option.
Polling maximum retries: Defines the maximum number of retries. The default value is set to 120 retries and this can be configured as per your requirements, but it cannot be a negative number. Once the integration has reached it's maximum retries limit, you are able to refire the integration to start the polling again.
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.
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.
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. 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, consider we are making a polling request to an endpoint and expecting that a status property with value of “successful“ or “failed“ will signal polling to stop.
The response from the API would look something like the following:
{status: "continue"}
The status value “continue“ will be stored with the custom field “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.
Next steps
You can now set up a Custom Integration. By following the steps, you are now ready to add your integration action. You should thoroughly test your integration and address any issues that may arise during the testing phase.
We encourage you to maintain detailed documentation of your configuration and any changes you make in the future. This will be invaluable for troubleshooting and maintenance.
If you are interested in integrations and would like to create further integrations in Cutover, please get in touch with your Customer Success Manager (CSM). If you would like to know more about Cutover please contact info@cutover.com.
Thank you for using this guide, and we wish you every success with your integration project. If you have any feedback or suggestions for improving this documentation, please feel free to send it to docs@cutover.com.
