Skip to main content

HelloID

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.

Example
{
  "CommonName": "omar.treutel",
  "DisplayName": "Omar Treutel",
  "proxyAddresses": [
    "smtp:[email protected]",
    "smtp:[email protected]",
    "SMTP:[email protected]"
  ],
  "mail": "[email protected]",
  "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": "[email protected]",
  "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.

Example
{
  "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:

  1. Action

    The type of action that has been performed in the target system. Available actions include:

  2. Message

    A human-readable log message.

  3. IsError

    A Boolean indicating whether the operation encountered an error. $false indicates that the operation succeeded without an error.

Example
$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 and IpAddress of the domain controller used to perform the entitlement action on the account.

adUser

The sAMAccountName, distinguishedName, and objectGuid 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.

Example
{
  "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:[email protected]",
      "smtp:[email protected]",
      "smtp:[email protected]"
    ],
    "mail": "[email protected]",
    "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": "[email protected]"
  },
  "account": {
    "CommonName": "omar.treutel",
    "DisplayName": "Omar Treutel",
    "proxyAddresses": [
      "smtp:[email protected]",
      "smtp:[email protected]",
      "SMTP:[email protected]"
    ],
    "mail": "[email protected]",
    "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": "[email protected]",
    "Manager": "Connie ten Anderson (connie.van.den.wint1)"
  },
  "previousAccount": {
    "CommonName": "omar.treutel",
    "DisplayName": "Omar Treutel",
    "proxyAddresses": [
      "smtp:[email protected]",
      "smtp:[email protected]",
      "SMTP:[email protected]"
    ],
    "mail": "[email protected]",
    "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": "[email protected]",
    "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.

Example
{
  "Accounts": {
    "_9b8001cfb5534b578d9dcf507279f111": {
      "userPrincipalName": "[email protected]",
      "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": "[email protected]"
    },
    "Business": {
      "Address": {
        "Street": null,
        "StreetExt": null,
        "HouseNumber": null,
        "HouseNumberExt": null,
        "PostalCode": null,
        "Locality": null,
        "Country": null
      },
      "Phone": {
        "Mobile": null,
        "Fixed": null
      },
      "Email": "[email protected]"
    }
  },
  "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": "[email protected]"
  },
  "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).

Example
{
  "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.

Example
{
  "Accounts": {
    "_9b8001cfb5534b578d9dcf507279f111": {
      "userPrincipalName": "[email protected]",
      "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": "[email protected]"
    },
    "Business": {
      "Address": {
        "Street": null,
        "StreetExt": null,
        "HouseNumber": null,
        "HouseNumberExt": null,
        "PostalCode": null,
        "Locality": null,
        "Country": null
      },
      "Phone": {
        "Mobile": null,
        "Fixed": null
      },
      "Email": "[email protected]"
    }
  },
  "Excluded": false,
  "ExclusionDetails": {
    "Hr": false,
    "Manual": false
  },
  "PrimaryManager": {
    "PersonId": "7f101509-1a4b-48ab-842b-efb4915fa001",
    "ExternalId": "00248685",
    "DisplayName": "Stacey de Tromp (00248685) - HR generator",
    "Email": "[email protected]"
  },
  "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:

Must be converted to JSON and sent to HelloID via Write-Output as the last line of your script.

Example
$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.

Example
$success = $true
In this section: