Skip to main content

HelloID

PowerShell target system variable reference

These variables are used in various PowerShell scripts in PowerShell target systems, including the Account scripts, Single permission script, Separate permission scripts, and the Resource create script.

$account

  • Direction: output

  • Datatype: PSCustomObject

Should contain a property for each field that you want to map into target accounts. Get the values from $person. At minimum, should contain an ExternalId unique identifier, which is usually a GUID generated with the New-Guid cmdlet (which should also be sent to HelloID in the AccountReference property of $result.

You initially construct $account in the Account Create script, and can subsequently update it in the Account Update script. Must be sent to HelloID via the Account property of $result.

Useful to access persons' current target account values in Notifications without making API calls into the target system.

Example
$account = [PSCustomObject]@{
    DisplayName = $p.DisplayName
    FirstName   = $p.Name.NickName
    LastName    = $p.Name.FamilyName
    UserName    = $p.UserName
    ExternalId  = $accountGuid
    Title       = $p.PrimaryContract.Title.Name
    Department  = $p.PrimaryContract.Department.DisplayName
    StartDate   = $p.PrimaryContract.StartDate
    EndDate     = $p.PrimaryContract.EndDate
    Manager     = $p.PrimaryManager.DisplayName
}
$accountReference

  • Direction: input

  • Datatype: JSON

A reference to the current person's target account. Initially created in the in the AccountReference property of $result in the Account Create script. Then passed back to you in subsequent account and permission scripts.

Example
{
  "value": "34b9b839-8a5f-4bde-a367-fc9542d83d26",
  "Guid": "34b9b839-8a5f-4bde-a367-fc9542d83d26"
}
$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"
        Message = "Created account with username $($account.UserName)"
        IsError = $false
    }
$configuration

  • Direction: input

  • Datatype: JSON

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

Example
{
  "text": {
    "required": "Example text",
    "multiline": "Example multiline text"
  },
  "password": "Fh6%@gX^ZP8zM2",
  "email": "[email protected]",
  "switch": false,
  "radio": "one"
}
$contract.Context.InConditions

  • 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
$currentPermissions

  • Direction: N/A

  • Datatype: hash table

Used in Permissions-related scripts for permission sets which are using Sub-permissions.

You build this object yourself by iterating through the CurrentPermissions property of $entitlementContext ($eRef). It represents the sub-permissions that are granted to the current person for the current standard permission.

Example
$currentPermissions = @{ }
foreach ($permission in $eRef.CurrentPermissions) {
    $currentPermissions[$permission.Reference.Id] = $permission.DisplayName
}
$desiredPermissions

  • Direction: N/A

  • Datatype: hash table

Used in Permissions-related scripts for permission sets which are using Sub-permissions.

You build this object yourself. Each property represents a Sub-permission that should be granted for the current standard permission.

Most commonly, sub-permissions are granted 1:1 based on Departments of in-conditions Contracts. The default script templates reflect this use case. For example:

Example
$desiredPermissions = @{ }
if (-Not($o -eq "revoke")) {
	foreach ($contract in $p.Contracts) {
		if ($contract.Context.InConditions) {
			$desiredPermissions[$contract.Department.ExternalId] = $contract.Department.DisplayName
		}
	}
}

After building $desiredPermissions, iterate through it to build $subPermissions.

$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

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.

Example
{
  "CurrentPermissions": [
    {
      "DisplayName": "Jewelery, Clothing & Electronics",
      "Reference": {
        "Id": "zifa92ldvk"
      }
    },
    {
      "DisplayName": "Sports",
      "Reference": {
        "Id": "zrfbrxegq6"
      }
    },
    {
      "DisplayName": "Games",
      "Reference": {
        "Id": "f6xs2hlssj"
      }
    },
    {
      "DisplayName": "Health & Books",
      "Reference": {
        "Id": "17thfkl0kg"
      }
    },
    {
      "DisplayName": "Games, Sports & Home",
      "Reference": {
        "Id": "nh7oz64jie"
      }
    }
  ],
  "DataStorage": null,
  "PermissionDisplayName": "Permission - First permission",
  "Configuration": {
    "text": {
      "required": "Example text",
      "multiline": "Example multiline text"
    },
    "password": "Fh6%@gX^ZP8zM2",
    "email": "[email protected]",
    "switch": false,
    "radio": "one"
  }
}
$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": "Virginia Kunze"
    },
    "_05c394d2b98c4c63a2a0a51980c8f590": {
      "DisplayName": "Virginia Kunze (00248674) - HR generator",
      "UserName": "Virginia_Kunze",
      "ExternalId": {
        "value": "736859cf-0d02-4a9b-9a3b-7183d0407880",
        "Guid": "736859cf-0d02-4a9b-9a3b-7183d0407880"
      },
      "LastName1": "Kunze"
    }
  },
  "Contracts": [
    {
      "Context": {
        "InConditions": false
      },
      "ExternalId": "C-31190280",
      "StartDate": "2016-03-07T00:00:00Z",
      "EndDate": "2033-03-24T00:00:00Z",
      "Type": {
        "Code": null,
        "Description": null
      },
      "Details": {
        "Fte": 0,
        "HoursPerWeek": 35,
        "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": "776gak2muw",
        "DisplayName": "Beauty, Home & Industrial"
      },
      "Division": {
        "ExternalId": null,
        "Code": null,
        "Name": null
      },
      "Title": {
        "ExternalId": "C-38482839",
        "Code": null,
        "Name": "Internal Mobility Associate"
      },
      "Organization": {
        "ExternalId": null,
        "Code": null,
        "Name": null
      },
      "Custom": {},
      "Source": {
        "SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
        "DisplayName": "HR generator"
      }
    }
  ],
  "PrimaryContract": {
    "Context": {
      "InConditions": false
    },
    "ExternalId": "C-31190280",
    "StartDate": "2016-03-07T00:00:00Z",
    "EndDate": "2033-03-24T00:00:00Z",
    "Type": {
      "Code": null,
      "Description": null
    },
    "Details": {
      "Fte": 0,
      "HoursPerWeek": 35,
      "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": "776gak2muw",
      "DisplayName": "Beauty, Home & Industrial"
    },
    "Division": {
      "ExternalId": null,
      "Code": null,
      "Name": null
    },
    "Title": {
      "ExternalId": "C-38482839",
      "Code": null,
      "Name": "Internal Mobility Associate"
    },
    "Organization": {
      "ExternalId": null,
      "Code": null,
      "Name": null
    },
    "Custom": {},
    "Source": {
      "SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
      "DisplayName": "HR generator"
    }
  },
  "PersonId": "27f65293-ed6a-4018-9072-f9a7ef743bdf",
  "PersonVersion": "v1",
  "DisplayName": "Virginia Kunze (00248674) - HR generator",
  "ExternalId": "00248674",
  "UserName": "Virginia_Kunze",
  "Location": {
    "ExternalId": null,
    "Code": null,
    "Name": null
  },
  "Details": {
    "Gender": "F",
    "HonorificPrefix": null,
    "HonorificSuffix": null,
    "BirthDate": "1982-03-23T00:00:00Z",
    "BirthLocality": "New Rodhaven",
    "MaritalStatus": "Single"
  },
  "Name": {
    "Initials": "V.",
    "GivenName": "Virginia",
    "NickName": "Virginia",
    "FamilyName": "Kunze",
    "FamilyNamePrefix": null,
    "FamilyNamePartner": null,
    "FamilyNamePartnerPrefix": null,
    "Convention": "B"
  },
  "Status": {
    "Blocked": false,
    "Reason": null
  },
  "Contact": {
    "Personal": {
      "Address": {
        "Street": "Orn Bridge",
        "StreetExt": null,
        "HouseNumber": "88",
        "HouseNumberExt": null,
        "PostalCode": "38021",
        "Locality": "Dessieville",
        "Country": "Guyana"
      },
      "Phone": {
        "Mobile": "808-228-4311",
        "Fixed": "352.762.2858 x8973"
      },
      "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": "b5730b54-8b76-4390-9939-40158103df5f",
    "ExternalId": "00248678",
    "DisplayName": "Bernard Flatley (00248678) - 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
{
  "value": "736859cf-0d02-4a9b-9a3b-7183d0407880",
  "Guid": "736859cf-0d02-4a9b-9a3b-7183d0407880"
}
$newCurrentPermissions

  • Direction: N/A

  • Datatype: hash table

Used in Permissions-related scripts for permission sets which are using Sub-permissions.

You build this object yourself by iterating through $currentPermissions and adding a property for each current permission that also exists in $desiredPermissions. In this loop, you also revoke all current permissions that do not exist in $desiredPermissions.

Example
$newCurrentPermissions = @{ }
foreach ($permission in $currentPermissions.GetEnumerator()) {
	if (-Not $desiredPermissions.ContainsKey($permission.Name)) {
		if (-Not($dryRun -eq $true)) {
			# Write permission revoke logic here
	}
	
		$auditLogs.Add([PSCustomObject]@{
			Action  = "RevokePermission"
			Message = "Revoked access to department share $($permission.Value)"
			IsError = $false
		})
	} else {
		$newCurrentPermissions[$permission.Name] = $permission.Value
	}
}
$operation

  • Direction: input

  • Datatype: JSON

HelloID passes this variable into the Single permission script. For a permission set using a single script, the same script is invoked during the grant, update, and revoke steps of enforcement. $operation tells you which step is currently happening, so you can make the appropriate API calls into the target system to grant, update, or revoke sub-permissions as needed. The default script template shows the recommended way to use $operation.

Possible values include:

grant

Indicates the Grant step of enforcement.

update

Indicates the Update step of enforcement.

revoke

Indicates the Revoke step of enforcement.

$permissionReference

  • Direction: input

  • Datatype: JSON

. See Standard permissions.

Example
{
  "Reference": "Permission2"
}
$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"
    },
    "_05c394d2b98c4c63a2a0a51980c8f590": {
      "DisplayName": "Angel Rath (00248691) - HR generator",
      "UserName": "Angel_Rath",
      "ExternalId": {
        "value": "f4dd8dfa-25ee-47a7-a940-b269a0aba796",
        "Guid": "f4dd8dfa-25ee-47a7-a940-b269a0aba796"
      },
      "LastName1": "Rath"
    }
  },
  "Contracts": [
    {
      "Context": {
        "InConditions": false
      },
      "ExternalId": "C-41151375",
      "StartDate": "2012-05-23T00:00:00Z",
      "EndDate": "2031-06-17T00:00:00Z",
      "Type": {
        "Code": null,
        "Description": null
      },
      "Details": {
        "Fte": 0,
        "HoursPerWeek": 14,
        "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": "cdw1qyvavn",
        "DisplayName": "Jewelery, Beauty & Movies"
      },
      "Division": {
        "ExternalId": null,
        "Code": null,
        "Name": null
      },
      "Title": {
        "ExternalId": "C-19565774",
        "Code": null,
        "Name": "Senior Creative Coordinator"
      },
      "Organization": {
        "ExternalId": null,
        "Code": null,
        "Name": null
      },
      "Custom": {},
      "Source": {
        "SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
        "DisplayName": "HR generator"
      }
    }
  ],
  "PrimaryContract": {
    "Context": {
      "InConditions": false
    },
    "ExternalId": "C-41151375",
    "StartDate": "2012-05-23T00:00:00Z",
    "EndDate": "2031-06-17T00:00:00Z",
    "Type": {
      "Code": null,
      "Description": null
    },
    "Details": {
      "Fte": 0,
      "HoursPerWeek": 14,
      "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": "cdw1qyvavn",
      "DisplayName": "Jewelery, Beauty & Movies"
    },
    "Division": {
      "ExternalId": null,
      "Code": null,
      "Name": null
    },
    "Title": {
      "ExternalId": "C-19565774",
      "Code": null,
      "Name": "Senior Creative Coordinator"
    },
    "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-21T00: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": "27f65293-ed6a-4018-9072-f9a7ef743bdf",
    "ExternalId": "00248674",
    "DisplayName": "Virginia Kunze (00248674) - HR generator",
    "Email": "[email protected]"
  },
  "Custom": {},
  "Source": {
    "SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
    "DisplayName": "HR generator"
  }
}
$personDifferences

  • Direction: input

  • Datatype: JSON

Contains the differences between $previousPerson and $person. Useful to make targeted API calls to update only certain fields in target accounts, instead of overwriting the entire target account. Only used in the Account Update script script.

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 contains dummy data.

Example
{
  "DisplayName": {
    "Change": "updated",
    "New": "Jimmy Doe",
    "Old": "John Doe"
  },
  "ExternalId": {
    "Change": "updated",
    "New": null,
    "Old": "123456789"
  },
  "UserName": {
    "Change": "updated",
    "New": "JimmyD",
    "Old": null
  },
  "Name": {
    "GivenName": {
      "Change": "updated",
      "New": "Jimmy",
      "Old": "John"
    }
  },
  "Contracts": [
    {
      "Change": "removed",
      "Old": {
        "ExternalId": "3",
        "StartDate": null,
        "EndDate": null,
        "Type": null,
        "Details": null,
        "Location": null,
        "CostCenter": null,
        "CostBearer": null,
        "Employer": null,
        "Manager": null,
        "Team": null,
        "Department": null,
        "Division": null,
        "Title": null,
        "Organization": null,
        "Custom": null,
        "OriginalPersonId": null,
        "Source": null
      },
      "OldIndex": "_2"
    },
    {
      "Change": "added",
      "New": {
        "ExternalId": "4",
        "StartDate": null,
        "EndDate": null,
        "Type": null,
        "Details": null,
        "Location": null,
        "CostCenter": null,
        "CostBearer": null,
        "Employer": null,
        "Manager": null,
        "Team": null,
        "Department": null,
        "Division": null,
        "Title": null,
        "Organization": null,
        "Custom": null,
        "OriginalPersonId": null,
        "Source": null
      },
      "Index": "2"
    },
    {
      "Change": "updated",
      "Index": 0,
      "Value": {
        "StartDate": {
          "Change": "updated",
          "New": null,
          "Old": "2022-09-30T00:00:00+00:00"
        },
        "EndDate": {
          "Change": "updated",
          "New": "2022-09-30T00:00:00+00:00",
          "Old": null
        }
      }
    },
    {
      "Change": "updated",
      "Index": 1,
      "Value": {
        "EndDate": {
          "Change": "updated",
          "New": "2022-09-30T00:00:00+00:00",
          "Old": "1970-01-01T00:00:00Z"
        }
      }
    }
  ],
  "Custom": {
    "OldCustomField": {
      "Change": "removed",
      "Old": "This custom field has always been here."
    },
    "NewCustomFIeld": {
      "Change": "added",
      "New": "This is a new custom field."
    }
  }
}
$previousAccount

  • Direction: output

  • Datatype: PSCustomObject

Contains all fields from the previous $account object. Only used in the Account Update script.

Should be sent to HelloID in the PreviousAccount property of $result.

Example
$previousAccount = [PSCustomObject]@{
    DisplayName = $p.DisplayName
    FirstName   = $p.Name.NickName
    LastName    = $p.Name.FamilyName
    UserName    = $p.UserName
    Title       = $p.PrimaryContract.Title.Name
    Department  = $p.PrimaryContract.Department.DisplayName
    StartDate   = $p.PrimaryContract.StartDate
    EndDate     = $p.PrimaryContract.EndDate
    Manager     = $p.PrimaryManager.DisplayName
}
$previousPerson

  • Direction: input

  • Datatype: JSON

Tip

In most cases, it is easier to use the pre-calculated $personDifferences object instead of $previousPerson.

Contains all fields from the previous person object, i.e., in the second-to-most-recent snapshot. Only used in the Account Update script script.

This also corresponds to the values labeled Old when you View a snapshot for the current snapshot:

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

$previousPerson is only usable in production. In the script preview, $previousPerson is always identical to $person.

Example
{
  "Contracts": [
    {
      "Context": {
        "InConditions": false
      },
      "ExternalId": "C-41151375",
      "StartDate": "2012-05-23T00:00:00Z",
      "EndDate": "2031-06-17T00:00:00Z",
      "Type": {
        "Code": null,
        "Description": null
      },
      "Details": {
        "Fte": 0,
        "HoursPerWeek": 14,
        "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": "cdw1qyvavn",
        "DisplayName": "Jewelery, Beauty & Movies"
      },
      "Division": {
        "ExternalId": null,
        "Code": null,
        "Name": null
      },
      "Title": {
        "ExternalId": "C-19565774",
        "Code": null,
        "Name": "Senior Creative Coordinator"
      },
      "Organization": {
        "ExternalId": null,
        "Code": null,
        "Name": null
      },
      "Custom": {},
      "Source": {
        "SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
        "DisplayName": "HR generator"
      }
    }
  ],
  "PrimaryContract": {
    "Context": {
      "InConditions": false
    },
    "ExternalId": "C-41151375",
    "StartDate": "2012-05-23T00:00:00Z",
    "EndDate": "2031-06-17T00:00:00Z",
    "Type": {
      "Code": null,
      "Description": null
    },
    "Details": {
      "Fte": 0,
      "HoursPerWeek": 14,
      "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": "cdw1qyvavn",
      "DisplayName": "Jewelery, Beauty & Movies"
    },
    "Division": {
      "ExternalId": null,
      "Code": null,
      "Name": null
    },
    "Title": {
      "ExternalId": "C-19565774",
      "Code": null,
      "Name": "Senior Creative Coordinator"
    },
    "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-21T00: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": "27f65293-ed6a-4018-9072-f9a7ef743bdf",
    "ExternalId": "00248674",
    "DisplayName": "Virginia Kunze (00248674) - HR generator",
    "Email": "[email protected]"
  },
  "Custom": {},
  "Source": {
    "SystemId": "36c440ef-a8e5-4686-9abd-8c45125cdd09",
    "DisplayName": "HR generator"
  }
}
$resourceContext

  • Direction: input

  • Datatype: JSON

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
{
  "SourceData": [
    "zifa92ldvk",
    "imudgaptwt",
    "fo7w13ugoa",
    "p504w51ohe",
    "wq0d3r5437",
    "17thfkl0kg",
    "7ojvyyms5y",
    "bbot9zbd53",
    "776gak2muw",
    "xo30oi5pq9"
  ]
}
$result

  • Direction: output

  • Datatype: PSCustomObject, converted to JSON

Most scripts in PowerShell 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
    AccountReference = $accountGuid
    AuditLogs        = $auditLogs
    Account          = $account

    # Optionally return data for use in other systems
        ExportData = [PSCustomObject]@{
            DisplayName = $account.DisplayName
            UserName    = $account.UserName
            ExternalId  = $accountGuid
    }
}

Write-Output $result | ConvertTo-Json -Depth 10
$subPermissions

  • Direction: output

  • Datatype: JSON

Used in Permissions-related scripts for permission sets which are using Sub-permissions.

You build this object yourself and send it back to HelloID in the SubPermissions property of $result. This allows HelloID to track the state of granted sub-permissions.

Example
$subPermissions = [Collections.Generic.List[PSCustomObject]]::new()

foreach ($permission in $desiredPermissions.GetEnumerator()) {
	$subPermissions.Add([PSCustomObject]@{
		DisplayName = $permission.Value
		Reference   = [PSCustomObject]@{
			Id = $permission.Name
	}
})
$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: