Active Directory target system variable reference
These variables are used in various PowerShell scripts in Active Directory target systems, including the Directory scripts, the OU scripts, and the Post-action scripts.
$account
Direction: input
Datatype: JSON
Contains the current person's target AD account information. Calculated automatically by HelloID based on this AD system's Target mappings.
Tip
In the Post-action scripts, this variable is instead available as $eRef.account.
You can manually add/modify/remove account fields. For example, $account | Add-Member -NotePropertyName "customField" -NotePropertyValue "custom value"
.
Useful to access persons' current target account values in Notifications without making API calls into the target system.
{
"CommonName": "omar.treutel",
"DisplayName": "Omar Treutel",
"proxyAddresses": [
"smtp:omar.treutel_1@tools4ever.com",
"smtp:omar.treutel_2@tools4ever.com",
"SMTP:omar.treutel@tools4ever.com"
],
"mail": "omar.treutel@tools4ever.com",
"c": "NL",
"department": "Tools & Outdoors",
"description": "Managed by HelloID",
"division": null,
"employeeId": "00248681",
"employeeNumber": "00248681",
"givenName": "Omar",
"l": null,
"physicalDeliveryOfficeName": null,
"sn": "Treutel",
"streetAddress": null,
"telephoneNumber": null,
"title": "Legacy Program Developer",
"initials": "A",
"userPrincipalName": "omar.treutel@tools4ever.com",
"Manager": "Connie ten Anderson (connie.van.den.wint1)"
}
$accountReference
Direction: input
Datatype: JSON
A reference to the current person's target AD account and directories.
{
"ObjectGuid": "766afe8c-b4ba-4a0f-90db-a693ce641cef"
}
$auditLogs
Direction: output
Datatype:
List
of PSCustomObject
Each object in $auditLogs
represents a log message for a single action taken in the target system. Must be sent to HelloID via the AuditLogs
property of $result. HelloID parses these objects into the system's Audit logs.
Each object takes three properties:
Action
The type of action that has been performed in the target system. Available actions include:
EnableAccount
: Represents an Account Access entitlement Grant.DisableAccount
: Represents an Account Access entitlement Revoke.MoveAccount
: Represents a target account being manually moved to a different OU.GrantMembership
: Represents a Group Membership entitlement GrantRevokeMembership
: Represents a Group Membership entitlement RevokeCreateMailbox
: Represents an Exchange mailbox being manually created for a target account.
Message
A human-readable log message.
IsError
A Boolean indicating whether the operation encountered an error.
$false
indicates that the operation succeeded without an error.
$auditLogs = [Collections.Generic.List[PSCustomObject]]::new()
$auditLogs.Add([PSCustomObject]@{
Action = "CreateAccount" # Optionally specify a different action for this audit log
Message = "Post create action script for user $($p.commonName)"
IsError = $false
}
$dryRun
Direction: input
Datatype: Boolean
Indicates whether the script is running in preview (true
) or in a production enforcement (false
).
Warning
All your API calls must be wrapped in the script's if (-Not($dryRun -eq $true)) { }
block. Otherwise, your production code will run during script previews.
$entitlementContext ($eRef)
Direction: input
Datatype: JSON
- domainController
The
Name
andIpAddress
of the domain controller used to perform the entitlement action on the account.- adUser
The
sAMAccountName
,distinguishedName
, andobjectGuid
of the current AD account. Use this object instead of binding to the user object in the external AD system.- configuration
Contains values from the target system's input form, if one exists. See Input forms.
- exchangeConfiguration
The configuration that was used for Exchange, if Exchange integration is enabled.
- exportData
All fields shared for the current AD account via the Share account fields between target systems feature.
- mappedData
The Target mappings of this AD target system.
Only available in the Account Create post-action script and the Account Update post-action script. In the Account Create post-action script, all mapped attributes are included. In the Account Update post-action script, only properties with the Update This Field toggle enabled are included.
- account
Contains the current person's target AD account information. Calculated automatically by HelloID based on this AD system's Target mappings.
Used by HelloID to construct the {{differences}} variable in the Account Update notification event. Also available in the Account Create notification event and the Account Delete notification event as
{{Account.}}
(see Notifications variable reference).You can manually add/modify/remove account fields. For example,
$account | Add-Member -NotePropertyName "customField" -NotePropertyValue "custom value"
.This object is not available during script preview.
Tip
In the Directory scripts, this variable is available as $account, instead of
$eRef.account
.- previousAccount
Contains the current person's target AD account information, prior to the update action. Only available in the Account Update post-action script.
Note that if you modify $eRef.account in the Account Update post-action script, you must return both
$eRef.account
and$eRef.previousAccount
(by uncommenting the relevant lines in $result). You should never modify$eRef.previousAccount
itself.This object is not available during script preview.
{
"domainController": {
"Name": "Lab159.t4edemo.com",
"IpAddress": "fe80::b154:f01:8210:e141%6"
},
"adUser": {
"SamAccountName": "omar.treutel",
"DistinguishedName": "CN=omar.treutel,OU=docs,DC=t4edemo,DC=com",
"ObjectGuid": "988a9c77-2c37-4ef7-8860-39897ef1792c"
},
"configuration": {},
"exportData": {},
"exchangeConfiguration": {
"Integration": false,
"Manage": true,
"Remote": false,
"RemoteRoutingAddressDomain": null,
"Url": null,
"Username": null,
"Password": null,
"SkipCaCheck": false,
"SkipCnCheck": false,
"SkipRevocationCheck": false,
"AuthenticationMode": "Default"
},
"mappedData": {
"commonName": "omar.treutel",
"proxyAddresses": [
"SMTP:omar.treutel@tools4ever.com",
"smtp:omar.treutel_1@tools4ever.com",
"smtp:omar.treutel_2@tools4ever.com"
],
"mail": "omar.treutel@tools4ever.com",
"displayName": "Omar Treutel",
"c": "NL",
"department": "Tools & Outdoors",
"description": "Managed by HelloID",
"division": null,
"employeeId": "00248681",
"employeeNumber": "00248681",
"givenName": "Omar",
"l": null,
"physicalDeliveryOfficeName": null,
"sn": "Treutel",
"streetAddress": null,
"telephoneNumber": null,
"title": "Legacy Program Developer",
"initials": "A",
"userPrincipalName": "omar.treutel@tools4ever.com"
},
"account": {
"CommonName": "omar.treutel",
"DisplayName": "Omar Treutel",
"proxyAddresses": [
"smtp:omar.treutel_1@tools4ever.com",
"smtp:omar.treutel_2@tools4ever.com",
"SMTP:omar.treutel@tools4ever.com"
],
"mail": "omar.treutel@tools4ever.com",
"c": "NL",
"department": "Tools & Outdoors",
"description": "Managed by HelloID",
"division": null,
"employeeId": "00248681",
"employeeNumber": "00248681",
"givenName": "Omar",
"l": null,
"physicalDeliveryOfficeName": null,
"sn": "Treutel",
"streetAddress": null,
"telephoneNumber": null,
"title": "Legacy Program Developer",
"initials": "A",
"userPrincipalName": "omar.treutel@tools4ever.com",
"Manager": "Connie ten Anderson (connie.van.den.wint1)"
},
"previousAccount": {
"CommonName": "omar.treutel",
"DisplayName": "Omar Treutel",
"proxyAddresses": [
"smtp:omar.treutel_1@tools4ever.com",
"smtp:omar.treutel_2@tools4ever.com",
"SMTP:omar.treutel@tools4ever.com"
],
"mail": "omar.treutel@tools4ever.com",
"c": "NL",
"department": "Tools & Outdoors",
"description": "Managed by HelloID",
"division": null,
"employeeId": "00248681",
"employeeNumber": "00248681",
"givenName": "Omar",
"l": null,
"physicalDeliveryOfficeName": null,
"sn": "Treutel",
"streetAddress": null,
"telephoneNumber": null,
"title": "Legacy Program Developer",
"initials": "A",
"userPrincipalName": "omar.treutel@tools4ever.com",
"Manager": "Connie ten Anderson (connie.van.den.wint1)"
}
}
$manager
Direction: input
Datatype: JSON
Contains the person object of the current person's manager (see Managers). If the person has no manager defined, it is empty.
{
"Accounts": {
"_9b8001cfb5534b578d9dcf507279f111": {
"userPrincipalName": "stacey.de.tromp@t4edemo.com",
"DisplayName": "Stacey de Tromp"
}
},
"Contracts": [
{
"Context": {
"InConditions": false
},
"ExternalId": "C-58895950",
"StartDate": "2013-11-15T00:00:00Z",
"EndDate": "2032-11-24T00:00:00Z",
"Type": {
"Code": null,
"Description": null
},
"Details": {
"Fte": 0,
"HoursPerWeek": 32,
"Percentage": 0,
"Sequence": 0
},
"Location": {
"ExternalId": null,
"Code": null,
"Name": null
},
"CostCenter": {
"ExternalId": null,
"Code": null,
"Name": null
},
"CostBearer": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Employer": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Manager": {
"PersonId": "00000000-0000-0000-0000-000000000000",
"ExternalId": null,
"DisplayName": null,
"Email": null
},
"Team": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Department": {
"ExternalId": "17thfkl0kg",
"DisplayName": "Health & Books"
},
"Division": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Title": {
"ExternalId": "C-83467599",
"Code": null,
"Name": "Internal Infrastructure Developer"
},
"Organization": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Custom": {},
"Source": {
"SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
"DisplayName": "HR generator"
}
}
],
"PrimaryContract": {
"Context": {
"InConditions": false
},
"ExternalId": "C-58895950",
"StartDate": "2013-11-15T00:00:00Z",
"EndDate": "2032-11-24T00:00:00Z",
"Type": {
"Code": null,
"Description": null
},
"Details": {
"Fte": 0,
"HoursPerWeek": 32,
"Percentage": 0,
"Sequence": 0
},
"Location": {
"ExternalId": null,
"Code": null,
"Name": null
},
"CostCenter": {
"ExternalId": null,
"Code": null,
"Name": null
},
"CostBearer": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Employer": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Manager": {
"PersonId": "00000000-0000-0000-0000-000000000000",
"ExternalId": null,
"DisplayName": null,
"Email": null
},
"Team": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Department": {
"ExternalId": "17thfkl0kg",
"DisplayName": "Health & Books"
},
"Division": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Title": {
"ExternalId": "C-83467599",
"Code": null,
"Name": "Internal Infrastructure Developer"
},
"Organization": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Custom": {},
"Source": {
"SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
"DisplayName": "HR generator"
}
},
"PersonId": "7f101509-1a4b-48ab-842b-efb4915fa001",
"PersonVersion": "v1",
"DisplayName": "Stacey de Tromp (00248685) - HR generator",
"ExternalId": "00248685",
"UserName": "Stacey.Tromp",
"Location": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Details": {
"Gender": "F",
"HonorificPrefix": null,
"HonorificSuffix": null,
"BirthDate": "1967-03-10T00:00:00Z",
"BirthLocality": "Diegoburgh",
"MaritalStatus": "Married"
},
"Name": {
"Initials": "S.",
"GivenName": "Stacey",
"NickName": "Stacey",
"FamilyName": "Tromp",
"FamilyNamePrefix": "de",
"FamilyNamePartner": "Heller",
"FamilyNamePartnerPrefix": "van der",
"Convention": "B"
},
"Status": {
"Blocked": false,
"Reason": null
},
"Contact": {
"Personal": {
"Address": {
"Street": "Pat Squares",
"StreetExt": null,
"HouseNumber": "177",
"HouseNumberExt": null,
"PostalCode": "57999",
"Locality": "Gregoryborough",
"Country": "Cook Islands"
},
"Phone": {
"Mobile": "453-315-3716",
"Fixed": "987.898.9280"
},
"Email": "Stacey.Tromp@gmail.com"
},
"Business": {
"Address": {
"Street": null,
"StreetExt": null,
"HouseNumber": null,
"HouseNumberExt": null,
"PostalCode": null,
"Locality": null,
"Country": null
},
"Phone": {
"Mobile": null,
"Fixed": null
},
"Email": "S.Tromp@felicita.com"
}
},
"Excluded": false,
"ExclusionDetails": {
"Hr": false,
"Manual": false
},
"PrimaryManager": {
"PersonId": "489c0ba8-df17-4b20-ac06-5c27a80e60a5",
"ExternalId": "00248676",
"DisplayName": "Randall van de Keeling (00248676) - HR generator",
"Email": "R.Keeling@deondre.com"
},
"Custom": {},
"Source": {
"SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
"DisplayName": "HR generator"
}
}
$managerAccountReference
Direction: input
Datatype: JSON
The $accountReference of the current person's manager (see Managers).
{
"HomeDirectory": null,
"TsHomeDirectory": null,
"ProfileDirectory": null,
"TsProfileDirectory": null,
"ObjectGuid": "d52bb1e6-27e1-45d2-8557-efaa2c8c2a9a"
}
$person
Direction: input
Datatype: JSON
Contains all fields from the current person object (see Person schema and Contract schema) that are mapped in your Source mappings.
{
"Accounts": {
"_9b8001cfb5534b578d9dcf507279f111": {
"userPrincipalName": "angel.rath@t4edemo.com",
"DisplayName": "Angel Rath"
}
},
"Contracts": [
{
"Context": {
"InConditions": false
},
"ExternalId": "C-68854614",
"StartDate": "2014-04-10T00:00:00Z",
"EndDate": "2026-01-23T00:00:00Z",
"Type": {
"Code": null,
"Description": null
},
"Details": {
"Fte": 0,
"HoursPerWeek": 37,
"Percentage": 0,
"Sequence": 0
},
"Location": {
"ExternalId": null,
"Code": null,
"Name": null
},
"CostCenter": {
"ExternalId": null,
"Code": null,
"Name": null
},
"CostBearer": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Employer": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Manager": {
"PersonId": "00000000-0000-0000-0000-000000000000",
"ExternalId": null,
"DisplayName": null,
"Email": null
},
"Team": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Department": {
"ExternalId": "hn7m9ac8ld",
"DisplayName": "Tools"
},
"Division": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Title": {
"ExternalId": "C-68432656",
"Code": null,
"Name": "Lead Intranet Strategist"
},
"Organization": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Custom": {},
"Source": {
"SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
"DisplayName": "HR generator"
}
}
],
"PrimaryContract": {
"Context": {
"InConditions": false
},
"ExternalId": "C-68854614",
"StartDate": "2014-04-10T00:00:00Z",
"EndDate": "2026-01-23T00:00:00Z",
"Type": {
"Code": null,
"Description": null
},
"Details": {
"Fte": 0,
"HoursPerWeek": 37,
"Percentage": 0,
"Sequence": 0
},
"Location": {
"ExternalId": null,
"Code": null,
"Name": null
},
"CostCenter": {
"ExternalId": null,
"Code": null,
"Name": null
},
"CostBearer": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Employer": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Manager": {
"PersonId": "00000000-0000-0000-0000-000000000000",
"ExternalId": null,
"DisplayName": null,
"Email": null
},
"Team": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Department": {
"ExternalId": "hn7m9ac8ld",
"DisplayName": "Tools"
},
"Division": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Title": {
"ExternalId": "C-68432656",
"Code": null,
"Name": "Lead Intranet Strategist"
},
"Organization": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Custom": {},
"Source": {
"SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
"DisplayName": "HR generator"
}
},
"PersonId": "e39afd56-c9dc-4949-b761-4f2924294b2d",
"PersonVersion": "v1",
"DisplayName": "Angel Rath (00248691) - HR generator",
"ExternalId": "00248691",
"UserName": "Angel_Rath",
"Location": {
"ExternalId": null,
"Code": null,
"Name": null
},
"Details": {
"Gender": "F",
"HonorificPrefix": null,
"HonorificSuffix": null,
"BirthDate": "1974-12-20T00:00:00Z",
"BirthLocality": "Port Jacqueschester",
"MaritalStatus": "Single"
},
"Name": {
"Initials": "A.",
"GivenName": "Angel",
"NickName": "Angel",
"FamilyName": "Rath",
"FamilyNamePrefix": null,
"FamilyNamePartner": null,
"FamilyNamePartnerPrefix": null,
"Convention": "B"
},
"Status": {
"Blocked": false,
"Reason": null
},
"Contact": {
"Personal": {
"Address": {
"Street": "Langosh Turnpike",
"StreetExt": null,
"HouseNumber": "185",
"HouseNumberExt": null,
"PostalCode": "61178",
"Locality": "Friedaborough",
"Country": "Australia"
},
"Phone": {
"Mobile": "437-999-4350",
"Fixed": "1-549-487-4540 x15639"
},
"Email": "Angel9@hotmail.com"
},
"Business": {
"Address": {
"Street": null,
"StreetExt": null,
"HouseNumber": null,
"HouseNumberExt": null,
"PostalCode": null,
"Locality": null,
"Country": null
},
"Phone": {
"Mobile": null,
"Fixed": null
},
"Email": "A.Rath@cary.com"
}
},
"Excluded": false,
"ExclusionDetails": {
"Hr": false,
"Manual": false
},
"PrimaryManager": {
"PersonId": "7f101509-1a4b-48ab-842b-efb4915fa001",
"ExternalId": "00248685",
"DisplayName": "Stacey de Tromp (00248685) - HR generator",
"Email": "S.Tromp@felicita.com"
},
"Custom": {},
"Source": {
"SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
"DisplayName": "HR generator"
}
}
$result
Direction: output
Datatype: PSCustomObject, converted to JSON
Most scripts in Active Directory target systems must return a $result
object to HelloID. Takes a slightly different set of properties depending on the script. Each script's default template specifies which properties are required.
All $result
objects, regardless of the specific script, take the following properties:
Success
: $success.
Must be converted to JSON and sent to HelloID via Write-Output
as the last line of your script.
$result = [PSCustomObject]@{
Success = $success
AuditLogs = $auditLogs
ExportData = $eRef.exportData
Account = $eRef.account
}
$success
Direction: output
Datatype: Boolean
A Boolean value denoting whether the script's operation was a success. Use error trapping (e.g., try/catch blocks) to determine whether you should set it to true or false.
Must be sent to HelloID in the Success
property of $result.
$success = $true