Oracle Cloud Infrastructure Documentation

Providing Completion Criteria

Specify the condition that determines the criteria for a successful completion of the REST execution.

A success condition is required to complete any REST invocation, whether the API invokes a short-running or long-running operation.

To define the completion of the REST invocation for a long-running operation by using polling, see also Providing Completion Criteria by Using Polling.

Using Functions in a Condition

Basic String and Operator functions are supported in success and polling conditions.

The expression for a success or polling condition can include only the functions as shown in the following section. To extract values from JSON structures, use the json_path function.

Basic arithmetic

+

-

*

. and so on
Basic boolean

AND

OR

NOT
Basic compare

>

<

!=
Basic null

IS NULL

IS NOT NULL

NVL
Basic string

CONCAT

LENGTH

UPPER

LOWER
Basic date/time

DATE_ADD
json_path function

For JSONPath syntax elements, see:

http://goessner.net/articles/JsonPath/

For example, to retrieve the current status value from the following response, use the syntax: $.status.current-status

{
   "processName": "createCustomer",
   "region" : "usa-1",
   "status" : {
      "current-status": "accepted",
      "id" : "usa1h3l4ewrt0989"
}
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.
Parameterizing the Success Condition

You can assign a task parameter to the success condition in a REST task.

The following procedure can also be used to parameterize a polling condition.

To parameterize a condition:

  1. On the Configure REST API details page, go to the Specify completion criteria step.

    To parameterize the polling condition, go to the Specify completion criteria step and click the Polling tab. Note that the Polling tab appears only when the Configure a polling and termination condition for a no-wait REST call checkbox is selected.

  2. In the Conditions block, click Assign parameter that's next to the condition.
  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 cannot be changed.
  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: json_path(SYS.RESPONSE_PAYLOAD, '$.@STATUS')

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

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

The following procedure can also be used to edit the polling condition parameter.

To edit the parameterized condition:

  1. On the Configure REST API details page, go to the Specify completion criteria step.

    To edit the parameterized polling condition, go to the Specify completion criteria step and click the Polling tab. Note that the Polling tab appears only when the Configure a polling and termination condition for a no-wait REST call checkbox is selected.

  2. In the Conditions block, click Edit parameter.
  3. In the Edit parameter panel, edit only the description and the condition expression . You cannot change the identifier (name) and data type.
  4. Click Save changes.
Removing the Success Condition Parameter

Removing the condition parameter removes only the association of the parameter to the success condition specified for the REST task.

The following procedure can also be used to remove the polling condition parameter.

To unassign the parameter from the condition:

  1. On the Configure REST API details page, go to the Specify completion criteria step.

    To unassign the parameter from the polling condition, go to the Specify completion criteria step and click the Polling tab. Note that the Polling tab appears only when the Configure a polling and termination condition for a no-wait REST call checkbox is selected.

  2. In the Conditions block, click Remove parameter.
  3. In the Remove parameter dialog box, click Remove.

    The parameter is unassigned from the condition. The condition expression that was assigned to the parameter becomes the default condition.

    Note

    The parameter is not deleted from the REST task. To delete the parameter, see Deleting a REST Task Parameter.