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 Namely (SCIM)
Integrating with Paylocity New!
Here is an example setting up the integration with Personio:
Now let’s import the new hires:
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:
Once the connection is up, you can start import the users by click the “start manual import” button:
Note: We will soon have a brand new capability to import the users on hourly basis, this is how it looks like:
(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:
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!
