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

Preparing a User File to Make a Hierarchy (CX)

What's on This Page:


Was this helpful?


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: CX Hierarchies are only available to CX licenses with ticketing included. If you’re interested in this feature, reach out to your Account Executive.
Qtip: CX Hierarchies and EX Hierarchies are very similar, but have some key differences. If you are an EX client, please see Preparing Your Participant File for Import (EE) instead.

About Preparing a User File to Make a Hierarchy

When importing users to your CX Dashboard, there are a few important things to keep in mind. For example, every import will need the following columns:

  • First Name: The user’s first name.
  • Last Name: The user’s last name.
  • Email: The user’s email address. This detail is the most important. Email can act as username for each user or as a way to remember which users already exist in the User Admin.
  • Username: If your organization uses SSO, you must include a Username column. This column should contain the same information as the Email column, because the#brandId will be automatically added to the end.
  • Language: This column is technically optional. However, if you choose to include this, you must be careful to capitalize Language as seen here, and enter the value for each user in language code

In addition, you’ll want to make sure that you’ve chosen the right hierarchy for your project, since this affects the User Attributes, or custom columns of user 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.

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 users support page.
Qtip: If you forget to include the correct metadata to begin with, that’s ok! You can always update your users’ attributes after the fact by following the steps at the link.

Preparing a File 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.

When you have finished building your file and are ready to build a hierarchy, see Generating a Parent-Child Hierarchy.

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:

  • Every participant must also have a unique Employee ID. Multiple participants cannot share the same ID.
  • 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.
    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.

Preparing a File 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.

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.

When you are finished building your file and are ready to create a Level-Based hierarchy, see Generating a Level-Based Hierarchy.

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

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.

FAQs