PowerShell v2 target system variable reference
These objects are used in various PowerShell scripts in PowerShell v2 target systems, including the Account scripts, Permission actions-related scripts, and the Resource create script. Some fields are also available in notifications (see Notifications variable reference).
Direction: input
Datatype: PSCustomObject
$actionContext contains information related to the current provisioning operation.
- AccountCorrelated
Contains the value you set for $outputContext.AccountCorrelated in the Account Create script.
- Configuration
Contains values from the target system's input form, if one exists. See Input forms.
- CorrelationConfiguration
Contains the following properties pertaining to Correlation:
Enabled: Whether the Enable Correlation toggle is turned on.
PersonField: The currently selected Person Correlation Field.
PersonFieldValue: The value of the PersonField for the current person.
AccountField: The currently selected Account Correlation Field.
AccountFieldValue: The value of the AccountField for the current person.
Typically, you'll only use CorrelationConfiguration in the Account Create script.
- CurrentPermissions
Contains a
CurrentPermissions
array with the current person's currently-granted sub-permissions for the current standard permission.Used in Permissions-related scripts for permission sets which are using Sub-permissions.
- Data
Contains the target mappings configured on the Fields tab. You'll primarily use it when you're making API calls into the external system to set target account attributes.
- DryRun
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($actionContext.DryRun -eq $true)) { }
block. Otherwise, your production code will run during script previews.- Operation
Indicates the current account lifecycle stage. Primarily intended for use in the Uniqueness script. Possible values include:
enable
: Account Access Grantdisable
: Account Access Revoke
- References
Contains the following:
Account
: The reference to the current person's target account that you initially set in $outputContext.AccountReference in the Account Create script.ManagerAccount
: A reference to the current person's manager's account.Permission
(only used in the Permission actions scripts): Contains theReference
value of the standard permission currently being enforced. Use it in your code (e.g., in aswitch
statement) to identify the current standard permission. See Standard permissions.
{ "Configuration": { "text": { "required": "AQTSFEPYVYKJSGIJIDDMGBMEEBVHAHXC" }, "password": "JxkppPWgYhEwZgTHyffgJMcnsNMekEXm" }, "DryRun": false, "Operation": "update", "Data": { "DisplayName": "Victoria van de Auer (00248687) - HR generator", "NickName": "Victoria", "FamilyName": "Auer", "UserName": "victoria.van.de.auer", "Title": "International Marketing Representative", "Department": "Grocery", "StartDate": "07/21/2019 00:00:00", "EndDate": "10/10/2027 00:00:00", "Manager": "Ronald Hauck (00248686) - HR generator", "Country": "Azerbaijan" }, "CorrelationConfiguration": { "Enabled": false, "PersonField": "", "PersonFieldValue": null, "AccountField": "", "AccountFieldValue": null }, "AccountCorrelated": false, "References": { "Account": "98250063387448", "ManagerAccount": "2585425307418913" } }
Direction: output
Datatype: PSCustomObject
$outputContext is the object that you build in your PowerShell code to send data back to HelloID. You should not explicitly return $outputContext. HelloID will automatically parse it.
- AccountCorrelated
Only used in the Account Create script, to tell HelloID whether you correlated the current person to an existing account in instead of creating a new account. If yes, you must set this field to
true
. Subsequently returned to you in the Account Update script as $actionContext.AccountCorrelated.$outputContext.AccountCorrelated = $True
- AccountReference
A reference to the current person's target account in the external system. You must initially set this in the Account Create script, typically to the person's ExternalId (the default unique identifier in persons). AccountReference is then passed back to you in subsequent account scripts as $actionContext.References.
$account = $actionContext.Data $outputContext.AccountReference = $account.ExternalId
- AuditLogs
A
List
of PSCustomObject. Each object represents a log message for a single action taken in the target system, which HelloID will parse into the system's Audit logs. Use theAdd
method to add objects, following the example below.$outputContext.AuditLogs.Add([PSCustomObject]@{ Action = "UpdateAccount" Message = "Account with username $($account.userName) updated" IsError = $false })
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.CorrelateAccount
: Represents an account Correlation.GrantMembership
: Represents a Group Membership entitlement GrantRevokeMembership
: Represents a Group Membership entitlement RevokeGrantPermission
: Represents a Permission entitlement Grant.UpdatePermission
: Represents a Permission entitlement Update.RevokePermission
: Represents a Permission entitlement Revoke.CreateResource
: Represents a resource creation (see Resources).CreateMailbox
: 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.
- Data
HelloID's internal model of the target account. Any time you write to a target account in the external system, you should write parallel changes into $outputContext.Data. Maintaining an internal model inside HelloID allows you to easily use target account attributes in notifications without making external API calls.
Fields in $outputContext.Data whose Use In Notifications toggle is enabled will be available in the Notification events for their selected Actions, under {{Data.}}.
Fields in $outputContext.Data whose Store In Account Data toggle is enabled will be shared via the Share account fields between target systems feature. Note that the shared value is only updated when the Account Update script runs, and not in any other account scripts.
$account = $actionContext.Data # make any necessary changes to $account $outputContext.Data = $account
- Iteration
- NonUniqueFields
- Permissions
Used in the Retrieve permissions script to define the Standard permissions in a permission set.
- SubPermissions
Used in Permissions-related scripts for permission sets which are using Sub-permissions.
Allows HelloID to track the state of granted sub-permissions.
- PreviousData
Same as $outputContext.Data, except intended to store the previous account model (i.e., the one being overwritten in the current account script). Useful if you want to report the old values of updated fields in a notification in addition to the new ones.
Unless you make any changes to your mappings in your account scripts, all you typically need to do is set this to $actionContext.Data.
$account = $actionContext.Data $outputContext.PreviousData = $account # make any necessary changes to $account $outputContext.Data = $account
- Success
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.
$outputContext.Success = $true
Direction: input
Datatype: PSCustomObject
$personContext contains information related to the current person.
- Person
Contains all fields from the current person object (see Person schema and Contract schema) that are mapped in your Source mappings.
Available in notifications as {{Person.}}.
Note
$personContext.Person.Accounts.
, which contains fields shared via the Share account fields between target systems feature, is available but not included in autocomplete.- PreviousPerson
Contains all fields from the previous person object, i.e., in the second-to-most-recent snapshot. In other words, it contains the values labeled Old when you view the current snapshot (see View a snapshot):
$previousPerson
is only usable in production. In the script preview,$previousPerson
is always identical to$person
.Tip
In most cases, it is easier to use the pre-calculated $personContext.PersonDifferences object when you're writing changes into the target account.
- PersonDifferences
Contains the differences between $personContext.PreviousPerson and $personContext.Person. Useful to make targeted API calls in the Account Update script to update only certain fields in target accounts, instead of overwriting the entire target account.
It is structured as follows:
One object per modified Persons field in the current snapshot. (Corresponds to the changes in persons fields shown when you View a snapshot and View Snapshot Details.)
A
Contracts
array containing one item per modified Contracts field in the current snapshot. (Corresponds to the changes in contracts fields shown when you View a snapshot and View Snapshot Details.)A
PrimaryContract
object containing one object per modified field in the person's Primary contract.A
Custom
object containing one object per modified custom person or contract field added with the Add a custom person or contract field feature.
Each object may have the following properties:
- Change
Whether the property was
added
,updated
, orremoved
- New
The new value if the property was
added
orupdated
- Old
The old value if the property was
removed
Note
A
null
value for New or Old properties indicates there was no previous value. This means, for example, that a property with"Change": "updated"
and"Old": null
is actually an added property. Oppositely, a property with"Change": "updated"
and"New": null
is a removed property.Note
PersonDifferences is only usable in production. In the script preview, it is empty.
- Manager
Contains the person object of the current person's manager (see Managers). If the person has no manager defined, it is empty.
Available in notifications as {{Manager.}}.
{ "Person": { "Accounts": { "_5f35bf3668ea425d82c6b10fb7c76773": { "SamAccountName": "victoria.van.de.auer" }, "_a08a1b299cca46888ad694be12d6f2a7": { "DisplayName": "Victoria van de Auer (00248687) - HR generator", "UserName": "Victoria97", "ExternalId": { "value": "4b5c3aa1-c892-4d8e-ad14-49005431364e", "Guid": "4b5c3aa1-c892-4d8e-ad14-49005431364e" } }, "_e25b1efbd05a4e01bdb62242ed33795f": {} }, "PersonId": "0a820620-c3e9-4a39-b4f3-0eb09cce6350", "PersonVersion": "v1", "DisplayName": "Victoria van de Auer (00248687) - HR generator", "ExternalId": "00248687", "UserName": "Victoria97", "Location": { "ExternalId": null, "Code": null, "Name": null }, "Details": { "Gender": "F", "HonorificPrefix": "Ms. ", "HonorificSuffix": null, "BirthDate": "1987-10-14T00:00:00Z", "BirthLocality": "Ashtynland", "MaritalStatus": "Married" }, "Name": { "Initials": "V.", "GivenName": "Victoria", "NickName": "Victoria", "FamilyName": "Auer", "FamilyNamePrefix": "van de", "FamilyNamePartner": "Ullrich", "FamilyNamePartnerPrefix": "van", "Convention": "B" }, "Status": { "Blocked": false, "Reason": null }, "Contact": { "Personal": { "Address": { "Street": "Mathilde Gateway", "StreetExt": null, "HouseNumber": "44", "HouseNumberExt": null, "PostalCode": "20815-4677", "Locality": "Port Julius", "Country": "Azerbaijan" }, "Phone": { "Mobile": "248-316-6136", "Fixed": null }, "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]" } }, "Contracts": [ { "Context": { "InConditions": true }, "ExternalId": "C-32453640", "StartDate": "2016-02-23T00:00:00Z", "EndDate": "2032-03-26T00:00:00Z", "Type": { "Code": null, "Description": null }, "Details": { "Fte": 0, "HoursPerWeek": 10, "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": "72xhtz4uow", "DisplayName": "Home" }, "Division": { "ExternalId": null, "Code": null, "Name": null }, "Title": { "ExternalId": "C-89904977", "Code": null, "Name": "International Accounts Consultant" }, "Organization": { "ExternalId": null, "Code": null, "Name": null }, "Custom": {}, "Source": { "SystemId": "29a51501-3aa9-4cfd-9e9a-21ec548dcd39", "DisplayName": "HR generator" } }, { "Context": { "InConditions": true }, "ExternalId": "C-43833801", "StartDate": "2019-07-21T00:00:00Z", "EndDate": "2027-10-10T00:00:00Z", "Type": { "Code": null, "Description": null }, "Details": { "Fte": 0, "HoursPerWeek": 36, "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": "s6805ay53h", "DisplayName": "Grocery" }, "Division": { "ExternalId": null, "Code": null, "Name": null }, "Title": { "ExternalId": "C-49180478", "Code": null, "Name": "International Marketing Representative" }, "Organization": { "ExternalId": null, "Code": null, "Name": null }, "Custom": {}, "Source": { "SystemId": "29a51501-3aa9-4cfd-9e9a-21ec548dcd39", "DisplayName": "HR generator" } } ], "Excluded": false, "ExclusionDetails": { "Hr": false, "Manual": false }, "PrimaryContract": { "Context": { "InConditions": true }, "ExternalId": "C-43833801", "StartDate": "2019-07-21T00:00:00Z", "EndDate": "2027-10-10T00:00:00Z", "Type": { "Code": null, "Description": null }, "Details": { "Fte": 0, "HoursPerWeek": 36, "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": "s6805ay53h", "DisplayName": "Grocery" }, "Division": { "ExternalId": null, "Code": null, "Name": null }, "Title": { "ExternalId": "C-49180478", "Code": null, "Name": "International Marketing Representative" }, "Organization": { "ExternalId": null, "Code": null, "Name": null }, "Custom": {}, "Source": { "SystemId": "29a51501-3aa9-4cfd-9e9a-21ec548dcd39", "DisplayName": "HR generator" } }, "PrimaryManager": { "PersonId": "b2602f09-df34-4e35-8f74-be7c669843cc", "ExternalId": "00248686", "DisplayName": "Ronald Hauck (00248686) - HR generator", "Email": "[email protected]" }, "Custom": {}, "Source": { "SystemId": "29a51501-3aa9-4cfd-9e9a-21ec548dcd39", "DisplayName": "HR generator" } }, "PreviousPerson": { "PersonId": "0a820620-c3e9-4a39-b4f3-0eb09cce6350", "PersonVersion": "v1", "DisplayName": "Victoria van de Auer (00248687) - HR generator", "ExternalId": "00248687", "UserName": "Victoria97", "Location": { "ExternalId": null, "Code": null, "Name": null }, "Details": { "Gender": "F", "HonorificPrefix": null, "HonorificSuffix": null, "BirthDate": "1987-10-14T00:00:00Z", "BirthLocality": "Ashtynland", "MaritalStatus": "Married" }, "Name": { "Initials": "V.", "GivenName": "Victoria", "NickName": "Victoria", "FamilyName": "Auer", "FamilyNamePrefix": "van de", "FamilyNamePartner": "Ullrich", "FamilyNamePartnerPrefix": "van", "Convention": "B" }, "Status": { "Blocked": false, "Reason": null }, "Contact": { "Personal": { "Address": { "Street": "Mathilde Gateway", "StreetExt": null, "HouseNumber": "44", "HouseNumberExt": null, "PostalCode": "20815-4677", "Locality": "Port Julius", "Country": "Belgium" }, "Phone": { "Mobile": "248-316-6136", "Fixed": "277.429.9223 x47389" }, "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]" } }, "Contracts": [ { "ExternalId": "C-32453640", "StartDate": "2016-02-23T00:00:00Z", "EndDate": "2032-03-26T00:00:00Z", "Type": { "Code": null, "Description": null }, "Details": { "Fte": 0, "HoursPerWeek": 10, "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": "72xhtz4uow", "DisplayName": "Home" }, "Division": { "ExternalId": null, "Code": null, "Name": null }, "Title": { "ExternalId": "C-89904977", "Code": null, "Name": "International Accounts Consultant" }, "Organization": { "ExternalId": null, "Code": null, "Name": null }, "Custom": {}, "Source": { "SystemId": "29a51501-3aa9-4cfd-9e9a-21ec548dcd39", "DisplayName": "HR generator" } }, { "ExternalId": "C-43833801", "StartDate": "2019-07-21T00:00:00Z", "EndDate": "2027-10-10T00:00:00Z", "Type": { "Code": null, "Description": null }, "Details": { "Fte": 0, "HoursPerWeek": 36, "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": "s6805ay53h", "DisplayName": "Grocery" }, "Division": { "ExternalId": null, "Code": null, "Name": null }, "Title": { "ExternalId": "C-49180478", "Code": null, "Name": "International Marketing Representative" }, "Organization": { "ExternalId": null, "Code": null, "Name": null }, "Custom": {}, "Source": { "SystemId": "29a51501-3aa9-4cfd-9e9a-21ec548dcd39", "DisplayName": "HR generator" } } ], "Excluded": false, "ExclusionDetails": { "Hr": false, "Manual": false }, "PrimaryContract": { "ExternalId": "C-43833801", "StartDate": "2019-07-21T00:00:00Z", "EndDate": "2027-10-10T00:00:00Z", "Type": { "Code": null, "Description": null }, "Details": { "Fte": 0, "HoursPerWeek": 36, "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": "s6805ay53h", "DisplayName": "Grocery" }, "Division": { "ExternalId": null, "Code": null, "Name": null }, "Title": { "ExternalId": "C-49180478", "Code": null, "Name": "International Marketing Representative" }, "Organization": { "ExternalId": null, "Code": null, "Name": null }, "Custom": {}, "Source": { "SystemId": "29a51501-3aa9-4cfd-9e9a-21ec548dcd39", "DisplayName": "HR generator" } }, "PrimaryManager": { "PersonId": "b2602f09-df34-4e35-8f74-be7c669843cc", "ExternalId": "00248686", "DisplayName": "Ronald Hauck (00248686) - HR generator", "Email": "[email protected]" }, "Custom": {}, "Source": { "SystemId": "29a51501-3aa9-4cfd-9e9a-21ec548dcd39", "DisplayName": "HR generator" } }, "PersonDifferences": { "Details": { "HonorificPrefix": { "Change": "updated", "New": "Ms. ", "Old": null } }, "Contact": { "Personal": { "Address": { "Country": { "Change": "updated", "New": "Azerbaijan", "Old": "Belgium" } }, "Phone": { "Fixed": { "Change": "updated", "New": null, "Old": "277.429.9223 x47389" } } } } }, "Manager": { . . . } }
Direction: input
Datatype: Boolean
Used in Permissions-related scripts for permission sets which are using Sub-permissions.
Identifies which of a person's Contracts are in scope of the Conditions of the business rule that contains the current standard permission, in order to select the correct sub-permissions.
You can also access data from out-of-conditions contracts, if necessary, but this is less common.
The InConditions
field is re-calculated for all contracts during both Evaluation and Enforcement. It is not re-calculated when a snapshot is generated, or when a business rule is published.
Tip
This value is always false
in the script preview.
$true
Direction: input
Datatype: PSCustomObject
Contains the unique values in the Contracts field selected for the current resource. Iterate through it and make API calls into the target system to create the resources that do not yet exist.
{ "SourceData": [ "zifa92ldvk", "imudgaptwt", "fo7w13ugoa", "p504w51ohe", "wq0d3r5437", "17thfkl0kg", "7ojvyyms5y", "bbot9zbd53", "776gak2muw", "xo30oi5pq9" ] }