Correlation Rules

Correlation Rules automates the process of:

• Creating post processors,
• Replacing dynamic values with variables in requests.

A Correlation Rule is based on a Post processor of any kind:

• Regexp Post Processor,
• JMESPath Post Processor,
• JSONPath Post Processor,
• XPath Post Processor,
• CSS/JQuery Post Processor.

And Injection Rules that define when the replacement should be done.

The result of successfully applying correlation rules will be:

• New Post processors created,
• Corresponding values replaced by variables.

Which is why correlation rules can be seen as a search and replace for post processors.

These rules are common to a project, it is recommended to create them when working on your first virtual user. That way you can save time by applying them to all other virtual users created in the same project.

Warning

Recorded Requests/Responses are mandatory to apply correlation rules. To use them you must import a fiddler or firefox HAR file.

Correlation rules list

The correlation rules page uses a layout with the list on the left and edition on the right. The list features all the usual possibilities as described in the dedicated section about lists.

Create new rule

Convert to Correlation Rule

The most common method consists of creating a post processor first and using the contextual menu in the action tree, convert it to a correlation rule:

This process removes the Post processor to transform it into a correlation rule. If the correlation rule cannot apply you will lose this Post processor and it will have to be created again:

This is why it is recommended to convert to correlation rules before using the Post processor's variable name in your requests, otherwise we will not be able to search/replace since it has already been done.

Import a Correlation Rules Framework

Use either the menu or the right panel (when no correlation rule is currently being edited) to import a Framework:

Frameworks are groups of rules we have created for some technologies. If you want to add your custom rules on top of it, you can use one of the other methods to create a rule.

Copy/Paste between projects

To import or export the correlation rules you can also use the copy/paste button. Click copy rules:

Then simply navigate to another project and click Paste rules:

Tip

The copy/paste works across projects but also different workspaces.

Edit Correlation Rule

Post processor

The first section of the correlation rules contains information required for its Post processor creation:

You can update it directly from here but it is much simpler to work on the Post processor directly and then convert it.

Injection Rules

For each correlation rule, you can configure where to inject the extracted values:

Column name	Description
Replace	Part of value to replace only what is matched by the extraction rule or Whole value to replace the whole content
In	Where to replace: in POST bodies, query parameters, HTTP Headers, etc
Encoding	Whether to use the default automatic encoding, or force a particular encoding function around the replaced value. If left by default we will try to determine the best encoding but some HAR files might have been decoded when recording (Fiddler does that for URL encoding) leading to inconsistencies.
with name	The name of the POST Parameter, Query Parameters or Header whose value to replace (On available if the In selected is POST parameter values, query parameter values or header values)

Apply Correlation Rules

To apply Correlation Rules to the current VU, simply click on the Apply All rules button and select your virtual user:

In case you want to apply the rules to another script, make sure to select it in the list as well. By default it's the one you were editing last.

Warning

The modifications made to the VU cannot be reversed. So either apply them to a copy of your VU or try them on a fresh import that can be easily re-imported.

All correlation rules are applied at once on the Virtual User. The correlation rule algorithm will work as follows:

1. Search for values matching the Post Processor Extractor from each correlation rule,
2. Search for these potential values in all requests,
3. Extract and replace the value automatically if it is used in at least a request,
4. Create or re-use extractor depending if value changes or not later in the VU.

For this reason, if some rules have already been applied they will not apply a second time. Similarly if you've already replaced a value with a parameter, the correlation rule will not find it and will not be able to apply.

Warning

If the correlation rules take too long, the process may be killed after a timeout. In which case they may not all have time to apply. It is recommended to try to apply them in smaller groups when this happens. Typically by copy pasting some rules away in another project.