Introduction
HelloID supports JavaScript in complex field mappings for both source and target systems. Such complex mappings are useful for generating conditional output, or for formatting output in a specific manner.
Complex field mappings within HelloID allow you to leverage industry-standard knowledge and best practices to handle the data in your HelloID provisioning processes. This article will provide tips and examples to help you get started with complex field mappings.
HelloID fully supports the ECMAScript 5.1 standard.
Custom functions
HelloID provides the following custom JavaScript functions, to help generate attribute values:
Replace diacritical marks
function removeDiacrit(){ // Replace diacritical characters var saniName = deleteDiacriticalMarks(source.FirstName); return saniName } removeDiacrit()
This custom function replaces non-ASCII diacritical characters within a string, with their ASCII equivalents. The following character replacements are supported:
ÀÁÂÃÄÅàáâãäåÒÓÔÕÕÖØòóôõöøÈÉÊËèéêëðÇçÐÌÍÎÏìíîïÙÚÛÜùúûüÑñŠšŸÿýŽž
Source systems
Default variables
HelloID provides the following objects to leverage inside your complex mapping scripts for source systems. They are used to map data from the source system onto Persons objects. Their reference variables do not need to be initialized and should not be overwritten.
source
Information about the imported personnel record is available inside of the source
object. This object's properties match the fields that you have imported from your source system, and are accessible through dot notation. For example, a Person's first name may be available at source.firstname
.
Example source field mappings
The following script demonstrates how to use JavaScript to generate a complex attribute value for a source system. Customize this example for your organization's needs and data.
function getGender() { return source.Gender === 0 ? 'M' : 'F'; } getGender();
Target systems
Default variables
HelloID provides the following objects to leverage inside your complex mapping scripts for target systems. They are used to map data from Persons objects onto target system accounts. Their reference variables do not need to be initialized, and should not be overwritten.
Person
All complex field mappings for target systems have access to the entire Person
object. You can access the properties of a Person using dot notation. For example, a Person's first name is available at Person.Name.GivenName
.
Iteration
An integer that starts at 0 and represents how many times HelloID has run the JavaScript function. Mapping functions are rerun when you've specified that a target system attribute must be unique (either within the target system, or relative to external systems), but the function has generated a duplicate attribute value. When this happens, the Iteration
variable is incremented and the script is retried. Typically your PowerShell code should convert it to a string and append it to the generated attribute value. In this way, the script is rerun until a unique value is found for the target attribute. This is very useful for usernames and email addresses.
Iteration
is available for all native target system connectors, including on-premise AD and Azure AD. To achieve the same functionality in a custom PowerShell target connector, you'll need to create and increment your own custom variable.
Example target field mappings
The following scripts demonstrate how to use JavaScript to generate complex attribute values for a target system. Customize these examples for your organization's needs and data.
function generateDisplayName() { let firstName = Person.Name.NickName; let middleName = Person.Name.FamilyNamePrefix; let lastName = Person.Name.FamilyName; let middleNamePartner = Person.Name.FamilyNamePartnerPrefix; let lastNamePartner = Person.Name.FamilyNamePartner; switch(Person.Name.Convention) { case 'B': case 'BP': nameFormatted = firstName if (typeof middleName !== 'undefined' && middleName) { nameFormatted = nameFormatted + ' ' + middleName } nameFormatted = nameFormatted + ' ' + lastName; break; case 'P': case 'PB': nameFormatted = firstName if (typeof middleNamePartner !== 'undefined' && middleNamePartner) { nameFormatted = nameFormatted + ' ' + middleNamePartner } nameFormatted = nameFormatted + ' ' + lastNamePartner; break; default: nameFormatted = firstName if (typeof middleName !== 'undefined' && middleName) { nameFormatted = nameFormatted + ' ' + middleName } nameFormatted = nameFormatted + ' ' + lastName; break; } const displayName = nameFormatted; return displayName; } generateDisplayName();
function generateSamAccountName() { const suffix = Iteration === 0 ? '' : Iteration; let firstName = Person.Name.NickName; let middleName = Person.Name.FamilyNamePrefix; let lastName = Person.Name.FamilyName; let mailNickname = firstName + '.'; //Check if the middleName variable contains data if (typeof middleName !== 'undefined' && middleName) { mailNickname = mailNickname + middleName.replace(/\s+/g, '.') + '.' } mailNickname = mailNickname + lastName; //Remove blank chars mailNickname = mailNickname.replace(/\s/g,''); //Convert to lower case mailNickname = mailNickname.toLowerCase(); //Remove diacritical chars mailNickname = deleteDiacriticalMarks(mailNickname); mailNickname = mailNickname + suffix; return mailNickname; } generateSamAccountName();
Clone complex field mappings
If you wish to create similar complex field mappings in multiple source or target systems, you may be able to clone mappings from one system to another. It depends on which system(s) you're using. Cloning is supported for all source systems, but only some target systems. Learn how to clone mappings here.