Does your company struggle to manage all of your internal applications used across your organization, especially as new hires are onboarded and need immediate access? Your employees want to add value on day one, and time spent manually getting them set up to different systems can lead to frustrations that can be easily automated through Cloud Elements. Their first impression of your company should be that of a seamless, world-at-your-fingertips, the-world-is-my-oyster, happy-go-lucky kind of impression.
Worry not - this tutorial is made to deliver just that! Following the steps below will get you on your way by allowing your customer’s to sync their Application Tracking Systems into your application, using the Cloud Elements’ event framework to capture when candidates are marked as hire. In the second tutorial of this series, we will discuss how to use that new employee event as a trigger to then onboard them into different systems.
USE CASE
Our customers in the HRIS, Payroll and Talent Acquisition ecosystem often aim to connect their customers’ Applicant Tracking Systems (ATS) to sync candidate data to/from their application. This tutorial focuses on integrating with your customers’ favorite ATS, syncing data to/from the ATS, and using Virtual Data Resources to construct callable resources with the data you care about.
PREREQUISITES
Before beginning the tutorial, ensure you have access to:
- Cloud Elements trial account (if you do not have one, sign up here)
- ATS sandboxes accounts (you will need at least 1), for example:
- SmartRecruiters
- Taleo Business Edition
- Bamboo HR
- Greenhouse
- SuccessFactors
- See a full list of our Human Capital Elements to connect to here
Additional resources:
- Cloud Elements Introduction – overview of Cloud Elements concepts
- Integration & Authentication – video explaining instance creation (UI + API)
- Defining Virtual Data Resources – defining the data you care about
INSTRUCTIONS
This tutorial will cover:
- Connecting to the ATS
- Creating Virtual Data Resources
- Using Cloud Elements’ Platform APIs
Before you begin, log in to your Cloud Elements trial account and have a look around!
Important: all functionality done within the Cloud Elements Platform UI can also be done through an API call, as Cloud Elements is 100% API-first. To illustrate this, the steps below will include example API calls throughout.
1. CONNECTING YOUR ATS
This section details how to create an Element Instance to each of your customer’s ATS endpoints. An Instance represents an authenticated connection to an Element using you/your customer’s ATS account credentials.
In your Cloud Elements account, go to the Elements page and search for one of the ATS Elements for which you have access to an account. Hover over the Element card and click “Authenticate.” This takes you to the Instance Creation page:
- Provide a unique instance name (e.g., Customer A, or a name of one of your customers)
- Add the proper configuration information requested (e.g., API key).
- Toggle on “Events Enabled” (you can keep the default set-up as is, but may want to shorten the event poller refresh interval if you would like to poll more frequently )
- Click “Create Instance”
- Repeat this process for each ATS for which you have access
An example of SmartRecruiters’ authentication process is as follows (including the corresponding API call):
Via API:
curl -X POST 'https://staging.cloud-elements.com/elements/api-v2/elements/11749/instances' \ -H 'Authorization: User ******, Organization ******' \ -H 'Content-Type: application/json' \-d '{ "name": "Customer A", "configuration": { "authentication.type": "custom", "event.vendor.type": "polling", "event.poller.refresh_interval": "2", "event.notification.enabled": true, "event.poller.configuration": "{\"candidates\":{\"url\":\"/hubs/humancapital/candidates?where=updatedAfter='${gmtDate:yyyy-MM-dd'T'HH:mm:ss.SSS'Z'}'\",\"idField\":\"id\",\"datesConfiguration\":{\"updatedDateField\":\"updatedOn\",\"updatedDateFormat\":\"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'\",\"updatedDateTimezone\":\"GMT\",\"createdDateField\":\"createdOn\",\"createdDateFormat\":\"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'\",\"createdDateTimezone\":\"GMT\"}},\"jobs\":{\"url\":\"/hubs/humancapital/jobs?where=updatedAfter='${gmtDate:yyyy-MM-dd'T'HH:mm:ss.SSS'Z'}'\",\"idField\":\"id\",\"datesConfiguration\":{\"updatedDateField\":\"updatedOn\",\"updatedDateFormat\":\"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'\",\"updatedDateTimezone\":\"GMT\",\"createdDateField\":\"createdOn\",\"createdDateFormat\":\"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'\",\"createdDateTimezone\":\"GMT\"}}}", "api.key": "******" }}'
You can confirm proper Instance creation by going to the Instances page and confirm your named Instance appears in the list (refresh the page, if needed).
Important: each Element Instance is associated with a unique Element Instance Token that will be used in all subsequent API calls to that credentialed endpoint. On the Instances page, toggle the show/hide token icon to see each Element Instance token.
2. CREATING VIRTUAL DATA RESOURCES
Next, let’s define the data you care about! A Virtual Data Resource (VDR), allows you to define a data model that is central to your application. Then, you can map that arbitrary data structure to the native objects within an ATS for which you have Element Instances, which is call a transformation. After saving that transformation, you can add the VDR into the API Docs for that Instance, which creates a callable API in the data format which you have created for each Element Instance mapped.
Virtual Data Resources allow for different levels of mapping depending on your access - organizational, account and instance. Organization level users can map at any level, while other users can map only at the instance level. An organizational level field mapping will automatically be applied to each transformation. The account level field will be applied to those transformations specific to an account. Instance level fields apply specifically to unique Element Instances to which they are mapped.
In our UI, go to the Virtual Data Resources (VDR) page and create a new VDR called “myCandidates.” Create a similar structure to the one below by creating a list of field names of interest (perhaps field names used within your application UI or database). Once complete, click “Save.”
After saving your VDR, on the right side of the screen, select “Create new transformation for ‘myCandidates’.” This will open up a dialogue; select (one of) the ATS Instance(s) you created in step 1 and then select your object of interest - “candidates.” This will create a template to start your VDR transformation for the selected Instance, where you can map the created field names (left), to the endpoint’s native fields (right) within the “candidate” object. VDRs can include custom Javascript, if needed, by clicking the <> symbol in the top right corner. Custom Javascript can be used when the basic object mapping does not meed your needs. For example, you might need to break a single address object into its component parts.
Important: for all scripts, Javascript 'strict' mode is enforced. ES6 is supported. The function parameters are immutable, meaning they cannot be assigned to directly.To change an object or value passed into the function, first copy it to your own local variable, and then make the necessary changes.
An example of a transformation and Javascript snippet has been included below for SmartRecruiters. After completing the transformation, click “Save.”
Custom Javascript (shows in screen when selecting '<>'):
// Copy the transformed object to a local variablelet obj = transformedObject;// Check to see of the original candidate object from SmartRecruiters// contains a primary assignment fieldif (originalObject.primaryAssignment) { // Update the job statuses field in the transformed object // with the primary assignment job status obj.jobStatuses = originalObject.primaryAssignment.status ? [originalObject.primaryAssignment.status] : [];}// Return the updated transformed objectdone(obj);
Important: after saving the transformation, click the settings wheel in the top right corner, toggle “Add to API Docs” on, and click save. This creates a callable API resource.
Repeat the transformation process for each ATS of interest.
If you would like to create and map a VDR via API, consider the following calls:
Creating the Virtual Data Resource:
curl -X POST 'https://staging.cloud-elements.com/elements/api-v2/organizations/objects/definitions' \ -H 'Authorization: User ******, Organization ******,' \ -H 'Content-Type: application/json' \ -d '{ "myCandidates": { "fields": [ { "path": "email", "type": "string" }, { "path": "employeeId", "type": "string" }, { "path": "firstName", "type": "string" }, { "path": "id", "type": "string" }, { "path": "jobStatuses", "type": "string" }, { "path": "lastName", "type": "string" }, { "path": "lastUpdated", "type": "string" }, { "path": "role", "type": "string" }, { "path": "startDate", "type": "string" } ] }}'
Creating the ATS Transformation:
curl -X POST \ https://staging.cloud-elements.com/elements/api-v2/organizations/elements/smartrecruiters/transformations/myCandidates \ -H 'Authorization: User ******, Organization ******' \ -H 'Content-Type: application/json' \ -d '{ "level":"organization", "vendorName":"candidates", "fields":[ { "path":"id", "type":"string", "vendorPath":"id", "vendorType":"string" }, { "path":"email", "type":"string", "vendorPath":"email", "vendorType":"string" }, { "path":"firstName", "type":"string", "vendorPath":"firstName", "vendorType":"string" }, { "path":"lastName", "type":"string", "vendorPath":"lastName", "vendorType":"string" }, { "path":"lastUpdated", "type":"string", "vendorPath":"updatedOn", "vendorType":"string" }, { "path":"role", "type":"string", "vendorPath":"primaryAssignment.job.title", "vendorType":"string" }, { "path":"startDate", "type":"string", "vendorPath":"primaryAssignment.startsOn", "vendorType":"string" } ]}'
3. USING NORMALIZED API CALLS
Now that we have connected to the proper Applicant Tracking Systems and created the myCandidates VDR, the new API is available on the endpoints and we can test out the true power of Cloud Elements’ normalized APIs.
Go to the Instances page, where you will find a list of your authenticated Element Instances. In the row of an Element Instance of choice that you have mapped to the myCandidates VDR (and selected to add to API docs), select the “API docs” button at the end of the row. This will bring you to the Element’s API documentation for you to test out different API calls.
Find the “GET /candidates” call. Toggle it open and Click the “Try it out” button. Click the blue “Execute” button that now appears. You will see the native response returned for all candidates at the endpoint.
Scroll down the page and repeat this process for “GET /myCandidates,” which is the VDR you created. After executing, you will see all of the candidates from the endpoint returned in the format you defined in your VDR.
Here is the API call to make to get the same response:
curl -X GET \ https://staging.cloud-elements.com/elements/api-v2/myCandidates \ -H 'Authorization: User ******, Organization ******, Element <Element_Instance_Token>' \ -H 'accept: application/json' \
Important: these calls look exactly the same for any ATS system you mapped your VDR to, with only the Element Instance Token in the Authorization header changing, and now you can guarantee the same data format returned for each Element.
Play around with other API calls for your authenticated Instances, including POST, PATCH and DELETE operations.
SUMMARY
By using the Cloud Elements platform, you have now set up at least one Applicant Tracking System integration by:
- Connecting your customer's ATS account, creating a live Element Instance
- Creating a Virtual Data Resource to represent the data that your application cares about, so you have one data model you can call for several endpoints, regardless of the native data structure
- Using Cloud Elements’ APIs to receive data from or push it to different endpoints in a standard format
This is just the start to the robust capabilities of the Cloud Elements platform. There is a complimentary tutorial that will allow you to automate onboarding workflows as candidates are marked as hired in your customer's ATS. In addition, you are now equipped to apply this use case to topics of similar functionality, like syncing requisitions or invoice data from ERPs. You can also repeat this tutorial with different endpoints.
QUESTIONS?
For any questions you may have during this tutorial, please email gts@cloud-elements.com. And if you're ready to discuss how you can improve your integration strategy, contact one of our API strategy specialists below.
