Positions - XML File Format

This document explains how to create an XML file containing your hierarchy.

Requirements

• Your hierarchy must be complete and functional. This involves checking that every position in the file reports to a position that eventually reports to the CEO/MD. If any positions fail this test, the ENTIRE file will be rejected. This check is to ensure that your recognition program is not affected by any short term internal data issues.
• The file must contain no more than 10,000 positions. If you have more than 10,000 positions, please speak to your account manager.
• The file should be validated against our XSD schema prior to being uploaded
• Employee files will always be processed before position files to help avoid errors.

Encoding

The data in the file should be UTF-8 encoded. You should ensure that retrieving the data from your system also respects UTF-8 characters, otherwise you might see some characters replaced with ?’s.

For example, “Direktör” will be shown as “Direkt�r”.

File Specification

• The first line should be as shown below. Please see the “Encoding” section above as this does convert the content to UTF-8, it just states that the content should be encoding in UTF-8.

<?xml version="1.0" encoding="utf-8"?>

• The positions should be within a <positions> element
• The root position (i.e. the position at the top of the hierarchy) should be within a <root> element. There should only be one of these in the file. It should contain:
  • <position_title> element
  • <position_id> element
  • <employee_id> element (if appropriate)
• For each position there should be a <position> element. It should contain:
  • <position_title> element
  • <position_id> element
  • <parent_position_id> element
  • <employee_id> element (if appropriate)

For example:

<?xml version="1.0" encoding="utf-8"?>
<positions>
    <root>
        <position_title>CEO</position_title>
        <position_id>1</position_id>
        <employee_id>64788</employee_id>
    </root>
    <position>
        <position_title>HR Director</position_title>
        <position_id>2</position_id>
        <parent_position_id>1</parent_position_id>
        <employee_id>38456</employee_id>
    </position>
    <position>
        <position_title>Benefits Manager</position_title>
        <position_id>4</position_id>
        <parent_position_id>2</parent_position_id>
        <employee_id>59383</employee_id>
    </position>
    <position>
        <position_title>HR Manager</position_title>
        <position_id>5</position_id>
        <parent_position_id>2</parent_position_id>
        <employee_id>87845</employee_id>
    </position>
    <position>
        <position_title>Sales Director</position_title>
        <position_id>3</position_id>
        <parent_position_id>1</parent_position_id>
        <employee_id>95466</employee_id>
    </position>
    <position>
        <position_title>Sales Manager</position_title>
        <position_id>6</position_id>
        <parent_position_id>3</parent_position_id>
        <employee_id>75238</employee_id>
    </position>
    <position>
        <position_title>Sales Manager</position_title>
        <position_id>7</position_id>
        <parent_position_id>3</parent_position_id>
    </position>
</positions>

Element Details

Below are more details about each element. Although we have included some validation rules, please refer to the schema file for exact requirements.

<position_title>

This should contain the the job title for the position:

• Required
• Max 100 characters

<position_id>

This should be a unique ID for the position:

• Required
• Must be alphanumeric (lowercase only)
• Max 50 characters
• Must be unique

<parent_position_id>

The <position_id> (from above), which relates to the position it reports to.

• Required (except for the root position)
• Must be alphanumeric (lowercase only)
• Max 50 characters
• Must contain a valid <position_id> from the file

<employee_id>

Enter the Employee ID of the person occupying this role. We use this field to map employees to positions. If the position is vacant, then this element is not required (it should not be present rather than blank).

• Must be alphanumeric (lowercase only)
• Max 30 characters
• Must contain a valid <position_id> from the file

Troubleshooting

Content Issues

If you are seeing strange characters in position titles (e.g. “Direkt�r”.), this is because you are either retrieving the content from your HR system with an incorrect encoding or you are saving them with some software that is using an incorrect encoding. You should ensure you use UTF-8 encoding when retrieving and saving content.

Error Messages

Please see the Positions - Error File Messages.