ERP / HRIS Integration

Typical self-service integration with your ERP / HRIS platform for Ready to Hire candidates using the REST API.

Scenario

When a candidate is ready to hire, their details are added to your ERP system and the originating Oleeo Recruit system is also updated with an ERP reference.

This example will involve using the REST API

Steps

Webhook Notification

API consumers subscribe to a notification for candidates at a status of ‘Ready to Hire’. When a candidate’s application reaches that status a JSON payload is posted to the consumer Endpoint URL informing the consumer of the application id and REST API endpoint to use.

Retrieve Candidate Resource Details

Consumer calls the supplied endpoint and retrieves the application information including the candidate details and any additional information required for the ERP such as some of the vacancy details. Update the ERP records with the data as per your ERP integration method.

Update Candidate with ERP reference values

Consumer then calls the candidate application endpoint to update any values returned from the ERP and to flag it has been exported.

Setup Webhook Notification

Set up a Webhook so we can be notified when there are new candidates at a Ready to Hire status in the Oleeo Recruit system.

The notification consists of a topic which is the trigger for the change and a subscription which tells the system where to send the notification.

Topic

The notification topic will be setup to trigger whenever an application changes to a status of Ready to Hire, which in this case we know is id 279.

Create a Notification Topic

 POST https://example.tal.net/api/v1/notification_topics
{
 "type": "STATE_CHANGE_APPLICATION",
 "name": "Application status change",
 "description": "Application status has changed to Ready to Hire",
 "expression": "application.main_process_state.state.id == 279"
}
Your system will have different statuses so you’ll need to use the REST API to find the list of statuses and their respective ids to select the appropriate status id for your trigger.
Get a list of Statuses to find the appropriate ids
GET https://example.tal.net/vx/config-jail/api/v1/states


Example Response Body
{
   "description": "Congratulations. Welcome to Oleeo",
   "applicant_title": "Application successful",
   "status_groups": [
     {
       "title": "Offer Stage",
       "id": 29,
       "url": "https://example.tal.net/vx/api/v1/status_groups/29"
     }
   ],
   "is_deprecated": false,
   "process_type": "application",
   "id": 279,
   "offline_entry_point": false,
   "processes": [
     {
       "id": 12,
       "title": "Standard Application Process"
     },
     {
       "title": "Electronic Document Signature",
       "id": 26
     }
   ],
   "title": "Offer - accepted (docs received)",
   "display_order": 98,
   "is_terminal": false,
   "url": "https://example.tal.net/vx/api/v1/states/279"
 },

Subscribe to Notification Topic

Now we’ve created a topic for applications at a Ready to Hire status, we can subscribe to it. This allows us to set a URL which the notification will be sent to and a period this subscription should cover.

To get a list of topics and their ids call the GET notification_topics enpoint in the REST API

Create a subscription to the topic with a start and end date, along with the URL you require the notification to be sent to.

Get all the notification topics if you need to check any details
GET https://example.tal.net/vx/config-jail/api/v1/notification_topics


Post the subscription to the topic
POST https://example.tal.net/api/v1/notification_topics/123/subscriptions
{
"start_dt": "2021-10-12T09:22:30.579Z",
"end_dt": "2022-10-12T09:22:30.579Z",
"destination_url": "https://myapp.example.com/webhooks"
}

Receive Notification

When a candidate’s application moves to a status Ready to Hire (or whichever status was setup in your notification topic) a payload as shown in the example will be sent to the destination URL setup in the topic above. In our case we set it to https://myapp.example.com/webhooks

The Payloads do not contain actual data attributes, instead they contain just IDs and URLs so that suitably privileged client applications can fetch the details if required.

In this case we can see that user that caused the event, the subscription and topic that triggered the event and the details which can be used to retrieve the appliciation resource. In this example it’s Application id 222.

The Webhooks page provides more detail on payloads and authentication.

Example Notification Payload 

{
  "message_id": "51dd550c-6dda-4dd2-81f4-3309bb04d094",
  "timestamp": "2021-10-13T16:50:12Z",
  "details": {
    "id": 222,
    "url": 'http://example.tal.net/vx/api/v1/applications/222'
    "state_changes":
      "url": 'http://example.tal.net/vx/api/v1/applications/222/history'
  },
  "user": {
   "id": "36",
   "url": "https://example.tal.net/vx/api/v1/recruiters/36"
  },
  "subscription": {
    "id": 10,
    "url": "https://example.tal.net/vx/api/v1/notification_topics/4/subscriptions/10",
    "uuid": "c34db4e8-ffc0-40dc-9150-cce795cbf3c2",
    "topic": {
      "url": "https://example.tal.net/vx/api/v1/notification_topics/4",
      "uuid": "218fc25b-9dd8-4793-be92-14a5d391da31",
      "id": 4
    }
  }
}

Retrieve Application Resource Details

From the notification payload we can use the URL supplied to retrieve the resource.

The default payload returns basic information about the vacancy and candidate, along with some information about other actions available which we can ignore here.

Depending on the information required for the ERP we can return additional information in the call to include fields such as department etc by including a layout listing with any additional resource information.

Retrieve the resource for application id 222
  GET http://example.tal.net/vx/api/v1/applications/222


{
  "submitted_dt": "2019-02-11T09:25:19Z",
  "url": "https://example.tal.net/vx/api/v1/applications/222",

  ...
  "vacancy": {
    "url": "https://example.tal.net/vx/api/v1/vacancies/43",
    "title": "Python Developer",
    "id": 43
  },
  "user": {
    "url": "https://example.tal.net/vx/api/v1/candidates/185",
    "lastname": "Smith",
    "email": "bob.smith@example.com",
    "id": 185,
    "firstname": "Bob"
  },
  "id": 222
  ...

}

Update Candidate with ERP details

With resource information from the previous calls we can update the ERP with the information required. Once this is done we can update the Candidate record in Oleeo Recruit with a success flag that it has been updated in the ERP and optionally add other information such as an ERP reference if available.

In this situation we have two fields in Oleeo Recruit; ERP reference and ERP successful with ids 83354 & 83355 respectively.

Update the resource for application id 222 to show ERP reference and flag successful

POST https://example.tal.net/vx/api/v1/applications/222/form_values

Body 
{
  "log_history": true,
  "transaction": [
    {
      "item_id": 83354,
      "values": [
        {
          "instance": 1,
          "value": "ERP39939",
          "log_history": true
        }
      ]
    },
    {
      "item_id": 83355,
      "values": [
        {
          "instance": 1,
          "value": "1",
          "log_history": true
        }
      ]
    }
  ]
}