Introduction

Not every source of personnel data is a commercially available HRMS program. Some sources are built in-house and are completely unique to the organization. Other sources are just flat files, small Access databases, and more. These custom sources far outnumber the big names in the HRMS industry like SAP, ADP, Workday, and more.

Creating built-in connectors for thousands of home-grown personnel systems is impossible. But it is possible for organizations to integrate these systems with HelloID on their own, using HelloID's custom PowerShell source system.

This article will lead you through the basics of setting up and configuring the PowerShell source system in HelloID. It will use two CSV flat files as an example data source. The ideas and techniques introduced in this article can be adapted or extended to meet the needs of your own organization.

This configuration takes place in the System tab of the PowerShell Source connector. For information about configuring other tabs, which are common among all source systems, please see this article.

This system also allows you to set an Icon on the General tab, which works exactly the same as icons for custom PowerShell target systems.

To get started, add a PowerShell source system. Accept the default scripts that are present in the Specific step of the wizard—we will change them in the course of this article.

Select the source system's wrench icon, and then select its System tab:

Basic Configuration

In this section, we will go over the very basics of configuring the custom PowerShell source connector. We will define a static data set with only a couple of users and departments so you can get a feel for how the system works and interacts with HelloID.

Person Data

Persons PowerShell Script

This area is where you define the PowerShell script that retrieves both Person and Contract information. How, and from where, you retrieve this information can vary widely. For systems that provide a REST API, you can use the Invoke-Webrequest cmdlet to launch a GET request. For flat files, you can use the Import-CSV cmdlet to read the file data into memory. These are just two examples.

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

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 must be stored within a property called "Contracts" on the Person object as an array of hash tables.

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

$persons = @(
 @{
    ExternalId="JohnD-01";
    DisplayName="John Doe";
    FirstName="John";
    LastName="Doe";
    Contracts = @(
        @{
            SequenceNumber="1";
            DepartmentName="Administration";
            DepartmentCode="ADMINISTR";
            TitleName="Manager";
            TitleCode="Man";
            StartDate= Get-Date("2018-01-01") -Format "o";
            EndDate= $null;
        };
    );
 },
 @{
    ExternalId="JaneD-02";
    DisplayName="Jane Doe";
    FirstName="Jane";
    LastName="Doe";
    Contracts = @(
        @{
            SequenceNumber="1";
            DepartmentName="Administration";
            DepartmentCode="ADMINISTR";
            TitleName="Secretary";
            TitleCode="Sec";
            StartDate= Get-Date("2015-03-02") -Format "o";
            EndDate= $null;
        };
    );
 }
);

Write-Verbose -Verbose "Person import completed";

Write-Output $persons | ConvertTo-Json

Once the Person objects have been collected from the source system and properly formatted, you can send them to HelloID. Each Person object should 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.

Department Data

Departments PowerShell Script

This area is where you define the PowerShell script that retrieves departmental information for your organization. Departments can be referred to by a Person's contracts. 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 a single Department and sends it to HelloID as a JSON object via Write-Output.

$departments = @(
 @{
    ExternalId="ADMINISTR";
    DisplayName="Administration";
    Name="Administration";
    ManagerExternalId="JohnD-01";
 },
 @{
    ExternalId="HRM";
    DisplayName="Human & Resource management";
    Name="Human and Resource";
    ParentExternalId="ADMINISTR";
 };
);

Write-Verbose -Verbose "Department import completed";

Write-Output $departments | ConvertTo-Json

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

Mapping

With your PowerShell scripts in place, you can configure the field mappings in the Person and Contract tabs. Using the examples above, you can set the following field mappings:

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

Learn more about these mappings here.

Import

Once the scripts and field mappings are in place, you can import the source data into HelloID. To do so, refer to the "Perform a manual import" section of this article.

Custom connector configuration

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

On-premise vs. cloud configuration

By turning off the Execute on-premises toggle you can execute your Persons and Departments PowerShell scripts directly on your HelloID instance's server instead of on-premise. A locally running Agent is not required to use this option. 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-premise and have multiple Agents installed in your HelloID environment, you can specify which Agent(s) it can use. See Specify Agent(s) for on-premise systems.