A developers guide to JobRelay

JobRelay is a tool that simplifies the integration process of a job posting service (Broadbean, Idibu, LogicMelon and JobAdder) with WordPress. It takes care of the tricky stuff such as processing data and saving it in WordPress, allowing WordPress developers to focus on WordPress development such as job display and search.

This overview talks through the main features of JobRelay and how the system works.

How does an integration work?

Any integration with a job multi-posting service has 3 parts.

  1. The posting service develop a method of posting (sending to a URL) job data to your website. This is often referred to as “building a feed” of data to your site.
  2. A URL, known as an “endpoint” is developed in WordPress, to which the posting service send the data to, about jobs. This endpoint should process the data and then save it into the WordPress database.
  3. Your WordPress site reads the saved data from the database and outputs jobs and associated functionality on the front end. This usually including search, a job listings page and a single page for each job with an application form.

Where does JobRelay fit in?

Looking at the list above, JobRelay takes care of points 1 and 2. We are already integrated with the posting service and therefore they have already created the “feed” of jobs to JobRelay. No development, only setup is needed on the posting services side. This cuts down the lead time to live.

JobRelay provide you with a connector plugin to add and activate on WordPress. This does 2 things:

  1. It adds an endpoint (URL) to your website which the job data from the posting service is forward to via JobRelay. This endpoint must always be available.
  2. The job data is processed and then mapped to be saved in WordPress where necessary so that your WordPress site can carry out number 3 above.

Put simply, the role of JobRelay is to make sure that the data arriving from the posting service is saved correctly in WordPress, ready for your WordPress site to use this data however you choose.

How are jobs saved in WordPress?

When jobs arrive at the endpoint URL, our connector plugin has settings to tell WordPress how to save each job.

Your WordPress site needs to have a custom post type for jobs, and the data is then either saved as post meta or as taxonomy terms, associated with the newly created job post, of that post type.

Many WordPress sites are already running a WordPress job board plugin, such as WP Job Manager. These plugins already provide a custom post type and associated fields and taxonomies which JobRelay can use to save to job data too.

However, it is often the case that WordPress sites have a more bespoke approach, for example using a custom post type with something such as Advanced Custom Fields to provide the job data fields.

From a developers point of view JobRelay can save the job data in 2 ways:

  1. As meta data (using save_post_meta())
  2. As terms within defined taxonomies

How is data mapped to be saved in the correct place?

A screenshot of the JobRelay settings page in the WordPress admin area.
The JobRelay settings page allows us to map data arriving for the posting service to be saved in WordPress.

Firstly it is worth mentioning that all the mapping of data (i.e. save the value of job salary to a custom field in WordPress with the meta key of job_salary) is included as part of the JobRelay cost. However it is also worth outlining how this happens here.

JobRelay comes with a settings page which is used to setup the connection and provided the mapping of JobRelay data to WordPress data.

Any of the data fields that arrive at your website can be mapped and saved in WordPress using this settings page. We tell WordPress which post type to use as well as where to save the data.

What JobRelay does not do

JobRelay is not responsible for jobs functionality on your WordPress site. This means the following is not the role of JobRelay:

  • Presentation and design of jobs on the front-end of your site. This is up to your theme or your chosen job board plugin to output the jobs. It is likely that you will need:
    • Job listings page to list all jobs
    • Single job post pages for displaying a single job
    • Application form
  • Job search
  • Expiration of jobs once their expiry data is reached
  • Delivering application emails – see below

How does applicant tracking work?

Most posting services include a form of applicant tracking. This means that when someone applies for a job on your WordPress site there is a method for that application to be delivered back to the posting service. This allows the consultant who posted to job, to see that application alongside other applications for the same job on other platforms.

The applicant tracking email address

Most providers, though not all, use an applicant tracking email address. This is a unique email address generated by the posting service and saved in WordPress as meta data against the newly created job post.

Any emails to this address are applying for the job and will show up in the posting service candidate section.

Therefore if you have an application form on your site, it is important that a notification email for the form entry, is delivered to that tracking address when the form is completed. This email must include the candidates name and email address (entered into the application form) in the Reply-To header of the email. The CV uploaded to your form must be attached to this email and any information entered into the form, included in the body of the email.

This email is then parsed in the posting service so the application shows up alongside applications for the same job from other job boards.

Developer note

If you have chosen to use the WP Job Manager job board plugin to provide your sites job board functionality, you can also use their applications add-on. This provides an application form for you, output underneath each job on the single job page.

Additional, our connector plugin includes the necessary code to make sure that notification emails are sent to the tracking address correctly.

The applicant tracking URL

Most posting services also provide an applicant tracking URL. This is a URL to a hosted applicant form, hosting on the posting services site. Posting services provide limited customisation methods for this form, for example the ability to add your company logo.

This can be used as a link on the apply buttons to take candidates to this form.

How customisable is JobRelay?

The connector plugin added to WordPress has a number of hooks and filters which developers can use to run their own code and change values at various different places. Below is a brief overview of the most useful.

JobRelay filters

The following hooks are available.

jobrelay_wpcon_job_data( $job_data )

This filter fires before any data is processed. It is passed the job data array including all of the data sent from the posting service. It allows developers to manipulate the data arriving in WordPress before it is processed.

jobrelay_wpcon_insert_job_post_args( $args, $job_data )

Allows developers to change the arguments used in the wp_insert_post() call when before the new job is created. The filter is passed the array of job data from the posting service.

jobrelay_wpcon_update_job_post_args( $args, $job_post_id, $job_data)

After a new job is saved to WordPress, it is updated in order to update the jobs URL, based on the newly assigned post ID. This filter allows developers to modify to arguments used in the call wp_update_post() when this happens. The filter is passed the the following arguments:

  • $job_post_id – this is the ID of then newly created job post
  • $job_data – this is the array of job data from the posting service

JobRelay actions

The following action hooks are available.

do_action( 'jobrelay_wpcon_job_inserted', $job_post_id, $job_data );

This action fires directly after a new job has been inserted into WordPress, but before any taxonomy term or meta data has been saved. It is passed the following arguments:

  • $job_post_id – this is the ID of then newly created job post
  • $job_data – this is the array of job data from the posting service

do_action( 'jobrelay_wpcon_meta_added', $job_post_id, $meta_key, $meta_value, $job_data );

Fires directly after job meta data is successfully saved. It is passed the following arguments:

  • $job_post_id – this is the ID of then newly created job post
  • meta_key – the meta key of the saved meta data
  • meta_value – the value of the meta data just saved
  • $job_data – this is the array of job data from the posting service

do_action( 'jobrelay_wpcon_job_term_added', $job_post_id, $job_tax_terms, $taxonomy, $job_data );

Fires directly after job taxonomy term data is successfully saved. It is passed the following arguments:

  • $job_post_id – this is the ID of then newly created job post
  • $job_tax_terms – the term names just added
  • $taxonomy – the name of the taxonomy the terms where added to
  • $job_data – this is the array of job data from the posting service

do_action( 'jobrelay_wpcon_job_inserted_complete', $job_post_id, $job_data );

This action runs after the job, its meta data and taxonomy terms have all be processed and added to WordPress. It is passed the following arguments:

  • $job_post_id – this is the ID of then newly created job post
  • $job_data – this is the array of job data from the posting service

do_action( 'jobrelay_wpcon_job_deleted', $update_post_id, $job_data );

Fires directly after a job has been deleted. It is passed the following arguments:

  • $update_post_id – this is the ID of deleted job post
  • $job_data – this is the array of job data from the posting service