Creating a reference using data correlation rules

You can create a data correlation rule that creates a reference from a regular expression when the rule is applied to test data.


  1. Open a data correlation rule set in the rules editor. A new rule set contains one empty rule pass.
  2. Click Insert, and then select Create a reference. An empty Create a reference rule is inserted in the rule pass.
  3. Under Details, supply information for all fields that are marked with asterisks and shaded in red. For Reference field, click the down arrow to select the field in which to create the reference. Use the push buttons at the top of the window to select a protocol, and then select a field. For example, to create a reference in the content field of an HTTP response, click the down arrow, and then click HTTP > Content. To create references in multiple fields, click the Add field push button to add another Reference field.
  4. In Regular expression, type an expression to use to locate the reference. If only a part of the regular expression is required for a reference, enclose that part in parentheses.
    1. Open the test, and locate the response to create the reference in.
    2. Copy the text from the response to the clipboard.
    3. In the rules editor, click the Toggle regular expression assistant push button to open the regular expression assistant.
    4. Paste the text from the clipboard to the Test regular expression page of the regular expression assistant window. If the Test regular expression page is empty, the contents of the clipboard is automatically pasted in.
    5. Click the Captured group tab in the regular expression assistant. The overall group is displayed, and the captured groups are displayed. If no groups are displayed, edit the regular expression accordingly.
    To create more than one reference using the same regular expression, enclose each part in parentheses. For example, two references can be created from this regular expression: name=(\S+)\svalue=(.+?).
  5. In Reference names, provide names for the references. The names that you specify are available to child rules. To use the references as arguments in child rules, enclose the reference name in percent signs. For example, if you specify a reference name of name, you can use %name% as an argument in a child rule.
  6. Optional: If an attribute contains multiple matches for the regular expression, in Occurrence, type or select the occurrence to use to create the reference.
  7. Optional: Under Create reference only if used, select true to create a reference only if a substitution site uses the reference. Select false to create the reference regardless of whether a corresponding substitution site is found.
  8. Optional: Under Overlapping site action, select the action to take when a new reference overlaps with existing references.
    Option Description
    Always remove existing If the new reference overlaps with other references, the other references are removed.
    Keep existing If the new reference overlaps with other references, the other references are not removed.
    Keep existing only if used If the new reference overlaps with other references, the other references are removed only if the references are unused.
  9. Optional: Under Create reference even if overlapping, select true to create a reference even if the new reference overlaps with existing references.
  10. Optional: In Log level, select the level of error data to be written to the error log. With logs, you can see which rules worked and which did not. When you are debugging data correlation rules, use the Action log level. If the Action log level does not provide enough data for troubleshooting, use the Detail log level. The Detail log level products a significantly higher number of log entries. Typically, when you are sure that the data correlation rules that you have written work correctly, use the None or Summary log levels to reduce memory and disk-space consumption and unrequired entries in the error log.
    Option Description
    None Nothing is logged.
    Warning A message is logged when there are potential problems that are detected when the rule is applied.
    Summary One message is logged for the rule, no matter how many times the rule is applied.
    Important A message is logged every time the rule is applied in a manner that is not typical. This is the default log level.
    Action A message is logged every time the rule is applied.
    Detail A detailed message is logged every time the rule is applied.
  11. Optional: In Label, type a label for the rule. If you do not type a label name, the rule is given a default name. The default name is the base name with the regular expression appended.
  12. Optional: In Description, describe the rule. Descriptions can be useful if you share rule set files with other testers.