Defining Responses for RA Web Service REST Agent Jobs

On the Response page, you can define response headers to extract values from the headers returned rather than from the response content. You can also define HTTP REST headers and single or multiple part responses

Adding Response Headers

You can define a response header to extract a value from the headers returned rather than from the response content. 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 parameter to an RA Web Service REST Agent Connection object:

  1. Add a row to the table.
  2. In the Response Headers section of the Response Headers page of an RA Web Service REST Agent Job, click in the Header column for the selected row and enter the HTTP header name.
  3. Select an output type in the Output Type column. Available options are:
    • Save as Variable: A variable with the name you specify in the Output Name field is saved to the database.

      • For Automation Engine v9/10, if the size is:

      • Less than 1024 bytes, the value is included in the database.
      • Greater than 1024 bytes, the value is written to <Agent>/bin/variableFileDirectory.

      An Automation Engine scripting language variable's name is limited to 32 alphanumeric characters, including the special characters "$", "_", "@", "§" and "#". German Umlauts are not allowed. The first character must not be a number.

    • 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 will be registered with the Automation Engine and viewable from the UserInterface. 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 the user interface.
  4. Enter the output name value in the Output Name column.

Adding Responses

About REST Response Reports

  • 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. Which is composed of one or more of the other types.
  • If the type is multi-part, each part will be written to a file. The file name will contain 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.

To define response(s) for an RA Web Service REST Agent Job:

  1. In the Parsing Configuration section of the Response page of an RA Web Service REST Agent Job, do one of the following:
    2. To define: Do this:
    A single part request Keep Multi-Part Response unchecked and follow the remaining steps for the fields in the Parse a Single Response section.
    A multi-part request Check Multi-Part Response and follow the remaining steps for the fields for each part of the response as described in the Adding Sections for the Parts of Multi-Part Responses section.
  2. Optionally enter a file name in the Custom Report File Name field.

    3. If the response is a file, it is registered as a custom report with the Automation Engine. JSON and XML are pretty printed to the file, and that file is registered with the Automation Engine. Otherwise the response is written to a file named <Agent_directory>/bin/task_reports/restResp_<runId>.<suffix> with the suffix json, xml or txt.

  3. Add parsings to the response(s) as described in the Adding Parsings to Responses.

Adding Sections for the Parts of Multi-Part Responses

When the Multi-Part Response box is checked, you can add or remove multiple sections for response parts.

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

Adding Parsings to Responses

To add parsings to a response of a REST request, click Add Row and enter values in the columns described below for the table below for the row.

  • Parsing Type

    • The parsing type. By default, the options are:

    • XPath
    • XQuery
    • JSONPath
    • JSON to XML and XQuery

    Groovy can be selected as parsing type when the Allow Groovy parsings of response data box on the General tab under the Web Service tab of the Agent is checked. The Allow Groovy parsings of response data box is unchecked by default for security purposes. If you need to define Groovy parsings, consult your Automation Engine Administrator to enable in on the Agent.

  • Output Type

    • The output type. Available options are:

    • Save as Variable: A variable with the name you specify in the Output Name field is saved to the database.

      • For Automation Engine v9/10, if the size is:

      • Less than 1024 bytes, the value is included in the database.
      • Greater than 1024 bytes, the value is written to <Agent>/bin/variableFileDirectory.

      An Automation Engine scripting language variable's name is limited to 32 alphanumeric characters, including the special characters "$", "_", "@", "§" and "#". German Umlauts are not allowed. The first character must not be a number.

    • 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 will be registered with the Automation Engine and viewable from the UserInterface. 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 the user interface.

  • Output Name

    • The output name which will be used as the variable or file name; depending on your selection in the Output Type column.

  • Expression

    • The expression for the parsing. To open the a dialog with a larger field for entering the expression, click the cell editor icon.

  • Use Array

    • Uses an array when you select Save as Variable in the Output Type column. When this checkbox is checked, 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 Save as Variable is not selected, the whole result is returned as one variable.

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

    • An array can include up to 99999 elements.

Note: If the job is part of a workflow, the variables are published automatically to the parent object as well as to the successor job.

Testing Parsings

To test a parsing: 

  1. Click the Test button for a parsing.

    2. This opens the Response Expression Tester dialog.

  2. Do one of the following:
    • To enter a response to test, enter a response 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 override the parsing type from the parsing table.
  4. Optionally override the expression from the parsing table.
  5. Click Evaluate.

    6. The result is displayed in the Result text area.

    Important !

    Always test your JSONPath expressions against the Event Engine before putting them in production. JSONPath Expressions created in external tools might not work as expected because there is no common standard for the JSONPath query syntax.