Overview
The username generator transform allows you to specify logic to use when attempting to derive a unique value for an attribute in an account create profile, . Oftentimes this can be as simple as combining parts of a user's name and/or HR data (e.g., firstName.lastName), but sometimes generator logic such as a uniqueness counter might be needed to find a unique value in the target system (e.g., firstName.lastName1 if firstName.lastName is already taken).
Note: This transform can only be used for generation of unique value for the Account ID attribute marked for the source. For other attributes please use OOTB Create Unique LDAP Attribute Rule or create your own Attribute Generator Rule.
Other Considerations
- The transform allows for the use of "uniqueCounter" as a reserved variable for numerically trying the next iteration of the pattern. Once the generator is active on a pattern with "uniqueCounter," it will keep incrementing until it either has found a unique username candidate or it exhausts "cloudMaxUniqueChecks" value. This means that any patterns after one containing "uniqueCounter" will not be processed. The use of "uniqueCounter" should always be last in the pattern list.
- Within the account attribute definition structure, there is a field for "cloudMaxUniqueChecks" that identifies how many times the uniqueness check logic should be invoked before the username generator should stop executing. The maximum allowed value for this field is 50.
Transform Structure
The username generator transform is intended to be used as a configuration within the account create profile for a source. As such, the structure of this transform is more extensive than a typical Seaspray implementation -- it must be assigned to a create profile attribute (designated by name) and provide certain uniqueness check attributes such as cloudMaxSize, cloudMaxUniqueChecks and cloudRequired.
The cloudMaxSize attribute denotes the maximum length of generated data that should be allowable as a result of the generator logic. Any characters over thecloudMaxSize are truncated. The cloudMaxUniqueChecks attribute determines the maximum number of iterations the generator should attempt before failing to generate a value. The cloudRequired attribute is an internal flag required for the IdentityNow platform, and can simply be left as true.
The username generator transform itself should be supplied in the create profile attribute entry's transform parameter.
Example
{
"attributes": {
"cloudMaxSize": "100",
"cloudMaxUniqueChecks": "5",
"cloudRequired": "true"
},
"isRequired": false,
"multi": false,
"name": "distinguishedName",
"transform": {
"type": "usernameGenerator",
"attributes": {
"sourceCheck": true,
"patterns": [
"CN=$fi.$ln,OU=Users,DC=YourDomain,DC=com",
"CN=$fn.$ln,OU=Users,DC=YourDomain,DC=com",
"CN=$fn.$mi.$ln,OU=Users,DC=YourDomain,DC=com",
"CN=$fn.$mi.$ln${uniqueCounter},OU=Users,DC=YourDomain,DC=com"
],
"fn": {
"type": "identityAttribute",
"attributes": {
"name": "firstname"
}
},
"ln": {
"type": "identityAttribute",
"attributes": {
"name": "lastname"
}
},
"fi": {
"type": "substring",
"attributes": {
"input": {
"type": "identityAttribute",
"attributes": {
"name": "firstname"
}
},
"begin": 0,
"end": 1
}
},
"mi": {
"type": "substring",
"attributes": {
"input": {
"type": "identityAttribute",
"attributes": {
"name": "middlename"
}
},
"begin": 0,
"end": 1
}
}
}
},
"type": ""
}
Attributes
-
Required Attributes
-
type - This must always be set to usernameGenerator
-
patterns - A JSON array of patterns for the generator to evaluate for uniqueness, in sequential order
- Note that
$uniqueCounter can be leveraged here to automatically increment a counter if the value generated is not available and you would like to try appending numeric values (i.e., 1, 2, 3, etc.) instead of progressing beyond the current pattern.
-
Optional Attributes
-
sourceCheck - A boolean value (true/false) to indicate whether the generator should check only the IdentityNow database's representation of accounts for uniqueness, or whether the generator should query the target system directly. If not provided, the attribute will default to false.
true indicates the generator should check the target system directly. This is honored only if the system supports the "getObject" functionality -- for systems that do not have the ability to query for single account objects, the setting here is ignored and defaulted to false. Note also that only the attribute identified in the account schema as the accountID is checked.false indicates the generator should check only the IdentityNow database of accounts. Only the accountID is checked.
Examples
Example 1
{
"attributes": {
"cloudMaxSize": "100",
"cloudMaxUniqueChecks": "25",
"cloudRequired": "true"
},
"isRequired": false,
"multi": false,
"name": "userId",
"transform": {
"type": "usernameGenerator",
"attributes": {
"sourceCheck": true,
"patterns": [
"$fi$ln${uniqueCounter}"
],
"ln": {
"type": "identityAttribute",
"attributes": {
"name": "lastname"
}
},
"fi": {
"type": "substring",
"attributes": {
"input": {
"type": "identityAttribute",
"attributes": {
"name": "firstname"
}
},
"begin": 0,
"end": 1
}
}
}
},
"type": ""
}
This generator takes the user's first initial, appends the user's full last name, and then leverages a uniqueness counter to generate a unique value for userId. For example if the user's name were John Doe, the username generator will first try jdoe. If that is not unique, it will progress to jdoe1, then jdoe2, etc., until jdoe25.
Should a unique value not be found within those first 25 tries, then the generator will return an IllegalStateException.
Example 2
{
"attributes": {
"cloudMaxSize": "100",
"cloudMaxUniqueChecks": "10",
"cloudRequired": "true"
},
"isRequired": false,
"multi": false,
"name": "accountId",
"transform": {
"type": "usernameGenerator",
"attributes": {
"sourceCheck": true,
"patterns": [
"$fn.$ln${uniqueCounter}"
],
"fn": {
"type": "identityAttribute",
"attributes": {
"name": "firstname"
}
},
"ln": {
"type": "identityAttribute",
"attributes": {
"name": "lastname"
}
}
}
},
"type": ""
}
This generator takes the user's first name, appends a period and then the user's full last name, and then adds a uniqueness counter to generate a unique value for accountId. For example if the user's name were Adam Smith, the username generator will first try adam.smith. If that is not unique, it will progress to adam.smith1, then adam.smith2, etc., until adam.smith10.
Should a unique value not be found within those first 10 tries, then the generator will return an IllegalStateException.
References
