This describes how to build a Job Board app that will integrate with the Job Board Hub in Talent App Store.
Job Board Hub is a central Job Advertisement creating app that allows customers to choose Job Boards that they have installed in Talent App Store and post, update or expire advertisements without having to navigate to all the different apps individually.
To have data flowing to and from your app, there are a couple of prerequisite apps that need to be installed first.
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").
First, follow these instructions to install Developer ATS and create a job. Then:
Before building a Job Board App, take a look over the App Install and Setup recipe and familiarise yourself with that. Once you are confident in building a basic TAS app that can be installed and show an necessary settings screens, it is time to move on.
A Job Board App does not need to consume any TAS Tenant APIs only produce them. To see more details about the APIs that need to be produced, see below in the "Produce APIs" section.
Once you have the basic App setup on Talent App Store, you will need to start implementing the APIs for the Job Board Hub to consume. The first thing the Job Board Hub does when your Job Board App is installed is call the ```/jobBoards/forApp``` API and create a record for your Job Board App where recruiters will be able to select your Job Board as one of the platforms to post their new Advertisement.
Note: The Job Board Hub will produce the application url. The final URL will include the legacy source code and a tracker.
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.
See the Job Boards schema for a detailed description of the properties you need to populate when producing this API.
Immediately after your app is installed, the Job Board Hub, a separate app, consumes GET /jobBoards/forApp on your app to fetch information about your app and stores in the Job Board Hub database.
When you refresh the page on the Developer ATS Jobs page, you will now see your app available to be selected as a Job Board to post a new advertisement to. The following information is used during this process within the Job Board Hub:
"label": "Super Job Board",
"logo": "https://talentappstore.com/logo.png",
"domain": "https://superjobboard.example",
"defaultAdvertisementDuration": 30,
"defaultLegacySourceCode": "SJB",
"defaultSetupErrorMessage": "Missing required information"
If you have some required settings before the recruiter can use your app, populate the "defaultSetupErrorMessage" field with some useful message for the recruiter to understand.
For example: "You need to finishing adding your credentials into the Super Job Board app in Talent App Store".
When a recruiter has selected your Job Board App in the Job Board Hub, the Job Board Hub will consume the API GET /jobBoards/forApp from your app and fetch the information that your app requires when creating a new Advertisement on your platform.
When building your Item Metas note that the Job Board Hub only supports the following:
There are also some general fields that all Job Boards have access to. You may choose to ignore these fields if they are not relevant to your Job Board. If you have specific requirements on these, for example the title cannot be longer than 50 characters you can specify this. Take a look at StringValidationMeta schema.
Once the recruiter has completed the new advertisement through the Job Board Hub and hits submit, the Job Board Hub will POST to your app an AdvertisementWrite that will contain all the information from the General fields and the information from the fields that your app required to create a new Advertisement.
Your app will need to process this information real time, whether the data is stored in your app and processed shortly after or processed instantly as the Job Board Hub expects a response from your app to indicate if the AdvertisementWrite is valid or there are some errors that the recruiter needs to go back and fix.
If the AdvertisementWrite has some issue with it when the new Advertisement request comes in, it is important to make your error messages as friendly and readable as possible to non tech savvy users. For instance, if the user has put an invalid URL into a field, you will need to return a message that clearly indicates that the issue was and how they can resolve it, the returned result for error messages is an array of errors and you can also indicate what field it is for.
Example of a bad Error Message: "URL Field for Terms and Conditions is invalid"
Example of a good Error Message: "The URL you have entered into the Terms and Conditions needs to follow the following format: www.talentappstore.com"
When editing an advertisement in the Job Board Hub, the Job Board Hub will ask the Job Board Apps for the advertisement information each of the specific Job Boards. Your app will need to produce an AdvertisementRead that contains all the information from the last time the Advertisement was updated. From this AdvertisementRead the fields will be prepopulated with the information from the existing Advertisement and allows the recruiter to easily make minor tweaks if required or change information as required.
It is up to your app whether it is stored in the Job Board App or fetched on demand from your Job Board.
The Job Board Hub updates and expires advertisements on the Job Boards consuming this API.
At times, the recruiter may miss some information or the job listing has been updated and needs to be updated within the Job Boards. This will prompt the recruiter to go an update the listing through the Job Board Hub. The information, in most cases, will be the same with a few minor adjustments.
The patch that is sent through to your Job Board App will include an action field with the value update. This field indicates that the Advertisement needs to be updated and your app will need to apply any changes on demand similar to that of the new Advertisement request and return any errors to the recruiter in an easy to read and understand format.
If the action field has the value: expire, you can ignore all other fields on the AdvertisementWrite and expire / archive the advertisement from your Job Board.
Different Job Boards have different time lengths an Advertisement can be advertised. The ATS may have the Job Listing open longer on their end. The other scenario is that the recruiter will go into the Job Board directly and expire the advertisement. This API allows the Job Board Hub to ask your Job Board App if the advertisement is still open.
The Job Board Hub will poll your app periodically and send through an array of advertisement Ids and expects a response that contains an array of objects with the following data:
"advertisementId": "123-4324-23423"
"status": "expired"
"title": "Advert title"
"referenceCode": "1234"
Status can be either 'open' or 'expired'.
Polling will happen every 30 minutes At *:00 and *:30.
Once the advertisement has expired, ideally the advertisement listing information will still be available for a period of time to allow the recruiter to repost the advertisement if required through the Job Board Hub. In this instance, the Job Board Hub will calling the GET /advertisements/byID/{advertisementId}/byApp API to fetching the information for the advertisement
Below is the APIs that need to be produced by the Job Board app along with example JSON for both the request and the response.
When apps are installed by a Tenant there are times where additional information is needed to get the app up and running properly for that tenant. If this is required by the Job Board App, the Job Board App will need to produce the following API /appStatus. Below is an example response when TAS calls this API.
{
"landingPage": "https://example.url",
"settingsPage": "https://settingsExample.url",
"setupRequired": true,
"domainsUsed": [
"https://domain1.example",
"https://domain2.example"
]
}
The Job Board Hub will ask the Job Board App for the rules that need to be applied when building and presenting the new Advertisement screen. The API called is /jobBoards/forApp. Below is an example response.
Response example:
{
"label": "Super Job Board",
"logo": "https://talentappstore.com/logo.png",
"domain": "https://superjobboard.example",
"defaultAdvertisementDuration": 30,
"defaultLegacySourceCode": "SJB",
"defaultSetupErrorMessage": "Missing required information",
"applicationURLRules": {
"type": "string",
"minLength": 10,
"maxLength": 200,
"mandatory": true,
"pattern": "regex"
},
"titleRules": {
...
},
"referenceCodeRules": {
...
},
"shortSummaryRules": {
...
},
"descriptionRules": {
...
},
"recruiterNameRules": {
...
},
"recruiterEmailRules": {
...
},
"advertisementRules": [
{
"title": "Section header 1",
"instructions": "Some meaningful instructions",
"advertisementFields": [
{
"name": "question1",
"title": "Question 1",
"instructions": "Some text",
"format": "singleLine",
"minLength": 10,
"maxLength": 200,
"defaultValue": "Testing",
"mandatory": true,
"pattern": "some regex"
},
{
...
}
]
}
]
}
Job Board apps need to produce the following APIs as non source of truth (SoT)
When a recruiter has submitted their new advertisement through the Job Board hub, the Job Board Hub will call the selected Job Boards calling the /advertisements/byApp API. The request will look similar to the example below.
{
"applicationURL": "https://aotal.com",
"title": "test title",
"referenceCode": "C1234",
"shortSummary": "My short Summary",
"description": "My description",
"recruiterName": "Joe Smith",
"recruiterEmail": "joe.smith@example.com",
"advertisementFields": [
{
"name": "birthdate",
"type": "date",
"value": "2015-11-05T13:15:30Z"
},
{
"name": "keenworkerflag",
"type": "boolean",
"value": true
}
]
}
When the Job Board App has completed processing the information, the app will return the following example if it was successful.
{
"advertisementId": "1234567",
"status": [
"Open"
],
"applicationURL": "https://aotal.com",
"title": "test job",
"referenceCode": "C1234",
"shortSummary": "This is the short summary",
"description": "Description is here!",
"recruiterName": "Joe Smith",
"recruiterEmail": "joe.smith@example.com",
"advertisementFields": [
{
"meta": {
...
},
"item": {
...
}
},
{
"meta": {
...
},
"item": {
...
}
}
]
}
If, for some reason, the information coming into the Job Board App has some information missing or it failed for some reason, the Job Board App will need to return the following:
{
"messages": [
{
"message": "Human readable message here",
"name": "field the message it regarding"
},
{
...
}
],
"type": "Bad Request",
"code": 400,
"traceId": "123-432-123-145"
}
When the following is returned, the Job Board Hub will show the message to the recruiter to let them know they may need to change something or to try sending it again.
From time to time, the recuriter may need to update the advertisment posting on Job Boards to reflect any changes made from the Applicant Tracking System (ATS). To do this, the Job Board Hub will send through an API call to /advertisement/byID/{advertisementId}/byApp where the Job Board App will need to process the request and update the relevant advertisement with the new details.
{
"action": "update",
"applicationURL": "https://aotal.com",
"title": "test title",
"referenceCode": "C1234",
"shortSummary": "My short Summary",
"description": "My description",
"recruiterName": "Joe Smith",
"recruiterEmail": "joe.smith@example.com",
"advertisementFields": [
{
"name": "birthdate",
"type": "date",
"value": "2015-11-05T13:15:30Z"
},
{
"name": "keenworkerflag",
"type": "boolean",
"value": true
}
]
}
{
"advertisementId": "1234567",
"status": [
"Open"
],
"applicationURL": "https://aotal.com",
"title": "test job",
"referenceCode": "C1234",
"shortSummary": "This is the short summary",
"description": "Description is here!",
"recruiterName": "Joe Smith",
"recruiterEmail": "joe.smith@example.com",
"advertisementFields": [
{
"meta": {
...
},
"item": {
...
}
},
{
"meta": {
...
},
"item": {
...
}
}
]
}
Similar to the new advertisement API, if there is an error, the Job Board App will need return an error response similar to the one below:
{
"messages": [
{
"message": "Human readable message here",
"name": "field the message it regarding"
},
{
...
}
],
"type": "Bad Request",
"code": 400,
"traceId": "123-432-123-145"
}
The Job Board Hub does not store the advertisement data for each of the Job Board Apps, it instead calls the Job Board Apps for the advertisement information real time to display to the recruiter when they are editing an advertisement.
The Job Board App needs to produce the /advertisements/byId/{advertisementId}/byApp API and return the advertisement data. Below is an example of the response the Job Board App should return.
{
"advertisementId": "1234567",
"status": [
"Open"
],
"applicationURL": "https://aotal.com",
"title": "test job",
"referenceCode": "C1234",
"shortSummary": "This is the short summary",
"description": "Description is here!",
"recruiterName": "Joe Smith",
"recruiterEmail": "joe.smith@example.com",
"advertisementFields": [
{
"meta": {
...
},
"item": {
...
}
},
{
"meta": {
...
},
"item": {
...
}
}
]
}
Frequently the Job Board Hub will poll all Job Board Apps to check that advertisements in the Job Board Hub that are still marked as "active" have not been expired from the Job Board.
When the Job Board Hub is requesting the status of advertisements, the Job Board Hub will send through a request which contains an array of the advertisement ids it is looking for.
[
{
"id": "123-4324-23423"
}
]
[
{
"advertisementId": "123-4324-23423",
"status": "expired",
"title": "Advert title",
"referenceCode": "1234"
}
]