Skip to main content

HelloID

Departments import script

In the departments import script, you retrieve your raw Departments data. HelloID uses it to associate Contracts with departments during Imports, as well as to populate departments in Department conditions.

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 departments import script.

2023-05-16_14-33-00.jpg

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 department data, construct a $departments array. Each department is a hash table in this array. The attributes for each department include:

ExternalId

Required. A stable unique identifier of your choice. For example, HRM. HelloID uses it as follows:

DisplayName

Required. A department name of your choice. For example, Human & Resource management. HelloID uses it as follows:

  • As the display name of departments in contracts (via the same lookup process described above).

  • As the display name of departments in Department conditions

ManagerExternalId

Optional. HelloID looks up each person's mapped Person.ExternalId against the ManagerExternalIds defined in this script, to determine which department they manage (if any). This process depends on the manager determinant setting; see Managers.

ParentExternalId

Optional. If specified, must be the ExternalId of this department's parent department. Used for the specifically hierarchical aspects of manager determination. Also depends on the manager determinant.

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

$numberOfDepartments = 2
if(-Not($dryRun -eq $True)) {
    # Write real import logic here
    $numberOfDepartments = 20    
}

Write-Verbose "Starting department import" -Verbose
for ($i=0; $i -lt $numberOfDepartments; $i++) {
    Write-Output @(
        @{
            ExternalId          = "ADMINISTR_$i"
            DisplayName         = "Administration $i"
            ManagerExternalId   = "JohnD-0"
        },
        @{
            ExternalId          = "HRM_$i"
            DisplayName         = "Human & Resource management $i"
            ParentExternalId    = "ADMINISTR_$i"
        }
    ) | ConvertTo-Json
}

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