Introduction

HelloID supports the use of 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.

At present, HelloID fully supports the ECMAScript 5.1 standard.

Custom Functions

HelloID provides custom JavaScript functions to help make generating attribute values easier.

Delete Diacritical Marks

// Replace diacritical characters
var variableName = deleteDiacriticalMarks(variableName);

This custom function will replace non-ASCII characters within a string, that have diacritical marks, with their ASCII equivalents. The following character replacements are supported: 

ÀÁÂÃÄÅàáâãäåÒÓÔÕÕÖØòóôõöøÈÉÊËèéêëðÇçÐÌÍÎÏìíîïÙÚÛÜùúûüÑñŠšŸÿýŽž

Source Systems

Default Variables

HelloID provides some variable values that you may leverage inside of your complex mapping scripts for source systems. These 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 inside of source.firstname.

Attribute Examples

The following scripts are examples of how you can use JavaScript to generate attribute values for a source system in a complex mapping. Each example should be tailored to your organization's needs and data.

Gender

function getGender() {
    return source.Gender === 0 ? 'M' : 'F';
}

getGender();

Initials

function getInitials() {
	return source.FirstName.charAt(0) + source.LastName.charAt(0);
}

getInitials();

Target Systems

Default Variables

HelloID provides some variable values that you may leverage inside of your complex mapping scripts for target systems. These variables do not need to be initialized, and should not be overwritten.

Person

All complex field mappings for target systems have the entire Person object model within the "Person" variable. 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

When you have specified that a target system attribute must be unique, the "Iteration" variable becomes available to your script. This is an integer that represents how many times HelloID has run the JavaScript function while trying to generate a unique attribute value. The value of "Iteration" begins at 0, and increases by one for every iteration until a unique value is found for the target attribute. This is very useful for usernames and email addresses.

Attribute Examples

The following scripts are examples of how you can use JavaScript to generate attribute values for a target system in a complex mapping. Each example should be tailored to your organization's needs and data.

Display Names

function generatedisplayName() {
var firstName = Person.Name.NickName;
var middleName = Person.Name.FamilyNamePrefix;
var lastName = Person.Name.FamilyName;
var middleNamePartner = Person.Name.FamilyNamePartnerPrefix;
var lastNamePartner = Person.Name.FamilyNamePartner;
    
switch(Person.Name.Convention) {
	case "B":
		nameFormatted = firstName;
		if (typeof middleName !== 'undefined' && middleName) { 
			nameFormatted = nameFormatted + ' ' + middleName;
		}
		nameFormatted = nameFormatted + ' ' + lastName;
		break;
	case "P":
		nameFormatted = firstName;
			if (typeof middleNamePartner !== 'undefined' && middleNamePartner) { 
				nameFormatted = nameFormatted + ' ' + middleNamePartner;
			}
		nameFormatted = nameFormatted + ' ' + lastNamePartner;
		break;
	case "BP":
		nameFormatted = firstName;
		if (typeof middleName !== 'undefined' && middleName) { 
			nameFormatted = nameFormatted + ' ' + middleName;
		}
		nameFormatted = nameFormatted + ' ' + lastName + ' - ';
		if (typeof middleNamePartner !== 'undefined' && middleNamePartner) { 
			nameFormatted = nameFormatted + ' ' + middleNamePartner + ' '; 
		}
		nameFormatted = nameFormatted + lastNamePartner;
		break;
	case "PB":
		nameFormatted = firstName;
		if (typeof middleNamePartner !== 'undefined' && middleNamePartner) { 
			nameFormatted = nameFormatted + ' ' + middleNamePartner;
		}
		nameFormatted = nameFormatted + ' ' + lastNamePartner + ' - ';
		if (typeof middleName !== 'undefined' && middleName) { 
			nameFormatted = nameFormatted + ' ' + middleName + ' ';
		}
		nameFormatted = nameFormatted + lastName;
		break;
	default:
		nameFormatted = firstName;
		if (typeof middleName !== 'undefined' && middleName) { 
			nameFormatted = nameFormatted + ' ' + middleName;
		}
		nameFormatted = nameFormatted + ' ' + lastName;
		break;
}

	const displayName = nameFormatted.trim();
	return displayName;
}

generatedisplayName();

Email Addresses

function generateEmail() {
	const domain = 'yourdomainhere';
	const suffix = Iteration === 0 ? '' : Iteration;
	
	var firstName = Person.Name.NickName;
	var middleName = Person.Name.FamilyNamePrefix;
	var lastName = Person.Name.FamilyName;
	
	var Email = firstName + '.';
	
	//Check if the middleName variable contains data
	if (typeof middleName !== 'undefined' && middleName) { 
		Email = Email + middleName.replace(/\s+/g, '.') + '.';
	}
	
	Email = Email + lastName;
	
	//Remove blank chars
	Email = Email.replace(/\s/g,'');
	
	//Convert to lower case
	Email = Email.toLowerCase();
	
	//Remove diacritical chars
	Email = deleteDiacriticalMarks(Email);
	
	//Remove specific chars 
	Email = Email.trim().replace(/[^0-9a-zA-Z.]/g, '');
	
	Email = Email + suffix + '@' + domain;
	
	return Email;
}
	
generateEmail();

Passwords

function generatePassword(){
	// Initialize these variables for the algorithm to meet your password complexity rules
	const passwordLength = 8;
	const minUpper = 1;
	const maxUpper = 3;
	const minNumeric = 0;
	const maxNumeric = 2;
	const minSpecial = 1;
	const maxSpecial = 1;

	// Do not change any code below this line !!!
	const numberUpper = Math.floor((Math.random() * maxUpper) + minUpper);
	const numberNumeric = Math.floor((Math.random() * maxNumeric) + minNumeric);
	const numberSpecial = Math.floor((Math.random() * maxSpecial) + minSpecial);
	const numberLower = passwordLength - (numberUpper + numberNumeric + numberSpecial);

	var upperChars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
	var lowerChars = 'abcdefghijklmnopqrstuvwxyz';
	var numberChars = '0123456789';
	var specialChars = '!#$@*?';

	var getRandomValue = function(values) {
		return values.charAt(Math.floor(Math.random() * values.length));
	};

	var password = [];
	var i;
	
	for(i = 0; i < numberNumeric; ++i) { 
		password.push(getRandomValue(numberChars))
	}

	for(i = 0; i < numberUpper; ++i) { 
		password.push(getRandomValue(upperChars))
	}

	for(i = 0; i < numberSpecial; ++i) { 
		password.push(getRandomValue(specialChars))
	}

	for(i = 0; i < numberLower; ++i) { 
		password.push(getRandomValue(lowerChars))
	}

	function randomizeCharSequence(passwordObject){
		for(var j, x, i = passwordObject.length; i; j = Math.floor(Math.random() * i), x = passwordObject[--i], passwordObject[i] = passwordObject[j], passwordObject[j] = x);

		return passwordObject;
	}

	return randomizeCharSequence(password).join('');
}

generatePassword();

Usernames

function generateSamAccountName() {
	const suffix = Iteration === 0 ? '' : Iteration;
	var maxAttributeLength = 20 - suffix.toString().length;
	
	var firstNameChar = Person.Name.substring(0, 1);
	var firstName = Person.Name.NickName;
	var middleName = Person.Name.FamilyNamePrefix;
	var lastName = Person.Name.FamilyName;
	
	var sAMAccountName = "";
	
	if (Iteration == 0) {
		sAMAccountName = firstName + '.';
		
		//Check if the middleName variable contains data
		if (typeof middleName !== 'undefined' && middleName) { 
			sAMAccountName = sAMAccountName + middleName.replace(/\s+/g, '.') + '.';
		}
		
		sAMAccountName = sAMAccountName + lastName;
		
		sAMAccountName = sAMAccountName.trim().substring(0, 20);
	}
	
	if (Iteration == 1) {
		sAMAccountName = firstNameChar + '.';
		
		//Check if the middleName variable contains data
		if (typeof middleName !== 'undefined' && middleName) { 
			sAMAccountName = sAMAccountName + middleName.replace(/\s+/g, '.') + '.';
		}
		
		sAMAccountName = sAMAccountName + lastName;
		
		sAMAccountName = sAMAccountName.trim().substring(0, 20);
	}
	
	if (Iteration >= 2) {
		sAMAccountName = firstNameChar + '.';
		
		//Check if the middleName variable contains data
		if (typeof middleName !== 'undefined' && middleName) { 
			sAMAccountName = sAMAccountName + middleName.replace(/\s+/g, '.') + '.';
		}
		
		sAMAccountName = sAMAccountName + lastName;
		
		sAMAccountName = sAMAccountName.trim().substring(0, maxAttributeLength) + suffix;
	}
	
	//Remove tailing ...
	sAMAccountName = sAMAccountName.replace(/\.+$/, "");
	
	//Remove leading ...
	sAMAccountName = sAMAccountName.replace(/^\.+/, "");
	
	//Convert to lower case
	sAMAccountName = sAMAccountName.toLowerCase();
	
	//Remove diacritical chars
	sAMAccountName = deleteDiacriticalMarks(sAMAccountName);
	
	//Remove specific chars 
	sAMAccountName = sAMAccountName.replace(/[^0-9a-zA-Z.]/g, '');
	
	return sAMAccountName;
}
	
generateSamAccountName();