New hires, payroll and onboarding

This article describes how to build a new hires app (e.g. onboarding or payroll) in Talent App Store.

New hires apps learn about job applications that have transitioned into a new "phase" such as Hired, using the batch oriented pull APIs, and optionally the more real time push APIs.

Both models rely heavily on application views. You'll need a good understanding of views to build your app. You can learn about views here.

Pulling events

In this example, your app uses the pull model to maintain its set of recent new hires:

• Your app consumes the pull API GET /applications/views/at/onboard/now.
  
• A new hire is made:

• Fred applies for a job, resulting in a job application
  
• The recruitment team moves the application into the "shortlist" phase and evaluates Fred's suitability
• Eventually the team decides to hire Fred, and moves the application into the "onboard" phase.

• On the hour, your app starts its scheduled pull of the latest candidates to be onboarded.
  
• Your app consumes GET /applications/views/at/onboard/now

• Filtering to only get new onboarders since the previous upload
  
• The response includes a view for every new onboarder

• Once complete, your app stores the date of this upload, so it can be used as a filter when the upload next runs.
  

Using incoming push events

In this example, your app uses the push model:

• Your app produces the push API POST /applications/views/at/onboard/now/byID/{application}/pushes.
  
• Fred applies for a job, resulting in a job application
• The recruitment team moves the application into the "shortlist" phase and evaluates Fred's suitability
• Eventually the team decides to hire Fred, and moves the application into the "onboard" phase.
• Immediately, the applicant tracking system (ATS) notifies your app by consuming POST /applications/views/at/onboard/now/byID/{application}/pushes on it.
  
• The request body includes a view - a formatted json object containing all the data your app needs about the job application, the candidate, the job, and other resources such as the job's manager and recruiter.

You can use push events alone for integration if you want. However if your system is down, or an API call is lost on the internet, then you may miss out on a new hire.

This is not a good thing, as it can be quite a hassle for someone at the customer or the ATS support team to remedy the situation.

Even when using push, its good practice therefore to always pull events, just to pick up on any that you may have missed the push event for.

Setup

Let's look at the push APIs in action by installing some apps.

Install apps and prepare test data

• First, follow these instructions to install Developer ATS and create a job application.
  
• Return to Developer ATS and you should see the incoming job application (in the Incoming bucket).
• Install the Developer Alerts app. This is a test app that listens to the push APIs, and emails the view to you.
  
• Open and sign into Developer Alerts, and enable notifications for "Hire".

In the following steps, we'll complete the setup to get a view, containing a new custom data field, pushed to the Developer Alerts when a a new hire is made.

Capture data into a custom field when a new hire is made

• Click to Settings -> Custom Fields -> Candidate -> User Provided.
  
• Create a date field with the title "Date hired", and key "DATEHIRED".
• On the same page, click the Workflow mappings tab.
  
• Check the box to map your new field to the Hired bucket - i.e. you are saying that when a new hire is made the field should be provided.

Add your custom field to the default view

• Click to Setting -> Views and edit the default view.
  
• Under candidate, you'll see your Date hired field - check to add it to the default view.

Map the default view to the new hires event, for the test app

• Click to Settings -> Pushes. We want the default view to be pushed to the Developer Alerts app whenever a new hire is made, so create a new push with these details:
  

• A name (anything)
  
• The app (Developer Aalerts in this case)
• The view to be used (default)
• The phase (Hire)

Make the new hire

Now that setup is complete:

• Go back to Developer ATS, and click to move your job application to the Hired bucket.
  
• You'll see your new field - enter a date in it and complete the move.

You're done! Now check your email (including your spam folder) and you should see an email from the Developer Alerts app, with the contents of the default view, including your custom field.

API flow to/from your app

Implementing the APIs

Produced APIs

These are APIs that your app exposes for other apps to consume them.