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