Providing Completion Criteria by Using Polling
For a REST task that invokes a long-running REST API operation, select the Configure a polling and termination condition for a no-wait REST call checkbox on the Specify completion criteria step to specify the polling configuration for identifying the completion of the REST invocation.
In addition to the success condition, polling configuration includes a polling REST URL and condition, and values for a polling interval and polling timeout.
Optionally, you can specify a termination configuration to cancel the long-running API operation.
To use the API response from the execution step in the polling or termination configuration, create expressions and then include the named expressions in the polling and termination URLs, and the polling and success conditions.
Before you configure polling or termination, create the expressions to fetch the API response values you need.
See also Polling in Long-Running Operations.
Expressions let you assign a value or expression to a variable that you can then use when configuring the completion criteria step.
Create expressions that use the API response from the REST execution step. You
provide a name for the expression when you create it. To include the named
expression in the polling or termination URL, or the polling or success condition,
use the syntax #{expression_name}.
For example, if the REST task invokes the API operation to create a project using a specific project name, the polling request can check the project key to determine whether polling continues or stops. To use the project key as a variable in the polling URL, create an expression that extracts the key from the API payload response, converting it to a value of data type String or JSON_TEXT.
Note that an expression that you create here cannot be used as a REST task output in other operators that are downstream from the task.
To add an expression:
You can edit and delete expressions that you have created in polling.
To edit or delete an expression:
- On the Configure REST API details page, Specify completion criteria step, expand the Expressions section.
- In the Expressions table, find the expression that you want to edit or delete.
-
From the Actions menu (
) of the expression, select Edit or Delete.
- In the Edit expression panel, make the changes, then click Save.
- In the Delete expression dialog box, confirm that the named expression is the one you want to delete, then click Delete.
In a long-running API operation, define the HTTP method and the URL to poll the status of the REST call.
Similar to the REST URL in the execution step, you can include parameters in the
polling URL by using the syntax ${parameter_name}.
In addition, you can include named expressions using the syntax
#{expression_name}. Create
the expressions you need before you configure the polling URL.
To configure the polling method and URL:
The polling configuration includes a polling condition, and values for a polling interval and polling timeout.
The polling condition is an expression that determines whether polling stops or continues. When the expression returns false, polling stops.
Data Integration issues a polling call repeatedly at the specified polling interval until the value for the specified polling timeout is reached, or until the polling condition returns false, whichever occurs first.
To configure the polling condition:
- On the Configure REST API details page, Specify completion criteria step, select the Configure a polling and termination condition for a no-wait REST call checkbox.
-
On the Polling tab, Conditions
section, do the following:
-
In the Conditions section, below Polling
condition, enter a value and choose a unit of measurement for
Polling interval and Polling
timeout.
- Polling timeout: The maximum length of time that's allowed for repeated polling to occur at the specified interval rate. The timeout value must be greater than or equal to 120 seconds but less than or equal to 30 days.
- Polling interval: The length of time to wait before sending the next polling request. The interval value must be greater than or equal to 60 seconds, and less than the specified timeout value.
- To assign a task parameter to the condition, click Assign parameter. See Parameterizing the Polling Condition.
After adding a polling condition, you can assign a task parameter to the condition.
To parameterize the polling condition in a REST task:
You can change the description and default value of the task parameter for the polling condition.
To edit the parameterized polling condition:
- On the Configure REST API details page, go to the Specify completion criteria step.
- In the Conditions block, click Edit parameter.
- In the Edit parameter panel, you can edit only the description and the expression for the polling condition. You cannot change the identifier (name) and data type.
- Click Save changes.
Removing the condition parameter removes only the association of the parameter to the polling condition specified for the REST task.
To unassign the parameter from the polling condition:
For a REST task that invokes a long-running REST API operation, you can specify the REST API details for terminating the long-running operation.
On the Termination tab, define the HTTP method and the URL to terminate the REST call.
Similar to the polling URL, you can include parameters and expressions in the
termination URL by using the syntax ${parameter_name} and
#{expression_name}. Create
the expressions you need before you configure the termination URL.
To configure the termination method and URL:
The success condition in a REST task is an expression that determines a successful completion of the REST API call. Polling stops when the success condition is met.
By default, Data Integration provides a success condition for a REST task. The default success condition is an HTTP status code of 200 or greater but less than 300, written as the following expression:
SYS.RESPONSE_STATUS >= 200 AND SYS.RESPONSE_STATUS < 300
The success condition expression references output in the JSON response that's received from the REST request defined in the execution step.
You can use the default success condition, or you can write a condition expression using system outputs or extracted JSON property values from the response.
To edit the success condition: