Introduction
While provisioning accounts with HelloID, you may want to leverage information from one target system in another target system. For example, you may want your users' Active Directory usernames to be used in their G Suite email address. This is easily done by marking attribute data to be exported and stored in a person's global record, or exporting them in the case of a custom PowerShell system.
Store attribute data in a person record
Before you can leverage attributes from one target system in another, you must choose which attributes you want to export from a target system for later use. Here, we will show you how to do this in both a simple target system, and a custom PowerShell system.
Simple target system
Within a simple target system (e.g., Active Directory), making attributes available to other systems is as easy as toggling a switch. Edit the target system of choice, and navigate to the Account tab. Then, find the attribute that you wish to make available and enable the Store this field in person account data setting.
When you are finished marking attributes, click the Save button to apply your changes. Then, click the Force update account(s) button. This will cause HelloID to update the target accounts as necessary, and pull the marked attribute data back into HelloID.
Custom PowerShell target system
Just like a simple target system, you can export account data from a custom PowerShell target system. In this case, however, it must be done in the code of your Account Create lifecycle stage.
Edit the PowerShell target system of your choice, and navigate to its Account tab. Once there, click on the Configure button for the Account Create stage, as seen below.
In the $result object that the PowerShell script returns to HelloID, you may add a member object called ExportData. Properties of this object and their values will be available after the account has been granted to a user. You can see the code for the object below.
$result = [PSCustomObject]@{
Success= $success;
AccountReference= $account_guid;
AuditDetails=$auditMessage;
Account = $account;
# Optionally return data for use in other systems
ExportData = [PSCustomObject]@{
displayName = $account.DisplayName;
userName = $account.UserName;
externalId = $account_guid;
};
};
In this case, the display name, username, and external ID are returned from the PowerShell target system and may be used in other systems.
After you've shared variables from a target system using one of the above techniques, you can see them in Persons > (select a Person) > Accounts. Shared variables are displayed inside the target system's tile:
Note that you may need to select the target system's Force update accounts button or perform an enforcement to complete the process of sharing variables.
Use attribute data from another system
After you have configured one or more target systems to export and store data inside of a person record for later use, you may leverage that information in other target systems. Here, we will show you how to do this in both a simple target system, and a custom PowerShell system.
Simple target system
Inside of a simple target system, using data from other systems is easy. Edit the target system in question, and navigate to the Account tab. In this example, we've set up a connection to a different Active Directory domain, but you can use any target system you'd like.
Once on the Account tab, click the wrench icon next to Use account data from systems.
This will bring up a dialog where you may choose which system(s) you'd like to get data from. Choose a system from the dropdown menu at the bottom of the dialog, and click Add. A reference name for the system is automatically generated (e.g., "MicrosoftActiveDirectory"). This name will be used to access the system's information during attribute mapping. When you are finished adding target systems, close the dialog.
Important: You may change the reference name if you wish, but you should only do so before mapping any attribute data. Changing the name afterward will break any existing mappings from that target system.
After adding the system, you will see its information just above the attribute list.
At this point, you may map attribute data from the other target system onto your current one. In the screenshot below, we are taking the givenName attribute from our other Active Directory domain and using it in this one.
Attributes from other systems are all available under the Accounts property, followed by the reference name of the other target system.
Custom PowerShell target system
Inside of a custom PowerShell target system, using data from other systems can be done through scripting. Edit the target system in question, and navigate to the Account tab. Once there, click on the wrench icon next to Use data from other target systems.
This will bring up a dialog where you may choose which system(s) you'd like to get data from. Choose a system from the dropdown menu at the bottom of the dialog, and click Add. A reference name for the system is automatically generated (e.g., "MicrosoftActiveDirectory"). This name will be used to access the system's information during attribute mapping. When you are finished adding target systems, close the dialog.
Important: You may change the reference name if you wish, but you should only do so before mapping any attribute data. Changing the name afterward will break any existing mappings from that target system.
After adding the desired system(s) you will see their information appear on screen.
When you are ready, you may configure any one of the lifecycle stages. In the PowerShell scripts, you can access information from the other target system(s) in the Accounts property of the Person object. The snippet of code below shows how we can access the givenName attribute from our "MicrosoftActiveDirectory" target system.
#Initialize default properties
$p = $person | ConvertFrom-Json;
# Get givenName from Active Directory target system
$givenName = $p.Accounts.MicrosoftActiveDirectory.givenName;
#Change mapping here
$account = [PSCustomObject]@{
firstName= $givenName;
}
if(-Not($dryRun -eq $True)) {
#Write create logic here
}
$success = $True;
#build up result
$result = [PSCustomObject]@{
Success= $success;
Account = $account;
};
#send result back
Write-Output $result | ConvertTo-Json -Depth 10
When we test the results of this script, we can see that a user who has an Active Directory account will get their givenName attribute value populated inside of our PowerShell target system.
What if no account exists in the primary target system?
When sharing information between target systems, you should ensure that any users who receive accounts in the secondary (dependent) system also have accounts in the primary (parent) system. Using our previous examples, if a user did not have an account in our first Active Directory system, then any attempts to use their givenName attribute in another system would result in a blank/null value.
If it is not possible or feasible to ensure that everyone has an account in the primary system, then you should plan your deployment of the secondary system accordingly by using complex mappings and/or scripting to handle blank values.
A note on dependencies
When you choose to use data from a primary (parent) target system, that target system's processing priority is automatically configured so that it is processed before the secondary (dependent) system. This is to help ensure that the requisite data is in place in the primary target system before processing the secondary one, in cases where both accounts are granted at the same time (e.g., within the same business rule).
Important: Do not make two systems dependent on each other. This create a "chicken and egg" scenario, where one account will inevitably not have the required data during creation. In addition, if accounts for both systems are granted at the same time, then they will both be stuck in a state of "pending grant" while waiting on each other.