Creating a substitution with data correlation rules

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

Procedure

  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 substitution.
    An empty Create a substitution 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 Field, click the down arrow to select the field for which to create a substitution. Use the push buttons at the top of the window to select a protocol, and then select a field. To create a substitution in the data field of an HTTP request, click the down arrow, and then select HTTP > Data.
  4. In Regular expression, type a regular expression to use to locate the substitution. If only a part of the regular expression is required for a substitution, enclose that part in parentheses.
    1. Open the test, and locate the request to create the substitution in.
    2. Copy the text from the request 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 substitution site using the same regular expression, enclose each part in parentheses. For example, two substitution sites can be created from this regular expression: (.+?)=(.*?).
    To use values that were created in a parent Create a reference rule as arguments in the regular expression, enclose the reference names in percent signs. For example, if a parent rule created a name reference and a value reference, you could use them in this regular expression: \:\{%name%,%value%\}. When the rule is run, %name% and %value% are substituted with the values extracted by the parent rule, and then the resulting regular expression is evaluated. Two substitutions are created, each linked to the corresponding reference.
  5. In Substitution names, type names for the substitutions.
  6. Under Decode the field, select true to decode the specified attribute before searching for a matching reference. Select false to search for a matching reference without decoding the attribute. The type of encoding depends on the selected protocol and attribute. For example, HTTP data can be URL-encoded.
  7. Under Create substitution only if used, select true to create a substitution only when a matching data source is found. Select false to create the substitution regardless of whether a matching data source is found.
  8. Under Conflict action, select the action to take when a new substitution overlaps with existing substitutions.
    OptionDescription
    Always replace existing If the new substitution overlaps with other substitutions, the other substitutions are removed.
    Replace existing if dataset candidate If the new substitution overlaps with other substitutions, and all the other substitutions are dataset candidates, other substitutions are removed. If at least one current substitution site that overlaps with the new substitution site is associated with a reference, then no current substitution is changed, and the new substitution is not created.
    Replace existing if enclosed in the new site If the new substitution overlaps with other substitutions that are all completely enclosed in the new substitution, other substitutions are removed. If at least one current substitution overlaps with the new substitution without being completely enclosed by the new substitution, then no current substitution is changed, and the new substitution is not created.
    Replace existing if dataset candidate or enclosed If the new substitution overlaps with other substitutions, and each of the other substitutions is either a dataset candidate or is completely enclosed in the new substitutions, other substitutions are removed. If at least one current substitution overlaps with the new substitution without being completely enclosed by the new substitution, or if at least one current substitution site that overlaps with the new substitution site is actually associated with a reference, then no current substitution is changed, and the new substitution is not created.
    Keep existing If the new substitution overlaps with other substitutions, the other substitutions are not removed. The new substitution is not created.
  9. 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 produces 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.
    OptionDescription
    None Nothing is logged.
    Warning A message is logged when potential problems 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 that 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.
  10. 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.
  11. In Description, describe the rule. Descriptions can be useful if you share rule set files with other testers.