cancel
Showing results for 
Search instead for 
Did you mean: 

HRIS Integration Deep Dive - Onboarding

shawnsong
Rising Star II
Rising Star II

Hey Folks,

(A massive kudos to my colleague @SamMorganJC  for supporting me throughout the process! This post wouldn't have been possible without her invaluable guidance.)

Following my post about onboarding users from HRIS to JC, a lot of people have been asking about how to practically build the integrations in the first place.

I would like to address the "how" with a structure that looks like this:

  • Leverage the pre-built integrations in JC.
  • Use the custom API import integration option in JC.
  • Utilise third-party workflow automation tools.
  • Use custom scripting.

The primary focus of this post is onboarding, as the title suggests, since this is the area where most assistance is needed.

The magic occurs when a user is created in the "Staged" status and is ready to be "Activated" on the onboarding date.

Based on each user's department, we utilise the "Automated Group Membership" (an EA feature) to organise users into groups with corresponding applications bound at the group level.

In short, users will have access to the applications specific to their designation on day one. Boom!

Let’s dive deeper into it, shall we? 

The pre-built integrations

The pre-built integrations are the most recommended and probably the easiest approach out there. Here is the complete list of native integrations we have built so far:

Integrating BambooHR with JumpCloud

Integrating Bob with JumpCloud

Integrating with Gusto

Integrating with Namely (SCIM)

Integrating with Personio

Workday Integration

Integrating with Paylocity New!

Here is an example setting up the integration with Personio:

shawnsong_0-1680775326722.png

shawnsong_1-1680775334855.png

Now let’s import the new hires:

shawnsong_2-1680775367329.png

The custom API import integration in JumpCloud

Prerequisites - for the HRIS

  • Supports API Key, Bearer Token, or OAuth 2.0 authorization code as the authentication method.
  • An integration cannot be created for any application with the API that:
    • Requires multiple custom headers.
    • Does not return the full schema for the list users endpoint. (e.g., only ids are returned)
    • Returns responses in any format other than JSON.
    • Requires the following authentication methods: OAuth 2.0 basic auth header, client credentials, refresh token, or authorisation code with PKCE.

Here is a sample data from an API key based HRIS, in JSON format:

 

 "employees": [
       {
           "id": "2351",
           "jobTitle": "Sales Manager",
           "lastName": "Doe",
           "location": "USA",
           "pronouns": null,
           "username": "John.doe",
           "firstName": "John",
           "workEmail": "John.doe@shawntest.com",
           "workPhone": null,
           "department": "Sales",
           "supervisor": null,
           "displayName": "JohnDoe",
           "mobilePhone": null,
           "preferredName": null,
           "canUploadPhoto": null,
           "onboardingDate": "2023-05-04T16:00:00.000Z",
           "employeementstatus": "active"
       },
       {
           "id": "12461",
           "jobTitle": "Sr. SRE",
           "lastName": "Roe",
           "location": "SGP",
           "pronouns": null,
           "username": "Jane.roe",
           "firstName": "Jane",
           "workEmail": "Jane.roe@shawntest.com",
           "workPhone": null,
           "department": "Engineering",
           "supervisor": null,
           "displayName": "JaneRoe",
           "mobilePhone": null,
           "preferredName": null,
           "canUploadPhoto": null,
           "onboardingDate": "2023-06-06T16:00:00.000Z",
           "employeementstatus": "active"
       }
   ],
   "total_count": 2

 

 

You may follow the steps here for setting it up. It looks like this on mine:

shawnsong_3-1680775470396.png

shawnsong_4-1680775488856.png

Once the connection is up, you can start import the users by click the “start manual import” button:

shawnsong_5-1680775514930.png

shawnsong_6-1680775528683.png

Note: We will soon have a brand new capability to import the users on hourly basis, this is how it looks like: 

shawnsong_7-1680775555484.png

(Thanks for the heads up, Sam!)

3rd party workflow automation approach

TL;DR - For detailed steps, please follow this link

All you need to do is keep the CSV updated with the newcomers on the new rows, and Make.com will pick them up on a schedule, which is by default every 15 minutes.

The onboarding process looks like this:

makeFlow.gif

The custom scripting approach

This the last resort for the case that:

  • You just wanted a simple script to get the job done.
  • OR a CSV and a terminal are all you got.

Here is a sample script, assuming we are calling the same API as the section 2 “Custom API import”:

 

# Calling the API to get the data
# Using an example here where assuming the API is service agnostic
#
################################################################################
$url = 'http://your.hris.com'
$apiKey = "your-api-key"
$headers = @{
   'Content-Type' = 'application/json'
   'x-api-key' = $apiKey
}
################################################################################
# Do not edit below
################################################################################


# getting the data from via api
$data = Invoke-RestMethod -Uri $url -Method Get -Headers $headers


# creating the new users
foreach ($e in $data.employees){


 try {
   $newuser =  New-JCUser -firstname $e.firstName`
    -lastname $e.lastname -email $e.workEmail`
    -location $e.location -employeeIdentifier $e.id`
    -displayname $e.displayname -jobTitle $e.jobTitle`
    -department $e.department -username $e.username


   New-JcSdkBulkUserState -StartDate $e.onboardingDate -State ACTIVATED -UserIds $newuser._id
 }
 catch {
   Write-Error $_.Exception.Message # Will display an error if the user by any chance already been created
 }
   
}

 

And this is for the CSV scenario (you can use the CSV template in the same link above):

 

# Reading the CSV for HR data#
################################################################################


$csv = "/your/path/to/OnboardingCSVSample.csv"
$companyDomain = "yourcompany.com" # use your corp email domain here


################################################################################
# Do not edit below
################################################################################


# getting the data from via api
$data = Import-Csv $csv


# creating the new users
foreach ($e in $data){


   # generating the user name by convention: firstname.lastname
   $username = $e."First Name".trim().tolower() + '.' + $e."Last Name".trim().tolower()
   $email = $username + "@"+ $companyDomain
   $displayname = $e."First Name" + ' ' + $e."Last Name"


   # coverting the start date to datetime structure
   $formatString = "yyyy-MM-ddTHH:mm:ss.fffZ"
   $onboardingdate = get-date $e."start date" -Format $formatString 
  
   try {
   $newuser =  New-JCUser -firstname $e."First Name"`
       -lastname $e."Last Name" -email $email`
       -location $e.location -employeeIdentifier $e."Employee Id"`
       -displayname $displayname -jobTitle $e."Job Title"`
       -department $e.Department -username $username


   New-JcSdkBulkUserState -StartDate $onboardingdate -State ACTIVATED -UserIds $newuser._id
   }
   catch {
       Write-Error $_.Exception.Message # Will display an error if the user by any chance already been created
   }
   
}

 

Done!

Thanks for reading all the way thus far - it’s a long post 😀. I hope it helps!

1 REPLY 1

JCDavid
Iron I
Iron I

very helpful information!