Rest Api Action

This help page is for Desktop Studio. This information is also available for CXone Studio.

Rest Api Action icon

Handles RESTful API calls asynchronously to better handle high loads. This action enables the system to handle higher loads. The action returns both the body and headers for the API call. This makes it easier to test and debug scripts. In order to see the response header, you must save all scripts that contain the REST API action so that the SNIPPET action incorporates the change.

You can also make REST API calls using SNIPPET actions, but they happen synchronously.

Dependencies

There are limitations on the use of this action. Limitations are imposed at tenantClosed High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment level so that one should not impact the other. The limitations within the platform are:

  • Response Format: Only JSON response format is supported.
  • Retries on Failure: Action handler will automatically try two times if a failure message is received before returning the response.
  • Timeout: You specify the timeout value in the request. The value cannot be more than 90 seconds.
  • Max Response Size: The maximum response size is 32 KB. This is consistent with existing Snippet functionality.
  • Throttle Limit: The throttle limit is defined by two parameters:
    • Max Concurrent Requests: Up to 100 concurrent requests are allowed by default. This limit is the same for all CXone customers. This means that 100 concurrent requests result in much higher throughput than the existing Snippet functionality. If you need more than 100 concurrent requests, talk to your CXone Account Representative about increasing the limit for your tenant. Special approvals are required.
    • In Queue Count: When requests exceed the limit, the extra requests enter a processing queue. Once requests drop below the limit, queued requests are processed.
  • Circuit Breaker: If your specified URL is down or unreachable, you can get too many failures on your request. When this happens, CXone will back off (that is, reduce) request execution of ALL URLs from the REST API action for a period of time. This allows your specified URL to recover from the failure. Limits are identified below.
    • Back Off Time or Duration of Break: If the failure rate is reached, no requests from the REST API action will execute for 30 seconds.
    • Minimum Throughput: 100 requests per second. If your tenant is not executing the minimum number of requests, it will continue to execute your requests even though the requests are failing.
    • Failure Rate: If 50% of the requests failed during 30 seconds, your requests will not be executed for the following 30 seconds. 30 seconds is a rolling window.

Input Properties

These properties define data that the action uses when executing.

Property

Description

Caption

Enter a short phrase that uniquely identifies this action in the script. The caption appears on the script canvas under the action icon. The default is the action name.

Verb

Supports basic REST actions such as GET, PUT, POST, DELETE, and PATCH.

Parameters

Supports ability to specify query parameters or post any data. Any kind of JSON - Jobject , Jarray, Jtoken should be acceptable. Currently, the action requires JSON to be provided in a single line. Variable substitution from string containing JSON or converting Dynamic Data type to JSON using the asjson() function is supported. You can also pass the output variable resultSet(out) from a previous REST API action to this property as well.

Headers

Supports the ability to add custom headers to allow for customer authentication (such as bearer tokens). Key value pairs expressed in JSON format is accepted. This action requires JSON to be provided in a single line. Variable substitution from a string containing JSON or converting Dynamic Data type to JSON using the asjson() function is supported. You can also pass the output variable resultSet(out) from a previous REST API action to this property as well.

Important If your custom URL endpoint requires different headers, it must be specified in this property. To keep feature parity with the existing Snippet action, CXone adds the following headers.

{"Accept":"application/json", "Content-Type" :"application/x-www-form-urlencoded"}

Command

Only option is MakeRestRequest, which functions the same when using in a Snippet action. Future development may offer addition commands that the Snippet action provides.

TimeOutInMilliSeconds

Allows a timeout of the REST call to be specified and honored. Must be less than 90 seconds (90000 milliseconds). If no timeout is specified, the default is 10 seconds (10000 milliseconds).

Service Address

Allows for a custom URL to be supplied, including ability to specify query parameters for a GET. Variable Substitution is also supported.

Output Properties

These properties contain variables that hold data returned from executing the action. They're available for reference and use when the action completes.

Property

Description

resultSet(out)

The property containing any information returned from the API specified in Service Address. In the Studio trace window it appears as Dynamic Object for display purposes. You can also pass this resultSet as-is into the header and parameters if needed.

errorArgList(out)

Error conditions have an object like the REST proxy for compatibility. Supports DynamicData type.

Result Branch Conditions

Result branch conditions allow you to create branches in your script to handle different outcomes when an action executes.

Condition

Description

Throttle

Path taken when too many requests are executed within a short period of time. See limitations below for more details.

InvalidInput

Path taken if invalid input is found or a timeout error occurs. Every parameter is validated when the script is saved.

Failure

Path taken when any error or exception happens within the NICE CXoneapplication executing the request.

Error

Path taken when the remote customer endpoint returns an http error code.

Default

Path taken when the response is not received within 90 seconds.

Success

Path taken if the action completes without errors and any API calls or data returns were successful (2xx response codes).

Other Options

You can replace external RESTful API requests currently completed in the Snippet action.