Serving buttons to other apps
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:
There are similar APIs for the other places where candidate-facing buttons can be displayed (global, and search results).
Set up
Install apps and prepare test data
Before you start, follow the 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):
- In or out at a global level, so that by default your button will appear or not appear on all jobs
- In or out at a job workflow level, so your button will apepar only on jobs that have a specific workflow (e.g. "retail")
- In or out of a specific job
Implementing the APIs
Produced APIs
These are APIs that your app exposes for other apps to consume them.
-- CODE language-json --
[
{
"actionName": "apply",
"availableToInternals": true,
"availableToExternals": true,
"mayRequireSetupFlag": true
},
{
"actionName": "share",
"availableToInternals": true,
"availableToExternals": true,
"mayRequireSetupFlag": false
},
{
"actionName": "refer",
"availableToInternals": true,
"availableToExternals": false,
"mayRequireSetupFlag": true
}
]
The data that you are passing back in this example is as follows:
Install your app into your tenant.
- 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 the example above, 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).
To test that your API can be consumed by other apps:
- Reboot the tenant, checking, e.g. via logging in your app, that your "possibles" API is being called.
- Open switchgear and your button should be visible under job actions.
- 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.
-- CODE language-json --
{
"name": "qualify",
"uri": "https://acme.myapplygate.com/jobs/1022?relayPage=blah&tracker=106645",
"label": "I want in!",
"type": "button",
"textColor": "111111",
"backgroundColor": "eeeeee",
"disabled": false
}
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:
-- CODE language-json --
[
{
"actionName": "bigapply",
"availableToInternals": true,
"availableToExternals": true,
"mayRequireSetupFlag": false,
"semantics": {
"purpose": "apply"
}
},
{
"actionName": "easyquiz",
"availableToInternals": true,
"availableToExternals": true,
"mayRequireSetupFlag": false,
"semantics": {
"gateFor": [
{
"purpose": "apply"
}
]
}
}
]
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, let's 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:
- When your button is dragged to the global or workflow areas, you capture the minimum, maximum and default cash reward (number fields)
- When your button is dragged or clicked on for a specific job, you capture the actual cash reward for this job
