REST Request Variables

The system includes a dynamic variable mechanism that automatically inserts variables into REST client requests initiated by server-side scripts.

To use this mechanism, you need to create a script that triggers a REST request with the substituted variable values.

You can either reference an existing REST request by specifying a link or create a new request within the script.

The REST Request Variables (sys_rest_request_variable) table stores records of encrypted (AES-256) and non-encrypted variables that can be dynamically added to REST requests. Encrypted variables used for storing keys and secrets are decrypted when added to a request.

To pass the variables in the URL, body, and header of the requests, use the {param} format.

To use the variables, do the following:

1. Create a REST request. You can also use the SimpleRestRequest methods in step 2.

   Specify the following:

   • The REST request name
   • The endpoint URL that the request is created for
   • Access Type
   • Authorization type
   • Basic authorization profile if needed for the integration with the service
   • REST request headers
   • REST request methods. You can also specify the request method parameters.

2. Execute the server-side script with the REST request.

   • A link to a preconfigured REST request is passed to the script, or the necessary methods of the SimpleRestRequest object are overridden within it.
   • At the end of the script, the execute() method is called.
   • Variable values are inserted into the request, with decryption applied beforehand if this option was enabled in their forms.
   • The request is sent to the host with the decrypted variable values.

3. Configure the execution of the server-side script with the business rules.

caution

• When passing a parameter name to a script, it is converted to lowercase. Use unique, case-insensitive names when creating a record.

You can use Latin letters, [0..9] digits, space and the underscore symbol ( _ ).

• When passing a value to a header, it is transformed according to the following rules:

  1. The header name is converted to lowercase.
  2. Spaces are replaced with hyphens.
  3. The first letter of the name and each letter following a hyphen are converted to uppercase.

  Example: incident caller → Incident-Caller

REST Request Variables form fields

Field	Mandatory	Description
Name	Y	Specify the variable name. It must be unique and case-insensitive.
Value	N	Specify the variable value. The length must not exceed 256 bits. This value is passed to the REST requests if the Encrypted checkbox is cleared.
Encrypted value	N	Specify the value that will be encrypted with the AES-256 algorithm after saving the record. This value is passed to the REST requests if the Encrypted checkbox is selected.
Encrypted	N	Select the checkbox to pass the encrypted value.

caution

The system passes the password encrypted value if both Value and Encrypted Value are filled.

Create request variable

---

To create a new REST request variable, do the following:

1. Open the REST Request Variables table by the ({your instance URL}/list/sys_rest_request_variable) address.
2. Click Create and fill in the fields.
3. Click Save or Save and exit to apply the changes.

Verify functionality

For testing, it is recommended to use the following services:

• postman-echo.com/post for POST requests.
• postman-echo.com/get for GET requests.

For more details on the request types, see the Scripted REST API article.

1. Create two variables following the instruction above and name them as follows:

   1. test1 – non-encrypted variable.
   2. test2 – encrypted variable.

2. Navigate to System Settings → Server Scripts.

3. Create a request record with the following body:

Example of request variables in use

const scriptJSON = {
    'script': 'ss.info(new SimpleDateTime().getValue()); ss.info("{test}");'
}


const request = sws.restRequestV1();
request.setRequestUrl('https://postman-echo.com/post?bot1860462740:{test2}/sendMessage');
request.setQueryParameter('chat_id', '{test1}');
request.setQueryParameter('text', 'telegram {test2}');

request.setRequestMethod('POST');

request.setRequestBody(JSON.stringify(scriptJSON));

request.setRequestHeader('Test-header', 'a-{test2}-b-{test1}');
const response = request.execute();

ss.info(response.getBody());