Defining Requests for RA Web Service REST Agent Jobs

You can define requests from cURL commands or request sheets. Request sheet requests can have single or multiple parts. Select the Request Headers & Query Parameters object menu item and define HTTP headers and/or query parameters for RA Web Service REST Agent Jobs. HTTP headers and query parameters can be defined both as defaults for the Connection object, or in individual Jobs. You can edit the values of default Connection object headers in the Job definition, or delete them.

To define request(s) for an RA Web Service REST Agent Job, go to the Define Request section of the Request page of an RA Web Service REST Agent Job, pick whether the request will be entered from a:

  • cURL command: When this option is selected, the Define cURL command section is presented below the Define Request section. In it, you enter a cURL command in a text field.
  • Request sheet: When this option is selected, the Request Settings section is presented. In it, you select a resource from the Job's Connection object and select and define the method for the request.

Defining cURL Command Requests

To define cURL commands for the request, select the cURL command option from Define Request with in the Define Request area as shown below and enter a cURL command in the cURL command text box.

This field allows Automation Engine variables and the replacement values below.

  • {user}
    • User field for Connection objects with Basic, Digest, or NTLM authentication.
  • {password}
    • Password field for Connection objects with Basic, Digest, or NTLM authentication.
  • {client_key}
    • Client Key field for Connection objects with OAuth 1.0a or OAuth 2.0 authentication.
  • {client_secret}
    • Client Secret field for Connection objects with OAuth 1.0a or OAuth 2.0 authentication.
  • {authorization_token}
    • Authorization Token field for Connection objects with OAuth 1.0a or OAuth 2.0 authentication.
  • {token_secret}
    • Token Secret field for Connection objects with OAuth 1.0a authentication.
  • {access_key}
    • Access Key field for Connection objects with AWS Signed URL authentication.
  • {secret_access_key}
    • Secret Access Key field for Connection objects with AWS Signed URL authentication.
  • {verifier}
    • Verifier field for Connection objects with OAuth 1.0a authentication.

cURL is a computer software project providing a library and command-line tool for transferring data using various protocols.

To execute a cURL command, cURL must be available in the path of the RA Web Service REST Agent.

Because this option could be a security concern, it is turned off by default. cURL commands can only be entered when the Allow cURL Commands checkbox on the General tab under the Web Service tab of the Agent is checked. If you need to define cURL commands, consult your Automation Engine Administrator.

  • When this box is checked: The text box below the field becomes a required field where you enter cURL commands. These cURL commands are used instead of any request definition present in the Job definition.
  • When this box is unchecked (default): The text box below the field remains uneditable.

cURL commands are executed as a system command exactly as they are entered. You can use the replacement values described in the Defining Sheet Requests table below in the cURL command line.

This is useful for example in order to not display the user name and password on the command line.

https://api.twilio.com/2010-04-01/Accounts/{user}/SMS/Messages.xml -k -i -u {user}:{password}

Defining Sheet Requests

  • The request types of requests using PUT or POST method can be:
    • JSON
    • XML
    • Octet-stream
    • Form Data (application/x-www-form-urlencoded)
    • File (text or binary)
    • Plain text.

    • The request type can be a multi-part request, which is composed of one or more of the other types.

    For a request report the file is prefaced with restReq.

    If the type is JSON, XML, or text, it will have the suffix (json, xml, or txt). If it's form-data, it will be .txt and contain name-value pairs in the format <field>=<value>. Any unrecognized (user defined) type will default to the behavior for text.

    JSON and XML are pretty printed to the file and that file is registered with the Automation Engine.

    If the type is multi-part, each part is written to a file. The file name contains the name of the part. If there is no name for the part, it will be Part_<number>. Spaces in the part name are replaced with underscores.

    For example, assume a two part multi-part request. Part 1 is called JSON and part 2 is called My Form Data.

    The first file will be named <Agent_directory>/bin/task_reports/restReq_JSON_111.json, and will contain the following:

    {

    "name":"value"

    }

    The second file will be named <Agent_directory>/bin/task_reports/restReq_My_Form_Data_111.txt, and will contain the following:

    Ffield1=fvalue1

    Ffield2=fvalue2

    To add sheet requests:

    1. Select the Request sheet option from Define Request with in the Define Request area.
    2. Optionally add request headers and/or query parameters as described in Adding Request Parameters and Query Parameters below.
    3. Add request settings as described in Specifying Request Settings below.

    Using Encrypted Values in Request XML

    You can use encrypted values in your REST request. There are different ways how this can be done:

    1. Use a PromptSet with a text field in your RA Web Service REST Agent Job and ensure that the box Show as Password is checked for the text field. Use the variable name defined for the text field in your request XML for the encrypted value.
    2. Use the same PromptSet attached to a Script object which you can utilize then as a kind of generator for encrypted values. Simply start your script, enter the value you would like to encrypt in the PromptSet and open the activation report afterward. You will find a line such as:

      3. 2017-08-25 09:39:59 - U00020206 Variable '&PW#' was stored with value

      '--106DA50A126F227F15'.

      Copy the value starting with ‘--10' to the clipboard and paste it directly into your request XML. Alternatively assign the value to an object variable and use the variable in your request.

    Adding Request Parameters and Query Parameters

    RA Web Service REST Agent Job definitions include all HTTP headers and/or query parameters. Headers and query parameters can be defined both as defaults for the Connection object, or in individual Jobs. You can edit the values of default Connection object headers and/or query parameters in the Job definition, or delete them.

    To add a query parameter or request parameter to an RA Web Service REST Agent Connection object:

    1. In the appropriate section of the Request Headers & Query Parameters page of an RA Web Service REST Agent Job, click in the Header or Parameter column for the selected row and enter an HTTP header or query parameter name.
    2. Enter the value in the Value column.

      3. The value column allows Automation Engine variables and the replacement values below.

      Replacement value: Will be replaced by the value of the:
      {user} User field for Connection objects with Basic, Digest, or NTLM authentication.
      {password} Password field for Connection objects with Basic, Digest, or NTLM authentication.
      {client_key} Client Key field for Connection objects with OAuth 1.0a or OAuth 2.0 authentication.
      {client_secret} Client Secret field for Connection objects with OAuth 1.0a or OAuth 2.0 authentication.
      {authorization_token} Authorization Token field for Connection objects with OAuth 1.0a or OAuth 2.0 authentication.
      {token_secret} Token Secret field for Connection objects with OAuth 1.0a authentication.
      {access_key} Access Key field for Connection objects with AWS Signed URL authentication.
      {secret_access_key} Secret Access Key field for Connection objects with AWS Signed URL authentication.
      {verifier} Verifier field for Connection objects with OAuth 1.0a authentication.

    Working in the Query Parameters Table

    To: Do this:

    Add a row to the table

    Click Add Row.

    Edit a row in the table

    Click the cell in the table and edit its value.

    Delete one of more rows to the table

    Check the checkbox for the row(s) and click Remove.

    Delete all rows to the table

    Check the checkbox column header and click Remove.

    Cut a row and add it to the AWI clipboard

    Click Cut.

    Cut a row and add it to the AWI clipboard

    Click Copy.

    Paste a row to the bottom of the table

    		 Click Paste.

    Move a row up or down in the table

    Drag and drop the row, or select the row and use the Move down buttons.

    Move one or more rows up or down in the table

    Select the checkbox for the rows to move and use the Move down buttons.

    Viewing, Editing or Deleting Default Headers/Query Parameters From a Job's Connection Object

    Default headers/query parameters that are defined in a Job's Connection object are included in the Request Headers and/or Query Parameters tables in gray italics. They are read-only, unless the Request Headers, Use Job Headers only or Query Parameters, Use Job Parameters Only checkboxes are checked. If one of these checkboxes is checked, all headers or query parameters defined in the Connection object will remain in the table and their backgrounds switch to white like the headers defined for the Job and they will become editable or deletable.

    Specifying Request Settings

    1. Select or type in a resource in the Resource field.

      2. Resources in the drop down list are defined in the Connection object definition. For more information, see topic Defining Resources for RA Web Service REST Agent Connection Objects.

      This field allows Automation Engine variables and the replacement values in the table below.

      Replacement value: Will be replaced by the value of the:
      {user} User field for Connection objects with Basic, Digest, or NTLM authentication.
      {password} Password field for Connection objects with Basic, Digest, or NTLM authentication.
      {client_key} Client Key field for Connection objects with OAuth 1.0a or OAuth 2.0 authentication.
      {client_secret} Client Secret field for Connection objects with OAuth 1.0a or OAuth 2.0 authentication.
      {authorization_token} Authorization Token field for Connection objects with OAuth 1.0a or OAuth 2.0 authentication.
      {token_secret} Token Secret field for Connection objects with OAuth 1.0a authentication.
      {access_key} Access Key field for Connection objects with AWS Signed URL authentication.
      {secret_access_key} Secret Access Key field for Connection objects with AWS Signed URL authentication.
      {verifier} Verifier field for Connection objects with OAuth 1.0a authentication.
    2. Select a method in the Method field. Methods include:
      • GET
      • PUT
      • POST
      • DELETE
      • HEAD
      • OPTIONS

      3. If neither PUT or POST are selected in the Method field, the Multi-Part Request checkbox is grayed out.

      When specifying request settings and PUT or POST are selected in the Method field, you have the option to define a single request, or a multi-part request.

    3. To define a multi-part request, check the Multi-Part Request box.

      4. For information on multi-part requests, see the Adding Sections for the Parts of Multi-Part Requests section below.

    4. Respond to the fields described below in either:
      • The Request Data box, when the Multi-Part Request box is unchecked (default).
      • The tabs, when the Multi-Part Request box is checked.
      FieldDescription

      Media Type

      When the method in the Method field is PUT or POST, this field is active. Unless the type is application/x-www-form-urlencoded, you will get an Upload content via field where you will choose whether to select a file or directly enter text to define the request. If the type is application/x-www-form-urlencoded you will have the Form Parameters table.

      Upload content via

      Allows you to select either:

      • File: Uploads content from a file you specify in the File Path field.
      • Direct Input: Uploads content from you enter in the Direct Input box.

      File Path

      Allows you to select a file to define the request.

      You can browse to a file using the browse icon.

      Direct Input

      Allows you to enter text to define the request.

      Form Parameters

      		Allows you to add form parameters to the request when the type is application/x-www-form-urlencoded. For information on form parameters, see the Adding Form Parameters section below.

    Adding Sections for the Parts of Multi-Part Requests

    When the Multi-Part Request box is checked, you can add or remove multiple sections for request parts as shown below.

    You can: By clicking:
    Add a section for a part Add New Request Part
    Delete a section for a part Its trash icon

    The sequence of the parts in the request is strictly aligned with the definition here for processing.

    Adding Form Parameters

    If the media type is application/x-www-form-urlencoded,the request is mimicking a Web page that accepts field values and you will instead have a From Parameter table as described below.

    To add form parameters to a REST request:

    1. Click in the Name column for the selected row and enter a form parameter name.
    2. Enter the value in the Value column.