Introduction

Not every source of personnel data is a commercially available HRMS program. In fact, proprietary sources built in-house far outnumber the big names in the HRMS industry like SAP, ADP, and Workday. Other sources are just flat files, small Access databases, etc. 

Creating built-in connectors for thousands of home-grown personnel systems is impossible. But it is possible to integrate your organization's system using HelloID's custom PowerShell source system.

This article leads you through the basics of setting up and configuring the PowerShell source system in HelloID. Adapt the ideas and techniques introduced in this article to meet the needs of your own organization.

This configuration takes place in the System tab of the PowerShell source system. For information about configuring other tabs, which are common among all source systems, see Configure and manage source systems.

To get started, add a source system of the PowerShell type. Select the source system's wrench icon, and then select its System tab:

Basic configuration

In this section, we will define a static data set with a small number of users and departments so you can get a feel for how PowerShell source systems work.

Select the Persons and/or Departments buttons to edit their respective scripts. On the left side of the dialog is the script editor. On the right side is a preview area. When select the Preview button, the script is executed as a "dry run", where the $dryRun variable is set to true. Previews return up to the first 10 results.

Persons import script

The Persons script retrieves both Person and Contract data. 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 (see How to import a CSV file with a custom PowerShell source system). 
• For SQL databases, see How to connect to SQL with a custom PowerShell source system.

Place your import logic in the if statement at the beginning of the script.

Each Person object is represented as a PowerShell hash table object. That is, a collection of key/value pairs. You may import as many Persons as you wish, but you must ensure that each Person record has at least one field that uniquely identifies it, such as an employee ID or a GUID. This is the ExternalId.

Contracts define the employment details of each Person in your organization. They can include the start and end date of employment, cost center, department ID (more on that later), and more. Contract information is stored within a property called Contracts on the Person object as an array of hash tables.

After the Person objects have been collected from the source system and properly formatted, you must send them to HelloID. Each Person object must sent individually via the Write-Output cmdlet (as a converted JSON object). So, if you have 1,000 Person objects to send, Write-Output would be called 1,000 times—once for each object—instead of once for the entire batch. You can see this in our example with the foreach loop.

The following example script defines ten Person objects, each with a single Contract object.

$numberOfPersons = 5;

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

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 0";
                    DepartmentCode="ADMINISTR_0";
                    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 0";
                    DepartmentCode="ADMINISTR_0";
                    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 -Verbose "Person import completed";

Departments import script

The Departments script retrieves department information for your organization. Departments are referenced in contract objects. For example, John Doe has an employment contract as a Manager of the Administration department. Departments are defined separately from Persons and Contracts to facilitate a one-to-many relationship. That is, one Department can relate to many Persons and Contracts.

Just like Persons and Contracts, Departments are defined as hash table objects within PowerShell. The following code defines four Departments and sends them to HelloID as JSON objects via Write-Output.

$numberOfDepartments = 2;

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

$departments = @()
for ($i=0; $i -lt $numberOfDepartments; $i++) {
    Write-Output @(
        @{
            ExternalId="ADMINISTR_$i";
            DisplayName="Administration $i";
            Name="Administration $i";
            ManagerExternalId="JohnD-0";
        },
        @{
            ExternalId="HRM";
            DisplayName="Human & Resource management $i";
            Name="Human and Resource $i";
            ParentExternalId="ADMINISTR_$i";
        };
    ) | ConvertTo-Json;
}

Write-Verbose -Verbose "Department import completed";

Unlike Persons objects, Departments can be sent to HelloID as an array of objects, rather than individually. This is because there are fewer Departments than Persons within an organization, and fewer calculations are run on Departments on the back end of HelloID.

Wrapping up

Mappings

With your PowerShell scripts in place, you can now configure mappings in the Person and Contract tabs. Import the system's raw data, and then set the following mappings:

• Person
  • ExternalId
    ExternalId
  • Name.FamilyName
    LastName
  • Name.GivenName
    FirstName
  • Name.NickName
    FirstName
• Contract
  • Department.ExternalId
    DepartmentCode
  • EndDate
    EndDate
  • ExternalId
    SequenceNumber
  • StartDate
    StartDate

Import data

After your mappings are in place, perform a manual import to create a new snapshot.

Custom connector configuration

See Configure an input parameter form for source or target systems.

On-premises vs. cloud configuration

By turning off the Execute on-premises toggle you can execute your Persons and Departments PowerShell scripts directly on your HelloID cloud instance instead of on-premises via a locally running Agent. Be aware that functionality is currently limited to PowerShell Core commands and importing extra modules is not supported.

Specify Agent(s)

If you are running this system on-premises and have multiple Agents installed in your HelloID environment, you can specify which Agent(s) it can use. See Agent configuration for on-premises systems.