Employees - XML file format

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
• Employee files will always be processed before position files to help avoid errors
• The file must include all Active employees; Do not include Inactive employees or specific types that you want to exclude (ex Contractors or Interns)

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 doesn't actually convert the content to UTF-8, it just states that the content should be encoded 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 program 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

<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.

• Required
• Must be the ISO 2 digit country code (see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
• Must be a country that has been setup in your program

<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”

Offline Invites

If your program is configured to allow employees without an email address (i.e. you have email addresses for some, but not all of your employees):

• You must exclude the <email> element for them.
• If you provide an email address - the system will send the usual welcome email.
• If you do not orovide 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 used for all 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.

Error Messages

Please see Employees - Error File Messages.