Creating REST Tasks

A REST task lets you call a REST API endpoint to perform an operation.

After sending the REST request, by default Data Integration waits for the call to return the response before performing other tasks (synchronous API mode). The REST invocation completes when the response is received for the REST request.

If the REST request invokes an operation that is long running, you can specify a polling condition, and an optional termination configuration, to identify the completion of the REST invocation. By using polling, Data Integration does not wait for the REST call to return the response before proceeding to other tasks (asynchronous API mode).

Note

The maximum size supported for a response returned from a REST task is 512K. Larger responses are truncated.

Parts of a REST Task

To invoke a REST API endpoint, provide the information for executing and completing the REST request in a REST task.

Creating a REST task involves the following main steps:

  • Define execution details: Define the execution details for the REST request, including the HTTP method, URL, and request header.

    The URL is the REST server to contact and the relative path to the resource that you want to access in the request. For example:

    http://myserver.com:8081/workspaces/finance1234/dataAssets

    For a POST or PUT method, you also provide the request body. Currently, only JSON is the supported format for a request body.

    Defining execution details in Data Integration is the same for short-running API operations and long-running API operations.

  • Specify completion criteria: Specify the success condition criteria that must be satisfied to consider the REST task a successful completion.

    Write the condition that evaluates to true or false using the response from the REST call in the execution step. If the condition returns true, the outcome of the REST task is successful. If false, the outcome is a failed REST task.

    Data Integration provides a default success condition that you can use or edit.

    Specifying completion criteria for a long-running API operation requires adding a polling condition and other polling values. Adding a termination request is optional.

See also how to use parameters in a REST task, and what you need to set up before you use the Oracle Cloud Infrastructure Resource Principal to authenticate an API endpoint in a REST task.

Polling in Long-Running Operations

For a long-running REST API operation, in addition to a success condition, you must specify a polling URL and condition, and polling interval and timeout values to identify the completion of the REST invocation.

The polling configuration is used to periodically poll the status of the REST call that is invoked at the execution step.

In polling, the success condition is an expression that is written on the response of the polling request. The polling call evaluates the polling condition to determine whether polling stops or continues. 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.

The polling interval is the length of time to wait before sending the next polling request. The polling timeout is the maximum length of time that is allowed for repeated polling to occur at the specified interval rate. The interval value must be less than the timeout value.

Suppose that the polling timeout is 24 hours, and the polling interval is 1 hour. After the REST request at the execution step is invoked, the polling REST request is sent at 1-hour intervals, but only for up to 24 hours, or until the polling condition returns false.

If the criteria specified in the success condition is satisfied, the REST call is completed successfully, and the REST task run is considered a success. If the success condition returns false, the outcome of the REST task run is considered as failed.

For example, suppose the polling configuration polls the progress of a task run by evaluating the status in the response:

cast(json_path(SYS.RESPONSE_PAYLOAD, '$.status') as String) != 'SUCCESS' or cast(json_path(SYS.RESPONSE_PAYLOAD, '$.status') as String) != 'ERROR'

Polling stops when the success condition is met.

cast(json_path(SYS.RESPONSE_PAYLOAD, '$.status') as String) == 'SUCCESS'

Termination in Long-Running Operations

Configuring the HTTP method and REST URL to terminate the REST call is optional for a long-running API operation.

Defining the details for the REST termination request in Data Integration is similar to defining the REST request in the execution step. You can, however, include expressions that use the API response from the REST execution step in the termination URL.

If you terminate a REST task run, and a termination configuration is not provided in that REST task, Data Integration:

  • Stops the REST task run
  • Does not stop the underlying API operation invoked by the REST task

If a termination configuration is provided, then Data Integration stops the REST task run and the underlying API operation.

Authentication

Provide the authentication for invoking the REST API endpoint in the REST task.

Currently, you can use Oracle Cloud Infrastructure Resource Principal as the method to authenticate Oracle Cloud Infrastructure API endpoints. You can use workspace or application resource principal.

Resource Principal Authentication

The Oracle Cloud Infrastructure Resource Principal can be specified as the authentication method for executing an Oracle Cloud Infrastructure API endpoint in a REST task.

A resource principal enables resources to be authorized principal actors that can perform actions on service resources. The Oracle Cloud Infrastructure Resource Principal authentication method uses a temporary resource provider session token (RPST) for authentication, and authorization is established through Oracle Cloud Infrastructure Identity and Access Management (IAM) dynamic groups and policies. Permission must be granted to the Data Integration workspace or application, and network resources. Set up the following in IAM before you use Oracle Cloud Infrastructure Resource Principal:

  • Create a dynamic group.

  • To define the resources that belong to the dynamic group, create the following matching rule in the dynamic group:

    ALL{resource.type = 'disworkspace', resource.compartment.id = <compartment-ocid>}
  • Add the following policy statement that permits the dynamic group access to network resources.

    allow dynamic-group <dynamic-group-name> to use virtual-network-family in tenancy
  • To use the Oracle Cloud Infrastructure application resource principal to authenticate an API endpoint in a REST task:

    allow any-user to use ai-service-language-family in tenancy where ALL {request.principal.type = 'disapplication', request.principal.id = '<disapplication-ocid>'}

Parameters

You can include parameters in your REST task, so that you can reuse the task in different runtime situations.

You can use parameters for the following parts of the REST request in a REST task:

  • One or more sections of the REST execution URL, polling URL, or termination URL. In Data Integration, the parameterized variable sections of the URL are known as URL parameters.
  • The value of a header in the request.
  • The entire request body in a POST or PUT request.
  • The success condition that determines the criteria for a successful completion of the REST call.
  • The polling condition (written on the response that is returned from the polling request) that determines whether polling stops or continues.

Creating a REST Task

A REST task lets you call a REST API endpoint using the HTTP protocol.

You create a REST task in a project or folder. Data Integration includes one default project to get you started, but if you want to create your own, see Using Projects and Folders.

To create a REST task:

  1. On the workspace home page, in the Quick actions tile, select Create REST task.

    Alternatively, you can navigate to a project or folder, and click Tasks on the project or folder details page. Then select REST from the Create task menu.

  2. On the Create REST task page, enter a name and description (optional).

    The Identifier field is a system-generated value based on what you enter for Name. You can change the value, but after you save the task, you cannot change the value again.

  3. For Project or folder, click Select, and select the project or folder to save your REST task to.

    If you're creating this task from a project or folder details page, this field is auto-populated for you.

  4. In the REST API details section, click Configure.

    The Configure REST API details page displays, showing numbered configuration steps at the top. Currently, you configure your REST API endpoint in two steps:

    • Define the REST API execution details. See step 5.

    • Specify the completion criteria (success condition) for a successful REST call. For a long-running API operation, you must also configure polling. See step 6.

    To move between the steps, click Next or Previous.

    Click Configure to create the REST API details for the first time (or update the details when you edit the section after creating).

  5. To define the REST API execution details:
    1. Specify the HTTP method and REST URL.
    2. (Optional) Configure any URL parameters.
    3. Add a REST request header.
    4. (Optional) Add a task parameter for the value of the REST header.
    5. For a POST or PUT HTTP method, add the request body.
    6. (Optional) Add a task parameter for the entire request body.
    7. To show the REST URL that you have configured, click Show preview URL.
  6. To specify the criteria for a successful completion of the REST API execution, edit the default success condition that is provided.

    By default, the Configure a polling and termination condition for a no-wait REST call check box is not selected, to indicate that Data Integration waits for the REST invocation to complete before performing other tasks (synchronous behavior).

    If your REST API invokes a long-running operation, select the Configure a polling and termination condition for a no-wait REST call check box and specify the required details for a polling configuration (asynchronous behavior) in addition to the success condition. See Providing Completion Criteria by Using Polling.

  7. When you have completed configuring the REST API details, click Create and close or Save and close.
  8. On the Create REST task page, in the Authentication section, click Configure to specify the authentication method for executing the REST API endpoint. By default, no authentication method is needed.
  9. (Optional) In the Parameters section, click Configure to view or edit values for the parameters that are available in the scope of this REST task.
  10. (Optional) In the Validate task section, click Validate to check for errors and warnings for the task.
  11. When you have completed working on your REST task, click Create and close or Save and close.
Publish the REST task to an application in Data Integration before you can run the task, schedule the task for running, or use the task in a pipeline.

Configuring the HTTP method, URL, and URL Parameters

Specify the HTTP method and URL for the REST request to execute, and configure any URL parameters for the REST task.

Configuring the HTTP Method and URL

The method is a standard HTTP method such as GET or POST. The URL is the REST API endpoint to the resource to access in the REST request.

For example, the following REST endpoint lists the data assets in the workspace that has the ID finance123:

http://myserver.com:8081/workspaces/finance123/dataAssets

The URL can include parameters by using the syntax ${}. For example, the following REST endpoint lists the data assets in a workspace by using parameter syntax for the variable sections of the URL that specify the server host and the workspace ID.

http://${myserver}:8081/workspaces/${workspaceId}/dataAssets

When you specify parts of the URL using parameter syntax, those parts are converted into String URL parameters for the REST task. A default value must be assigned to each URL parameter.

When the task is run, you can change the values of those URL parameters. For example, at runtime you can supply different values for the server and the workspace ID.

To configure the URL for a REST task:

  1. On the Define execution details step of the Configure REST API Details page, select the HTTP method to use for the REST URL.
  2. 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.

    To assign a default value to each URL parameter, see Configuring URL Parameters. You can change the data type, and add a description to each parameter.

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

After entering the REST URL and pressing Enter, any section in the URL that uses the parameter syntax ${} are converted into URL parameters for the REST task.

The default data type of all newly added URL parameters is String. On the URL parameters tab, you can add default values for the REST task parameters, and also change the parameter data type, if needed.

To configure URL parameters for the REST task:

  1. On the Define execution details step of the Configure REST API Details page, select URL parameters.
  2. In the table row for a newly added URL parameter, select Edit from the Actions menu.
  3. In the Edit parameter panel, the Identifier read-only field is the REST task parameter name for the URL variable section that is parameterized.
    1. Enter an optional Description for the parameter.
    2. If necessary, use the Data type menu to change the parameter data type.
    3. In the Value field, enter the default value for the parameter.
    4. Click Save.
      The table row of the URL parameter for the REST task is updated.
  4. To show or hide the REST URL using the parameter default values you have configured, click Show preview URL or Hide preview URL.

Adding and Managing a Header

Define one or more headers to pass to the header section of the REST request. A header has a key and a value.

For example, you can add the Content-Type header for a POST or PUT request.

All standard REST API request headers are supported.

Creating a Header

To create a header:

  1. On the Define execution details step of the Configure REST API Details page, select Header to create a header for the REST task.

    To create a header for a polling URL, go to the Specify completion criteria page, select the Configure a polling and termination condition for a no-wait REST call check box. On the Polling tab, select Header.

  2. Click Add header.
  3. In the Key field, start typing the name of a header.
    When a matching key is found, a list of suggestions displays in a menu. Select the header you want.
  4. In the Value field, start typing the name of the header value.
    When a matching value is found, a list of suggestions displays in a menu. Select the header value you want.
  5. Click Add.

    The header key and value is added to the Header table.

    You can use a parameter for the value of the header key-value pair. See Parameterizing a Header Value.

Editing a Header

You can edit the key and value of a header.

To edit a header in a REST task:

  1. On the Define execution details step of the Configure REST API Details page, select Header.
  2. In the table row for a header, select Edit from the Actions menu.
  3. In the Edit Header panel, you can modify the Key and Value.

    As you start typing in either field, a list of suggestions displays in a menu when a matching item is found. You can then select the header key or header value you want.

  4. Click Save.
Deleting a Header

Deleting a header removes the header key-value pair from the REST task.

To delete a header in a REST task:

  1. On the Define execution details step of the Configure REST API Details page, select Header.
  2. In the table row for a header, select Delete from the Actions menu.
  3. In the Delete Header dialog, click Delete.

    The header key-value pair is removed from the Header table.

    Note

    If the header value was parameterized, the parameter that was associated to the header value is not deleted. To delete the parameter, see Deleting a REST Task Parameter.
Parameterizing a Header Value

After defining the key-value pair for a header, you can assign a task parameter to the header value.

To parameterize the header value of a header in a REST task:

  1. On the Define execution details step of the Configure REST API Details page, select Header.
  2. In the table row for a newly added header, next to the header value, click Expose as task 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 Data type is String. You cannot change the data type.
  6. Set the Length.
  7. Set the Default value for the parameter.
    The default header value is used at runtime, unless you change the value later at design time or runtime.
  8. Click Add.
    The table row of the header is updated with the parameter name next to the header value.
Editing a Header Value Parameter

You can modify the default value of the parameter only.

To edit the default value for a parameterized header value:

  1. On the Define execution details step of the Configure REST API Details page, select Header.
  2. In the table row for the header you want to modify, next to the parameter name, click Edit parameter.
  3. In the Edit parameter panel, modify the Value.
  4. Click Save.
Removing a Header Value Parameter

Removing a header value parameter removes only the association of the parameter to the header value of the header.

Removing the header value parameter does not delete the header key-value pair.

To remove a header value parameter:

  1. On the Define execution details step of the Configure REST API Details page, select Header.
  2. In the table row for the header you want to modify, next to the parameter name, click Remove parameter.
  3. In the Remove Parameter dialog, click Remove.

    The parameter is unassigned from the header value of the header. The value that was assigned to the parameter becomes the header value.

    Note

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

Providing a Request Body

Provide the request body that is required for a REST request that uses the POST or PUT method.

Adding the Request Body

Currently, only JSON is the supported format for a request body.

To create a request body:

  1. On the Define execution details step of the Configure REST API Details page, select Request to create a request body for the REST task.

    To create a request body for a polling URL, go to the Specify completion criteria page, select the Configure a polling and termination condition for a no-wait REST call check box. On the Polling tab, select Request.

    If you do not see the Request tab, ensure that you have selected the appropriate HTTP method.

  2. In the editor, enter the request body.
    • You can type or copy and paste the entire payload.

    • You can reference existing parameters in the payload using the syntax ${}. For example:

      {
          "modelType": "USER_PROJECT",
          "modelVersion": "20200901",
          "parentRef": {},
          "name": "${PROJECT_NAME}",
          "identifier": "${PROJECT_NAME}",
          "description": "Creating my project",
          "objectVersion": 0,
          "objectStatus": 8,
          "registryMetadata": {
              "registryVersion": 0
          }
      }
    Note

    The built-in validator in the editor validates the request body. If you see a red dot with an 'x' at the side of the editor, hover on the icon to see the error for that line of code.
  3. To assign a task parameter to the entire request body, click Expose as a task parameter. See Parameterizing the Request Body.
Parameterizing the Request Body

In addition to using parameters within the request body, you can parameterize the entire request body.

See Adding the Request Body.

After you create the request body in the editor, then you can assign a task parameter to the entire body.

To parameterize the entire request body in a REST task:

  1. On the Define execution details step of the Configure REST API Details page, select Request.
  2. Click Expose as a task parameter.

    If you have not yet entered the request body, Data Integration displays a warning message in a dialog. Enter a request body first, then assign a parameter to the entire body.

  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 Data type of the parameter is JSON, which you cannot change.
  6. In the Value field, set the default JSON for this task parameter.
  7. Click Add.
    The parameter name is added to the top of the editor.
Editing the Request Body Parameter

You can modify the default value of the task parameter for the request body.

To edit the parameterized request body:

  1. On the Define execution details step of the Configure REST API Details page of a POST or PUT method, select Request.
  2. Click Edit parameter.
  3. In the Edit parameter panel, you can edit only the Value field. You cannot change the data type or description.

    To edit the description, see Editing a REST Task Parameter.

  4. Click Save.
Removing the Request Body Parameter

Removing the parameter removes only the association of the parameter to the request body for the REST task.

To unassign the parameter from the entire request body:

  1. On the Define execution details step of the Configure REST API Details page of a POST or PUT method, select Request.
  2. Click Remove parameter.
  3. In the Remove Parameter dialog, click Remove.

    The parameter is unassigned from the request body for the REST task. The request body that was assigned to the parameter becomes the default request body for the task.

    Note

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

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 check box.
  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. Then click Save.
    • Incoming: You can use the incoming response outputs SYS.RESPONSE_PAYLOAD, SYS.RESPONSE_HEADERS, 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. 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 check box, 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.

To parameterize the success condition in a REST task:

  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 check box.
  3. In the Conditions block, next to Success condition, click Assign parameter.
  4. 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.

  5. (Optional) Enter a Description to help identify the purpose of the parameter to other users.
  6. The Type of the parameter is Expression, which you cannot change.
  7. 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.

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

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

To edit the parameterized 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 check box.
  3. In the Conditions block, next to the parameterized Success condition, click Edit parameter.
  4. In the Edit parameter panel, edit only the description and the expression for the success condition. You cannot change the data type.
  5. 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.

To unassign the parameter from 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 check box.
  3. In the Conditions block, next to the parameterized Success condition, click Remove parameter.
  4. In the Remove parameter dialog, click Remove.

    The parameter is unassigned from the success condition. The condition expression that was assigned to the parameter becomes the default success 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.

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 check box 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 datatype String.

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 check box.
  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, SYS.RESPONSE_HEADERS, 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, '$.key') AS String)
  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, 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 check box.
  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 check box.
  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. Then click Add.
      • Incoming: You can use the incoming response outputs SYS.RESPONSE_PAYLOAD, SYS.RESPONSE_HEADERS, 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. 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.

  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, next to the parameterized Polling condition, 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 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, next to the parameterized Polling condition, click Remove parameter.
  3. In the Remove parameter dialog, click Remove.

    The parameter is unassigned from the polling condition. The condition expression that was assigned to the parameter becomes the default success 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 check box.
  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 check box.
  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. Then click Save.
    • Incoming: You can use the incoming response outputs SYS.RESPONSE_PAYLOAD, SYS.RESPONSE_HEADERS, 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. 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 check box, 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.

Providing Authentication in the REST Task

By default, no authentication is needed to execute the REST endpoint in a REST task.

You can, however, use Oracle Cloud Infrastructure Resource Principal to authenticate an Oracle Cloud Infrastructure API endpoint in a REST task.

You must set up Oracle Cloud Infrastructure Identity and Access Management (IAM) dynamic groups and policies before you can use OCI Resource Principal for authentication. See Authentication.

To specify the authentication to use for the REST task:

  1. Click Open tab (plus icon) in the tab bar, and select Projects.
  2. On the Projects page, select the project containing the task you want to edit.
    If the task is saved to a folder in this project, click Folders and select the folder that contains the task you want to edit.
  3. Click Tasks on the project or folder details page.
  4. From the tasks list, select View details from the Actions menu of the task that you want to edit.
    Alternatively, you can click the name of the task in the tasks list.
  5. In the Authentication section of the REST task panel, click Configure or Edit.
  6. From the Authentication menu, select OCI resource principal.
  7. Under Authentication source, select Workspace or Application.

Viewing and Managing Parameters in a REST Task

View and manage the parameters that are added or used in the scope of one REST task.

Viewing All the Parameters in a REST Task

Open the REST task in the project or folder to see a list of the parameters created and assigned in the task. Unassigned parameters are also available in the list.

  1. Click Open tab (plus icon) in the tab bar, and select Projects.
  2. On the Projects page, select the project containing the task you want to edit.
    If the task is saved to a folder in this project, click Folders and select the folder that contains the task you want to edit.
  3. Click Tasks on the project or folder details page.
  4. From the tasks list, select View details from the Actions menu of the task that you want to edit.
    Alternatively, you can click the name of the task in the tasks list.
  5. In the Parameters section of the REST task page, click Configure.
  6. In the table list on the REST task parameters page, you can review all the parameters that you have defined in this REST task.

    The Used in column indicates where the parameter is currently used in the task.

Adding Parameters

You can add scalar, JSON, and expression parameters in the scope of a REST task, for referencing in parameterized elements within the same REST task.

  1. Open the REST task in the project or folder.
  2. In the Parameters section of the REST task page, click Configure.
  3. On the REST task parameters page, click Add parameter and select the type of parameter to add from the menu.
  4. In the Add parameter panel, you can define the following parameter types.
    • Scalar: Add a conventional name-value pair parameter. Specify a unique identifier, the data type, and the default value.
    • JSON: Add a JSON data type parameter. Specify a unique identifier, and a valid JSON as the value.
    • Expression: Add an expression type parameter. Specify a unique identifier, then use the condition builder to write the expression.
  5. Click Add.
  6. Click Done on the REST task parameters page.
Editing a REST Task Parameter

You can edit the description, data type, and value of a parameter.

  1. Open the REST task in the project or folder.
  2. In the Parameters section of the REST task page, click Configure.
  3. On the REST task parameters page, in the table row for a parameter, select Edit from the Actions menu.
  4. In the Edit parameter panel, edit the fields.

    You cannot change the data type of a condition or request body task parameter.

  5. Click Save.
Deleting a REST Task Parameter

You can delete a parameter only if the parameter is not in use in the REST task.

The Used in column on the REST Task Parameters page indicates where a parameter is being used in the task.

  1. Open the REST task in the project or folder.
  2. In the Parameters section of the REST task page, click Configure.
  3. On the REST task parameters page, in the table row for a parameter, select Delete from the Actions menu.
    If the parameter is in use in the REST task, the Delete action is not available.
  4. In the Delete parameter dialog, click Delete.

Validating a REST Task

To validate a REST task at any time:

  1. Click Open tab (plus icon) in the tab bar, and select Projects.
  2. On the Projects page, select the project containing the task you want to edit.
    If the task is saved to a folder in this project, click Folders and select the folder that contains the task you want to edit.
  3. Click Tasks on the project or folder details page.
  4. From the tasks list, select View details from the Actions menu of the task that you want to edit.
    Alternatively, you can click the name of the task in the tasks list.
  5. In the Validate task section of the REST task panel, click Validate.

Editing a REST Task

You can edit a REST task to modify any of the configured details, including parameters and parameter values.

You edit a task from the project or folder details page where the task is saved.

  1. Click Open tab (plus icon) in the tab bar, and select Projects.
  2. On the Projects page, select the project containing the task you want to edit.
    If the task is saved to a folder in this project, click Folders and select the folder that contains the task you want to edit.
  3. Click Tasks on the project or folder details page.
  4. From the tasks list, select View details from the Actions menu of the task that you want to edit.
    Alternatively, you can click the name of the task in the tasks list.
  5. Edit the sections you want to change.
  6. Save periodically while you work. You can click:
    • Save: Commits changes since your last save. You can continue editing after saving.
    • Save and close: Commits changes, closes the page, and returns you to the project or folder details tasks page.
    • Save as: Commits changes (since your last save) and saves to a copy instead of overwriting the current task. You can provide a name for the copy, then select a different project or folder for the copy, or save the copy in the same project or folder as the existing task.

Deleting a REST Task

If you want to delete a REST task, you can do so from the tasks list on a project or folder details page. After a task is deleted, it cannot be restored.

To delete a REST task:

  1. Click Open tab (plus icon) in the tab bar, and select Projects.
  2. On the Projects page, select the project containing the REST task you want to delete.
    If the task is saved to a folder in this project, click Folders and select the folder that contains the REST task you want to delete.
  3. Click Tasks on the project or folder details page.
  4. From the tasks list, select Delete from the Actions menu of the task that you want to delete.
  5. In the Delete task dialog, confirm that you want to delete the task, and then click Delete.