A dimension is automatically populated based on the data detected each hour for the dimension values that are configured to populate it. Depending on the traffic volume and the variation in the data, the maximum values per hour can be quickly filled with data that is not important for meaningful evaluation.

A logged value for a dimension can be in the whitelist or the blacklist, but not both.

You can use whitelists and blacklists to specify the values that are permitted or forbidden from populating the configured dimension, which allows you to restrict the possible data set to the most useful values.

If you map multiple detected values to a single recorded value, you must use a group list as your data source.

List types

• Whitelist: defines values that are permitted to populate the dimension.

  A fixed whitelist specifies the only values that are permitted. If the specified whitelist is configured to be fixed, then any value that is not on the whitelist is not allowed.

• Blacklist: defines values that are not permitted to populate the dimension.
• You can create lists of both types for a single dimension. If a dimension uses both a whitelist and a blacklist, the whitelist is evaluated first. If the dimension value is not in a non-fixed whitelist, it is evaluated against the blacklist.

Note: If there are significant changes to your web application, your dimension whitelists are likely to need rebuilding. Contact your web application development team for details on the changes.

Value limits for list dimensions

A whitelist or blacklist can contain up to 50,000 total values.

By default, Tealeaf limits the number of unique values that are recorded for a dimension per hour. Suppose you capture 110 unique values in a given hour and configured the dimension to capture 100 unique values per hour. The last 10 captured values are assigned the [Limit] value.

• Dimension values can be up to 255 characters. Longer dimension values are truncated at 255 characters.
• Dimension limits are enforced on an hourly basis per Processing Server.
• When a dimension limit is reached, an error is reported in the Event Log:

  
  Dimension ID = XXX has surpassed its hourly limit of YYY values
  

• For blacklist dimensions: The Max Values per Hour setting is enforced for values outside of the blacklist, which does not include the configured Default Value for the dimension.
• Fixed whitelist dimensions: No hourly limit is imposed on these dimensions, but any captured value must appear in the whitelist. Otherwise, the value is substituted by the specified default value.
• Non-fixed whitelist dimensions: The Max Values per Hour setting is enforced. It is discounted by the size of the whitelist. The number of permitted unique values is the following:

  
  MaxPerHour - <items in whitelist>
  

Under Advanced Options in the Add or Edit Dimension dialog, you can configure the maximum values that are captured per hour and the default value for the dimension. Increasing the number of dimensional values that are captured per hour requires extra storage space in the database.

Specify whitelists and blacklists

Through the Edit List window, you can manually create whitelists and blacklists or populate them with values retrieved from reference value log files.

Note: After you specify the values in your whitelist and save the changes to the server, you cannot change the source value for existing items.

After you specify your whitelist and blacklist for a dimension, you should export the list to a file. In case you need to make changes later, you can use the exported file as one of your data sources for population of the list in the new dimension.

Note: After you create a whitelist of values, newly added values are not automatically included in Top Mover calculations. Any imported or manually added values must be specifically selected for inclusion in Top Mover calculations.

If you selected Order whitelist as shown in the Dimension properties, you can use the up and down arrows next to the Value column to reorder the display of whitelist values. To move an item to the top or bottom of the list, press SHIFT and then click the appropriate arrow.

Note: You can remove only values if the list was not yet saved to the server.

You can specify a whitelist or blacklist in one of the following ways:

• A whitelist or blacklist can be imported from a text file to the server.
• Add values to your list from a database log of captured values.

  Note: Logging of dimension values must be enabled.

• A whitelist or blacklist can be manually created.

Manually editing values

1. In the List editor, click Add.
2. Enter the value and display value in the available textboxes. If no display value is specified, then the value is used for display in reports.

   Avoid adding entries that match your dimension constants, such as others and limit, which may cause confusion.

3. For values that you want to be included in deviations calculations, click the check box in the Track Top Movers column.

   Note: Tracking dimensional values for deviation calculations can affect data storage. You should track only the dimensional values that are most meaningful to the accurate computation of the standard deviation of the dimension.

4. Click Add again.
5. Repeat the above steps until you specify all values.
6. To save a draft, click Done.

   Note: Saving a draft saves the item to the session cache on the server. Changes must be committed before they are applied to the incoming session data.

Import a list

You can import text files to augment your whitelists, blacklists, or group lists.

• For group lists, the ListName and DisplayName are the same value. Both values are required in the imported file.
• To import a list, click Import File....

  Note: No data validation is performed during import. Duplicate values are not allowed. If a value appears in a dimension whitelist, it cannot be added to the blacklist until you delete the value from the whitelist.

Values should be in the following tab-separated format:

DetectedValue1    DisplayValue1
DetectedValue2    DisplayValue2
DetectedValue3    DisplayValue3

For whitelists and blacklists, the second column is optional. For group lists, both columns are used and should contain the same value.

1. In the Dimension edit window, click Edit Whitelist or Edit Blacklist.
2. In the Edit List window, click Import File.
3. In the file uploader, browse to select the file to upload and click Open.
4. To upload the selected file, click Import.

The values are added to the dimension list accordingly.

Note: To include the items in deviation calculations, you must manually edit the list.