How to configure an XML importer?

Use an XML importer to create and maintain jobs from a feed. This guide explains how to connect a feed, map its job information and prepare the importer for regular use.

There are two configuration views:

• Simple setup: Scans the feed and suggests field mappings for you to review.
• Advanced setup: Provides XPath Parser Settings for manual configuration.

Both views configure the same importer. You can switch between them at any time; changes appear in the other view where supported. Simple view opens first when you edit an existing importer and displays its current configuration

For an introduction to the feature, see What is an XML importer and how can I use it?. To check your feed or request setup by Jobiqo, see [LINK: XML feed requirements and setup checklist].

Create the importer

1. Log in with an admin account.
2. Go to Jobs > Job Importers, or open /admin/content/feed.
3. Select “Add Feed”, or open /feed/add.
4. Choose the importer type:
   • Job importer template: creates regular job ads with text content.
   • Job importer per link: displays jobs through an embedded Job Widget using an iframe.

The importer type cannot be changed after the importer has been created.

Enter the feed details

1. Enter a title that helps you identify the importer in the backend.
2. Select the owner frontend. Only one owner frontend can be selected. (On single-frontend projects, the publishing frontend is already selected and cannot be changed).
3. Select the frontend or frontends where the jobs should be published (One importer can publish jobs on several frontends).
4. Enter the XML feed URL.
5. Configure authentication if required.

Connect and authenticate the feed

Site admins and full admins can configure protected feeds directly, without manual downloads or workarounds.

Unprotected feed

1. Leave “Authorization mode” set to “Static token”.
2. Enter the feed URL.
3. Leave the authentication fields empty.
4. Continue with “Scan XML”.

With no authentication details entered, the feed is treated as unprotected.

Feed with a static token

1. Select “Static token”.
2. Enter the feed URL.
3. Complete the relevant fields using the provider’s instructions:
   • Authorization header key: the header key supplied by the provider, if required.
   • Authorization header token: the token supplied by the provider, if required.
   • Accept encoding headers: optional values for the Accept-Encoding header, such as deflate or gzip;q=1.0.

Feed with OAuth2 client credentials

1. Select OAuth2 client credentials.
2. Enter the credentials supplied by the provider.
3. Complete the required source settings.

The system handles authentication and retrieves a fresh copy of the job data automatically. The copy is stored locally on your site and processed using the importer’s parsing, field mapping and scheduling settings.

Set the Context

Your XML feed contains a separate section for each job. The “Context” field tells the importer which tag marks each job and where to find it.

For example, this feed has two jobs. Both use a <job> tag inside the outer <jobs> tag. For this feed, enter the following in “Context”: /jobs/job:

<jobs>
  <job>
    <title>Software Engineer</title>
  </job>
  <job>
    <title>Marketing Manager</title>
  </job>
</jobs>

This means: look inside <jobs> and read each <job> as a separate job. Use the tag names and structure from your own feed. For example, if the jobs sit inside <data>, then <jobs>, the path is /data/jobs/job.

Alternative tag names, such as <listings> and <listing>, are supported as long as they are consistent across the feed. Mixing tags for the same object, for example, <jobs> and <listings> in the same feed, is not supported.

Example XML Feed

The following is a representative example of a well-formed XML feed containing a single job listing with all recommended fields populated:

<jobs>
  <job>
    <jobId><![CDATA[12345]]></jobId>
    <title><![CDATA[Senior Software Engineer]]></title>
    <description><![CDATA[Full job description here...]]></description>
    <company><![CDATA[Acme Corporation]]></company>
    <city><![CDATA[Richmond]]></city>
    <state><![CDATA[VA]]></state>
    <country><![CDATA[US]]></country>
    <postalCode><![CDATA[23890]]></postalCode>
    <postedAt><![CDATA[2024-03-01T10:00:00Z]]></postedAt>
    <jobUrl><![CDATA[https://example.com/apply/12345]]></jobUrl>
    <applicationEmail><![CDATA[jobs@example.com]]></applicationEmail>
    <category><![CDATA[Engineering]]></category>
    <companyLogo><![CDATA[https://example.com/logo.png]]></companyLogo>
    <salaryMin><![CDATA[80000]]></salaryMin>
    <salaryMax><![CDATA[120000]]></salaryMax>
    <salaryCurrency><![CDATA[USD]]></salaryCurrency>
    <salaryFrequency><![CDATA[Yearly]]></salaryFrequency>
  </job>
</jobs>

Map the job information: Simple setup

Once you’ve added the feed details and specified the job path in the Context field, select Scan XML.

The system:

• Detects the XML structure.
• Displays the first job in the XML preview.
• Lists the job’s XML tags.
• Suggests mappings for recognised fields based on the structure and node names.

If a node contains more than five lines, the preview shows the first five followed by an ellipsis (...). Check the complete imported job during testing rather than relying only on the preview.

Review the suggested mappings

The XML mapping appears in the left column for each field. You can add or change a mapping in four ways:

• Select a field, then select a tag.
• Drag an XML tag from the panel into the field.
• Choose an available tag from the drop-down.
• Enter an XPath expression.

For nested information, use the path to the child node, such as location/street or location/city. Review every automatic mapping before saving.

Required fields and settings

Application workflow

The selected workflow determines which application field is shown. Other application fields remain hidden.

Additional fields

Map the additional information you want to import:

• Company, Country, State and Postal code
• Occupational field and Employment type
• Remote option
• Logo
• Salary range
• Salary min, Salary max, Salary frequency and Currency

For salary, use either the minimum and maximum values or the Salary range. Salary range is a separate taxonomy-based range, not another name for minimum and maximum salary.

For the broader field reference, see [LINK: XML feed requirements and setup checklist].

Map several XML tags to one field

Four fields accept more than one XML tags:

• Description
• Occupational field
• Employment type
• Remote option

Drag the first tag into the field, then add further tag. Additional paths are separated by |, for example:

node1|node2|node3

Check taxonomy matching

For fields such as Employment type and Occupational field, check that the feed values match your site’s taxonomy terms. If the feed uses different wording, add synonyms before importing.

For instructions, see How can I edit an imported job?.

Advanced setup

Open “XPath Parser Settings” to configure additonal field mappings manually.

Always enter the path to the information, not the value itself. For example, enter jobId, not 12345. Always configure “Feeds item: guid”, which is a job ID so the importer can recognise the job on subsequent imports.

For a larger example and field reference, see [LINK: XML feed requirements and setup checklist].

Match feed values to taxonomy terms

The importer matches feed values to existing taxonomy terms for:

• Required degree level
• Employment type
• Years of experience
• Fields of study
• Required languages
• Occupational field
• Salary range
• Required skills
• Remote option
• Industry

Add synonyms where the feed uses different wording from your site. For example:

If the same synonym is assigned to several terms, a job can receive all matching terms.

For instructions on adding synonyms and updating existing imported jobs, see How can I edit an imported job?

Review the remaining settings

The remaining importer settings appear below the Simple mapping and are shared by both configuration views.

For detailed instructions, see Importer Interface.

5. Test before publishing

Before running the first import:

1. Enable “Jobs need review”.
2. Enable “Exclude from Google 4 Jobs index and sitemaps”.
3. Limit the import to a small test batch.
4. Save the configuration and run the test.
5. Review the job content, location, taxonomy, application details and organisation assignment.

Follow What should I consider when testing a new XML importer? for the test filter and complete checklist.

Use the test-batch filter only for a new importer. Applying it to an importer with live jobs can cause jobs outside the filter to be treated as removed from the source and unpublished. The Google exclusion setting alone does not prevent jobs from appearing in Google.

6. Start regular imports

Once testing is complete:

1. Remove any test filter from “Context”. Running “Scan XML” again does not remove it automatically.
2. Turn off “Jobs need review” if future jobs should publish automatically.
3. Turn off the Google exclusion setting if jobs should be eligible for inclusion.
4. Under Import options, enable “Active” for automatic imports.
5. Choose the “Import period”.
6. If required, set “Active until” to deactivate the importer at a specified date and time.
7. Save the configuration and run the full import.

The default import period is every three hours. This sets the scheduling interval, not an exact start time; an import may wait for other background tasks to finish.

Use “Save” to store the configuration without explicitly starting an import, or “Save and Import” to save and start the initial import. For an existing importer, select “Import in background” on the View tab to request a run at the next available time.

Copy an existing importer

Use “Clone” to create another importer with the same configuration.

• All settings and mappings are copied.
• The title and feed URL are not copied; both are empty.
• Enter a new title and URL before saving or importing.

“Clone” is available at the bottom of the feed configuration page and under “Edit” in the Job Importers overview. Check the copied settings before running the new importer.