The purpose of the Lookup Table Extension is to look for a certain value in one Variable (formerly Data Source) and replace it with another value or set the new value in another Variable, depending on what you specify in the Lookup Table. You can use this to change numeric information like product IDs into a readable identifier, such as a product description.

Configuring the Extension

lookup table dialog box.png

  1. Title: Enter a descriptive name to identify the Extension instance.
  2. Scope: This determines when to load the extension and which Tags can access its data. You may choose the default 'All-Tags' or set it to a specific Tag.
  3. Execution: This drop-down only appears for the All-Tags scope and requires utag.js version 4.38 or higher (older versions may cause Extension to run more than once). It allows you to control when this Extension can run in the utag lifecycle.


    • Before any Load Rules are evaluated
    • After any Load Rules are evaluated (default)
    • After all the Tags have loaded
  4. Lookup Value in : Select the Variable that contains the value you want to look up. Think of it as a reference Variable.
  5. Destination : Select the target Variable that will hold the 'Output' value you specify. There is a plus icon next to the drop-down list that, when clicked, allows you to create a Variable on the fly.
  6. Variable Type - Specify whether the value you're looking up is a string or an array. If you select array, any output will go into the same array index as its corresponding lookup match.
  7. Match Type - When doing the lookup, this determines what you are matching the lookup against
    • Exact - If the value is exactly what you specify in the Lookup Match field.
    • Contains - If the value contains something you specify in the Lookup Match field.
    • RegExp - Run a regular expression you specify against something in the Lookup Value field. Any special characters that you need to escape with a backslash "\" should instead be double-escaped with two backslashes "\\". The ignore case "i" flag will be applied automatically.
  8. Lookup Match - Enter the precise value you're looking for in the Lookup Variable. Do not enter quotes in here.
  9. Output - Enter the value you wish to place/overwrite in the Destination when the lookup match IS found. Do not enter quotes in here.
  10. Note (optional) - Add notes pertinent to each Lookup match and output value. The note is not passed to the destination Variable.
  11. Default Output - If the lookup match is NOT found, the Destination is replaced by this default value instead of the original Output.
    NOTE: If you don't wish to apply any default value at all, you may completely disable the field by checking the 'Disable Default' box.

How Default Output works

The Default Output takes effect only when the lookup match has failed and the disable box is unchecked. This table explains how the Destination changes in relation to the Variables and the default value .

  Default Output is populated Default Output is blank
Lookup and Destination are unique Destination value is replaced by the default value Destination value is left blank
Lookup and Destination are identical Both Lookup and Destination values are replaced by the default value Lookup and Destination values are NOT replaced.

Import from CSV

You can enter large numbers of Lookups with the 'Import from CSV' feature. Enter the CSV (comma-separated value) formatted text in the order of Lookup value, Output value and corresponding notes. The lookup value is entered into the Lookup Match field and the corresponding output value is entered into the Destination field.

One example of a Lookup-Output value pair is product IDs linked to product names. A product might have an ID of "123" and a name of "LED TV". Another product might have and ID of "789" and a name of "Plasma TV". In both these situations, the value of the Lookup-Output pair is the product's ID, while the value of the Lookup-Output pair is the English-readable name of the product.

To add Lookup-Output values in bulk:

  1. Click the 'Import from CSV' button.
  2. Enter in the CSV-formatted data in the order of Lookup value, Output value, notes.
  3. You may either add to or replace the existing Lookup Table.
    1. Click 'Append' to add to the existing table.
    2. Click 'Replace' to replace the existing table.


Export to CSV

This feature exports the lookup values into a .CSV file. Enter the values for Lookup Match, Output, and Notes in their respective fields and click the 'Export to CSV' button. At least one instance of lookup match, output, and note value is required to perform a successful export. If all the three lookup fields are blank, no data will be exported.
NOTE: This feature is compatible with most modern browsers, with the exception of IE. If you are using Firefox or Chrome, the values are directly exported into a 'lookup.csv' file. In a Safari browser, the CSV-formatted values are exported into a new browser tab instead of a .CSV file.


Implementing the Lookup Table

You have a list of product IDs in your system. However, you find that looking at product ID numbers gives you a headache. When you look at the ID number, you don't immediately know if it corresponds to a Blue-ray player or a bag of kitty litter. The Lookup Table Extension allows you to match a readable value, such as a product's name, to that product's ID number.

  1. Navigate to the Extensions tab and click the 'Add Extension' button
  2. Locate the Lookup Table Extension under the Standard Data tab of the Extensions marketplace. Click the '+Add' button to add it.
  3. Enter a title for the Extension.
  4. From the Lookup Value in drop-down list, select the Variable whose value we will look for, in this case the 'product_id'.
  5. From the Destination drop-down list, select the Variable to which you will place the new value, in this case 'product_name'.
  6. In the Default Output field, enter "none" indicate when the product_id value doesn't contain any information.
  7. In this scenario, the product_id Variable only contains one ID per product, so we will select String for Variable Type.
  8. For Match Type, we will select 'Exact' since we supposedly know the exact product IDs.
  9. Now we're going to add the lookups to match product IDs to product names.
    1. In the Lookup Match field, enter the first product's ID, which is "123".
    2. In the Output field, enter the product's name, which is "Sony LED TV".
    3. Add relevant notes in the Note field.
    4. To add another Lookup, click the icon next to the existing Lookup entry.

Add more Lookups, matching the product ID "456" to "Sony Blue-ray Player" and "789" to "Panasonic Plasma TV". Add relevant notes for the lookups.


Now, when the Lookup Table Extension runs, it will look for the product IDs in the product-Id variable and populate the product_name variable with the corresponding product name.