Skip to main content

HelloID

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:

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 the Reference value of the standard permission currently being enforced. Use it in your code (e.g., in a switch statement) to identify the current standard permission. See Standard permissions.

Example (serialized)
{
  "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 the Add 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:

  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.

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):

2022-05-12_12-09-16.png

$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, or removed

New

The new value if the property was added or updated

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.}}.

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

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

Example (serialized)
{
  "SourceData": [
    "zifa92ldvk",
    "imudgaptwt",
    "fo7w13ugoa",
    "p504w51ohe",
    "wq0d3r5437",
    "17thfkl0kg",
    "7ojvyyms5y",
    "bbot9zbd53",
    "776gak2muw",
    "xo30oi5pq9"
  ]
}