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.

Before you begin

Roles required: activity_admin, activity_creator

About this task

Procedure

  1. Navigate to 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
    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.
    Parsing rules form
    Table 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.
    Note: 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.