Migrate to hierarchical departments and teams – Personio

This article explains how to migrate to hierarchical departments and teams if you previously used departments and teams in Personio.

Understand the benefits of migrating to hierarchical departments and teams

Previously, many customers used teams, custom attributes, or both to simulate sub-departments. For example, creating a "Sales" department with teams like "Sales EMEA," "Sales APAC," and "Sales Americas."

The new hierarchical structure provides:

True parent-child relationships for both departments and teams
Reporting that reflects your actual organizational hierarchy
Full structure visibility in employee profiles and org charts

We recommend migrating to take advantage of these benefits. However, you can continue using your current setup if it meets your needs.

Learn more about how hierarchical departments and teams work.

Before you start

You need these permissions:

Edit rights for Account configuration > Departments to set up departments and teams.
Edit rights for Imports > Employee data import to import the custom report as departments.

Understand the migration process

This migration converts your existing teams into hierarchical sub-departments. You complete the migration in these steps:

Export your current teams from Personio as a custom report.
Edit the exported file to prepare the data.
Import the file back into Personio as departments.
Assign parent departments to create the hierarchy.
Update permissions and integrations.

Export your current team structure

Create a custom report that contains your current team assignments. You use this report to import teams as departments in the next step.

To create and export a custom report:

Go to Analytics.
Click the Reports tab.
Click Create report.
Use the Classic Builder and create a custom report with this configuration:
- Name: Hierarchical department import
- Type of report: Historical data
- Date: Enter a custom date based on how far back you want the employee history considered
- Add columns: Email, First name, Last name, and Team.
- Set up conditions for the employees you want in the report. For example, filter by teams or active employees only.
Export the report and open it on your computer.

Prepare the report for import

Edit the exported report to make sure employees appear in the correct hierarchical teams:

Optional: rename the Team column to “New hierarchical department”. This makes it easier to track your changes.
Make sure each employee appears in their lowest hierarchical team.
Make sure the email address for each employee is the one currently in use. If an employee had a different email previously, replace it with the current one.
Save the edited report.

Import teams as departments

Upload the edited report using the employee data import. This converts your teams into departments. Learn how to import employee data.

When you reach the column matching step:

Remove the First name and Last name columns.
Keep only the Email column. This is the unique identifier for imports.
Match the Effective date column to the Valid since attribute.
Match the New hierarchical department column to the Department attribute.

Turn new departments into sub-departments

Go to Settings.
In the Organization section, click Departments & teams.
Click the Departments tab.
Review the list of departments. Check that the import was successful and that old teams now appear as departments.
If an old team (now department) is missing, create it as a new department.
Turn new departments into sub-departments by assigning a parent department to them. This creates the hierarchy.

Update permissions for new sub-departments

After creating your new sub-departments or sub-teams, update employee role permissions. This gives employees correct access to the new hierarchy.

Go to Settings.
In the Organization section, click Roles & permissions.
Select the affected employee role, such as All Employees, and click Permissions.
In the People data section, go to Personal data > Public profile.
Click View > Custom.
Click Condition and select the appropriate option:
- Department is own (assigned department): employees have access to everyone in the same department.
- Department is own (assigned and sub-departments): employees have access to the same department and all departments below.
- Department is own (entire department hierarchy): employees have access to everyone in the same parent department and below.

Note:
Previous custom filters with Department is own automatically update to Department is own (entire department hierarchy). The functionality remains the same.

Update integrations

After migrating to hierarchical departments and teams, update your integrations to work with the new structure.

First-party integrations (provided by Personio): change departments to department top-level in your integration settings.
Third-party integrations (provided by integration partners): you don’t need to take any action.

Update the public API version

If you use Personio’s public APIs (PAPI), switch to PAPI V2 to access hierarchical relationships. Learn more about Personio’s public APIs.

PAPI V1 shows departments and sub-departments without hierarchical connection. PAPI V2 shows all departments and teams an employee has, plus parent and sub-entities for each.

Update other features

You need to update these features to make sure they work with your new structure.

Replace Teams with Departments in:

Replace Departments with Departments top-level in:

Payroll groups

Remove old teams from the Teams tab

Your old teams now appear as sub-departments in the Departments tab. Remove them from the Teams tab to avoid confusion.

Unassign employees from their old teams.
Delete the teams.

Note:
Deleting teams doesn’t remove historic records. You can still see all past data in the employee history and reports. If you prefer not to delete the teams, you can rename them to indicate they’re no longer in use (for example, “Sales EMEA - OLD”).

Find the answers you need