Survey applicants app

Here's a quick walk through of what's required to write a survey app in Talent App store - e.g. an app that sends a survey to applicants who have been unsuccessful in order to understand candidate care levels.

About TAS

Writing an app may sound intimidating, but its not. You're not actually creating a downloadable app that the customer runs themselves. Instead you're just producing and consuming RESTful APIs on your own servers - in a way that looks like an app to the customer.

For example, when a customer clicks install on your app in Talent App Store, you'll receive an incoming API call to your own server telling you that you have a new customer. From this point you can start making API calls to fetch data for that customer.

All your app's code runs on your own servers, and we (Aotal) don't perform any review or testing of your code, nor do we need any IP rights to it. Also the APIs you will use are all open source, so you're free to use them in any way you see fit. And of course you can write and host your app using whatever tools and technologies you already use.

Steps

Here are the typical steps you would go through to build this app.

Define your data gathering strategy

Your survey will be triggered by an applicant being marked as unsuccessful in their application for a job. There are two ways you can learn about unsuccessful applicants:

Pull (polling)

You periodically (e.g. once an hour, overnight) call the API GET /applications/byPhase/decline/complete, passing in a date. The response includes all applications that have been declined since that date - typically the date you pass in will be the date of the previous poll operation.

This approach is not real time, but that's probably not a concern for this kind of app - you may want to allow some time for the candidate to absorb the fact that they've been unsuccessful before approaching them.

Push (delta ping)

You produce the API GET /applications/byPhase/decline/complete, which is called in real time each time a candidate is declined.

This approach requires high availability of your app. If your app is down at the point when a candidate is declined, you'll miss the message, and you would have to use GET /applications/byPhase/decline/complete when your app came back up again.

In this example, we'll use the pull approach.

Create your app and fetch declined candidates

Create a developer account

If you don't have one already, go to developer.talentappstore.com and create your developer account.

Define your app

Create a new app under your account, give it a name, logo etc. Make a note of your app's secret key - you'll need this later - and make sure you don't share this with anyone.

Finally, define the APIs that your app consumes - in this case, GET /applications/byPhase/decline/complete.

Make sure you specify source of truth == true

Later on, you'll write some code and then attach your actual servers. But for now, let's install your app and start making some API calls from the command line. In Talent App Store, your app can't do much at all until it's installed by a tenant. So to develop and test your app, and make API calls, you'll need a tenant of your own (its free to create one).

Create a tenant and install your app

From your app, copy the install token.

Go to the TAS Marketplace and click on Sign up, then create a new tenant.

Once created, open the tenant and on the top menu click on "Install from token". If you are using a different marketplace (e.g. SnapHire Marketplace) the wording could be slightly different (e.g. "Install private app").

Insert your token and click install.

Install the sandbox apps

For your app to consume the new API, some other app needs to produce it. In a production tenant, that app might be an Applicant Tracking System (ATS). Since installing an ATS and getting test data into it can be a somewhat lengthy process, we provide a simple test app that produces the APIs you're going to use and is pre-loaded with test data.

Follow the steps on Sandbox apps to setup your test environment.

Make the API call

Now you're ready to make an API call to fetch declined applications. We'll use the familiar curl command.

At the command line, type the following (substituting your own app, tenant and secret key).

You should see a list of applications come back, ordered by ID. If not, check the preceding steps. If you get an empty set back, you might need to scan further back in time to find some valid test data.

-- CODE language-CURL --
# as the app "myapp",
# and acting for tenant "acme",
# call the API GET /applications/byPhase/decline/complete
# fetching declined applications in the last week
# including application, job and candidate details
# as defined by the developer "tas"curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" \
https://myapp.tazzy.io/t/acme/devs/tas/applications/byPhase/decline/complete?since=2017-04-01T00:00:00+00:00&includeAppDetails=true&includeCandidateDetails=true&includeJobDetails=true

Paging through the result set

In a live system you'll see a lot of data. The API only returns a maximum of 100 applications each time you call it, so if you do see that many applications in the response, call the API again, this time passing in the minID parameter set to the ID of the last application in the previous response. Keep doing this until you've fetched all the applications.

Next result set

The next time your app pulls declines, you'll pass in a new value for the since parameter - most likely the point in time of your previous run. Again, page through the results, 100 at a time, until you've fetched all the declines.

Decode each job's category values

If you need to correlate your surveys in some way to some characteristic of each application's job (e.g. department), you'll likely do that using the job's categories.

If you look closely at each job's details, 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. 2113 == Auckland), you'll need to call two more APIs.

GET /categories

The GET /categories API gives you the list of categories - e.g., that this tenant has categorized their jobs by location and by expertise.

GET /categories/byID/{}/values

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.

Update your consumed APIs

At the developer site, update your app so that it consumes these APIs (again, as source of truth).

To test this out, you can call these APIs using CURL, e.g.:

-- CODE language-CURL --
curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" -H 'tazzy-tenant: acme' https://getjobstest.tazzy.io/devs/tas/categories

One of the categories returned above was 100001999, so to get the values for this category:

-- CODE language-CURL --
curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" -H 'tazzy-tenant: acme' https://mockjobstest.tazzy.io/devs/tas/categories/byID/100001999/values

Multiple applications

It's possible (and normal) for a candidate to apply to multiple jobs, and therefore to be declined multiple times. Also, a candidate could be declined for multiple jobs within a very short period of time (e.g. if all the applications were waiting on a single drug test result). You may want to apply some policy in your app that considers this.

Internal candidates

Some candidates are internal, i.e. already employed by the customer. If you want to treat internals differently, you can identify them via the candidate details that are passed back.