Preserve and reuse legacy usernames

Last updated: October 30, 2026NIM service baseline: v3.0.1457

Provisioning configuration example

Keep a history of usernames and email addresses to check new names against previously used values and restore identifiers when employees return.

At a glance

This example extends an existing account creation process with an internal lookup table. It records usernames and email addresses, including changes, and uses the source user's unique ID to find history when that person returns. The returning employee must have the same source ID as before.

Part	Purpose
Lookup table	Store the user ID, username, email, and entry date for each history record.
Relations and filters	Find values to record and returning users with existing history.
Name generator	Check new usernames and email addresses against historical values.
Mappings and job	Write history and use stored identifiers in the existing provisioning process.

Before you begin

You need an existing account creation process and provisioning job, connected source and target systems, and a stable unique ID in the source data. This is an example of a common configuration; adapt object names and target fields to your environment. The screenshots use Active Directory as the target system and an internal table called hrEmployees as the source system.

For the foundation, see the provisioning tutorial. This example focuses on adding username history to that existing process.

Configure legacy username history

Create the internal lookup table

Go to Configuration > Settings > Lookup tables > Add and name the table, for example LegacyUsernames.

Column	Value
ID	The user's unique ID from the source data.
Username	The username to retain.
Email	The email address to retain.
EnterDate	The date and time the history record is entered.
autoGUID	An automatically generated key for each history row. An auto-incrementing ID is another option.

Use the generated row identifier as the table key so the table can retain multiple records for one employee ID.

Enable the table and set its key

1. Go to Systems > Internal and enable the lookup table.
2. Expand Internal, select the table, and open Columns.
3. Set autoGUID, or your chosen generated identifier, as the key.

Relate source, target, and history records

In Processing > Relations, create the following relations using the corresponding fields in your systems:

Relation	Match
Target to history	Target user ID to the history table's ID.
Source to history	Source user ID to the history table's ID.
Target username to history	Target username to Username.
Target email to history	Target email to Email.

The ID relations identify the person. The username and email relations check whether the current values have already been recorded.

Target username to history: Match LegacyUsernames.Username in the Internal system to AD.Users.sAMAccountName.

Target email to history: Match LegacyUsernames.Email in the Internal system to AD.Users.userPrincipalName in this example.

Select usernames and email addresses to record

1. Go to Processing > Filters and add a filter, or a child filter under your existing active-user logic.
2. Select users present in both the source and target systems.
3. Join the history table twice: once through the username relation and once through the email relation.
4. Use OR logic to select users whose current username has no history match or whose current email has no history match. This also captures changes to either value.
5. In Column Specification > Add Script Column, add the entry date used by the history mapping.

The following script preserves the example's YYYY-MM-DD HH:MM:SS AM/PM format:

Show entry date script

function getCurrentDateTime() {
    const now = new Date();

    const year = now.getFullYear();
    const month = String(now.getMonth() + 1).padStart(2, '0');
    const day = String(now.getDate()).padStart(2, '0');

    let hours = now.getHours();
    const minutes = String(now.getMinutes()).padStart(2, '0');
    const seconds = String(now.getSeconds()).padStart(2, '0');
    const ampm = hours >= 12 ? 'PM' : 'AM';

    hours = hours % 12;
    hours = hours || 12;
    hours = String(hours).padStart(2, '0');

    return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} ${ampm}`;
}

return getCurrentDateTime();

Select history for returning users

1. Add a second filter, or child filter, for users present in the source data and history table but absent from the target system.
2. Use the ID-to-ID relation to retrieve history for the returning user's unique ID.
3. In Ordering & Selection, select the first record for each user's unique ID and order descending on EnterDate.

This example uses that ordering to choose the history record for the returning user.

Check generated names against history

Edit the existing name generator for the user population. Add the history table's username and email fields to the corresponding Uniqueness checks. Newly generated values, including those generated after a name change, are then checked against the stored history.

See Configure unique usernames for the name generator controls.

Create the history mapping

1. Go to Output > Mappings > Add.
2. Select Internal as the system, your history table as the target, and its create function, such as LegacyUsernames_create.
3. Name and save the mapping.
4. Select the filter that captures missing history values.
5. Map ID, Username, Email, and EnterDate to the corresponding filter columns.

Create the returning-user mapping

1. Add a mapping for your target system's user-create operation, such as Users > UserCreate.
2. Select the returning-user filter.
3. Follow your existing target account creation configuration, using the username and email from the history table in place of the name generator outputs.

Add the mappings to the existing job

1. Go to Output > Jobs, select your user synchronization job, and open Configuration.
2. Select Add twice, choose crud as the type, and select the two new mappings.
3. Arrange them around the existing standard create mapping as shown below.

Order	Mapping	Example name
Before standard create	Create a returning user's account with stored identifiers.	Employee_AD_User_Create_LegacyUsernames
Existing position	Existing standard account creation.	Your existing create mapping
After standard create	Record usernames and email addresses in the history table.	Employee_Internal_LegacyUsernames_Create

The example adds a history-based path for returning employees while using the existing account creation process for users without history.

Step 1 of 8

Related guides

• Lookup Tables explains how to manage internal reference data.
• Configure unique usernames covers uniqueness fields and fallback methods.
• Lifecycle & Account Provisioning describes the broader lifecycle process.

Report a problem with this page

Found an error or a missing step? Open the feedback form and describe what needs changing. The article details and Documentation topic are filled in for you.

Need help with your NIM environment? Contact Support.