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.