Defining REST Agent Jobs: Requests

On the Request page of the Job definition you specify the data (request) that you send to the target REST Web Service, namely, how the request will be defined (cURL or request sheet), the headers and query parameters, the resource and the method.

This page includes the following:

Using cURL commands is basically the same as coding the request on your REST API client. Using request sheets is more user-friendly. You do not have to remember the structure and syntax of the commands. You populate the parameters in the sheet and the Agent takes care of the rest. If you define the Job using a request sheet, consider the following:

• Request sheets can have single or multiple parts.

• In addition to establishing the connection to the target REST Web Service, REST Connection objects have an extra role. They can contain global parameters that will be then available for selection when creating REST Jobs. If this is the case with the Connection objects used with the Job, the HTTP Request Headers, the Query Parameters and the Request Settings sections on the Request page of the Job definition are already pre-populated. You can choose to use them or you can define new values.

PUT, POST and PATCH requests allow multi-part requests. Multipart requests combine one or more data sets into the body of a single request, separated by boundaries. A boundary is a unique string used to distinguish between these different data sets known as parts. Each part has its own section in the payload with internal HTTP headers.

Example:

A two part multi-part request. Part 1 is called JSON and part 2 is called My Form Data. The name of the first file is <Agent_directory>/bin/task_reports/restReq_JSON_111.json, and contains the following:

{

"name":"value"

}

The name of the second file is <Agent_directory>/bin/task_reports/restReq_My_Form_Data_111.txt, and contains the following:

Ffield1=fvalue1

Ffield2=fvalue2

JSON, XML and Text Request Types

If the type is JSON, XML, or text, it will have the suffix (json, xml, or txt). If it is form-data, it will be .txt and contain name-value pairs with the following 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.

Request Reports

The names of Request reports have the following prefix: restReq.

You can use encrypted values in your REST request. To do so, you have the following options:

1. Use a PromptSet with a text field in your REST Job and ensure that Show as Password is selected 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.

   1. Start your script.

   2. Enter the value you would like to encrypt in the PromptSet.

   3. Open the activation report afterward. You will find a line such as:

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

      '--106DA50A126F227F15'.

   4. 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.

If you have selected Define with cURL command in Define Request, the Define cURL Command section is displayed. cURL is a computer software project that provides 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 REST Agent.

To Define REST Requests through cURL Commands

1. On the Request page of the REST Job object definition, select Request with cUrl command in the Define Request section.

2. The Define cURL Command section is displayed. Enter the cURL command request there.

   You can use Automation Engine variables, as well as the following variables that retrieve values from your Connection definitions under the Authentication Method (see Configuring the Authentication Methods for the REST Agent):

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

If you have selected Request with Request sheet in the Define Request section, the actual request sheet is displayed on this page. It consists of the following sections: HTTP Request headers, Query Parameters, Request Settings and Define Single Part Request or Request Part : "Part <number>"

To Define REST Requests through a Request Sheet

1. On the Request page of the REST Job object definition, select Request with Request sheet in the Define Request section.

2. If necessary, define the HTTP Request Headers and Query Parameters.

   In addition to establishing the connection to the target REST service, REST Connection objects have an extra role. They can contain global parameters that will be then available for selection when creating REST Jobs. If this is the case with the Connection object assigned to the Job on its Web Service definition page, the HTTP Request Headers, the Query Parameters and the Request Settings sections are already pre-populated with those global parameters. You can choose to use them, modify them or discard them and define new parameters.

   To Add Headers or Query Parameters

   1. In the corresponding table 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. These columns allow both Automation Engine and the following variables:

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

   To Modify Headers or Query Parameters

   1. In the corresponding table, select the header or parameter.

   2. Change the Header/Parameter and/or the Value.

3. If the headers and query parameters are pre-populated with the Connection object global values and you want to ignore them, select Use Job Request Headers only / Use Job Query Parameters only. With these options selected, if you add Job-specific headers/query parameters, the global ones are ignored and only the Job-specific ones are used.

4. In the Request Settings section, specify the actions you want the Job to perform and the resources on which it should perform the actions. Do the following:

   1. Select a Resource.

      The resources that REST Jobs will be able to address are predefined in the Connection objects that those Jobs use to connect to the target Web Service. They are available for selection here. For more information, see Defining Resources for REST Agent Connection Objects.

   The Resource field allows both Automation Engine variables and the following variables:

    

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

   2. Select the Method. The options are:

      • GET

      • PUT

      • POST

      • PATCH

      • DELETE

      • HEAD

      • OPTIONS

      • TRACE

      With GET, DELETE, HEAD, OPTIONS and TRACE, multi-part requests are not possible. With PUT, POST and PATCH, you have the option to define a single request, or a multi-part request.

   3. With PUT, POST and PATCH requests, if you want to define a multi-part request, select Use Multi-part requests. As a result, the Add New Request Part is displayed. Click it to add as many sections as parts you want to define.

      1. Provide a meaningful Name to the request part.

      2. Specify the Media Type. The following options are available:

         • JSON

         • XML

         • Octet-stream

         • Form Data (application/x-www-form-urlencoded)

         • Text/plain

         • Text/xml

         If you select application/x-www-form-urlencoded, the request is mimicking a Web page that accepts field values. The From Parameter table is displayed.

         If you select any of the other options, in Upload content via select one of the following:

         • File to upload content from a file that you specify in File.

         • Direct Input to upload the content that you enter in the Direct Input editor.

      Repeat this for each part.

5. Save the Job.