Adding Dataset Mapper

You can include a Dataset Mapper in a compound test or a schedule to assign the dataset values to the variables that are defined in multiple tests. In previous releases, to apply the dataset values to multiple tests, you had to associate the dataset to each test. The Dataset Mapper is able to map the dataset columns with the variables.

Before you begin

You must have created at least one dataset. See Creating a dataset in a workspace.

About this task

For the Dataset Mapper to fetch the test variables, in the Variable Details section of the Test editor, you must set the Visible In field for the variable to All tests for this user. You can also fetch the variables from the custom code calls.

If the compound test or the schedule includes a Dataset Mapper that retrieves values from one dataset and a test in the compound test or schedule is also associated with another dataset, the run uses both the datasets.
Note: When you run the schedule or compound test with a Dataset Mapper, by default the test picks up the dataset values from the first row. For the test to pick up all of the dataset values, you must put the test in a loop.


  1. In the Schedule or Compound test editor, click Add > Dataset Mapper.
  2. In the Select Dataset dialog box, select a dataset to use for the tests and click OK. To change the dataset after it is associated, in Dataset Mapper Details, click Browse and select another dataset.
  3. Select the Open mode for the dataset. This mode determines the view that virtual users have of the dataset. This option is useful when you do a parallel test run.
    Option Description
    Shared (per test execution) (default)

    When you choose the Shared (per test execution) option, the virtual users running in the test share the dataset values in sequential order.

    For example, if your dataset has 10 rows, the dataset values are taken from row 1, row 2, row 3, and so on when you select this option.


    Virtual users draw from a private view of the dataset, with dataset rows apportioned to each user in sequential order.

    This option ensures that each virtual user gets the same data from the dataset in the same order. However, because each user starts with the first row of the dataset and accesses the rows in order, different virtual users will use the same row. The next row of the dataset is used only if you add the test that is using the dataset in a loop with more than one iteration.

    Shared (for all test executions)

    When you choose the Shared (for all test executions) option, the virtual users running in multiple tests share the dataset values from the current row.

    For example, if your dataset has 10 rows and when you set the current row as row 5, the dataset values are taken from row 5 instead of row 1 when you select this option. If you had set the current row as row 1 and used the dataset values until row 5, the dataset values are retrieved from row 6 when you run the test next time.

  4. Select the Access mode for the dataset:
    • Sequential: The rows in the dataset are accessed in the order in which they are physically stored in the dataset file, beginning with the first row and ending with the last.
    • Random: The rows in the dataset are accessed in any order, and any given row can be accessed multiple times or not at all. Each row has an equal chance of being selected each time.
    • Shuffled: Before each dataset access, the order of the rows is changed, and a different sequence results. Rows are accessed randomly but all rows must be selected once before a row is selected again.
  5. Select whether the test will reuse data when it reaches the end of the dataset.

    By default, when a test reaches the end of a dataset or dataset segment, it reuses the data from the beginning. To force a test to stop at the end of a dataset or segment, clear the check box Wrap when the last row is reached. Forcing a stop might be useful if, for example, a dataset contains 15 records, you run a test with 20 virtual users, and you do not want the last five users to reuse information. Although the test is marked as "Fail" because of the forced stop, the performance data in the test is still valid. However, if it does not matter to your application if data is reused, the default of wrapping is more convenient. With wrapping, you need not ensure that your dataset is large enough when you change the workload by adding more users or increasing the iteration count in a loop.

  6. Select whether the test will make the data in the dataset record permanent for each virtual user.

    By default, one row is retrieved from the dataset for each execution of a test, and the data in the dataset row is available to the test only for the duration of the test. Select Fetch only once per user to specify that every access of the dataset from any test being run by a particular virtual user will always return the same row.

    To illustrate how these options affect the rows that are returned, assume that a test contains a loop which accesses a dataset. The loop has two iterations. The following table shows the row that is accessed in each iteration:
    Dataset option Iteration 1 Iteration 2
    Sequential and Private row 1 row 2
    Shared and Shuffled row x row y
    Fetch only once per user row x row x
  7. In the Columns mapping table, the Column is automatically filled with the column names from the dataset.
  8. To use the variable names from the test, click the cell and click the Ellipsis button Ellipsis button and select the variable. By default, the variable names are also created with the same names as the dataset columns.
  9. If the dataset that you selected in step 2 was generated by HCL OneTest™ Data, you can choose to update the data by clicking Update dataset or update the data automatically for every run by selecting the Update dataset during deployment check box.
  10. To fetch all the dataset values, put the Dataset Mapper in a loop. Select the Dadtapool Mapper in the schedule and click Insert > Loop.
  11. Save the changes.