Position File

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 (see hrdatasync-overview-v2)
  • 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>HR 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.

Note

TIP: If you have data that contains diacritic characters (e.g. “ö”), you should open the XML file in a program that understands UTF-8 and visually check they are being saved correctly.

Validation Errors

Below are some error messages when using the schema to validate the file. Your messages might be slightly different as each programming language implements its own messages.

Line #17: Element 'position_id': Duplicate key-sequence ['12345'] in unique identity-constraint 'position_id_unique'

This is telling you that there is a duplicate ‘position_id’ of ‘12345’ in the file.

Line #19: Element 'employee_id': [facet 'pattern'] The value 'C1734345' is not accepted by the pattern '[a-z0-9]*'**

This is telling you that the ‘employee_id’ element doesn’t fit the pattern defined in the schema. In this case the pattern only allows lowercase a-z and 0-9. There is a capital ‘C’ which is not permitted, please ensure ‘employee_id’ elements are in lowercase.

Line #19: Element 'employee_id': [facet 'minLength'] The value has a length of '0'; this underruns the allowed minimum length of '1'

This is telling you that the ‘employee_id’ element should contain at least 1 character. In this case it is usually because the position is vacant and you have included the element. Remove the element for vacant positions.

Line #18: Element 'parent_position_id': This element is not expected. Expected is ( employee_id )

This is telling you that the element ‘parent_position_id’ is not expected. In this case its because you have included it in the <root> position element, this is the top of the hierarchy and as such can’t have a parent position.

Line #60: xmlParseEntityRef: no name

This is because the value contains a ‘&’ character. For example, if you have a position title of “Head of Sales & Marketing” then you must replace the ‘&’ with ‘&amp;’ (e.g. “Head of Sales &amp; Marketing”). Alternatively, you can just replace it with the text equivalent (e.g. “Head of Sales and Marketing”)