NHS Jobs List Employer Adverts Purpose The purpose of this document is to describe the process and identify the different options that you have when listing your organisation’s job adverts from NHS Jobs on your website or intranet, using the NHS Jobs List Employer Adverts interface. This document and the interface service is only for the use of NHS organisations enabled and authorised to use NHS Jobs. Listing adverts Once you have posted your job adverts on the NHS Jobs website they will be accessible through the NHS Jobs online search features and Jobs by Email to job hunters on the internet. Those identified as for ‘All NHS Jobs Visitors’ will be available to any job seekers with public internet access to the Wold wide Web. Those identified as for ‘Internal Only’ can be available to an organisation’s own employees and will not be available to job seekers visiting the NHS Jobs website or receiving Jobs by Email from NHS Jobs. You can list your job adverts, both ‘All NHS Jobs Visitors’ and ‘Internal Only’, from or within your own website or intranet (‘Internal Only’ adverts should only be available through your own intranet, to avoid receiving applications from job seekers outside of your organisation.) You can do this in one of the following ways: 1. you can put a button, banner or link on your website or intranet which, when selected, will display a page from the NHS Jobs site listing your vacancies only. 2. you can put a button, banner or link on your website or intranet which, when selected, will return a list of your vacancies in xml format which can then be formatted on your website or intranet to be displayed as part of it. These options are explained further in the following pages. Version 1.0 1 © NHS Jobs 2013 Option 1 The first option will result in an NHS Jobs service page listing your vacancies being displayed with all navigable options available to the jobseeker as shown in Figure 1. Figure 1 - Option 1 search results page Using option 1 means that the visitor will be viewing the list directly on NHS Jobs website, not your website, and will have all NHS Jobs search and refine features available to them. You could display this information in a new browser window/tab so that your website remains open in their browser. For this option, use the following url with the button, banner or link (where the number 123456 is replaced by your client_id1 ): www.jobs.nhs.uk/extsearch?client_id=123456 Your client_id is the unique identifier used to identify an organisation within the NHS Jobs system. This is not your vpd_code. You can see your client_id by looking at your “Employer details” page on the NHS Jobs site. Version 1.0 2 © NHS Jobs 2013 Option 2 The second option allows the results to be embedded within your website or intranet under your control. In this case NHS Jobs will return the raw data in an RSS feed xml structure. You will need to produce the necessary software to format the data, with styles and images held locally, as required upon the page on your website or intranet. To do this simply use ‘search_rss’ instead of ‘extsearch’ in the url. www.jobs.nhs.uk/search_rss?client_id=123456 The xml structure returned is as follows: <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT nhs_search (status, vacancy_details*) > <!ELEMENT status (number_of_jobs_found, message*)> <!ELEMENT number_of_jobs_found (#PCDATA)> <!ELEMENT message (#PCDATA)> <!ELEMENT vacancy_details (id, job_reference, job_title, job_description, job_employer, job_type, job_specialty?, job_salary, job_location, job_closedate, job_postdate, job_staff_group, job_url)> <!ELEMENT id (#PCDATA)> <!ELEMENT job_reference (#PCDATA)> <!ELEMENT job_title (#PCDATA)> <!ELEMENT job_description (#PCDATA)> <!ELEMENT job_employer <!ELEMENT job_type (#PCDATA)> (#PCDATA)> <!ELEMENT job_specialty (#PCDATA)> <!ELEMENT job_salary (#PCDATA)> <!ELEMENT job_location (#PCDATA)> <!ELEMENT job_closedate (#PCDATA)> <!ELEMENT job_postdate (#PCDATA)> <!ELEMENT job_staff_group <!ELEMENT job_url Version 1.0 (#PCDATA)> (#PCDATA)> 3 © NHS Jobs 2013 Element definitions: nhs_search – root element, this contains all other elements. status – contains the elements listed below. number_of_jobs_found - contains the overall number of search results. message – contains error message generated by the request. vacancy_details – contains the elements listed below, all of which make up the individual vacancy. id – internal reference to the vacancy. job_reference – contains the reference from the job advert. This is structured as [vpd_code] & ’-‘ & [original reference] eg. 123-1234 job_title – the Position Title from the job advert. job_description – some selected text from the main text component of the job advert. The text will contain html formatting to highlight the terms matched from the original query. job_employer – the employer organisation advertising the job. job_type – the job type of the vacancy. job_specialty – the Specialty/Function from the job advert. job_salary – the salary from the job advert. job_location – the Displayed Location from the job advert. Note that the detail from the Postcode field is not included. job_closedate – the current expiry date from the job advert. job_postdate – the creation date from the job advert. Job_staff_group – the staff group category for the vacancy. job_url – the link to the vacancy details on the NHS Jobs website. Version 1.0 4 © NHS Jobs 2013 Setting up your own search You can set up your own search links by including any of the attributes below in the search string. Search links can be used to provide the visitor to your website with a link to quickly perform a predefined search on your jobs advertised on NHS Jobs. Examples of this could include: For “Internal Only” jobs www.jobs.nhs.uk/extsearch?client_id=123456&internal_only=Y www.jobs.nhs.uk/search_rss?client_id=123456&internal_only=Y For “scientist” jobs www.jobs.nhs.uk/extsearch?client_id=123456&keywords=scientist&field=title www.jobs.nhs.uk/search_rss?client_id=123456&keywords=scientist&field=title For “nursing” jobs www.jobs.nhs.uk/extsearch?client_id=123456&keywords=nurse nursing&field=title www.jobs.nhs.uk/search_rss?client_id=123456&keywords=nurse nursing&field=title For jobs including “Day Care” in advert text www.jobs.nhs.uk/extsearch?client_id=123456&keywords='day care'&field=description www.jobs.nhs.uk/search_rss?client_id=123456&keywords='day care'&field=description For jobs including “Day Care” or “child” in job title www.jobs.nhs.uk/extsearch?client_id=123456&keywords='day care' child&field=title www.jobs.nhs.uk/search_rss?client_id=123456&keywords='day care' child&field=title (where ‘123456’ is your client ID) A search form, or search box, would be a form on your website where the visitor can enter the term(s) they are searching for. When the visitor activates the search, the values entered would produce the necessary search on the NHS Jobs database and list the results on your website. An example is available upon request. Some of the additional attributes that you may wish to include in search links or a search form are listed on the following pages. Version 1.0 5 © NHS Jobs 2013 Table 1 Search attributes Attributes Action Notes client_id Use this to ensure that all jobs are limited to your employer id comma separate multiple employer_ids if necessary internal_only Use this to ensure that only jobs marked as ‘Internal Only’ are listed. If this parameter is used then you must also include a “client_id” parameter Use this to filter on the job title, advert description or job reference. If this parameter is used then you should also include a “field” parameter keywords Values Default values Value must be: Y If more than one keyword, separate them with spaces field Directs the use of keyword searching to relevant fields Only required if “keywords” is also used. Value must be: title description ref location To filter on the vacancy postcode use this parameter If this parameter is used the you should also include a “distance=” parameter Value should be outer postcode e.g. ‘BN11’ is the outer postcode of ‘BN11 1EG’ distance The location search can be expanded in radial increments. Only required if “location” is Value must be: Version 1.0 6 Defaults to searching in all three areas if not specified. Defaults to ‘10’ if © NHS Jobs 2013 Attributes Action Notes Values Default values Using E only returns jobs where there is an exact match with either the Displayed Location or the Postcode. Using any of the number values searches for jobs in other locations where the centre1 of the locations are within the radial distance (eg within 3 miles). also used. ‘E’ = exact location only not specified. ‘5’ = within 5 miles ‘10’ = within 10 miles ‘20’ = within 20 miles ‘30’ = within 30 miles ‘50’ = within 50 miles client_name To filter on Employer Name use this parameter. min_salary Use this and the following field to filter the search to jobs between 2 values Value format of ‘A’ followed by two or three digits as the number of thousands of pounds. (eg. A23 for £23,000) Value must be of format: Use this field with the previous field to filter the search to jobs between 2 values Value format of ‘A’ followed by two or three digits as the number of thousands of pounds. (eg. A23 for £23,000) Value must be of format: max_salary 1 Axy or Axyz Axy or Axyz the centre is the approximate centre based on ‘eastings’ and ‘northings’ obtained from the published PAF file. Version 1.0 7 © NHS Jobs 2013 Attributes Action jobtype Use this field to filter on the type of job. Value must be: ‘P’= Permanent ‘F’= Fixed Term ‘B’= Bank ‘H’= Honorary ‘L’= Locum ‘V’= Voluntary ‘TR’= Training ‘S’= Secondment ‘AP’= Apprenticeship sort_by Used to control the order in which the search results are displayed. Value must be: Used to control whether the shorter form of the job advert is shown. Value must be: daysback Used to control how recent the returned jobs should be Value must be: ‘7’= in the last 7 Days ‘3’= in the last 3 Days ‘2’= in the last 2 Days ‘0’= Today Defaults to all jobs if not specified. resonly Use this if you want to embed Value must be: Defaults to ‘0’ if simple_view Version 1.0 Notes 8 Values ‘date’= Most recent first ‘salary’= Highest salary first ‘Y’= exclude description Default values Defaults to most relevant first, if not specified. Defaults to long descriptions, if not specified. © NHS Jobs 2013 Attributes from_date Action Notes Values Default values the search results within your own web page. This is an optional attribute used to return the ‘results only’ without the header, side and footer navigation. ‘1’= don’t show navigation items not specified. Use this if you want to filter the search results by the date they were published on NHS Jobs Format must be: ‘0’= show navigation items “DD-MMM-YYYY” department Use this to filter on text within the department field area_of_work Use this field to filter on the Area of Work. Value must be a code value for the area of work category. Please see ‘Area of Work list’ document. pay_scheme Use this field to filter on the Pay Scheme Value must be: ‘AC’=Agenda for Change ‘MD’=Hospital Medical and Dental ‘SM’=Very Senior Manager ‘OT’=Other Version 1.0 9 © NHS Jobs 2013 Attributes Action pay_band Use this field to filter on the Pay Band Value must be: ‘1’ ‘2’ ‘3’ ‘4’ ‘5’ ‘6’ ‘7’ ‘8a’ ‘8b’ ‘8c’ ‘8d’ ‘9’ ‘CN’=Consultant ‘AS’=Associate Specialist ‘SG’=Staff Group ‘SR’=Specialty Registrar staff_group Use this field to filter on the Staff Group, to separate out different categories of adverts Value must be: 'ANY'= any staff group 'SG20'= Additional Clinical Services 'SG25'= Additional Professional Scientific & Technical 'SG10'= Administrative & Clerical Version 1.0 Notes 10 Values Default values © NHS Jobs 2013 Attributes Action Notes Values Default values 'SG15'= Allied Health Professionals 'SG30'= Estates & Ancillary 'SG35'= Healthcare Scientists 'SG45'= Medical & Dental 'SG40'= Nursing & Midwifery Registered 'SG55'= Students Document Revision Version Date Author Issue 1.0 6/9/2013 Peter Brown First published Version 1.0 11 © NHS Jobs 2013