Employee File

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

Requirements

  • The file must contain no more than 10,000 employees. If you have more than 10,000 employees 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, “Maïté” will be shown as “Ma�t�”.

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 employees should be within an <employees> element

  • For each employee there should be an <employee> element which should contain:

    • <forename> element
    • <surname> element
    • <employee_id> element
    • <employee_type> element
    • <department> element
    • <start_date> element
    • <country> element
    • <email> element

    For example:

    <?xml version="1.0" encoding="utf-8"?>
    <employees>
        <employee>
            <forename>John</forename>
            <surname>Smith</surname>
            <employee_id>12345</employee_id>
            <employee_type>employee</employee_type>
            <department>IT</department>
            <start_date>2012-12-13</start_date>
            <country>GB</country>
            <email>john.smith@workstars.com</email>
        </employee>
        <employee>
            <forename>Rob</forename>
            <surname>Jones</surname>
            <employee_id>54321</employee_id>
            <employee_type>employee</employee_type>
            <department>SALES</department>
            <start_date>2014-07-01</start_date>
            <country>GB</country>
            <email>rob.jones@workstars.com</email>
        </employee>
    </employees>
    
  • If your scheme doesn’t have hierarchy, it can also contain:

    • <job_title> element
    • <manager> element (if required)

    For example:

    <?xml version="1.0" encoding="utf-8"?>
    <employees>
        <employee>
            <forename>John</forename>
            <surname>Smith</surname>
            <employee_id>12345</employee_id>
            <employee_type>employee</employee_type>
            <department>IT</department>
            <start_date>2012-12-13</start_date>
            <country>GB</country>
            <email>john.smith@workstars.com</email>
            <job_title>IT Manager</job_title>
            <manager>1</manager>
        </employee>
        <employee>
            <forename>Rob</forename>
            <surname>Jones</surname>
            <employee_id>54321</employee_id>
            <employee_type>employee</employee_type>
            <department>SALES</department>
            <start_date>2014-07-01</start_date>
            <country>GB</country>
            <email>rob.jones@workstars.com</email>
            <job_title>Sales Manager</job_title>
            <manager>1</manager>
        </employee>
    </employees>
    

Element Details

Below are more details about each of the possible elements. Although we have included information about validation please refer to the schema file for the exact validation rules.

<forename>

This should contain the employee’s forename.

  • Required
  • Must be alphanumeric
  • Max 50 characters

<surname>

This should contain the employee’s surname.

  • Required
  • Must be alphanumeric
  • Max 50 characters

<department>

This is the department where the employee works. It must be unique (e.g. SALES, IT, MARKETING, etc.) and preferably should be a unique reference rather than a name.

  • Required
  • Max 100 characters

Note

Before uploading the file you must login to the administration portal and setup your Reporting Groups. You can then map your departments to them. If a mapped entry cannot be found, the employee will not be added and an error will be reported.

<employee_id>

This is the employee’s unique ID.

  • Must be alphanumeric (lowercase only)
  • Max 30 characters
  • Must be unique

<employee_type>

This field defines the type of employee. Some functionality in the system can be restricted based on this data (e.g. contractors might be excluded from financial reward).

  • Required
  • Must be “employee” or “contractor”

<start_date>

This is the date the employee joined your organisation

  • Required
  • Must be in the format YYYY-MM-DD (e.g. 2017-12-13)

<country>

This is the country the employee works in.

<email>

This is the email address of the employee.

  • Required
  • Max 75 characters
  • Must be in lower case
  • Must be a valid email format
  • The domain must accept email (we will check its DNS MX record)

<job_title>

This is the job title of the employee.

  • Required if you are not using hierarchy
  • Max 100 characters

<manager>

This is whether the employee is a manager or not.

  • Optional and only if you are not using hierarchy
  • To enable manager tools set it to a value of “1”
  • To disable manager tools set it to a value of “0”

Note

To avoid this overriding what has been done manually in the administration portal, if the element is not present it will NOT automatically remove the manager flag. To disable manager tools you must set it to “0” or remove the privilege manually by using the administration portal.

Offline Invites

Note

Please contact your account manager to enable this setting.

If you are running a scheme that uses offline invites (e.g. you email addresses for some but not all of your employees) then the email element is optional.

For employees where you provide an email address, the system will send the usual welcome email.

For employess where you do not provide an email address, you will be able to download a file from the administration portal. The file will contain a unique activation code which the employee can use along with their employeeID to register. During registration we will capture a personal email address for the employee, which will be use for future communications.

Troubleshooting

Content Issues

If you are seeing strange characters in employee names (e.g.”Ma�t�”), 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 'email': [facet 'pattern'] The value 'John.Smith@workstars.com' is not accepted by the pattern '[a-z0-9_\+\-\.]*@[a-z0-9\-\.]*'

This is telling you that the ‘email’ element doesn’t fit the pattern defined in the schema. In this case its because it contains upper case characters.

Line #27: Element 'email': [facet 'pattern'] The value 'bob!jones@workstars.com' is not accepted by the pattern '[a-z0-9_\+\-\.]*@[a-z0-9\-\.]*'

This is telling you that the ‘email’ element doesn’t fit the pattern defined in the schema. In this case its because the “!” character is not permitted in an email address.

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

This is telling you that there is a duplicate ‘employee_id’ of ‘12345’ in the file. Each employee must have a unique employee ID.

Line #19: Element 'employee_id': [facet 'pattern'] The value 'CWED1234' 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 to z and 0 to 9. The value in this example contains capital letters which are not permitted, please ensure ‘employee_id’ elements are in lowercase.

Line #10: Element 'country': [facet 'enumeration'] The value 'DE' is not an element of the set {'GB','FR'}

This is telling you that the element ‘country’ either contains an invalid country code or it is for a country not setup in your scheme. It shows the supported values at the end (e.g. GB, FR).

Line #21: Element 'start_date': '2007-26-10' is not a valid value of the atomic type 'xs:date'

This is telling you that the element ‘start_date’ contains an invalid date. The date must be in the format YYYY-MM-DD and must be valid.

Line #60: xmlParseEntityRef: no name

This is because the value contains a ‘&’ character. For example, if you have a job 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”)

Processing Errors

Employee '92': The 'department' has not been mapped to a Reporting Group. Please login to the admin portal and map this department to one of your Reporting Groups.

This is because the “department” in your file has not been mapped to a reporting group. Login to the admin portal and goto “Employees > Reporting Groups > Department Mappings”, click “Add Mapping” then enter your “Department” and select a reporting group.

Employee '92': The 'start_date' is different to what was provided when this employee was added. Please login to the admin portal and edit the start date manually.

This is because the “start_date” in your file is different than the one you provided when the employee was added. Login to the admin portal and goto “Employees”, search for the employee and update their Start Date manually.