This recipe describes building an sourcing app in Talent App store - i.e. an app that:
There are two approaches you can use:
Your app should not poll either the feed or the GET /jobs API to look for changes to the jobs. Instead, it should sign up for real-time notifications of changes by producing the POST /jobs/byID/{}/deltaPings API. Then your app will receive an incoming API call whenever a job is changed at the source.
In response your app might:
Note: don't pull the feed too agressively. e.g. queue the fetches to avoid overloading the upstream app.
Let's start by installing some apps and entering some test data.
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 the first few steps (up to and including creating a job) of these instructions.
Create some more jobs, so that you have useful test data.
Now install the Feed app ("Browse apps").
Finally, to see the XML feed on a web page, install the Agile feed viewer app, using this install token:
eyJhbGciOiJSUzUxMiJ9.YWdpbGVmZWVkdmlld2Vy.dP2CZUOGIeS9QAaDtaUTxeugYY8jaGS2Bm9dXrm7EYKV7rlFCHixtWdIrrXC7Q6pGUBWwi_Ilupk6zy6zmd0uDtkJyW_WCSwF8XWg2oQI9tdGx6-r85wk2D6V2OFV-iP4MHIubgd7TxZLbweIyeUP2cEjOcJtghcIuCcD6UpXHn0gIopUBau1mCK9dp8ss1o8i6VkZod4HkTJTvrSWUySl3q6WHCCroZ4oSOhNHSZjIIkHKJZjrZZk0u-0LSKQ1IT6UCoDHXZa7qOBjegpnN9B8z7OrBTuge_jfMwBVJBGs8nAzlx5UhjSw87pv4xMfsR5Ddc87yXC_a9BqcteS6Zw
From the storefront, click to the feed viewer app and you should be able to see the XML feed.
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.
POST /jobs/open/externally/byID/{id}/deltaPings
Your app produces this API to learn about changes to jobs, so it can re-fetch them.
To produce a tenant API like this (see the programming guide):
Your endpoint will now be hit every time a change is made to an upstream job (e.g. recruiter in the ATS marks the job as closed).
In response you can fetch just the changed job, or, if you are using the feed APIs, all jobs.
When using the feed APIs, you fetch all of the upstream jobs as XML in one API call.
e.g. (first have your app consume the API):
# as the app "getjobstest",
# and acting for tenant "acme",
# call the API GET /jobs/feeds/full
# as defined by the developer "tas"
curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" https://getjobstest.tazzy.io/t/acme/devs/tas/jobs/feeds/full
Instead of the feed, you can also access jobs using individual API calls.
Have your app consume GET /jobs. Then fetch the first 100 open jobs:
# as the app "getjobstest",
# and acting for tenant "acme",
# call the API GET /jobs
# as defined by the developer "tas"
curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" https://getjobstest.tazzy.io/t/acme/devs/tas/jobs
You should see a list of jobs come back.
On each returned job, you'll see that the job's category values (e.g. its location) are identified by ids. To obtain the mapping from those ids into actual values (e.g. 2013 == Auckland), you'll need to call two more APIs.
The GET /categories API gives you the list of categories - e.g., that this tenant has categorized their jobs by location and by expertise.
The GET /categories/byID/{}/values API gives you all of the values for any single category - e.g., all the locations that this tenant has set up.
You should cache the results of these APIs so that you don't need to make the API calls too often, or your app might be throttled.
e.g.:
curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" https://getjobstest.tazzy.io/t/acme/devs/tas/categories
One of the categories returned above was 100001999, so to get the values for this category, call:
curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" https://getjobstest.tazzy.io/t/acme/devs/tas/categories/byID/100001999/values
The next step in building your app is to compose a link leading back to the job. The tenant may have many career sites (e.g. graduate site, main site, campaign site for a new store opening). One of these will be marked as the default - your app learns which by calling an API.
Your app consumes this API to learn which career site is the primary.
The /careerSites/forApp/byID/{site}/jobLinks API lets you fetch the links for an array of jobs in a single API call.
Pass in the array of jobs that you want links for as parameters. Cache the results to minimise API traffic.
(This step is optional).
So far you have extracted a list of jobs, and for each one, you've built a link that the candidate can click on to lead them to the job (on the primary careers site).
When the candidate reaches the primary career site, their browser will add your site (in the referer http header), so there's a fair chance that any candidate job applications made via your app will be attributed as the source of any resulting job applications (by the career site checking the referer header set by the candidate's browser).
However you may want to make sure that source detection works correctly - or add aditional tracking information that you can use later - by attaching a tracker to the link. Trackers get passed through to any job applications resulting from clicking on your link. As a result:
You can also embed your own information into trackers. For example, if your app is a kind of social referral app, then you could embed in the tracker the details of the person who shared the job. Then, when someone is hired after applying using that shared link, you could pay the referrer a bounty.
Learn more about trackers here.