Creating a reference or field reference

When you designate a test value as a reference or designate a set of test data as a field reference, you can use the data elsewhere in the test.

About this task

A reference, which is typically located in response data, points to a specific value that you want to use in a subsequent test location, typically a request. You can substitute a request value with a reference. This substitution is called data correlation. You can also use a reference as input to an IF-THEN condition in a test or as input to custom Java code that your test calls.

A field reference points to an entire block of test data. For example, an entire HTTP response can be designated as a field reference. You can use a field reference as input to custom Java code that your test calls.


  1. In the Test Navigator, browse to the test, and double-click it. The test opens.
  2. Locate the value or set of data to designate as a reference or field reference.
    Different protocols support different references. For HTTP tests, you can create references and field references in these fields:
    • A response header value, the Value column of a Response Headers table
    • Response content, the Content field
    For HTTP responses, you can create field references in these fields:
    • The Status field
    • The Reason field
  3. Create the reference:
    1. For response contents, highlight the value. For response header contents, click the row in the Response Headers table, and then click Modify.
    2. Right-click, and then click Create Reference.

      The value is highlighted in light blue to indicate that it is an unused reference. When you use it, the highlight changes to dark blue. The reference is given a name automatically. To see the name of the reference, right-click the value, and then select Properties. To edit the regular expression that is used to locate the reference, click the Toggle regular expression assistant push button on the Properties window. The regular expression assistant displays the response content matched by the regular expression and the groups captured by the regular expression. To ensure that the details about the reference is always logged, select a reference and click Properties, and then click the Always log details check box. To create a reference that will be used by the HTTP secondary request, you must select All occurrences. You can also match the reference within a given range of all the occurrences.


      If an HTTP response is JSON, you can create a reference of that JSON value and use the JSON expression. You can select the JSON value, right-click the value, and then click Create Reference to create a reference. The Regular Expression field in the Reference dialog box displays the JSON expression instead of the regular expression.

      You can also verify the same from the reference Properties dialog box after the reference is created. From the test editor, select and right-click the JSON value that is highlighted in dark blue color, and then select Properties to open the Reference dialog box. You can see that the Regular Expression field displays the JSON expression.


    A reference that is created to be used by the HTTP secondary request cannot be used by custom code or other data sources.

    You can always log the details of Substituters, Data Sources, and Requests.

  4. To create a field reference, do not highlight the value. Instead, right-click the value, and then click Create Field Reference.
    1. Field references are not automatically given names. To name a field reference, right-click the field reference, and then select Properties. Type a name in the Name field, and then click OK.
    The entire field is highlighted in yellow to indicate that it is a field reference.