REST Web Services package
- Zuletzt aktualisiert2025/07/15
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.
- 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 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.
-
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“.
-
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:
In the above request body, you can replace the variables enclosed within double braces by clicking Add substitution and adding the required values.{ "name":"{{name}}", "email":"{{email}}", "status":"Active" }
- 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.
- 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:
- Insert a Loop action after the REST Web Services action.
- Select the For each key in the dictionary iterator.
- In the Dictionary variable field, select the variable that holds the REST Web Services action output.
- Assign the value of each key to
$prompt-assignment$
. - Insert a Log text to file action.
- Provide the file path to a text file to hold the list of header names.
- Insert
$prompt-assignment$
in the Enter text to log field. - Select the Overwrite existing file option.
- Click Save.
When you run the bot, it prints the header names from the API resource to the selected file.
Passing values securely
- 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:
|
Patch method | Modifies the resource that is identified by the URI. |
Post method | Creates a new resource in the URI.
|
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.