Oracle Cloud Infrastructure Documentation

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.

Adding Expressions for Use in Polling

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:

  1. 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.
  2. Expand the Expressions section, then click Add expression.
  3. In the Add expression panel, Expression information section, do the following:
    1. Enter a name for the expression in the Identifier field.
    2. From the Data type menu, select a type for this expression.
    3. Complete the property fields for the data type you selected. For example, enter a Length for the STRING data type.
  4. In the Expression builder section, you can visually construct the expression by double-clicking or dragging incoming response outputs, parameters, or functions to add to the editor to build your expression. Or you can manually write the expression yourself. Create an expression that uses output from the response of the REST request.

    • Incoming: You can use the system outputs SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, and SYS.RESPONSE_STATUS.

    • Parameters: You can use any parameter that is defined in the scope of this REST task. See Viewing and Managing Parameters in a REST Task.

    • Functions: You can use basic String and Operator Data Integration functions.

    Not all functions are supported when creating the expression. See the supported list here.

    To extract JSON property values from the API response body, use the String json_path function with the incoming response output SYS.RESPONSE_PAYLOAD. For example:

    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.key') AS String)
    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.emp.ID') AS JSON_TEXT)
  5. Click Add.
Editing or Deleting Expressions in Polling

You can edit and delete expressions that you have created in polling.

To edit or delete an expression:

  1. On the Configure REST API details page, Specify completion criteria step, expand the Expressions section.
  2. In the Expressions table, locate the expression you want to edit or delete.
  3. 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.
Configuring the Polling HTTP Method and URL

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:

  1. 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.
  2. On the Polling tab, select the HTTP method to use for the polling URL.
  3. In the URL field, enter the complete URL and then press Enter.

    If ${} parameter syntax is used for parts of the URL, those parts are converted into URL parameters for the REST task.

    The table in the URL parameters tab below the URL field is updated with the parameterized parts. The default data type for each URL parameter is String.

    If you edit the URL at any time by adding or removing parameter syntax, the URL parameters table is updated accordingly.

  4. To assign a default value to a parameter, see Configuring URL Parameters.
  5. To show or hide the polling URL using the parameter default values you have configured, click Show preview URL or Hide preview URL.
  6. To add a header, see Adding and Managing a Header.
  7. If a request body is required, see Providing a Request Body.
Specifying the Polling Condition

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:

  1. 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.
  2. On the Polling tab, Conditions section, do the following:
    1. Next to Polling condition, click Create.
    2. In the Create polling condition panel, enter an expression that uses output from the response of the REST request.

      The condition expression can include the following elements:

      • Incoming: Incoming response outputs (for example, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

      • Parameters: Parameters that are defined in the scope of this REST task. See Viewing and Managing Parameters in a REST Task.

      • Functions: Basic String and Operator Data Integration functions. The json_path function, which is located under String, lets you extract property values from the response using JSONPath syntax elements in the format: json_path(json_string, json_filter_path)

      For example: CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'

  3. 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 is 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.
  4. To assign a task parameter to the condition, click Assign parameter. See Parameterizing the Polling Condition.
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:

  1. On the Configure REST API details page, go to the Specify completion criteria step.
  2. In the Conditions block, next to Polling condition, click Assign parameter.
  3. In the Add parameter panel, enter a name for the parameter in the Identifier field, or use the default value.

    The parameter name must be unique in the REST task. For a current list of the parameters in the task, see Viewing All the Parameters in a REST Task.

  4. (Optional) Enter a Description to help identify the purpose of the parameter to other users.
  5. The Type of the parameter is Expression, which you cannot change.
  6. In the Condition builder, set the default condition expression for this parameter. This default condition is used at runtime, unless you change the value later (at design time or runtime).

    The condition expression can include the following elements:

    • Incoming: Incoming response outputs (for example, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Parameters: Parameters that are defined in the scope of this REST task. See Viewing and Managing Parameters in a REST Task.

    • Functions: Basic String and Operator Data Integration functions. The json_path function, which is located under String, lets you extract property values from the response using JSONPath syntax elements in the format: json_path(json_string, json_filter_path)

    For example: CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'

  7. Click Add.
    The parameter name is added next to the polling condition.
Editing the Polling Condition Parameter

You can modify the description and default value of the task parameter for the polling condition.

To edit the parameterized polling condition:

  1. On the Configure REST API details page, go to the Specify completion criteria step.
  2. In the Conditions block, click Edit parameter.
  3. 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.
  4. Click Save changes.
Removing the Polling Condition Parameter

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:

  1. On the Configure REST API details page, go to the Specify completion criteria step.
  2. In the Conditions block, click Remove parameter.
  3. In the Remove parameter dialog box, click Remove.

    The parameter is unassigned from the polling condition. The condition expression that was assigned to the parameter becomes the default polling condition for the REST task.

    Note

    The parameter is not deleted from the REST task. To delete the parameter, see Deleting a REST Task Parameter.
Configuring the Termination HTTP Method and URL

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:

  1. 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.
  2. On the Termination tab, select the HTTP method to use for the URL.
  3. In the URL field, enter the complete URL and then press Enter.

    If ${} parameter syntax is used for parts of the URL, those parts are converted into URL parameters for the REST task.

    The table in the URL parameters tab below the URL field is updated with the parameterized parts. The default data type for each URL parameter is String.

    If you edit the URL at any time by adding or removing parameter syntax, the URL parameters table is updated accordingly.

  4. To assign a default value to a parameter, see Configuring URL Parameters.
  5. To show or hide the URL using the parameter default values you have configured, click Show preview URL or Hide preview URL.
  6. To add a header, see Adding and Managing a Header.
  7. If a request body is required, see Providing a Request Body.
Specifying the Completion Criteria (Success Condition)

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 is received from the REST request defined in the execution step.

You can use the default success condition, or you can write your own condition expression using system outputs or extracted JSON property values from the response.

To edit the success condition:

  1. On the Configure REST API details page, go to the Specify completion criteria step.
  2. If your REST API invokes a long-running operation, select the Configure a polling and termination condition for a no-wait REST call checkbox.
  3. In the Conditions block, next to Success condition, click Edit.
  4. In the Edit success condition panel, enter an expression that uses output from the response of the REST request.

    The condition expression can include the following elements:

    • Incoming: You can use the incoming response outputs (for example, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Parameters: You can use any parameter that is defined in the scope of this REST task. See Viewing and Managing Parameters in a REST Task.

    • Functions: You can use basic String and Operator Data Integration functions. The json_path function, which is located under String, lets you extract property values from the response using JSONPath syntax elements in the format: json_path(json_string, json_filter_path)

      For example: json_path(SYS.RESPONSE_PAYLOAD, '$.@STATUS')

    Not all functions are supported in a success condition expression. See the supported list here.

    (For long-running operations) If you selected the Configure a polling and termination condition for a no-wait REST call checkbox, the success condition is an expression that is written on the response of the polling request. You can create expressions that use the API response from the execution step, and then include the named expressions to build the success condition.

  5. To assign a task parameter to the success condition, click Assign parameter. See Parameterizing the Success Condition.