Defining REST Agent Jobs: Responses

When you execute a REST Request Job, the target REST Web service delivers a structured response that can have multiple formats depending on how you configure the Response Job. The exact structure of the response depends on the resource and URI of the request. The response includes all available resources from any point within the API. On the Response page of the REST Job object definition you can parse the received data so that they can be further processed in subsequent Jobs in a Workflow.

Defining the Response in a REST Job consist of the following activities:

• Specify whether the data is taken from the response headers and configure parsing parameters for them.

• Define the parsing configuration (both single-part and multi-part)

• Specify the Retry settings

When you define a REST Agent Job, you can define whether the response values should be extracted from the returned header or from the response content on the Response page. You can also define HTTP REST headers and single or multiple part responses.

Your definition in the Response Headers section determines that the response is taken from the response header sent by the target REST Web Service. For example, you may have a call that returns a token value in a response header that you want to extract to use in subsequent Jobs.

To Add a Response Header

1. Add a row to the table.

2. In Header enter the HTTP header name.

3. Select an Output Type column. The options are:

   • Save as Variable

     A variable with the name you specify in the Output Name field is saved to the database.

   The name of script variables is limited to 32 alphanumeric characters. Special characters ("$", "_", "@", "§" and "#") are allowed. German Umlauts are not allowed. The first character must not be a number.

   Script variables set in Web Service Job responses are resolvable in the requests of the following Jobs in the same Workflow. However, they are not propagated to the Workflow.

   • Write to Job Report

     Writes the resulting value to the Job's report log based on the name you specified in the Output Name field.

   • Save as Report

     Saves the resulting value to a report in the <Agent>/bin/task_reports directory based on the name you specified in the Output Name field. The file is registered with the Automation Engine and you can view it in AWI. When this option is used, the Web Service Agent expects a parameter value of just a stand-alone file name. If you enter a file name with fully qualified path, the Job will get an error like the following:

   java.io.FileNotFoundException: task_reports/u01/users/qa4/v9/RA_WS_Alpha/test3.txt (No such file or directory)

   • Write to File

     Writes the resulting value to a file in the Agent's file system. You can enter either a stand-alone file name to write to the <Agent>/bin/task_reports directory on the Agent's file system or a file name with fully qualified path to a different location on Agent's file system. The file will not be registered with the Automation Engine and is not viewable from AWI.

4. Enter the output name value in the Output Name column.

If you do not want to take the response from the response header but from the response content, you specify the necessary parameters in the Parsing Configuration and Parse a Single Part/Part <number>of Response sections.

Your definition in the Parse a Single Part/Part <number>of Response section determines that the response is taken from the response content. The responses are delivered as reports. Consider the following

• If the response is a file, it is registered as custom report with the Automation Engine. JSON and XML are pretty printed to the file and that file is registered with the Automation Engine.
• If the response is not a file, the response is written to the file <Agent_directory>/bin/task_reports/restResp_<runId>.<suffix>, where suffix is json, xml or txt.
• The response type can also be a multi-part response composed of one or more of the other types.
• 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, the name is Part_<number>. Spaces in the part name are replaced with underscores.

To Add a Response

1. Add a row to the table.

2. In Parsing Type, select one of the following:

   • JSONPath

   • XPath

   • XQuery

   • JSON to XML and XQuery

   • Groovy

     This option is only available if the definition of the REST Agent allows it (the Allow Groovy parsings of response data option is selected in the Settings section). For more information, see Defining the REST Agent. This option is NOT selected by default for security reasons. If you need to define Groovy parsings, ask your Automation Engine Administrator to enable in on the Agent.

3. Select an Output Type column. The options are:

   • Save as Variable

     A variable with the name you specify in the Output Name field is saved to the database.

   The name of script variables is limited to 32 alphanumeric characters. Special characters ("$", "_", "@", "§" and "#") are allowed. German Umlauts are not allowed. The first character must not be a number.

   Script variables set in Web Service Job responses are resolvable in the requests of the following Jobs in the same Workflow. However, they are not propagated to the Workflow.

   • Write to Job Report

     Writes the resulting value to the Job's report log based on the name you specified in the Output Name field.

   • Save as Report

     Saves the resulting value to a report in the <Agent>/bin/task_reports directory based on the name you specified in the Output Name field. The file is registered with the Automation Engine and you can view it in AWI. When this option is used, the Web Service Agent expects a parameter value of just a stand-alone file name. If you enter a file name with fully qualified path, the Job will get an error like the following:

   java.io.FileNotFoundException: task_reports/u01/users/qa4/v9/RA_WS_Alpha/test3.txt (No such file or directory)

   • Write to File

     Writes the resulting value to a file in the Agent's file system. You can enter either a stand-alone file name to write to the <Agent>/bin/task_reports directory on the Agent's file system or a file name with fully qualified path to a different location on Agent's file system. The file will not be registered with the Automation Engine and is not viewable from AWI.

4. Enter the Output Name that will be used as the variable or file name, depending on your selection in the Output Type column.

5. Specify the Expression for the parsing.

6. The Use Array option is available if the Output Type is Save as Variable. If you select this option, the results are saved to an Automation Engine array variable, where each value can be referenced numerically, for example &VAR[1], &VAR[2], etc. If you do not select it, the whole result is returned as one variable.

   Notes:

   • Array names can be up to 24 alphanumeric characters long.

   • An array can include up to 99999 elements.

Important! If the Job is part of a Workflow, the variables are published automatically to the parent object as well as to the successor Job.

The Test button lets you check your parsing configuration.

1. Click the Test button to open the Response Expression Tester dialog.

2. Do one of the following:

• Enter the response that you want to test in the text area at the top of the dialog.

• To replace the input response with the response of the last execution, click Replace.

3. Optionally, select a Parsing Type that is different from the one you defined in the parsing table.

4. Optionally, select an Expression that is different from the one you defined in the parsing table.

5. Click Evaluate. The result is displayed in the Result text area.

The Retry Settings section allows you to configure a looping mechanism by which the Job keeps executing the request until the response delivers the expected value/status. The REST call only ends when this value/status is true. The runID stays the same all the while. If you activate and configure this option, when the Job executes, it remains in progress in the Process Monitoring perspective until the maximum number of retries or the expected value/status is reached. The Job report contains the details of the execution of each retry.

You can cancel a REST Job where you have defined the retry settings in the same way as you cancel any other Job. If you do so, be aware that it can take up to 10 seconds to update the status of a canceled REST Job (for example, from Active to Canceled) and display it in the Process Monitoring perspective accordingly.

1. Select Enable Retry if you want to constantly poll the target REST Service.

2. In Retry Count specify the maximum number of calls (retries) that you allow.

3. In Retry Interval specify the period of time in minutes that you want the Job to wait between calls (retries).

4. In Stop Retrying if specify when the Job should stop polling the Rest Service:

   • Select HTTP response status is OK if you want the Job to stop polling as soon as REST call returns 200 (OK). Any other values are irrelevant.

   • Select HTTP response status is OK and Output Name value if you want the Job to keep polling until BOTH the REST call returns 200 AND the value of the Output Name variable configured in the previous Parse Response section meets the criteria you specify here:

     • The comparison options available after selecting this checkbox include specifying an Output Name, a comparison operator, and a value for comparison. The Output Name field refers to a variable that you've previously defined when parsing the response. You then use a comparison operator to compare the value of that Output Name with a specified value in the far-right section, determining when the job should stop retrying.

       The available comparison options are:

       • Equals

       • Equals one of

       • Not equals

       • Greater than

       • Greater than or equal to

       • Less than

       • Less than or equal to

       • Contains

       • Does not contain

       • Starts with

       • Ends with

       • Is empty

       • Is not empty

     For example, you can check if the value defined as the Output Name matches any value in a list such as [100, 200, 300, 400]. If a match is found based on the selected comparison, the REST job will stop retrying.

5. Note: You can use the GET_ATT and PUT_ATT script functions to get and set the Job retry options. For information about the Automation Engine scripting language, see Scripting and the Automation Engine Scripting Language.