Overview

This recipe describes building 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:

1. Your app consumes the pull API GET /applications/views/at/onboard/now.
2. A new hire is made:
   1. Fred applies for a job, resulting in a job application
   2. The recruitment team moves the application into the "shortlist" phase and evaluates Fred's suitability
   3. Eventually the team decides to hire Fred, and moves the application into the "onboard" phase.
3. On the hour, your app starts its scheduled pull of the latest candidates to be onboarded.
4. Your app consumes GET /applications/views/at/onboard/now
   1. Filtering to only get new onboarders since the previous upload
   2. The response includes a view for every new onboarder
5. 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:

1. Your app produces the push API POST /applications/views/at/onboard/now/byID/{application}/pushes.
2. Fred applies for a job, resulting in a job application
3. The recruitment team moves the application into the "shortlist" phase and evaluates Fred's suitability
4. Eventually the team decides to hire Fred, and moves the application into the "onboard" phase.
5. Immediately, the applicant tracking system (ATS) notifies your app by consuming POST /applications/views/at/onboard/now/byID/{application}/pushes on it.
6. 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.

Available phases

Set up

Lets look at the push APIs in action by installing some apps.

Note: when installing apps, the apps that have links are sandbox apps that you install via their install token - the other apps can be found publicly listed (find them with "Browse apps").

Install apps and prepare test data

1. First, follow these instructions to install Developer ATS and create a job application.
2. Return to Developer ATS and you should see the incoming job application (in the Incoming bucket).
3. Install the Developer Alerts app. This is a test app that listens to the push APIs, and emails the view to you.
4. 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

1. Click to Settings -> Custom Fields -> Candidate -> User Provided.
2. Create a date field with the title "Date hired", and key "DATEHIRED".
3. On the same page, click the Workflow mappings tab.
4. 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

1. Click to Setting -> Views and edit the default view.
2. 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

1. 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:

1. go back to Developer ATS, and click to move your job application to the Hired bucket.
2. 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

Produce POST /tenants

The first API call incoming to your app is to tell you that a tenant has installed it.

Typically you might handle this API call by inserting into your customer table, sending an email to customer support team, etc. You might show the "setup required" icon and a settings page to facilitate this.

See installing and controlling setup and launch pages for more.

Produce POST /applications/views/at/hire/now/byID/{application}/pushes

Example

POST /applications/views/at/hire/now/byID/{application}/pushes

Request:

Each incoming POST to your app's endpoint contains a view, with details about the new hire.

The view is customised by the customer to include only the fields that you need for the integration.