Skip to main content

NIM

Name generators

User attributes in target systems often have special formatting requirements. For example, the userPrincipalName attribute in Active Directory typically requires a @mydomain.com suffix. Or, a target attribute may require unique values. Other times, you may simply need to transform proper English names (e.g., "Stephanie Chen") into usernames (e.g., schen). And so on.

Name generators are the solution. They transform source attributes into target attributes via string manipulation, concatenation, and iteration. Use a name generator whenever you can't map source attributes 1:1 onto target attributes.

After creating a name generator, use its output in Mappings.

To get started, Create a name generator.

Each name generator contains the following elements:

 
Columns

The input to the name generator, provided by the specified filter. These are the source (starting) attributes.

Names

The output(s) of the name generator, which are fed into the Items pane of Mappings. These are the target (ending) attributes.

A name generator can produce multiple Names. This lets you construct multiple target attributes using the same name generator.

Some target system attributes take arrays of strings (e.g., proxyAddresses and other multi-value attributes in Active Directory). Create a multi-value name to generate these arrays.

Methods

Each name has one or more Methods. Methods are possible values for the currently selected name. The results of the currently selected method are displayed in the Results pane. When a mapping is executed, methods are evaluated in ascending order based on uniqueness requirements.

Tip

A name whose values do not need to be unique only requires a single method. A name whose values do need to be unique requires multiple methods and/or iterations.

Uniqueness requirements are specified on the Uniqueness tab of the name generator. See Enforce uniqueness for names.

Each method has one or more Parts and a priority (the Index value). Each part is a sub-string with its own set of Conversions. Parts are concatenated together in ascending (left to right) order to produce the method's value.

A method's Condition field works in conjunction with the Use Condition Based On dropdown. Enter a condition value for a method to restrict it to users with a matching value for the chosen filter attribute. This only applies if you have selected a filter in the Based On Filter dropdown. See Restrict a method by condition.

Conversions

Conversions are string manipulation rules. Each conversion is applied to a specific Part of a specific method.

Each conversion may take one or more Arguments. For example, the Add at End conversion takes one argument—the substring that it appends to the specified part.

A part that currently has a conversion applied is bolded. For example:

2021-05-24_14-01-12.png
Iterations

Iterations serve the same purpose as methods (i.e., they provide fallback outputs to fulfill uniqueness requirements). But, whereas methods ensure uniqueness via conversions applied to parts, iterations do so via one of two simple rules:

  • Use the first 1, 2, 3...X characters of the part

    • For example: Stephanie becomes S, St, Ste ... etc.

  • Append the number 1, 2, 3...X to the part

    • For example: Stephanie becomes Stephanie1, Stephanie2, Stephanie3 ... etc.

Each iteration takes a Max value, which specifies how many times it will iterate. If no value is specified, the iteration will iterate infinitely, until a unique value is returned.

Each iteration also takes an optional Start value, which specifies the number that it starts with.

Iterations are typically in cases where you expect a large (theoretically unlimited) number of uniqueness conflicts, and so it is impractical to create a sufficient number of methods. A common pattern is to create a handful of methods, and apply an iterator to the last method. Thus, the last method works as a "fallback" mechanism. See the Name generation example below.

A part with an iteration applied is underlined. For example:

2021-05-24_14-02-11.png

Name generation example

A common name generation pattern is:

  • Method 1: <First Initial><Last Name>

  • Method 2: <First Initial><Middle Initial><Last Name>

  • Method 3: <First Initial><Middle Initial><Last Name><Iteration>

2021-05-24_14-20-20.png

Method 1 transforms the name "Stephanie Chen" into the username schen (using the conversions Case Conversion: Convert to Lower Case and Shorten: Use First Character).

Method 2 then solves duplicates generated by Method 1 by differentiating on middle initial. For example, "Stephanie A. Chen" and "Stephanie B. Chen" are transformed into the usernames sachen and sbchen, respectively.

Finally, Method 3 solves duplicates generated by Method 2 by appending a number. For example, "Stephanie A. Chen", "Stephanie B. Chen", and another "Stephanie B. Chen" are transformed into the usernames sachen, sbchen, and sbchen1, respectively. By specifying a large Max value, this method can solve as many potential duplicates as necessary.

In this section: