Toggle document index

Overview

See also the job board hub.

Building a job board app in Talent App Store is simple, and a basic integration requires only 3 APIs, as the job board hub does most of the heavy lifting.

Once your job board app is installed at a tenant, it will appear as a posting destination inside the job board hub.

The hub provides all the UI through which users post jobs to job boards and manage their postings.

The job board hub provides a posting form UI that the user uses to post a specific job in the ATS to a job board (i.e. create a posting). The same job in the ATS can be posted to multiple job boards, or posted multiple times to a single job board (e.g. with slightly different locations each time).

The hub dynamically modifies the posting form so that it contains the fields that your job board app requires for a posting, so your app doesn't need job posting UI of its own - the hub provides it.

Once the user completes the posting form, your app is alerted of the new posting via an API call, so that it can finally upload the posting into your own back end.

This guide steps you through each of the APIs your job board app will use.

APIs

Publish your board's details

The job board hub looks after all of a tenant's installed job boards, and stores details for each board such as its name, the fields it requires on the posting form, how long postings remain on the board for, etc.

So that the hub can learn about these details about your board, your app must publish its details by producing GET /jobBoards/forApp.

The hub calls this API on your app when it is installed at a tenant, and every time a tenant with your app installed is rebooted.

Via this API, you pass back all the details about your job board:

  • your job board's name
  • its domain (e.g. www.jobboard.com - used for source tracking by the job board hub to create trackers when it creates links to your board)
  • default ad duration (how long do ads remain up on your site, e.g. 30d)
  • fields list (what fields appear on your board's posting form - e.g. job title, recruiter email, minimum salary)
  • default legacy source code (e.g. source=BIGJOBS)
  • a default value for the installed board's setup error message. If not null, setup required will light up on the app for all new installs.

In the example below, the job board has 4 fields on its posting form, arranged into a single group:

  • A field for "title" which defaults to the job's title in the ATS.
  • A similar field for "description".
  • A field for "advertiser profile". The board has its own admin screens and database for this field, and no default is available from the ATS.
  • The categories field. This causes your board's categories (e.g. Location, Job type) to be displayed in the posting form, with defaults provided by the category mapping app.

The hub tries to present sensible defaults for fields:

  1. from the job or its recruiter or manager in the ATS (when the defaultFrom field is present on the field)
  2. from any existing postings on the same job that have items with a matching name.

When the recruiter submits the posting form, the job board hub will store values for all of the board's fields on the posting object.


Publish the board's categories and their values

This step is optional. A board may have no categories at all.

If your job board categorises its jobs by e.g. location, classification/expertise etc. then it should publish these categories by producing GET /jobBoards/forApp/categories and GET /jobBoards/forApp/categories/byID/{category}/values.

These APIs are called by the hub and the category mapper apps.

Keeping the board's back end updated

The job board hub maintains its own state of all of the tenant's job board postings, i.e. whether they are open or closed, what values were used, the date posted, etc.

Whenever the state of a posting in the hub changes (e.g. a posting reaches its expiry date and is automatically closed), the hub will alert the relevant job board app. The job board app is then responsible for uploading the new state into its own back end.

To play its part, your job board app must produce POST /postings/byID/{id}/tenantDeltaPings to be alerted when its own postings are changed.

How the board does this synchronizing is up to the board. Some boards use bulk upload APIs where the client always sends up all open postings. Others have web services to modify individual postings. Some might use ftp, csv, etc. The board might do it instantly, or every hour.

There are 4 scenarios that will cause a job board app to receive a delta ping alerting of a change to posting state:

  • a posting is created by the user via the the user clicking the hub's UI
  • or edited (e.g. description is changed)
  • A posting has been closed (because of job closed or posting closed or posting expired):
    1. close date has been set (is non null)
    2. status == closed
    3. status message == e.g. Expired
  • A posting has been re-opened:
    1. close date has been set to null
    2. status now == open

Producing GET /appStatus (optional)

This step is optional. Your board might never need any setup (i.e. completely on demand).

The job board hub stores a "setup error message" against each of a tenant's installed job boards.

When that field is non-null, this indicates that the board is broken - i.e. requires some setup.

The job board hub needs this information so that it can display the board's broken-ness in its UI - for example, a user can't create new postings for a board that is broken.

When GET /appStatus is called on your job board app, it should pull its own value for "setup error message" (by calling GET /jobBoards/forApp/status) and use that to light up (or not) the setup required icon on the app itself.

A typical scenario for setting the "setup error message" field would be when your job board app detected bad credentials while calling its own upload APIs. Then your app would set the setup error message via PATCH /jobBoards/forApp/status.

Another way that "setup error message" can be set is by default on new installs of your app.

In other words, if your app is always broken when first installed (because you need the user to click to the setup page and enter credentials, advertiser details, etc.) then you should reflect that by passing back a default setup error message in your response to GET /jobBoards/forApp:


"defaultSetupErrorMessage": "At least one template must be created"

When you do this, your board is effectively marked as broken by default for all new installs. The user sees this in your app's panel, and is guided to your setup page to fix the situation.

Producing a setup page (optional)

This step is optional. Your board might be able to start working with no additional information.

You may need a setup page to capture required information for new installs, e.g. API tokens, advertiser codes, etc.

Your job board app passes back a link to its setup page in its response to GET /jobBoards/forApp/status. This allows the user to click on the link in the store, and reach the setup page.

When the user views the setup page, they should normally see any existing setup problems highlighted.

To do this your job board app should call GET /jobBoards/forApp/status to fetch its own setup error message (e.g "credentials have been denied"). The setup error message can then be displayed at the top of the setup page so that the user knows what needs to be fixed before the board can start working.

Once the user has entered all required data into the setup page, the settings page should update the board's status to say things are good to go by calling PATCH /jobBoards/forApp/status and nulling out the setup error message.

Synchronising after sleep (optional)

This step is optional. A highly available board may rely on always capturing delta pings.

When the job board app starts up after maintenance, it should pull all of its own open postings from the hub, and use that to call its own upload APIs to synchronise its back end.

This will handle for any activity (new postings, expired postings) that may have happened on the hub while the app was asleep.

Synchronising of preview link (optional)

This step is optional. Some boards won't provide a preview link.

Some boards will be able to provide a preview link where the recruiter can see the job on the board itself.

When a preview link is available, e.g. when the board's upload APIs are called, the board can update the posting within the hub by calling PATCH /postings/byID/{id}/appDetails.