Correlation for DevWeb scripts

This topic describes the processes used to correlate dynamic data in your scripts.

In this topic:

About DevWeb correlation

Correlation refers to the process of locating, extracting, and replacing recorded dynamic values with values that are valid at replay. For general information about correlations in VuGen, see Correlation overview.

DevWeb handles correlation for dynamic values using two methods: rules-based scan and record-based scan. Both add correlations to the generated code using extractors and appliers. During code generation, when a correlation candidate is discovered, the appropriate extractor is added to the web request step. For details, see Extractors and appliers.

Rules scan	DevWeb includes a set of predefined, extendable rules for correlating dynamic values in standard environments. You can edit these rules and define new ones. You can also activate or disable the rules for your scripts. During code generation, if rules scan is enabled, then all activated rules are loaded from the correlation rule files.
Record scan	When the record scan is enabled, DevWeb automatically scans the server responses for correlations. The search is based on internal engine configuration settings.

You can also manually search for values to correlate in your script. For details see Search and correlate selection.

Back to top

Working with correlation rules

By default, the rules and record scans are disabled. For either or both correlation scans to occur, you must enable them in the recording options.

If the rules and the record scans are both enabled, the rules scan takes priority. So if both scans identify the same value, the engine uses the rules scan correlation.

To use correlation rules:

1. Open your DevWeb script.

2. Define or edit the correlation rules that you require for your testing environment in the Correlation rules node of the recording options. Select the rules that you want to include.

   Note: The recommended way to edit correlation rules is using the recording options UI. However, you can also manually edit the correlation rule files (*.yml). They are located (by default) in the <DevWeb root folder>\CorrelationRules\ folder.

3. Enable and configure the required correlation parameters in the Code Generation node of the recording options:

   Rules scan	Enable to run a rules scan during code generation.
   Record scan	Enable to run a record scan during code generation. Select the preferred extractor type for plain text, Boundary or Regular expression.
   Show correlation candidates during code generation	Enable to display a dialog box with all the scan results during script generation. When this option is selected, you can manually select and approve the discovered correlations before they are applied to the code.

4. Generate or regenerate the script.
5. If the Correlation Candidates dialog box is displayed during code generation, select the required correlation candidates and click Correlate. For details, see Managing correlation candidates.
6. When a correlation match is found, the relevant extractor is added to the web request step.

After script generation, you can view correlation scan information in the Output pane:

In the code, view the comments to see extractors added by the scans:

Back to top

Extractors and appliers

DevWeb engine correlations are based on extractors and appliers. When the correlations are applied during code generation, extractors are added based on the rules or record scans.

You can define extractors and appliers for your DevWeb scripts by creating your own customized correlation rules. For details, see Correlation rules node.

When scanning server responses, the DevWeb engine adds an extractor for each identified dynamic value. This enables the value to be extracted and saved in a parameter. Then, the script code is scanned for the value, and matches are replaced with a reference to the parameter.

• The extractors locate and extract the dynamic data in the responses. They can be based on boundary definitions or regular expressions, or can be used to query for object values inside JSON, XML, and HTML-formatted data. They also include converters for Base64, URL, and HTML encoding and decoding.

  For more information on extractors and their parameters, see the JavaScript SDK in the LoadRunner Developer and DevWeb Help Center.

• The appliers apply the extracted values, so that the saved parameter is used instead of the recorded value in subsequent requests to the server. You use the appliers to refine the way the extracted value is applied in the request.

  If no appliers are defined for a rule, a default Simple applier is used.

Back to top

Managing correlation candidates

When the Correlation Candidates dialog box is displayed during code generation, you can manage the correlations that are applied to your script.

The Correlation Candidates dialog box provides a list of the results from the rules or record scans. It is displayed when you record and generate/regenerate the script, if there are discovered correlation candidates.

For each correlation candidate you can view the method used to discover it—rule or record scan. You can also view the response text to be correlated, and the extractor name that will replace the text in the requests.

To manage correlation candidates:

Prerequisite: To display the Correlation Candidates dialog box, make sure Show correlation candidates during code generation is enabled in the recording options. For details, see Working with correlation rules.

1. In the Correlation Candidates dialog box, to change an extractor name, select the appropriate correlation candidate line and type in the new extractor name.

2. To exclude a correlation candidate from this script, and from all future correlation scans for all scripts, select the candidate line and click the Exclude candidate button. Then click Exclude in the displayed warning message.

   The correlation candidate is removed from the list.

   Tip: You can remove strings from the excluded list by editing the <DevWeb root folder>\resources\CorrelationEngine\excluded_strings.txt file.

3. To continue with code generation for the script, select the check boxes for the correlation candidates that you want to apply to the script, and click Correlate.

   To continue code generation without applying correlations to the script, click Ignore.

Back to top

Search and correlate selection

If your DevWeb script includes recording snapshots, you can manually select the text you want to correlate inside the script, and then use the Correlate Selection option to add extractors.

To correlate your selection:

1. In the VuGen editor, within a web request in your DevWeb script, select the text to correlate.

2. Select Correlate Selection from the right-click menu.

   Note: The Correlate Selection option is enabled only if the following are true:

   • The script includes recording snapshots.
   • The selected text is in the context of a web request.
   • The selected text is not in the first request.
   • The selected text contains at least 4 characters.

3. VuGen searches backwards to find the first occurrence of the value in the response snapshots, and displays the Verify extractor name dialog box, providing information for the correlation:

   Parameter	Description
   Selected value	The text selected as the correlation value.
   Web request	The first web request referencing the selected value.
   Extractor type	The type of extractor to be used. This is determined automatically by VuGen, by assessing the origin file type for the selected text. VuGen then applies an appropriate context-based extractor, for example, XML or JSON. The default (if the type cannot be determined) is boundary extractor.
   Extractor name	Enables you to define a name for the extractor. A default name is provided.

   Click Add Extractor.

4. The Replace correlated values message is displayed, telling you how many references to the selected value were found in the script . Click Yes to replace them all with the extractor.

5. The extractor type determined by VuGen (shown in the Verify extractor name dialog box) is added to the script in all relevant locations.

Back to top

Actionable snapshots

From the Record or Replay snapshot panes, you can generate extractors directly into the web request step in the script.

The following extractor options are available:

• Text check. Use to search for, and validate the existence of, specific text in the server response.
• Variable. Use to search and save a variable in the server response. The saved variable is then available for later reference.
• Correlate. Use to correlate a value, and add extractors for each instance of the value in the request and subsequent requests.
  

The snapshot actions are available for the response header and response body of the main web request (not for resources).

To add a Text Check extractor:

1. Open the snapshot for the relevant web request step, and highlight the text to use for the extractor.

2. Select Add Text Check from the right-click menu.

   

3. The Add Extractor dialog box opens. Type a name for the extractor in the Extractor name field.

4. Click OK. The extractor is added to the web request step, using the selected text.

   For example:

   

5. If required, change the failOn value for the extractor to true and edit the scope.

To add a Variable extractor:

1. Open the snapshot for the relevant web request step, and highlight the value.
2. Select Add Variable from the right-click menu.
3. The Add Extractor dialog box opens. Type a name for the extractor in the Extractor name field.

4. Click OK. VuGen adds the extractor to the web request step, using an appropriate context-based extractor for example, JSON or XPath. The original value is added in a comment.

5. Edit the extractor properties as required.

To correlate a value:

1. Open the snapshot for the relevant web request step, and highlight the value to correlate.
2. Select Correlate from the right-click menu.
3. The Add Extractor dialog box opens. Type a name for the extractor in the Extractor name field.

4. Click OK. A message is displayed, telling you how many references to the selected value were found in the script . Click Yes to replace them all with the extractor.

   The relevant extractor is added to all referenced web request steps. The replacement is tailored to the specific context in each case.

Back to top

See also:

• DevWeb snapshots
• DevWeb > Recording Options