Create a parsing rule

Populate output variables defined in a custom activity with payload data returned from an inputs test on an external host or endpoint.

Avant de commencer

Roles required: activity_admin, activity_creator

Pourquoi et quand exécuter cette tâche

Procédure

1. Navigate to All > Workflow > Workflow Editor.
2. From the Custom tab in the palette, open a custom activity.
3. In the Activity Designer form, advance to the Output stage.
4. Drag an output variable from the data structure builder into the Variable name field in the Parsing rules builder.

   Figure 1. Mapping variables to parsing rules

   

   The parsing rules form appears for the selected variable. By default, the parsing type is set to Direct, which populates the variable with all the data from the selected payload, without parsing the contents. Each template has a specific default parsing source.

5. Complete the form using the fields in the table.
   In this example, the parsing type selected is XML, which allows you to select specific parameters from the payload to parse.

   

   Tableau 1. Parsing rules fields

   Field	Description
   Parsing source	Source of the data returned from the target host or endpoint. Each template opens to a specific, default payload. Available choices depend on the execution template selected for the activity. You can also use local variables as a parsing source if a parsing rule has previously been defined for them. For a list of the available payloads for each template, see Activity designer parsing sources.
   Expression	Expression used to extract specific data from the selected parsing source. This expression is created from clickable data in the sample payload and appears in the format selected in the Parsing type field. When testing, the expression can return multiple results. Discern which choice gives reliable or predictable results before choosing your expression. Remarque : The system cannot generate clickable RegEx expressions from sample data. You must write all regular expressions manually.
   Variable name	Revised variable name as it is used in the final output expression. The system adds the activityOutput or activityLocal prefix to the variable you specify.
   Parsing type	The language to use for querying the target host's payload. The selections are: Direct: Maps to the entire content of the payload selected in the Parsing source field, without any parsing. This is the default parsing type. XML: XPath query used for selecting nodes from an XML payload. JSON: JSONPath query for selecting parts of a JSON payload. RegEx: Parsing method that uses a regular expression to extract data from a payload. The RegEx parsing type does not support multi-line parsing and is not case sensitive.
   Short description	Brief description of this parsing rule.
   Sample payload data	Sample data from the source containing the data requested. This field is not available for Direct parsing types. After you click Parse sample data, the data in this field cannot be edited, but becomes clickable for the purpose of creating expressions. Click Edit sample data to make the field editable again.
   Parsing results	Displays the data returned from the source by the selected expression. This field is not available for Direct parsing types.

6. To retest the inputs, click Get sample payload from test.
   This action reopens the test form, allowing you to substitute different test values and create a different payload.
7. Click Save to have the parsing rules overwrite the previous payload with the one you just created.
8. To create an expression for the parsing rule, click the specific parameter you want to see in the sample payload.
   The value for that parameter appears in the Parsing result field, and the system creates the appropriate expression in the Expression field.
9. Click Submit to save the parsing rule for that variable.

Activity designer parsing sources

This table lists the parsing sources available with each execution template.

Tableau 2. Parsing sources

Template	Source
SOAP Web Service	executionResult.body (Default) executionResult.status_code executionResult.header executionResult.error
JDBC	executionResult.output (Default) executionResult.errorMessages executionResult.probeCompletedEccId executionResult.totalRows
JavaScript Probe	executionResult.payload (Default) executionResult.output executionResult.eccSysId executionResult.errorMessages
Powershell	executionResult.output (Default) executionResult.tags executionResult.hresult executionResult.eccSysId executionResult.errorMessages
REST Web Service	executionResult.body (Default) executionResult.status_code executionResult.header executionResult.error
SFTP	executionResult.output (Default) executionResult.eccSysId executionResult.errorMessages executionResult.tags
Probe	executionResult.output (Default) executionResult.payload executionResult.eccSysId
SSH	executionResult.output (Default) executionResult.eccSysId executionResult.errorMessages executionResult.tags
JMS	executionResult.status executionResult.standardHeaders executionResult.customHeaders executionResult.messagePayload executionResult.eccSysId executionResult.errorMessages

Activity designer parsing rule example

In this example, the parsing rule is configured to populate the activityOutput.ipv4 variable with the value for the IP address from a domain server, using PowerShell.

Avant de commencer

Role required: activity_creator, activity_admin

Pourquoi et quand exécuter cette tâche

To generate the sample data, the administrator must actually run the command on the host and then paste the data returned into the Sample payload data field when creating the parsing rule. The administrator can then create an expression that returns IP addresses from that sample in two formats: ipv4 and ipv6. In this example, the system produces two expressions to use for the parsing rule.

Procédure

1. Navigate to All > Workflow > Workflow Editor and open the activity that runs on the host.
2. Click the Inputs tab, and note the Command.

   Figure 2. Parsing rule PowerShell inputs command

   

3. In a PowerShell console, run the Command on the host to extract the XML sample that contains the values you need.
4. Copy the data that is returned to the clipboard.
5. In the activity designer, click the Outputs tab and paste the returned data into the Sample payload data field.

   In this example, the data includes IP addresses in two different formats and the domain name.

6. Select the parsing type for the source.
   In the following example, you would select XML.

   

7. Click Parse sample data.

   The system displays the XML in the proper format, and it becomes clickable. In this view, the system can translate clicked data from the sample into an expression.

   

8. To create the expression, click the elements in the data sample you want to map to the variable.

   Based on the sample data you clicked, the system creates two expressions.

   

9. Select an expression from the list.

   The desired result is the IP address that has a type attribute of ipv4. The system populates the Expression field with this choice.

   

10. Click Test expression.

    The system parses the payload using the selected expression and returns the requested data in the Parsing result field.

    

11. Click Submit.

    The view returns to the Outputs tab of the activity designer. The new parsing rule is listed, and a blank row is available for another rule.