REST Web Services package

Use the actions in the REST Web Services package as methods (DELETE, GET, PATCH, POST, or PUT) to send requests to and receive responses from an API.

Settings

The following settings are available for the REST Web Services actions. Configure appropriate settings to send a REST request and receive a response. Each method requires specific parameters.

Note: When you create automations on the macOS platform and use actions such as (DELETE, GET, PATCH, POST, or PUT) the following authentication modes are not supported:
  • NTLM Authentication (AD User)
  • Logged-in AD User
URI
Enter the URI for the API resource. Select one of the following options and configure the settings accordingly:
  • Enter the URI: Enter the URI directly or select the URI saved as a string variable.
  • Select credential as URI: Use this option to select a URI that is saved as a credential in the Credential Vault. Use Credential > Choose to select the credential directly. You can also use the Variable option to select a credential that is mapped to a credential variable. This option allows you to hide the URIs that contain sensitive information such as authorization codes or API keys.
Proxy configuration
Configure the proxy settings for the REST Web Services actions. Select one of the following options and configure the settings accordingly:
  • System: Select this option to enable the Bot Agent to use the system proxy. The system proxy is the proxy that you configure on the bot runner machine where the automation runs.
  • Custom: Select this option to configure custom proxy settings for the automation. Configure the following settings:
    • Host: The host name or IP address of the proxy server.
    • Port: The port number of the proxy server.
    • Username (Optional): The username for authenticating the proxy server.
    • Password (Optional): The password for authenticating the proxy server.
    Note: You must configure the Username and Password for any authenticated proxy server.
    You can use one of the Credential, Variable, or Insecure string options to configure the proxy settings.
    • Credential: To select a value available in the Credential Vault.
    • Variable: To select the credential variable that is mapped to a value.
    • Insecure string: To enter the value manually or select a value that is mapped to a predefined string variable..
Authentication mode
Configure the authentication settings for the REST Web Services actions. Select one of the following options and configure the settings accordingly:
  • No Authentication: Select this option to access the endpoints that do not require authentication to access their servers.
  • Control Room user token: Select this option to use the token generated when you log into the Control Room.
  • Basic: Select this option to enter the Username and Password to authenticate the REST Web Services API calls. This option adds a header named Authorization that contains a base64 encoded string representation of the Username and Password to the API call.
  • Logged-in AD User: Select this option to choose the Active Directory (AD) based authentication. The AD users that are authorized to access the related API are authenticated using AD. No credentials are required in the request.
  • Windows NT LAN Manager (NTLM) Authentication (AD User): Select this option to choose a challenge-response NTLM authentication. Configure the following settings:
    • Domain: Enter the domain in which the API call must be authenticated. You can also select a string variable that is mapped to the domain or the host.
    • Username (Optional): The username for authenticating the API call.
    • Password (Optional): The password for authenticating the API call.
    You can use one of the Credential, Variable, or Insecure string options to configure the username and password. We recommend that you either use the Credential option to choose a credential from the Credential Vault or use a credential variable.
  • OAuth2 - Control Room managed: Select this option to choose a Control Room managed OAuth connection as the authentication option. For more details, see Konfigurieren Sie OAuth-Verbindungen im Control Room.

    The following video shows how to use OAuth connection in REST Web Services:

Header
Add custom headers to include additional metadata in the API requests. Not all methods require a header. You can add headers like Authorization, Accept-Charset, Content-Type, Cache-Control, User-Agent, etc.

Click Add header, and follow the prompts in Custom header modal to add the required headers. You can select a credential stored in the Credential Vault, or credential variable, or enter the header directly as an insecure string.

Content type
The Content type header defines the media type of the content in the request body. The REST Web Services actions support the following content types:
  • application/x-www-form-urlencoded: Encodes the parameters in a URL query string format.
  • JSON (application/json): Enter a JSON format request body.
  • XML (application/xml): Enter an XML format request body.
  • Text (text/plain): Enter a text type request body in plain text format.
  • XML (text/xml): Enter a text type request body in XML format.
  • HTML (text/html): Enter a text type request body in HTML format.
  • multipart/form-data: Allows you to include both text and files in the request body. This content type supports all the file formats that the API supports. You can use this content type for sending multiple parts in a single request, typically including text data (like form fields) and potentially a file upload. This content type also supports file streaming.
    A file stream can be read after assigning it to a file type variable. For instance, you can read a file stream assigned to a variable in a OneDrive location. For more information, see action „Datei zuweisen“.
    Rest Web Services FileStream
  • Binary: Use Binary to send raw files such as images, videos, and audio files. You can upload the files using one of the following option:
    • Variable: Assign a file variable to upload a file from desktop or within the Control Room. You can also use this option to stream files from a storage location.
    • Control Room file: Upload a file that is available in the Control Room storage.
    • Desktop file: Upload a file directly from your desktop.
  • Custom
    Custom: Add custom content that does not fall under the standard content type. For example, when you are migrating from v.11.x to Automation 360, the following value does not fall under any of the standard content types: application/vnd.whispir.message-v1+json

For application/x-www-form-urlencoded and multipart/form-data, click Add parameter and follow the prompts in the Parameter model to add the required header parameters.

For other content-types, you can use Enter the parameters option or Select credential as parameters option to add the parameters. The Select credential as parameters option allows you to add sensitive data as request headers.

Add substitution
The Add substitution option allows you to enter variables in the REST request body. This option is available for JSON (application/json), XML (application/xml), Text (text/plain), XML (text/xml), HTML (text/html), and Custom content-type headers.
A variable is a symbolic representation of data, and it enables you to access a value without having to enter it manually wherever you need it. For example, consider the following REST body request:
{
   "name":"{{name}}",
   "email":"{{email}}",
   "status":"Active"
}
In the above request body, you can replace the variables enclosed within double braces by clicking Add substitution and adding the required values.
Advanced options
Capture failure response: Select the check box to capture the failure response except for the Success/Ok response. The failure response details are captured in the response body.
Allow insecure connection when using https: Select the check box to allow insecure connection when using https.
Accept Cookies: Select the check box to automatically capture session cookies from server responses.
  • Capture: When enabled, the feature captures session cookies included in server responses.
  • Secure Storage: Captured cookies are encrypted within process memory, ensuring they are never permanently stored and are inaccessible outside your automation session.
  • Reuse: Cookies are automatically included in subsequent REST calls, eliminating manual cookie handling and improving automation reliability.
  • Multiple Cookie Handling: The feature seamlessly handles multiple cookies returned by the server, ensuring all necessary authentication credentials are included.
  • Destruction: Captured cookies are automatically destroyed when the automation session ends or the bot finishes execution, ensuring data security and privacy.
Note: The captured cookies are specific to the domain they originate from and will not be automatically used for subsequent REST calls made to different domains. This means cookies captured from domainA.com will not be utilized for requests to domainB.com.
Download file: This option is available in Get method and Get file stream actions. The URI must return or download a file.

The Get method action lets you download the file to a specific location. Select this check box and enter the desired folder path and file name with extension. Ensure you use the correct file extension. For example: C:/Users/Downloads/image01.jpg

The Get file stream action lets you assign a file variable to the downloadable file. This allows you to stream the file directly from the source URI in subsequent actions within the session, eliminating the need to download and upload the file.

Tip: Mark the Overwrite file if already exists option to overwrite a file of the same name that already exists in the folder you are saving the file to.

The system displays an error message when one of the following scenarios occurs:

  • Invalid URI: If the provided URI is incorrect.
  • File not found: If the API response is empty because the file does not exist at the specified location.
  • Insufficient permissions: If you do not have write permissions for the download location.
  • File extension mismatch: If the file extension does not match the expected type.
Wait for action to complete
You can set a time-out value when you send a REST request and receive a response. When you perform actions such as POST, PUT, DELETE, PATCH, and GET, specify the wait time (in milliseconds) in the Wait for action to complete field. By default, the wait time is 60000 milliseconds
SSL/TLS configuration
Use this option to upload a certificate file with or without a password to provide additional authentication during the REST API calls.

The SSL/TLS configuration uses mutual TLS (mTLS) protocol to encrypt, authenticate, and secure communications between the API URI and client. mTLS requires both entities to authenticate each other by exchanging certificates. Data transmission occurs only if both entities authenticate the exchanged certificates successfully.

The REST Web Services support .p12 type certificates for Windows machines and .pfx format for non-Windows machines.

  • Keystore file path (optional): Upload the certificate file using the Variable, Control Room file, or Desktop file option.
  • Keystore password (optional): If the certificate is password protected, you can authenticate the certificate password using the Credential, Variable, or Insecure string option. For more information about securely storing passwords in Credential locker, see Anmeldedaten und lockers im Credential Vault.
Output variable
The response output is captured in a dictionary variable. A dictionary variable is a key-value pair. Use the response header name as key to return the header value, or "Body" as the key to return the response body.
Note: The response key with its value is available in the dictionary variable to display the response status of the REST API.
To obtain a list of the header names for the API resource, perform these steps:
  1. Insert a Loop action after the REST Web Services action.
  2. Select the For each key in the dictionary iterator.
  3. In the Dictionary variable field, select the variable that holds the REST Web Services action output.
  4. Assign the value of each key to $prompt-assignment$.
  5. Insert a Log text to file action.
  6. Provide the file path to a text file to hold the list of header names.
  7. Insert $prompt-assignment$ in the Enter text to log field.
  8. Select the Overwrite existing file option.
  9. Click Save.

    When you run the bot, it prints the header names from the API resource to the selected file.

Passing values securely

You can securely pass values from the Credential Vault to the web service by specifying the locker, credential, and attribute in the following supported action fields:
  • URI
  • Custom headers
  • Body: For the application/x-www-form-urlencoded content type, click Add parameter to select the value from the Credential Vault.

    For all other content types, select the Select credential as parameters option and click Pick.

Actions in the REST Web Services package

Action Description
Delete method Removes the resource that is identified by the URI.
Get method Retrieves information identified by parameters included in the URI. There is no Content type for the GET method because all the parameters are passed as part of the URI.

Limitations and characteristics of the GET method include the following:

  • URI length is limited to 2048 characters.
  • All parameters are passed in the URI.
  • The GET method exposes data that is in the URI, making it less secure than the POST method.
  • GET does not change any data, making it safe for all users regardless of authorization.

See Verwendung der GET-Methode.
Patch method Modifies the resource that is identified by the URI.
Post method Creates a new resource in the URI.
  • Parameters are passed in request body.
  • There is no limit on length for a request body.

See Verwendung der POST-Methode.
Put method Updates or replaces a resource based on parameters passed in the URI or body. See Verwendung der PUT-Methode.

Proxy-Support

Wenn Ihr Gerät mit einem Proxy konfiguriert ist, werden alle ausgehenden Anforderungen von diesem package über den Proxyserver geleitet. Einzelheiten finden Sie unter Den Bot Agent mit einem Gerät mit Proxy verbinden.