Replacing Contact User Gateway with Assyst ETM

This post is going to be a little lengthy, so apologies in advance. We have been experimenting with the ETM now for almost 4 years and learning as we go through trial an error.

ETM Overview:

https://wiki.axiossystems.com/assyst11-6Wiki/index.php/Integrations:assystETM_1.6_-_Overview

Channel Config:

https://wiki.axiossystems.com/assyst11-6Wiki/index.php/Integrations:assystETM_1.6_-_Channel_Configuration

Mapper Config:

https://wiki.axiossystems.com/assyst11-6Wiki/index.php/Integrations:assystETM_1.6_-_Data_Mapping

I often find myself referring to the common JavaScript variables when building out new mappers so worth familiarising yourself early:

https://wiki.axiossystems.com/assyst11-6Wiki/index.php/Integrations:assystETM_1.6_-_Data_Mapping#JavaScript_variables

If you’re looking to automate through a scheduled task on a virtual machine or a server then you should read the 'Remote Upload' section which outlines how to use the importtool.ps1 script that IFS provide to generate an encryption key and to trigger the import:
https://wiki.axiossystems.com/assyst11-6Wiki/index.php/Integrations:assystETM_1.6_-_Channel_Configuration#Remote_Upload

I cannot see the download of importtool.ps1 anymore on the wiki or the ETM console so it might be worth asking the help desk for an up-to-date copy. I do have one if you don't have any luck.

PowerShell Upload Example:

I have pulled out the barebones of this script. We have this configured to run leavers at the weekend to discontinue accounts no longer required.

$ETMImport = "C:\Temp\AutomatedassystUserImport.csv"

$PropertiesArray = ([INSERT ATTRIBUTES YOU WANT TO EXPORT])

Get-ADUser -Filter {(employeeType -ne 'Shared Account') -and (employeeType -ne 'Service Account') -and (employeeType -ne 'Admin Account') -and (enabled -eq $true)} -properties * -ErrorAction Stop | Select $PropertiesArray | Sort -property whenCreated -Descending | Export-csv $ETMImport -NoTypeInformation -Force <# Sorted by creation to ensure new accounts are added first for quicker debugging #>

.\importtool.ps1 -url https://[INSERT YOUR ETM DOMAIN]/assystETM/REST/ -username [INSERT ETM USERNAME] -password [Encrypted password output from importtool.ps1] -channel "Contact User Import" -filename "C:\Temp\AutomatedassystUserImport.csv" -simpleresult

Alternatively, we have updated to use MS Graph. Useful if you are have a hybrid or Azure Active Directory environment (or plan to in the near future) and skills are transferrable in using modern authentication on other sources like Exchange Online and SharePoint.
https://wiki.axiossystems.com/assyst11-6Wiki/index.php/Integrations:assystETM_1.6_-_Channel_Configuration#MS_Graph_REST

Graph Explorer | Try Microsoft Graph APIs - Microsoft Graph

Required ETM 1.5 or above

Example Uri:

https://graph.microsoft.com/v1.0/users?$select=givenName,surname,userPrincipalName,mail,businessPhones,mobilePhone,companyName,department,onPremisesDistinguishedName,onPremisesSyncEnabled,jobTitle,displayName,userType,employeeId,employeeType,accountEnabled,onPremisesExtensionAttributes,externalUserState, identities&$expand=manager($select=userPrincipalName,employeeId)&$filter=userType eq 'member'

Make sure that you create (if necessary) any prerequisites for each element before trying to create or update it. It is useful to map out in a flow before starting. We build the organisation, role and cost centre before the assyst alias user, then we work through contact user, privilege groups and csgs.

As you can see we go one step further and create the relationship with the CI in use in this import a we do not use assyst ITOM.

Finally, we tend to do the logic in the config mapper at the start. This was because of the number of users we have cause the mapper to run for hours. By assessing the existing account vs the imported data we can define which mappers should run and which should skip.

Example:

Config Mapper:

"configObject": {
	"contactUsr": {
		"updateRequired": true, // determines if the contact user mapper will run or not
		"sc": "TEST.USER@TEST.COM",
		"name": "Test User",
		"loginName": "ad-test.user@test.com",
		"licenseRole": 1,
		"updateReason": null, // Add to remarks for debugging
		 "room": {
			"id": 1
		},
		"discontinue": false,
		"delete": false,
		"manager": {
			"id": 2,
			"sc": "MANAGER@TEST.COM",
			"costCentreId": 12
		},
		"id": 14,
		"aliasUsrId": 14
	}
}

Iteration Expression:

var source = mapped[0].variables.configObject.contactUsr.updateRequired;

if(source === true){
	[inbound];//perform the mapping once
}else{
	[];//perform the division mapping 0 times
}

This also enables us to re-use the modular mappers for each element. Every channel can pass the data into the mappers in the format that they are expecting. Over time, we have found that this reduces the time required to create imports and enables use to delegate to less technical teams.

Hello. IFS does have a sample configuration for the user gateway (file name: ContactUserV11_2Beta.json). We had to get this from our IFS Partner (consultant), so they likely won’t give it to you directly.

I found the sample channel to be overly simple, but have been able to use it as a starting point for developing the mappers to do what we need them to. We already have a separate integration utility for managing our user alias accounts via ETM, so we are only looking to use this part of it to create the actual Contact User records from AD.

ETM 1.6.1 does have an LDAP channel source option. I haven’t explored using this yet, but it may eliminate the need to pull the AD data through powershell or some other way.

Hope this helps.

Duncan