Toggle document index

Apply gate apps - overview

(For a Java/Spring example see https://github.com/talentappstore/applygatedemo).

Customers can use apply gate apps to prevent candidates from applying for jobs until they've successfully completed some pre-requisite. For example:

  • Ask all candidates to agree to a set of non-negotiables before applying, e.g. mandatory skills
  • Only allow candidates to apply who are not from countries with draconian data security laws
  • Have candidates complete a culture/fit analysis before applying

An apply gate app works by suppressing the apply button(s) on a job.

Once the customer adds your button to a job, the apply buttons suddenly are hidden from the candidate (this happens via switchgear, which is the app that marshals all of the buttons that appear on jobs and elsewhere).

To apply, the candidate must now click on your button, and then pass your gate - e.g. some kind of quiz within your app.

Your app then marks the candidate as having satisfied the gate and redirects them back to the job.

The candidate can now see apply button(s), and can apply.

Gates can actually be used for any type of button (print/apply/whatever), but to keep the documentation simple we only talk about apply gates.

Getting ready

Produce a button

Your app will produce one button, which will cause some different buttons (i.e. any apply buttons) to be hidden.

The first step then is to complete the steps described in "Career site buttons" for your app.

Once you've got your own button appearing to the candidate, return here.

Install required apps

You should already have several apps installed from the steps in "Career site buttons".

Since your app requires SSO, you'll need to install at least one identity app with principal type == candidate (e.g. allow candidates to sign in with Google).

Create your app

Modify your button to be an apply gate

Adjust the response from the possibles API like this: 


GET /actions/byCandidate/job/possibles/byApp (produce as non-SoT)

Response:

This shows an app producing two buttons - one apply button, and another button that is an apply gate (i.e., can prevent apply buttons from appearing).

Verify that the apply button is hidden

After making these changes, open the qs8n app again. Your button should now be showing, but the apply button that was previous showing should be hidden - your app is doing its job.

Complete your app's experience

Acting as the candidate, click on your button. You should be redirected to the link you passed back in the API call previously.

You should now be at your app's web site, where you do your thing whatever that is (e.g. complete an online quiz).

Here's how we recommend you deal with candidates clicking on your action, where your action is some kind of quiz that saves results against the candidate. This approach makes sure that:

  • you don't waste candidates time or confuse them by asking them to complete the quiz when they may have an existing result
  • candidates can't immediately retake a quiz if they fail

Put SSO in front of your quiz

Here, if the candidate is not signed in, you ask them to sign in using SSO before attempting the quiz (otherwise you'll waste their time if you already have a result for them).

Put a SSO-protected web page up. Any page in your app under /t/{tenant} is automatically SSO-protected, and appears on the internet at https://<your app>communityapps.aotal.com.

e.g. if you put up a page at: 


/t/{tenant}/quiz/{quiz}
then that page appears on the internet at:

https://<your app>.communityapps.aotal.com/t/{tenant}/quiz/{quiz}

You can safely assume that all incoming traffic to that page is for a signed in candidate. You now have access to the candidate's details from the incoming request headers (name, email, image, etc.).

Your app can now check if the candidate has a result in your database (keyed by email).

  • if there is a result, redirect them back to the relay page, but add ?isSignedIn=candidate to the url, so that the ATS knows they are now signed in. This will eventually cause the ATS to re-fetch all buttons, this time for a signed in candidate. You might choose to inject a results page reminding the candidate what their previous result was before the above redirect.
  • if there is no result, redirect the candidate to your quiz.

Once the candidate completes the quiz:

  1. store the result in your database (pass/fail), keyed by email address
  2. redirect the candidate back to the relay page, but add ?isSignedIn=candidate to the url, so that the ATS knows they are now signed in

Verify the candidate can now apply

Finally, you should be back at the job, and now the apply button should be visible. It works!

How gates are applied - logic

Although you only need to worry about your own button, this describes the big picture for buttons getting shown:

At the point the job page is displayed, the coordinating app (e.g. switchgear) will decide which buttons to display on it as follows:

  1. switchgear already knows all the buttons that may possibly be displayed (by calling each app's "possibles" API)
  2. switchgear now fetches the actual details for your button(s) and all other possible buttons for the job (some of those buttons may return 404 indicating they aren't to be displayed).
  3. switchgear now has a full list (the "displayable list") of all buttons that wish to be displayed.
  4. Now switchgear selectively filters out any displayable buttons that:
    • have a purpose (like "apply"); and
    • are not gate buttons; and
    • where there exists at least one displayable gate button for that purpose which is not yet satisfied (e.g., your button).
    • a 404 from an apply gate is considered a "pass"

In other words, switchgear won't display any apply buttons if there is at least one apply gate that the candidate hasn't completed.

You might want to return 404 for your gate button if the candidate has an existing pass. Then, as soon as your quiz has been completed, they won't see your button again.

Don't return 404 if the candidate has an existing fail, as that is the same as returning a pass. In this case your button should display with an appropriate label ("sorry you can't apply") - the candidate needs this to understand why the apply button is being hidden from them.

General actions

As well as adding gates on job actions, you can also gate general actions (such as registering). 


GET /actions/byCandidate/me/general/byName/{action}/byApp
GET /actions/byCandidate/anonymous/general/byName/{action}/byApp