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. To that end, HelloID has provided the PowerShell source system in its provisioning module.
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.
To get started, add the PowerShell source (on premise) system by following the instructions in this article. Accept the default scripts that is present in the Specific step of the wizard—we will change them in the course of this article.
Configure the PowerShell Source System
After adding the PowerShell source system, you will immediately be taken to its configuration screen. If this is not the case, you can navigate to the target systems overview and click the system's wrench icon to begin configuration.
This article will cover 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.
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 that you can get a feel for how the system works and interacts with HelloID.
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 them, 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 a single person object with a single contract object, and sends it to HelloID with the Write-Output cmdlet (as a converted JSON object).
$persons = @(
Contracts = @(
StartDate= Get-Date("2018/01/01") -Format "o";
Contracts = @(
StartDate= Get-Date("2015/03/02") -Format "o";
foreach ($person in $persons)
Write-Output $person | ConvertTo-json
Write-Verbose -Verbose "Person import completed";
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 Write-Output. 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 model of a person is a JSON object that tells HelloID which fields of the person are available for mapping in the Person tab. The field names in the mapping should match those available on the object defined in the script (see above section), and are case-sensitive. You only need to define the precise fields you want available for import into HelloID; any non-essential fields can be left out of the model definition.
Using the previous example of the Persons PowerShell script, we would use the following code for the model. These fields will then be available for mapping on the Person tab. Note the absence of the Contracts field—that is defined separately, and covered in the next section of this article.
Similar to the person model, the contract model tells HelloID which fields of the Contracts object will be available for mapping in the Contract tab. All non-essential fields can be left out of the model.
Once again using the previous example of the Persons PowerShell script, we would use the following code for the contract model:
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 contracts and persons.
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 = @(The relationship between contracts and departments is defined in the Contract tab by setting the Department.ExternalId field.
Write-Output $departments | 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 due to the fact that there are fewer departments than persons within an organization, and fewer calculations are run on departments on the back end of HelloID.
With your PowerShell scripts and models 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:
- ExternalId: ExternalId
- Name.FamilyName: LastName
- Name.GivenName: FirstName
- Name.NickName: FirstName
- Department.ExternalId: DepartmentCode
- EndDate: EndDate
- ExternalId: SequenceNumber
- StartDate: StartDate
Once the scripts, models, and field mappings are in place, you can import the source data into HelloID. To do so, refer to the "Manual Import" section of this article.