Toggle document index

Buttons - overview

Apps can cause their own candidate-facing buttons to be displayed in various places within other apps. For example, you might display a "share" button on the job details page on the carer site. In this case your button might be displayed next to other buttons like "apply", "refer a friend", etc.

Displaying buttons involves a handful of APIs between your app and others (for example switchgear, which is an app provided by Aotal that gives tenants control over the order of buttons, and ways to control which buttons appear on which jobs).

The key APIs you'll produce and consume are:

• GET /actions/byCandidate/me/general/byName/{action}/byApp Your app should produce this API to return an array with an element for every different button that your app might ever provide (i.e., the superset of all of your app's possible buttons).
• POST /actions/byCandidate/job/possibles/byApp/deltaPings Your app should consume this API if it ever changes its set of possible buttons (e.g. maybe you added one in response to a customer's request).
• GET /actions/byCandidate/me/jobs/{job}/byName/{action}/byApp Your app should produce this API to return details for the given button, **given the logged in candidate and this specific job**. Your app might e.g. change the color, label, disabled, etc. of the button, or even hide it entirely (by returning 404).
• GET /actions/byCandidate/anonymous/jobs/{job}/byName/{action}/byApp As above, but for a logged in candidate.

There are similar APIs for the other places where candidate-facing buttons can be displayed (global, and search results).

Set up

Lets prepare by installing some sandbox apps.

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").

Install apps and prepare test data

Follow these instructions to install Developer ATS. The apply button will be showing and you can click on it to create a job application.

Use switchgear to control buttons

One of the apps you installed previously was Switchgear. Switchgear is an app that manages all of the buttons (apply, share, refer a friend, etc.) from all of the button-producing apps.

Typically a customer wants to show different combinations of those buttons to different candidates (e.g. internal vs external) on different jobs (e.g. IT jobs vs call centre jobs). This complexity is all handled via switchgear. Switchgear gives the customer a drag and drop user interface that they can use to drag button(s):

1. in or out at a global level, so that by default your button will appear or not appear on all jobs
2. in or out at a job workflow level, so your button will apepar only on jobs that have a specific workflow (e.g. "retail")
3. in or out of a specific job

Create your app - produce the /possibles API

Now that we've got the sandbox apps installed, we're ready to get your app up and running.

• Go to https://developer.talentappstore.com. Create a developer account if you don't already have one.
• Define your app, giving it a name and shortcode.

  Produce GET /actions/byCandidate/job/possibles/byApp

  Have your app produce the following API, to tell other apps (specifically switchgear) about its candidate facing buttons, e.g.:

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

  The data that you are passing back in this example is as follows:

  • actionName is the key for your button. Users recognise your button by this as they perform setup, e.g. controlling which jobs your button appears on. It should be unique among all buttons your app produces (if more than one). If you have only one button, consider using your company or app name.
  • The availableToInternals and availableToExternals fields control whether the user is able to present your button to public job seekers and/or employees.
  • In this example, mayRequireSetupFlag is false, meaning your app does not have a setup page. This means, for example, that when the tenant says that all of their "sales" jobs should have your button, they don't get to also configure your button at that point (e.g. for a quiz, perhaps add some sales-specific questions).

  Install your app

  Install your app into your tenant.

  Test that your API is being produced OK

  1. Reboot the tenant, checking, e.g. via logging in your app, that your "possibles" API is being called.
  2. Open switchgear and your button should be visible under job actions.

  Create your app - produce remaining APIs

  Now that your possibles API is working, have your app produce two more APIs, one for logged in candidates and one for anonymous ones.

  Produce GET /actions/byCandidate/../jobs/{job}/byName/{action}/byApp

  In your response, you pass back button details, like text, color, link, etc.

  
  GET /actions/byCandidate/me/jobs/{job}/byName/{action}/byApp
  GET /actions/byCandidate/anonymous/jobs/{job}/byName/{action}/byApp
  
  Response:
  
  
  

  The first form (/me/) is an on-behalf API.

  Switchgear will call this API when it is displaying your button to a logged in person (i.e. the candidate).

  As the producer of an on-behalf API, your app gets access to details about the logged-in person, such as their email address, name, and a unique identifier for them.

  You might use that information to customize the details of your button. For example, if your button is an apply button, and the candidate already has a job application for this job, you might decide not to show your button at all, or to show it in a disabled state.

  The second form (/anonymous/) is a normal API.

  As the producer of this API, you don't know anything about the candidate who is looking at the job details page for this job, so you should assume they are a public job seeker.

  Its up to you to decide whether to treat these two APIs differently in your app, or just return the same response for both.

  In the response above:

  • name corresponds to the actionName (that you passed back previously from your /possibles API).
  • uri is the link the user will be led to when they click your button. Since behaviour is "redirect", they will be redirected rather than seeing your web page in an iframe inside a modal. In this case we just pass the relayPage through - you should additionally generate a signature for it or otherwise prevent anyone from altering the relayPage, to prevent open relay attacks.
  • textColor and backgroundColor allow you to customise how the button appears, along with label and disabled.

  Check that your button is showing on the jobs page

  Click into the Developer Careers app. You should see a job, with your buttons displayed on it.

  Click on your button, and you should be redirected to your app's web experience (e.g. applying for a job, completing a quiz, sharing the job, etc.).

  Once completed, your web experience should redirect the candidate correctly back to the relayPage (i.e. the job details page).

  Advanced - changing the buttons your app produces

  The button coordinating app (e.g. switchgear) will call your /possibles API to learn about your app's buttons at the time your app is installed. That will work fine, as long as your app doesn't change its set of buttons after its been installed.

  However if your app does add new buttons (or remove or change existing ones) after install, then it should alert other interested apps of that by consuming:

  
  POST /actions/byCandidate/job/possibles/byApp
  
  Response:
  
  
  

  This acts as a hint to switchgear (or any other app that cares) that it should call your /possibles API again, since your buttons may have changed.

  Advanced - adding a setup page

  As long as your button doesn't need any additional information, the drag and drop user interface provided by switchgear is all the customer needs.

  However if your button requires some per-job or default setup then a setup page can be declared. The tenant will be prompted to complete setup when the add the button to a job or as a default for a group of jobs.

  A setup page is a small HTML page that your app can present to the user right at the point when they drag and drop your button into the global or workflow areas or onto a specific job.

  For example, lets say your app is an employee referral app. Employees can click your button on a job and then use your user interface to refer the job to their friends. They get a cash reward if they are hired.

  In this example your app might present two separate setup pages:

  1. when your button is dragged to the global or workflow areas, you capture the minimum, maximum and default cash reward (number fields)
  2. when your button is dragged or clicked on for a specific job, you capture the actual cash reward for this job