Skip to main content

HelloID

Persons import script

In the persons import script, you retrieve the raw personnel data that you'll use in Source mappings to generate your Persons and Contracts objects. It runs during the Imports process.

Note

Changes to the persons and/or departments import scripts do not have any effect during snapshots. They only have an effect during Imports.

To get started, Customize the persons import script.

2021-11-17_14-57-18.png

Write your retrieval logic (i.e., query your external HR database) in the if(-Not($dryRun -eq $True)) { } statement at the beginning of the script. When you are editing and previewing the script, HelloID sets $dryRun to false. When the script runs in production, HelloID sets it to true.

How, and from where you retrieve this information is up to you. For example:

  • For systems that provide a REST API, use the Invoke-WebRequest cmdlet to launch a GET request.

  • For flat files, use the Import-CSV cmdlet to read the data into memory.

Subsequently, using the retrieved raw personnel data, construct a $persons array. Each person is a hash table in this array. The requirements for each person are:

ExternalId

A unique identifier of your choice (e.g., a GUID)

DisplayName

A display name for the person (e.g., John Doe)

contracts

An array containing at least one hash table. Hash tables in this array define the person's Contracts. Each contract must have a DepartmentCode, which must correspond to the ExternalId of a department defined in the Departments import script.

You can add as many additional custom key/pair values to these hash tables as needed, to accommodate whatever data is in your external HR database.

After building your $persons array, send it to HelloID. Loop through the array and send each person individually via the Write-Output cmdlet (converted to a JSON string). For example, if you have 1,000 persons, Write-Output must be called 1,000 times. This is demonstrated in the for loop, below.

$numberOfPersons = 5

if(-Not($dryRun -eq $True)) {
    # Write real import logic here
    $numberOfPersons = 25    
}

Write-Verbose "Starting person import" -Verbose
for ($i=0; $i -lt $numberOfPersons; $i++) {
$persons = @(
        @{
            ExternalId	= "JohnD-$i"
            DisplayName	= "John Doe"
            FirstName	= "John"
            LastName	= "Doe"
            Convention	= "B"
            Contracts	= @(
                @{
                    SequenceNumber	= "1"
                    DepartmentName	= "Administration"
                    DepartmentCode	= "ADMINISTR"
                    TitleName		= "Manager"
                    TitleCode		= "Man"
                    StartDate		= Get-Date("2018-01-01") -Format "o"
                    EndDate		= $null
                }
            )
        },
        @{
            ExternalId	= "JaneD-$i"
            DisplayName	= "Jane Doe"
            FirstName	= "Jane"
            LastName	= "Doe"
            Convention	= "B"
            Contracts	= @(
                @{
                    SequenceNumber	= "1"
                    DepartmentName	= "Administration"
                    DepartmentCode	= "ADMINISTR"
                    TitleName		= "Secretary"
                    TitleCode		= "Sec"
                    StartDate		= Get-Date("2015-03-02") -Format "o"
                    EndDate		= $null
                }
            )
        }
    )

    foreach ($person in $persons) {
        Write-Output $person | ConvertTo-Json
    }
}

Write-Verbose "Person import completed" -Verbose
In this section: