Within the Wordpress plugin you’re able to do certain actions. We’ve listed these below, including any additional information you might need.
Webhook action
This guide expects you to know the basics of how actions work in WordPress and requires basic knowledge of PHP. For more information regarding actions in WordPress see the WordPress documentation at https://developer.wordpress.org/plugins/hooks/actions/
This action is available from version 1.3.18
What are webhooks?
OTYS has its own API layer OWS (OTYS Webservices). OWS is used by OTYS Go! as well as many third-party integrations with OTYS (like the OTYS WordPress plugin). Sometimes it's needed for third parties to know when something happened with data in OTYS. For example, the OTYS WordPress plugin needs to know when a vacancy gets edited so the cache from the plugin can be updated.
Via webhooks OTYS can let third party applications know when a specific action has been triggered in OTYS Go! so the third party can act accordingly. The WordPress plugin uses webhooks to listen to a variety of data:
Vacancy
Interaction forms
Match criteria
Candidate questionsets
Extra fields
Settings
The WordPress plugin uses [yourdomain.com]/webhooks as a entry point for OTYS. OTYS Go! will tell your plugin what happened in OTYS Go and your plugin will automatically update cache accordingly.
Use case
Sometimes it's not only enough to for the WordPress plugin to simply listen to the webhook and do it's thing. It might be that you as a developer need to some action when a webhook gets triggered. A good example might be that you are using your own caching methods on top of the WordPress transients (which the plugin uses). This means that it's not enough to only refresh the transient cache, but also your other caching method needs to get a heads up that it needs to refresh it's cache. Here the webhook action 'otys_webhook' comes in handy.
How to use the webhook?
We register a webhook by calling add_action('otys_webhook', 'example_callback', 10, 3). Now when a webhooks gets send to your website it will first handle the webhook as usual, at the end before giving a response back to OTYS the OTYS plugin will call the specified callback function example_callback($request, $webhook, $response).
The following parameters available in the callback function:
array $request | Webhook request data specified by OTYS |
array $webhook | Details about the webhook callback. The following fields are available;
|
array $response | Response that the plugin will give to OWS. The response will be an array with a 'message', 'code' and 'data'. Examples of available codes:
|
Cache delete
This guide expects you to know the basics of how actions work in WordPress and requires basic knowledge of PHP. For more information regarding actions in WordPress see the WordPress documentation at https://developer.wordpress.org/plugins/hooks/actions/
This action is available from version 1.3.19
About cache
The OTYS plugin uses WordPress transients to store responses of the OTYS API requests. These transients are stored in the WordPress database. By caching the responses it's not necessary for the plugin to do API requests every time which makes the plugin allot faster.
There are three scenario's of how cache can be removed:
By the cache expiring. All cache has an expiration date specified, when the cache expires it will not be used anymore and will be deleted by a WordPress CRON event (which gets registered by the plugin) within 24hours.
By a manual action. For example clicking the 'remove all cache' button in the plugin admin panel.
By a webhook. OTYS uses webhooks to refresh relevant cache based on events happening in OTYS Go!.
The OTYS plugin does not use the 'delete_transient' function of WordPress when removing many cache records. This is due the many records that will get removed and could be triggering the the delete_transient function 1000+ times, since there could be allot of cache records created by the plugin depending on how large your website is. Therefore OTYS has written efficient database queries to remove cache. The downside of not using the delete_transient function of WordPress is that you can't use the delete_transient_{transient} action. Therefore we have created our own actions when removing cache.
Use case
It might be that you as a developer need to some action when cache gets refreshed. A good example might be that you are using your own caching methods on top of the WordPress transients (which the plugin uses). This means that it's not enough to only refresh the transient cache, but also your other caching method needs to get a heads up that it needs to refresh its cache.
How to use the webhook?
On the left you see an example of the use case above. We register a webhook by calling add_action('otys_cache', 'example_callback', 10, 0). After the cache gets deletes the action is called.
The following parameters available in the callback function;
string $type | Describes what type of action got triggered i.e. 'refresh', 'delete_all', 'delete_expired', 'delete' |
array $transients | An array of all deleted transient names |
Application callback
This guide expects you to know the basics of how actions work in WordPress and requires basic knowledge of PHP. For more information regarding actions in WordPress see the WordPress documentation at https://developer.wordpress.org/plugins/hooks/actions/
When a candidate has successfully applied for a job the action 'otys_application' is called. The callback function gets provided an array with information regarding the application. The following information if available in this callback:
array $data | Array holding information about the application |
Below the keys are described which the $data variable contains, these keys are always present
Keys | Type | Value |
vacancy_uid | string | uid of the vacancy or 'open-application' if the application is a open application |
candidate_uid | string | uid of the (new) candidate |
procedure_uid | string | procedure id or empty string if it's a open application |
completed | bool | True if application was successful. False if something went wrong during the application (i.e. wrongly filled in the form) |
form_data | array | Validated form data |
Javascript events
This feature is available from version 2.0.39
The plugin is using rest forms to submit data to OTYS. For example when a candidate applies. Sometimes you would like to do something when a candidate submits data to OTYS, therefore we created an event 'otys-rest-form-callback'.
This 'otys-rest-form-callback' event is always called when the rest form receives a response. In the detail (data.detail) of the response you'll find all kinds of information (see example request).
These rest form events can for example be used for triggering dataLayers.
Change theme files
This content is more technical and is more suited for people with technical knowledge.
It is possible to overwrite theme files which are provided with the plugin. Each functionality provided with the OTYS WordPress plugin is using theme files which are provided within the plugin folder. It is possible to change (overwrite) these theme files by making a copy of the plugins theme files and placing the theme files within your own theme folder and changing the files.
How?
Navigate to the plugin view folder in your website, this folder should be located at [yourwebsite]/wp-content/plugins/otys-jobs-apply/app/views. Within this folder are all theme files located which are being used by the plugin.
To overwrite a theme file you can create a folder named 'otys-jobs-apply' in your own theme folder (this should look something like [yourwebsite]/wp-content/themes/[your-theme-name]/otys-jobs-apply) and copy a file from the plugin's view folder in there. The plugin will always prefer files in your theme folder above the view files in the plugin's folder.
Only overwrite theme files which you are changing, this will improve maintainability. Sometimes changes happen to theme files within the plugin, note that these changes will not affect your custom theme files.
OTYS will make sure to keep backwards compatibility in mind and not change variable names when not needed. However, this could happen in the future, but when this happens, we will make sure that this is noted in the update notes. When this happens, we will have a new Major version release. When a new Major version is released make sure to read the changelog provided with the update.
Example
When you for example want to change the theme file of the [otys-vacancies-list] shortcode (so the vacancies list HTML) create a new folder in [yourwebsite]/wp-content/themes/[your-theme-name]/otys-jobs-apply called 'vacancies'. Now copy the file [yourwebsite]/wp-content/plugins/otys-jobs-apply/app/views/vacancies/vacancies-list.php to this folder.
Now you will be able to edit this file however you like. All theme files will have access to a variable $args this variable will contain all information available to this theme file. When you var_dump($args) you will see that there's allot more information available then there's initially displayed.