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

1. Geographic Information:

   • Transform location codes to country, region, city, or timezone information

   • Map office codes to physical addresses or facility types

2. Organizational Mapping:

   • Convert department codes to department names or business units

   • Map cost centers to budget codes or accounting categories

3. 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:

1. Takes the source attribute value

2. Looks up this value in the specified lookup table

3. Returns the corresponding value from the designated return column

4. 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:

location_code,state_code,state,city
MN001,MN,Minnesota,Minneapolis
CA001,CA,California,Los Angeles
TX001,TX,Texas,Houston
TX002,TX,Texas,Austin

Creating and Managing Lookup Tables

Creating a Lookup Table

To create a new lookup table:

1. Navigate to the Lookup Tables tab within your policy configuration

2. Click Edit mode to enable policy changes

3. Click Add New to create a new lookup table

4. Provide a Name and optional Description for the lookup table

5. Drag a CSV file or click Browse to upload your reference data

6. Review the automatically detected column names

7. 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:

1. In Destination Attribute, choose the attribute on the target entity that will be updated

2. In Formatter, choose the source attribute to transform

3. 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:

{<value> | LOOKUP <table_name>, <column_name>, <return_column_name>}

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:

{location | LOOKUP locationTable, location_code, state_code | LOWER}

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:

location_code,state_code,state,city
MN001,MN,Minnesota,Minneapolis
CA001,CA,California,Los Angeles
*,UNKNOWN,Unknown,Unknown Location

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

1. 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.

2. Document Mappings: Add descriptions for each lookup table to explain its purpose

3. 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

When creating workflows in Lifecycle Management policies to create, sync, or de-provision identities, you will use attribute transformers to specify how user attributes for target accounts should be structured. The target attributes to create or update are typically mapped and optionally transformed from user metadata from the source of identity, such as an identity provider, HR system, or CSV upload. Attributes can be synchronized once or kept in continuous sync as changes occur over the user’s lifetime.

For example, attribute mapping and transformation can be used across Joiner, Mover, and Leaver scenarios:

• Joiner: Set new Azure AD User Principal Name to {source username}@{your-email-domain.com}. This is an example of mapping multiple attributes and performing a transformation.

• Mover: Always update a user’s “Manager” and “Department” attributes in Okta to match the user’s manager and department in Workday, a source of identity, whenever a department change or other employee mobility event occurs. This is an example of attribute mapping with continuous synchronization.

• Leaver: Mote a user’s Active Directory account to an OU reserved for terminated accounts.

When synchronizing a user’s attributes, Veza can apply one (or more) transformations to convert the source attribute values to a more suitable format, and apply the result within the target application as user account attribute.

For example, a transformer might remove the domain from an email address, replace special characters, or convert a string from upper case to lower case. Transformers can apply to any attribute on the target user account with the complexity varying depending on your business requirements.

See the following sections for more information about formatting destination attributes and possible transformations:

Continuous Sync

Continuous Sync keeps identity attributes in target systems up to date with your source of truth. It has three configuration levels that work together to determine how attributes are synchronized:

Workflow Level

The workflow's continuous sync setting controls change detection:

• When enabled: The workflow monitors for any changes in the source system

• When disabled: The workflow only runs during initial provisioning

Action Level

For Sync Identity actions, this controls whether existing entities can be updated:

• When enabled: The action can update existing entities

• When disabled: The action only sets attributes during initial creation

Attribute Level

Individual attributes can be configured for continuous sync:

• When enabled: The attribute will be updated when changes are detected

• When disabled: The attribute is only set during initial creation

All three levels must be enabled for an attribute to be continuously synchronized. For example, if you want to keep an employee's department updated:

1. Enable continuous sync on the workflow to monitor for changes

2. Enable continuous sync on the sync action to allow updates

3. Enable continuous sync on the department attribute transformer

Recommended Settings

Enable continuous sync for attributes that change during employment:

• Employee name

• Department

• Title

• Manager

• Cost Center

• AD Distinguished Name (DN)

• AD User Principal Name (UPN)

• AD Email

Disable continuous sync for stable identifiers:

• Active Directory sAMAccountName

• Email Addresses (for Email Write-Back action)

This configuration ensures that dynamic attributes stay updated while preserving stable identifiers.

Common Transformers

As part of implementing lifecycle management processes with Veza, you should create sets of common transformers to define how values such as username, login, or ID should be sourced for each target application. These transformers can then be reused across all identity sync and de-provision workflows involving those targets. Create common transformers to consistently form attributes for specific entity types, and re-use them to avoid errors and save time when creating actions for that entity type.

For instance, defining a common synced attribute to describe how to format Azure AD account names {username}@evergreentrucks.com enables reuse across multiple workflow actions. You can also define synced attributes at the action level when they are used only once within a policy, such as setting the primary group DN and OU of de-provisioned identities to a group reserved for terminated accounts.

Common Transformer Examples:

Adding transformers

Transformers can be defined at the policy level or when configuring an individual action in a workflow. To configure a transformer, add basic details as well as how to source the value of each attribute:

1. Give the transformer a name and description, and specify the data source it applies to.

2. Entity Type: Choose the target entity type in the destination system.

3. Click Add Attribute. The Destination Attribute dropdown will list available attributes for the chosen entity type.

   1. Destination Attribute: Choose the attribute that Veza will create or update for the target entity.

   4. Continuous Sync: Enabling this option always syncs the attribute, whilst applying any defined transformations. By default, attributes will not sync if the target identity is already created.

After creating a common transformer, you can select it when editing a workflow action. You can edit or delete common transformers on the Edit Policy > Common Transformers tab.

Remember that “Sync Identity” and “De-Provision Identity” actions can have action-level transformers override common transformers. If the same destination attribute is defined in both, the action-level transformer will take precedence.

Formatters

Formatters specify the actual value of the attribute to synchronize. The target attribute can be set to a specific value, synchronized with a source attribute, transformed according to a function, or some combination of the three.

Note that some formatters should enable continuous synchronization for the attribute, while others should not. For example, the value of “Created By” should be immutable once a user account is provisioned. Other attributes that represent a state or status should be synchronized over the user or account lifecycle.

Simple Value Setting

To create a destination attribute with a fixed value, enter the desired value when configuring the formatter.

For setting the creator attribute:

For activating a re-hired employee:

Empty Values

To set empty values (common for de-provisioning flows):

Source of Identity Formatters

Target attributes can be updated based on attributes belonging to the source of identity. To reference the value of a source entity attribute, use the format {<source_attribute_name>}.

Examples:

Transformation functions

Based on the user metadata that is available from your source of identity, you may need to convert a full email address to a valid username, standardize a date, or generate a unique identifier for users provisioned by Veza. If an attribute value needs to be altered for compatibility with the target system, you can transform the value of a source attribute, or apply a range of other functions to generate the target value.

Formatter expressions use the following syntax: {<source_attribute_name> | <FUNCTION_NAME>,<param1>,<param2>}

For example:

Table of transformation functions

See the table below for all supported functions and parameters. Some commonly used transformation functions include:

• Replacing a character with a different one

• Removing domains from email addresses

• Transforming to upper, lower, camel, or snake case

• Using a substring from the original value

Please contact Veza if additional transformations are required for your use case.

Using the ASCII Transformer

The ASCII transformer is particularly useful when working with international user data or systems that have strict character limitations. This transformer performs two main operations:

1. Removes all non-printable characters (including control codes, zero-width spaces, tabs, and newlines)

2. Converts non-ASCII characters to their closest ASCII equivalents

Whereas the REMOVE_DIACRITICS transformer only removes accent marks while preserving the basic character, the ASCII transformer performs a more comprehensive conversion, replacing characters like "Ł" with "L" and handling a wider range of non-ASCII characters.

Pipeline Functions

You can pipeline multiple transformation functions together, separated by a |. Each will apply in sequence, allowing for complex attribute formatters that use the output of one function as the input of another.

Example Pipeline Functions

• {name | UPPER}

  • If name = Smith, the result is SMITH.

• {first_name | SUB_STRING,0,1 | LOWER}.{last_name | LOWER}

  • If first_name = John and last_name = Smith, the result is j.smith.

• {email | REMOVE_DOMAIN}

  • If email = john.smith@domain.com, the result is john.smith.

• {email | REPLACE_ALL, " ", "."}

  • If email = john smith@domain.com, the result is john.smith@domain.com.

• {location | LOOKUP locationTable, location_code, city}

  • If location = IL001, the result is Chicago (using a lookup table named locationTable).

Further reference