Rest API Action

Handles RESTful API calls synchronously. This action enables the system to handle higher loads. It returns both the body and headers for the API call. This makes it easier to test and debug scripts. You can test a script containing a REST API action and view response information. To do this, run the script using the start with trace option. You can also make synchronous RESTful API calls using the GetRestProxy() function in a SNIPPET action. This option doesn't handle high loads as well as the REST API action and is not the preferred method. This action is one of the supported methods of connecting to web services in a Studio script.

Dependencies

There are limitations on the use of this action that are imposed at the business unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment level. This is done 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. If you're reaching this limit, you must reduce the size of returned data.
• 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 making API calls from a Snippet action. If you need more than 100 concurrent requests, talk to your CXone Account Representative about increasing the limit for your business unit. 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 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 business unit 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.

Other dependencies of this action are: 

• JSON is the only supported response format. The action requires that all JSON be on a single line. When working with JSON in this action, you can:

  • Do variable substitution from a string containing JSON.
  • Convert a dynamic data object to JSON is supported using the asjson() function. Note that asjson() treats everything as a string, which means some manipulation is required when working with boolean or numeric values.
  • Pass the output variable resultSet(out) from a previous REST API action to this property as well.
• Responses are returned as jtoken objects. You can work with them just as you would with dynamic data objects in your script.
• Responses contain headers and the body of the response. They may also contain HTTP status codes. Not all responses will include status codes. If there is no error, if the REST API action fails to generate a valid response, or if the error returned cannot be parsed as a valid response, no status is included.
• Responses contain headers and the body of the response. They also include HTTP status codes in two variables, __httpstatuscode and __httpstatusdescription. These variables populate from information returned from the server. However, they do not populate if there is an error, timeout, overflow, broken circuit, or another situation where the server does not return a response.
• You can use more than one REST API action in a script, but they cannot both reference the same objects.

Supported Script Types

Generic	Email	Chat	Phone	Voicemail	Work Item	SMS	Digital

Input Properties

These properties define data that the action uses when executing.

Property	Description
Add Caption	Enter a short phrase that uniquely identifies this action in the script. The caption appears on the script canvas under the action icon.
Verb	Supports basic REST actions such as GET, PUT, POST, DELETE, and PATCH.
Parameters	Specify the parameters to include or data to post as a JSON object of key value pairs. Many kinds of JSON are acceptable, such as Jobject , Jarray, or Jtoken.
Headers	Allows you to add custom headers to allow for customer authentication, such as bearer tokens. You can use JSON in this field. 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 by default: {"Accept":"application/json", "Content-Type" :"application/x-www-form-urlencoded"}
Command	Currently the only option is MakeRestRequest. This functions the same as the MakeRestRequest()function used when making a REST API call in a Snippet action.
Wait Time In MilliSeconds	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	The URL of the REST API you want the action to call. You can use variable substitution with this property. Use the Parameters property to specify query parameters to include.

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
Result Set	A variable that holds any information returned from the API specified in Service Address. You can pass the contents of this variable as-is into the header and parameters if needed. The response is returned as a Jtoken object, but you can declare it as a dynamic object and work with it as you would other dynamic objects in your script.
Error Arg List	A dynamic data object that holds information about any errors that occur. When an error occurs, the object holds the HTTP status code, status description, and a message. When there is no error, the object is empty. HTTP status codes and descriptions are only returned in the error and can be properly parsed as a valid response. This means that not all errors will include an HTTP response code.

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.