REST Web Service package

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

Working with REST Web Service actions

Provide the following information to send a REST request and receive a response. Not all parameters are required for all methods.
  • Enter the URI: A unique address for an API resource.
  • Proxy configuration: To set the proxy, select the System or Custom tab from Proxy configuration.
    Option Description
    System

    System proxy is the proxy configured on the bot runner machine where the bot is running.

    If this option is selected, the Bot Agent uses the system proxy.
    Custom

    This option allows you to configure custom proxy settings within the actions of REST Web Service. For example, if a REST API is required to be routed through a different proxy other than the system proxy, you can select the Custom option and provide proxy details within the REST actions.

    Provide the following details:

    • Host: The host name or IP address of the proxy
    • Port: The port number of the proxy
    • Username (Optional): The username used for the proxy authentication
    • Password (Optional): The password used for the proxy authentication
      Note: If the proxy to be configured is authenticated proxy, then you must provide authentication credentials in the Username and Password fields.
    For Host, Port, Username, and Password fields, choose from Credential, Variable, or Insecure string tab :
    • Credential: Use a value available in the credential vault.
    • Variable: Use a variable that stores a credential value in a user-defined variable.
    • Insecure string: Manually specify the value that you want to use.
  • Authentication Mode: There are three supported authentication modes:
    • No Authentication: Use this option to access the endpoints that does not require authentication to access their servers.
    • Control Room user token: The REST Web Service actions uses the token generated while you logged in the Control Room to access the endpoints.
    • Basic: Basic is the simplest way to authenticate users. When you select this option, you will enter the username and password. This technique uses a header called Authorization, with a base64 encoded representation of the username and password entered.
    • Logged-in AD User: Active Directory (AD) users that are authorized to access the related API are authenticated through AD. No credentials are required in the request.
    • Windows NT LAN Manager (NTLM) Authentication (AD User): A challenge/response authentication method that allows clients to provide their user name and password as encrypted credentials or plain text. We recommend that you use credentials that are stored in the Automation Anywhere Credential Vault.
    • OAuth2 - Control Room managed: When you integrate OAuth with the Control Room, you can centrally manage and securely store tokens that are used to authenticate with third-party providers. You must configure the web service and make note of the authentication details (such as such as client ID, client secret, authorization URL, and so on) to use the OAuth connection in the Control Room. For more details, see Configure OAuth connections in Control Room

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

  • Header: Not all methods require a header. Headers represent the metadata associated with the request.
  • Content type: When a header contains a content type, it defines the content negotiation between the client and the server. REST Web Service actions support the following content types:
    • application/x-www-form-urlencoded: Encode the parameters in the URL.
    • JSON (application/json): Enter a JSON request body.
    • XML (application/xml): Enter an XML request body.
    • Text (text/plain)
    • XML (text/xml)
    • HTML (text/html)
    • multipart/form-data: Send binary data, in most cases for uploading files to the server.
    • 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
  • Add substitution: Allows you to enter variables in the REST request body. 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.
  • Wait for action to complete: You can set a time-out value when you send a REST request and receive a response. When performing actions such as POST, PUT, DELETE, PATCH, and GET, in the Wait for action to complete field, you can specify the wait time (in milliseconds). By default, the wait time is 60000 milliseconds.
  • 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 Service 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 Service action output.
    4. Assign the value of each key to $prompt-assignment$.
    5. Insert a Log 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 Service 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 Using the Get method.

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 Using the Post method.

Put method Updates or replaces a resource based on parameters passed in the URI or body. See Using the Put method.

Proxy support

If your device is configured with a proxy, all outbound requests from this package are routed through the proxy server. See Connect Bot Agent to a device with a proxy.