Overview
You can use Lookup transformers to convert identity attributes from a source system into appropriate values for target systems based on CSV reference tables. This is particularly useful when mapping values between systems that use different naming conventions, codes, or formats for the same conceptual data.
For example, you might need to transform a "Location" attribute from Workday (which might be stored as location codes like "MN001") into corresponding values for country, country code, or city names in a target system.
Use Table Lookup Transformers when:
You need to map source attribute values to different values in target systems
You have standardized reference data that must be consistent across applications
You need to extract different pieces of information from a single attribute value
You have complex mapping requirements that built-in transformers cannot support
Examples
Geographic Information:
Transform location codes to country, region, city, or timezone information
Map office codes to physical addresses or facility types
Organizational Mapping:
Convert department codes to department names or business units
Map cost centers to budget codes or accounting categories
System-Specific Configurations:
Transform job titles to role designations in target systems
Convert skill codes to certification requirements or training needs
How It Works
The Table Lookup Transformer references CSV-based mappings between source and destination values. When synchronizing user attributes, Veza:
Takes the source attribute value
Looks up this value in the specified lookup table
Returns the corresponding value from the designated return column
Applies this value to the target attribute
Lookup Table Structure
Lookup tables are CSV files with columns that map values from a source of identity to destination values. Each row represents a mapping entry. The first row must contain the column headers.
For example, a location mapping table might look like:
Creating and Managing Lookup Tables
Creating a Lookup Table
To create a new lookup table:
Navigate to the Lookup Tables tab within your policy configuration
Click Edit mode to enable policy changes
Click Add New to create a new lookup table
Provide a Name and optional Description for the lookup table
Drag a CSV file or click Browse to upload your reference data
Review the automatically detected column names
Click Save to store the lookup table
Managing Lookup Tables
From the Lookup Tables tab, you can:
Edit table descriptions or upload a new CSV
Delete tables that are no longer needed
Using Table Lookup Transformers
Basic Syntax
To use a Table Lookup Transformer in a common or action-synced attribute:
In Destination Attribute, choose the attribute on the target entity that will be updated
In Formatter, choose the source attribute to transform
In Pipeline Functions, specify the lookup table name, the column to match against, and the column containing values to return.
The full syntax for using lookup table transformers is:
Where:
<value>is the source attribute to transform (e.g.,{location})<table_name>is the name of the lookup table to use<column_name>is the column in the table to match against<return_column_name>is the column containing the value to return
Examples
Assuming a user has "location": "IL001" and a lookup table named locationTable structured as shown earlier:
Advanced Features
Pipeline Transformations
You can combine lookup transformations with other transformation functions in a pipeline:
This would look up the state_code corresponding to the location value and convert it to lowercase.
Default Values
If you need to handle cases where a lookup value is not found in the table, you can implement this by including a "wildcard" or default row in your lookup table:
This enables any unmatched values to return a default mapping instead of failing.
Technical Details
Implementation Notes
Lookup tables are immutable and automatically deleted when no longer referenced by any policy version
Multiple policy versions can reference the same lookup table (e.g., an active version and a draft version)
Lookup tables are defined at the policy level and can be referenced by any transformer within the policy
Lookup tables can have multiple columns to support different transformations from the same reference data
Best Practices
Standardize Naming: To use a lookup-based transformer, you will reference the table by file name. Apply consistent conventions for both the table and columns.
Document Mappings: Add descriptions for each lookup table to explain its purpose
Validate Data: Ensure lookup tables are complete and accurate before using them in transformers. Consider how lookup tables will be maintained over time, especially for values expected to change.
Troubleshooting
Common Issues
Related Topics
Last updated
Was this helpful?
