Skip to main content

HelloID

Account scripts (PowerShell v2 target systems)

All account scripts share a similar structure:

  1. HelloID passes you input variables, including your Target mappings, inside $actionContext and $personContext.

  2. These objects and their fields are used in the Account scripts to make calls to the target system's API inside the if (-Not($actionContext.DryRun -eq $true)) { } block. This is where the target account gets created, enabled, updated, disabled, or deleted, depending on which script it is.

  3. You pass the results of your work back to HelloID via $outputContext. This includes writing Audit logs.

accountscript_flow.png

The maximum execution time for each script is 30 seconds, at which time script execution is terminated.

Account scripts can be found in the GitHub repository of target connectors; see Target system connectors.

If your connector type is not available, or is not yet available as a PowerShell v2 connector, the PowerShell v2 connector template GitHub repository has all the essential resources you'll need to get started building out a new connector.

Always start by reading the main README.md file as well as the README.md file in the target folder of the GitHub repository.

Account Create script

Executed during the Grant step of Enforcement, when an Account entitlement is granted to a person.

Input

The following information in $actionContext is relevant for the Create operation:

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

  • Data: Contains the mapped data for the Create action as configured in the Fields tab, excluding fields whose mapping type is set to None.

    Note

    Fields whose mapping type is set to None are available in $outputContext.

  • DryRun: Indicates whether the script is running in preview (true) or in a production enforcement (false).

Script

In an Account Create script, the general flow is as follows.

If Correlation is enabled, the Create Account script tries to find an existing account that can be linked to the current person in HelloID. If it can find such an account, it sets the action to perform to correlate. If it can't, or if correlation is disabled, it sets the action to perform to create.

Next, a switch statement checks the action to perform.

  • If it is create, the script creates a new (disabled) user account in the target system. The script fetches the target mappings from $actionContext.Data and then uses them in the if (-Not($actionContext.DryRun -eq $true)) { } block to make the necessary API calls in the external system.

  • If it is correlate, the script correlates the found account with the user. It also sets AccountCorrelated to true so that the Account Update script is triggered after the Account Create script finishes.

Note

With a PowerShell v2 target, correlation cannot be performed manually and no correlation report can be made.

Output

Whether the account is created or correlated, you must send your results to HelloID via $outputContext. It should contain the following:

  • AccountCorrelated set to true, if a correlation was performed.

  • AccountReference set to a string that identifies the target account (often the person's ExternalId).

  • AuditLogs given a CorrelateAccount or CreateAccount audit log message, respectively.

  • Data set to the same account model you wrote into the target account (often identical to the mappings you received in $actionContext.Data).

  • Success set to true if an account was created or correlated successfully.

When this script finishes, an Account Create notification event triggers.

If a correlation was performed, the Account Update script runs.

Account Enable script

Executed during the Grant stage of Enforcement, when an Account Access entitlement is granted to a person.

Input

The following information in $actionContext is relevant for the Account Enable operation:

  • Data: Contains the mapped data for the Enable action as configured in the Fields tab, excluding fields whose mapping type is set to None.

    Note

    Fields whose mapping type is set to None are available in $outputContext.

  • DryRun: Indicates whether the script is running in preview (true) or in a production enforcement (false).

  • References: Includes (among other things):

Script

The Account Enable script gets the current person's account reference from $actionContext.References.Account, and uses it inside the if (-not($actionContext.DryRun -eq $true)) block to make the necessary API calls to enable the target account.

Output

At the end of the script, you must send your results to HelloID via $outputContext. It should contain the following:

  • AuditLogs given an EnableAccount audit log message.

  • Data updated with any attributes you altered in the target account.

  • PreviousData updated with any old attribute values you overwrote.

  • Success set to true if the changes written to the target account succeeded.

When this script finishes, an Account Enable notification event triggers.

Account Update script

Executed during the Update step of Enforcement. An update may be triggered by changes in a source system, or by using the Update accounts feature.

This script also runs immediately after the Account Create script if the account was correlated with a person in the Account Create script.

Input

The following information in $actionContext is relevant for the Update operation:

  • AccountCorrelated: Set to true in the Account Create script if a correlation was performed.

  • Configuration: Contains values from the target system's input form, if one exists. See Input forms.

  • Data: Contains the mapped data for the Update action as configured in the Fields tab, excluding fields whose mapping type is set to None. You'll primarily use it when you're making API calls into the external system to set target account attributes.

    Note

    Fields whose mapping type is set to None are available in $outputContext.

  • DryRun: Indicates whether the script is running in preview (true) or in a production enforcement (false).

  • References: Includes (among other things):

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

$personContext contains the following information related to the Update operation:

  • PersonDifferences: Contains the differences between a person's data in the most recent source snapshot and the previous one. For details on its structure, see $personContext.

Script

The Account Update script updates fields in the target account inside the if (-not($actionContext.DryRun -eq $true)) block, typically by using $personContext.PersonDifferences and/or $actionContext.Data.

The information in $personContext.PersonDifferences enables the script 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.

In the if ($actionContext.AccountCorrelated) { } block, any necessary additional changes to the account can be made if a Correlation occurred.

Note

In an update performed immediately after an account is correlated with a person, $outputContext.Data contains all Create action fields with Store in account data enabled, in addition to all fields mapped to the Update action. In this case, the mapping type of the Create action fields is None, regardless of their original mapping type.

Output

At the end of the script, you must send your results to HelloID via $outputContext. It should contain the following:

  • AuditLogs given an UpdateAccount audit log message.

  • Data given the account model you wrote into the target system.

  • PreviousData given the old account model you overwrote.

  • Success set to true if the changes written to the target account succeeded.

When this script finishes, an Account Update notification event triggers.

Account Disable script

Executed during the Revoke stage of Enforcement, when an Account Access entitlement is revoked from a person.

Input

The following information in $actionContext is relevant for the Disable operation:

  • Data: Contains the mapped data for the Disable action as configured in the Fields tab, excluding fields whose mapping type is set to None.

    Note

    Fields whose mapping type is set to None are available in $outputContext.

  • DryRun: Indicates whether the script is running in preview (true) or in a production enforcement (false).

  • References: Includes (among other things):

Script

The Account Disable script gets the current person's Account reference from $actionContext.References.Account, and uses it inside the if (-not($actionContext.DryRun -eq $true)) block to make the necessary API calls to disable the target account.

Output

At the end of the script, you must send your results to HelloID via $outputContext. It should contain the following:

  • AuditLogs given a DisableAccount audit log message.

  • Data updated in parallel with any attributes you altered in the target account.

  • PreviousData updated with any old attribute values you overwrote.

  • Success set to true if the changes written to the target account succeeded.

When this script finishes, an Account Disable notification event triggers.

Account Delete script

Executed during the Revoke stage of Enforcement, when an Account entitlement is revoked from a person.

Input

The following information in $actionContext is relevant for the Delete operation:

  • Configuration: Contains values from the target system's input form, if one exists. See Input forms.

  • Data: Contains the mapped data for the Delete action as configured in the Fields tab, excluding fields whose mapping type is set to None.

    Note

    Fields whose mapping type is set to None are available in $outputContext.

  • DryRun: Indicates whether the script is running in preview (true) or in a production enforcement (false).

  • References: Includes (among other things):

Script

The Account Delete script gets the current person's Account reference from $actionContext.References.Account, and uses it inside the if (-not($actionContext.DryRun -eq $true)) block to make the necessary API calls to delete the target account.

Output

At the end of the script, you must send your results to HelloID via $outputContext. It should contain the following:

  • AuditLogs given a DeleteAccount audit log message.

  • Success set to true if deleting the target account succeeded.

When this script finishes, an Account Delete notification event triggers.