Loading...
  • Customer Experience
    Customer Experience
  • Employee Experience
    Employee Experience
  • Brand Experience
    Brand Experience
  • Product Experience
    Product Experience
  • Core XM
    Core XM
  • Design XM
    Design XM

Preparing Your Participant File for Import (EX)

What's on This Page:


Was this helpful?


This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

The feedback you submit here is used only to help improve this page.

That’s great! Thank you for your feedback!

Thank you for your feedback!


Qtip: This first section of this page describes file requirements for uploading participants to Engagement, Lifecycle, and Ad Hoc Employee Research projects. However, keep in mind that the rest of this page also talks about hierarchy-specific file requirements, which do not apply to Lifecycle or Ad Hoc Employee Research. For more details on each, see Types of Employee Experience Projects.

About Preparing Your Participant File

When importing participants into your Employee Engagement project, there are a few important things to keep in mind. For example, every import will need the following columns:

  • First Name: The employee’s first name.
  • Last Name: The employee’s last name.
  • Email: The employee’s email address. This detail is the most important. Email can act as username for each participant or as a way to remember which users already exist in the directory.
  • UniqueIdentifier: Specify participants by whatever identifier your company prefers. You can use anything from internal numeric IDs to usernames, to a repeat of the EmployeeID column (but only if this is unique within the organization, and will not be shared with anyone in any other project).
    Qtip: Does your Example file have a UniqueIdentifier, and you’d like to know more? Are you transferring from email addresses as your identifier to Unique IDs? Check out the Unique Identifiers support page.
Qtip: If your organization has SSO, make sure to upload participants to your directory with a column for UserName that matches their SSO username attribute before uploading participants to your projects.

In addition, you’ll want to make sure that you’ve chosen the right hierarchy for your project since this affects the metadata, or custom columns of participant data, that you will include in your CSV/TSV file. For example, the Parent-Child hierarchy file should include columns for Employee ID and Manager ID, whereas the Level-Based hierarchy file should have different Level columns. We go over the metadata you need to include for each hierarchy on this page.

Qtip: You may have multiple hierarchies in your project, but metadata fields can only be used to generate one hierarchy. For example, if I use “ManagerID” to build my first hierarchy, I cannot use that field to build my second hierarchy.

If you forget to include the correct metadata to begin with, that’s ok! You can always update your participants’ metadata after the fact by following the steps at the linked section.

Qtip: Ready to upload the file, but not sure how? Once you’ve set up your hierarchy file according to the instructions on this page, head over to our Adding Participants support page.
Qtip: Not sure what type of hierarchy fits your HR data best? Check out a basic comparison of your options on the Hierarchies Basic Overview page.

Importing Participants for a Parent-Child Hierarchy

Parent-Child hierarchies are the most commonly used kind of hierarchy. They are the best option if your HR data is formatted so you have a list of employees’ IDs and the managers each employee reports up to.

Click here to access the Parent-Child hierarchy file template.

Required Metadata

There are two metadata columns you must include to create a Parent-Child hierarchy:

  • EmployeeID: This is the employee identification of the participant. It is best to use the IDs your company’s HR department has internally assigned, rather than trying to make up new randomly generated IDs.
  • ManagerID: This is the employee identification of the participant’s manager.

Example: In the image below, John Doe’s EmployeeID is 1, so his EmployeeID column says 1. Jill Davis, Sammy External, and Joseph Miller report directly to John Doe, so their ManagerID columns say 1.

A CSV. John Doe's EmployeeID EmployeeID column says 1. Jill Davis, Sammy External, and Joseph Miller ManagerID columns also say 1

Qtip: Technically, you can name the EmployeeID and ManagerID whatever you’d like. For example, if your organization prefers the term “employee number” or has a special term like “QID,” feel free to give your columns these names. What’s important is that you include these concepts and enter them into the correct fields when you generate your Parent-Child hierarchy.

When adding Employee and Manager IDs, there are a few important things to keep in mind:

  • If your license uses Unique Identifiers, then the Unique Identifier column of your data can be used for your Employee ID field when generating a Parent-Child hierarchy. Here’s how the previous example would look in that circumstance:
    Same file as before, but employee id column is now called unique identifier
  • Every participant must also have a unique Employee ID. Multiple participants cannot share the same ID. (Hence why we advise using Unique IDs, if your brand has this feature.)
  • Every participant must have a manager. The only exception are the highest members of the company you include in your hierarchy (e.g., CEOs). Leave the manager column empty to show this person doesn’t report to anyone.
  • An individual employee’s Employee ID and Manager ID columns should never be the same. Employees don’t report to themselves!
  • Every Manager ID must link back to an employee. Any participant with a Manager ID that does not correspond to an existing Employee ID will be assigned to an Unknown Manager. Please note that once someone is assigned to an Unknown Manager, the members of the hierarchy below this person will also be broken. To fix this issue, you must manually fix the data and regenerate the hierarchy.
  • Watch out for circular logic. If John Doe reports to Jane Smith, and Jane Smith reports to Joseph Miller, Joseph Miller cannot report to John Doe. You cannot manage your manager’s manager.

Optional Metadata

You can add any additional metadata that you wish when uploading your participant list. Anything from each employee’s birthday to their office locations can be included. However, there are two optional metadata that can help you format your Parent-Child hierarchy.

  • Org Unit ID: Org Unit IDs help you identify the same team over time, even if the team’s name changes. It serves the same purpose as a unique employee ID, but for a unit instead of an employee. Including a stable Org Unit ID means you don’t have to manually map hierarchy data; the system will recognize the ID and map appropriately.
    Qtip: Have different teams with the same name? Or, do you have separate sets of teams and managers reporting within the same division? You can reuse the same Org Unit Description by setting separate Org Unit ID fields. For example, one sales manager may run a team called Sales with an Org Unit ID of 001, and another manager may run a team called Sales with an Org Unit ID of 002.

    Org Unit IDs are also useful if a manager is over multiple teams. This means that if my manager is John Doe, but John Doe is the manager of Team A and Team B, I can specify to which team I belong with the Unit ID field.

  • Org Unit Description: When creating your hierarchy, units will be automatically named for a manager. The Org Unit Description setting allows you to name your units based on names or descriptions of the units instead.

The Org Unit Description is essentially the name provided for the provided Org Unit ID, and will appear as the unit’s label in dashboards when filtering or breaking out by unit. The columns shouldn’t necessarily contain the same exact values, but while ID is numeric, Description is descriptive. For example, Org ID 2’s Org Unit Description may be European Division.

Example: In the image below, John Doe manages two different teams: the European Division and Leads Investigation. The Org Unit Description column specifies which of these teams his 3 direct reports belong to. We see Jill Davis and Joseph Miller are in the European Division, but Sammy External is in Leads Investigation.

A CSV where John Doe's direct reports have different things written in their Org Unit Description to indicate they're in different teams of the same manager

Qtip: Technically, you can name the Org Unit ID Field and Org Unit Description whatever you’d like. For example, you can name your columns Unit Name, Team, or Department instead of Org Unit Description. What’s important is that you include these concepts, and enter them into the correct fields when you generate your Parent-Child hierarchy.

Importing Participants for a Level-Based Hierarchy

Level-Based hierarchies are a good option if your HR data includes each level the employee reports to, from the top of the hierarchy all the way down to where the employee sits. With Level-Based hierarchies, you don’t necessarily have to know who the employee’s manager is; you just need to know the chain of command for each employee you’re including in the project. This data format is often more common with companies that organize employee data by distinct levels, location, or functional breakout.

Click here to access the Level-Based hierarchy file template.

Example: Hierarchies can manage what data each participant can see on a dashboard. Let’s say you have stores in different locations competing for a company prize, and you want participants to be able to see their own engagement dashboards, but not each other’s. Building a hierarchy based on location allows you to restrict which location’s data each participant sees when you later build a dashboard role or set dashboard user permissions.

Required Metadata

You will need a separate column for each level of your organization you wish to define. The last level filled for a participant indicates their place in the hierarchy. For those higher up, this usually means the first Level column is filled, but the rest aren’t.

Example: Let’s say your company has locations across the United States. Level 1 might include all the states your offices are located in. Then Level 2 could be the city in which these offices are located. This means a participant in a Dallas, Texas office would have a Level 1 of Texas and a Level 2 of Dallas. Another participant with a Level 1 of Texas might have a Level 2 of Houston.
A CSV with participants whose Level 1 is Texas. Some have a Level 2 of Dallas, and other have a Level 2 of Houston

Manager Metadata

If you’re interested in assigning managers to units in your Level-Based hierarchies, there are two different ways to do it.

  • Manager: This column indicates whether the participant is a manager. The participant will be assigned as the manager of the lowest level he or she has listed. Most users use “yes” to indicate a manager, but you can also use “1,” “manager,” or any format you’d like, so long as you have one value in the column that indicates that the participant is a manager.
    Example: In the image below, the lowest level defined for Sammy Stanage is Level 1, where he is in a Customer Success role. The “yes” in his Manager column indicates he is manager over all of Customer Success. Meanwhile, Jeff Brown’s last level defined is Employee Experience within Engineering. This means that within Engineering, he is head of the Employee Experience level.
    A CSV where Jeff Brown has his Level 1 and 2 filled out, whereas Sammy External's Level 2 is blank.
  • Manager Level: Manager Level is a means of identifying managers by calling out the specific level they manage. In the previous example, the same value (“yes”) indicates whether or not a participant is a manager; for Manager Level, however, there are separate values for each level.
    Example: In the image below, Jeff Brown’s Manager Level is 2 to indicate he is manager of his Level 2 position in Employee Experience, not manager of his Level 1 position in Engineering.
    A CSV where Jeff Brown's Level 2 has a value and his manager level is set to 2

Optional Metadata

Org Unit IDs: Org Unit IDs help you identify the same team over time, even if the team’s name changes. Including a stable Org Unit ID means you don’t have to manually map hierarchy data; the system will recognize the ID and map appropriately. It serves the same purpose as a unique employee ID, but for a unit instead of an employee. You need to include as many Org Unit IDs as you do levels, so you can provide an ID for each level.

Example: The units in Level 1 correspond to the column Org Unit ID 1. Finance is unit 101, Engineering is 123, and so on. If we uploaded a hierarchy next year and renamed Finance to The Penny Patrol, we’d give it the same ID, 101, so that we wouldn’t have to manually map hierarchy data in order to report on multiple years’ worth of engagement data in our dashboard.
Level 1 and Org Unit ID 1 are highlighted
In the screenshot below, the units in Level 2 correspond to the column Org Unit ID 2. The Employee Experience engineering team is unit 201, and the Customer Experience engineering team is 224.
Level 2 and Org Unit ID 2 columns are highlighted
Qtip: Technically, you can give these metadata columns whatever names you’d like. For example, if your hierarchy is going to be based off of location, you can have columns named Country, State, and City instead of Level 1, Level 2, and Level 3. What’s important is that you include these concepts, and enter them into the correct fields when you generate your Level-Based hierarchy.

Importing Participants for a Skeleton Hierarchy

Skeleton hierarchies are used when you know the identity of your managers, but not their direct reports. Instead of organizing a hierarchy around a list of direct reports and the chain of command above them, you build out a list of managers and the units they roll up to.

Here is an example Skeleton hierarchy to get you started. Create a CSV/TSV and create a row with each manager on it. You must at least have manager information to build a Skeleton hierarchy.

For each manager, add a column for the manager’s First Name, Last Name, Email, and whatever additional metadata you’d like to include. Then, you must add the following metadata:

  • Org Unit ID: The ID of the unit the employee manages.
  • Parent Unit ID: The ID of the unit directly above this unit. This is the unit the employee reports to.
  • Org Description: This metadata is optional. It allows you to create a name for the unit the employee manages. This can be the name of the team, or even the manager’s name.

Example: In the below example, IT is a larger department that Engineering is nested underneath. John Doe is the manager of IT, so his Org Unit ID column says 1 to indicate IT’s unit ID is 1. Geoff Brown and Jill Davis are the managers of Engineering, so they both have a Parent Org ID of 1 to indicate that IT is the parent unit of Engineering.

A CSV where John Doe's Org Unit ID column says 1. Geoff Brown and Jill Davis have a Parent Org ID of 1.

Qtip: Is your participants file already imported? Head over to the Generating a Parent-Child Hierarchy support page for further instruction on generating the hierarchy.

FAQs