The Personio Interface module serves to connect ZEP time tracking with the Personio HR system.
The interface uses the Personio API and supports the following synchronizations:
Transfer of time bookings recorded in ZEP to Personio as Attendances. Through ZEP break regulations, the transferred time bookings can be adjusted to comply with the Working Hours Act (maximum working hours, compliance with statutory minimum breaks).
Synchronization of absences. Optionally, either ZEP or Personio can be configured as the leading system for absences and requests.
Import of master data from Personio. This makes Personio the leading system for HR data; changes are automatically transferred to ZEP.
Automatic import of employees newly created in Personio into ZEP.
The synchronization takes place via the Personio scheduler task in ZEP, which can be scheduled for regular, time-controlled execution.
Prerequisite:
To use the ZEP – Personio synchronization, the Personio Interface module must be licensed in ZEP.
Quick Start
Basic Configuration:
Personio:
Create API Credentials: Settings > API Credentials – Generate new credential
Name: "ZEP"
Integration: "ZEP"
Readable employee attributes: Select all attributes
Save
ZEP:
Administration > Interfaces > Personio
Copy API Credentials (Client ID, Client Secret) from Personio and enter them into ZEP.
Administration > System > Tasks
Create a new task with Personio Synchronization.
Synchronization of Master Data
Match Employee IDs via email address:
Select this option if users already exist in both ZEP and Personio. ZEP will then attempt to determine the associated Employee IDs based on identical email addresses and assign them to the ZEP users.
Import user data from Personio:
ZEP and Personio share a large number of identical employee attributes. To maintain these exclusively in Personio and then transfer them to ZEP, this option must be activated.
Employee Import from Personio
Identify new Personio users and create them in ZEP:
Import users newly created in Personio into ZEP.
If not all employees should be transferred from Personio to ZEP, please refer to the section Excluding Personio employees from automatic import.
In the settings, you can specify the format in which the ZEP username should be generated (Username for new users – ZEP username).
ZEP Clock: Importing users will result in an increase in ZEP license costs due to the higher number of users.
Synchronization of Time Bookings
ZEP: Administration > Interfaces > Personio
Synchronize time bookings: Select this option to transfer time bookings from ZEP to Personio.
Further Options:
Transfer ZEP time bookings in aggregate: Specifies whether ZEP summarizes a day's time bookings into a single "Attendance" in Personio or whether each individual ZEP time booking should be converted into its own Attendance.
Merge ZEP and Personio time bookings: Specifies whether ZEP time bookings should be mixed in between existing, manually recorded Attendances in Personio, or whether days with Attendances recorded directly in Personio (which may still need approval) should be excluded from synchronization or have synchronization deferred.
Import Personio time bookings (ZEP Clock only): If this option is active, time bookings manually recorded in Personio are imported into ZEP.
These imported Attendances are considered by the ZEP break regulations and can therefore affect the breaks determined by ZEP.
Synchronization of Absences
ZEP: Administration > Interfaces > Personio
Do not synchronize absences: Absences are not synchronized.
Import Personio absences into ZEP: Personio is the leading system for absences. These are transferred to ZEP, displayed in the ZEP calendar, and overwrite absences manually recorded in ZEP.
Transfer ZEP absences to Personio: ZEP is the leading system for absences. These are transferred to Personio or overwrite absences in Personio.
After activating an option, the Personio task should be started manually once. Based on its logs, you should check which ZEP absence reasons have not yet been mapped to Personio absence types and then perform the appropriate mapping.
Configuration
The configuration of the Personio interface takes place in ZEP under Administration > Interfaces > Personio.
Implementation date of the Personio Interface module:
This date indicates when the module was introduced in ZEP.
The date is used to limit the time bookings and absences synchronized with Personio. No time bookings or absences prior to the implementation date set here will be synchronized. This ensures that data not yet existing in one system at an earlier point in time does not overwrite or delete data in the other system.
The synchronization goes back a maximum of 3 years into the past, even if the implementation date is further back.
Personio Client ID and Client Secret
To allow ZEP to access Personio, the Personio Client ID and Client Secret must first be entered. These are generated in Personio to enable API access as follows:
Personio:
Create API Credentials: Settings > API Credentials – Generate new credential
Name: "ZEP"
Integration: "ZEP"
Readable employee attributes: Select all attributes
Save
Then, copy the Client ID and the Client Secret from Personio into the corresponding fields in ZEP under Administration > Interfaces > Personio.
Personio ID / Employee ID
In Personio, users are identified via the so-called Employee ID (hereafter also referred to as the Personio ID).
To ensure that a user's time bookings are correctly assigned in Personio during synchronization, the Personio ID must be stored in ZEP for every ZEP user whose times are to be synchronized with Personio.
The Personio ID can be manually stored for each user in the employee data under the Settings tab.
Match Employee IDs via Email Address
To minimize manual effort, the Personio task supports the automatic determination and import of Personio IDs based on email addresses. If a user is created in both ZEP and Personio with an identical email address, the task automatically transfers the user's Personio ID into the ZEP user profile.
This automatic import can be activated or deactivated via the option Match Employee IDs via email address.
To ensure that the matching process via email address can take place, you must verify that the Email field is included in the list of attributes to be transferred in the Personio section API > Access.
During synchronization, only time bookings from ZEP users with a set Personio ID are taken into account. Changes to time bookings in ZEP are only registered for synchronization from the moment the user's Personio ID has been set in ZEP.
If the option Transfer User Data from Personio is activated, the attributes enabled in the API definition in Personio are transferred to ZEP and used to update the data of the respective user in ZEP.
The attributes delivered by the Personio API are enabled in Personio under Settings > API > Access.
Important:
If this option is active, the field Last Modified must also be enabled in Personio among the attributes to be transferred; otherwise, Personio provides no modification date, and no transfer occurs.
During the transfer of Master Data, the date of the last modification of the user in ZEP is compared with the date of the last modification of the Employee in Personio. Changes are only transferred to ZEP if the user in Personio is newer than the one in ZEP.
The attributes supported by ZEP are:
Personio ID
Email
Gender: Transferred to the salutation in ZEP.
First Name
Last Name
Birthday
Personnel Number
Cost Center: In Personio, one or more cost centers can be assigned to an employee. The first of these cost centers is imported into ZEP (requires the "Export for Accounting" module).
Profile Picture: If a profile picture is stored in Personio, it will be transferred to ZEP.
Mobile Number (business)
Extension
Private Landline Number
Street and House Number
Postal Code
City
IBAN
BIC
Bank Name
Termination Date: The end of the employment relationship is imported as the end of the employment period. Note: This date is set in Personio by explicitly terminating the employment relationship and is not necessarily the contract end date.
Employment Type: (Permanent, working student, etc.) A corresponding employee category is searched for and assigned to the employee. If the corresponding category does not yet exist, it is automatically created in ZEP.
Work Schedule: Working hours can be assigned to the user in Personio. These are transferred to the employee's corresponding regular working hours in ZEP.
Employment Type (Internal/External): Indicates whether the employee is internal or external. This is imported accordingly into ZEP (requires the "Freelancers" activation in ZEP).
Username: By defining a "ZEP-Username" attribute, the username the user should receive in ZEP can be specified.
When creating a new user, the following additional information is imported:
Hire Date: The start of the employment period. If this date is not provided, ZEP sets it to the current date.
Team, Department, and Office: If a team, department, or office is assigned to the user in Personio, ZEP attempts to find a department with the corresponding short name (in the order: Team, Department, Office) and assigns it to the user (only available with the active "Locations & Departments" module).
Holiday Calendar: If a holiday calendar is assigned to the user in Personio, it will also be assigned to the user in ZEP—provided a holiday calendar with an identical name exists in ZEP.
Annual Leave Entitlement: If the employee has an annual leave entitlement defined in Personio, this is imported into the user's employment period in ZEP.
Identify and Create New Personio Users in ZEP
If the option Identify and create new Personio users in ZEP is active, the task checks whether there are users in Personio who do not yet exist in ZEP. If so, these users are created in ZEP with a generated, unique username, and all attributes enabled in the Personio API are imported.
Since email address, last name, and first name are mandatory fields in ZEP, at least these attributes must be enabled in the list of transferable attributes in Personio. Otherwise, creating or saving an imported user in ZEP will fail.
Using this option is particularly recommended if ZEP is to be tested with an existing Personio account, as importing employees minimizes the setup effort in ZEP.
Since the ZEP subscription fee depends on the number of active employees, you should verify whether this option should remain permanently activated.
ZEP Username for New Users
When users are transferred from Personio to ZEP, they require a unique username.
One of the following schemes can be configured to generate the username from the data retrieved from Personio (Example: Max Muster, Email: [email protected], Personio ID: 123456):
Email_personioId: max.muster_123456
user_personioId: user_123456
vorname.nachname: max.muster
vnachname: mmuster
Name from Email Address: max.muster
If a username generated this way already exists in ZEP, a digit will be appended to the name until it is unique.
By default, the Email_personioId scheme is used. If an employee in Personio does not have an email address assigned, they will be imported as user_personioId.
Alternatively, you have the option to maintain the username in Personio via a new attribute called ZEP-Username:
Define a new attribute named "ZEP-Benutzername" (Type: Standard) under Settings > Employee Information(e.g., in the Public Profile section).
Add the new "ZEP-Benutzername" attribute in Personio under Settings > API in the Access tab to the list of attributes to be transferred. This ensures the attribute is transmitted to ZEP during synchronization.
Set the appropriate ZEP username for individual employees. If the field remains empty, a default username will be generated during creation as described above.
The username is used when creating new employees. If the username is not unique or already exists in ZEP, a digit will be appended until it is unique.
Excluding Personio Users from Import
By default, all employees are imported when transferring new Personio staff to ZEP.
If you do not want all employees to be transferred to ZEP, you can achieve this as follows:
Define a new attribute in Personio under Settings > Employee Information named "Export to ZEP" (Type: Dropdown) with the options Ja (Yes) and Nein (No). You can choose any section for this attribute.
To allow ZEP to process this attribute, add it to the list of attributes to be transferred in Personio under Settings > API in the Access tab.
To exclude users from the import, set the "Export to ZEP" attribute to Nein for the relevant employees.
The attribute Export to ZEP must be set before the first transfer of employees. This attribute only controls the initial import into ZEP. Changing the field to Nein (No) at a later date will not delete an employee from ZEP who has already been imported.
If the Export to ZEP attribute is not created, or if it is set to Ja (Yes) or left empty for an employee, the employee will be transferred to ZEP.
Synchronization of Time Bookings
Under Administration > Interfaces > Personio, you can configure whether time bookings should be transmitted from ZEP to Personio.
Time bookings are only flagged for synchronization in ZEP once the Personio ID has been assigned to the employee.
Transfer ZEP Time Bookings in Aggregate
If this setting is active, ZEP summarizes all time bookings for a single day per employee and transfers them as one single time booking (i.e., from the start of work to the end of work). The breaks taken during the day are summed up and transmitted as a total break within that time booking.
If aggregation is not active, the time bookings recorded in ZEP are transferred to Personio individually.
Merge ZEP and Personio Time Bookings
By default, ZEP detects if there are manually created time bookings in Personio for a working day and skips that day during synchronization. If the manually recorded bookings in Personio are still pending approval, ZEP defers the synchronization for that day and adds a note to the log.
If the Merge time bookings option is activated, ZEP attempts to blend the time bookings from ZEP with the existing entries in Personio. This succeeds as long as there are no overlaps between the ZEP entries and the Personio entries. If the day in Personio contains bookings that require approval, the ZEP entries are also imported with a "pending approval" status.
Import Time Bookings from Personio (ZEP Clock only)
If employees record working hours directly in Personio, ZEP Clock users have the option to import these Personio attendances into ZEP. This ensures both systems remain in sync and display the same totals.
If a break regulation is active in ZEP, it considers the entire day, including the time bookings imported from Personio.
The import only occurs if the attendances in Personio and the time bookings in ZEP do not overlap. If an attendance to be imported from Personio covers a time booking already existing in ZEP, the import of that time booking will fail.
Retain Times Modified in Personio
All times for all days on which time bookings were created, modified, or deleted in ZEP are synchronized with Personio. All time bookings transferred from ZEP to Personio receive a remark starting with "ZEP".
The synchronization only modifies time bookings/attendances in Personio that were created by ZEP (i.e., those whose remark begins with "ZEP").
If a time booking originally created by ZEP is manually modified in Personio, the "ZEP" should be removed from its comment so that it is no longer recognized as a ZEP time booking during the next synchronization and is not deleted or overwritten.
Suspending Synchronization – "Pending Approvals"
In Personio, it can be configured that recorded times are initially "requested" and must be approved by a supervisor.
The synchronization detects days with time bookings that are still requested or pending approval and suspends synchronization for those days for a maximum of 7 days. If the time bookings have neither been approved nor rejected within these 7 days, a normal synchronization occurs on the 8th day, where the time bookings currently recorded in ZEP (or a zero booking) are transmitted to Personio.
Re-transfer a Month's Time Bookings to Personio
Once Personio IDs are assigned to ZEP employees, a specific month can be selected via Administration > Interfaces > Personio using the Synchronize Now button. This allows the time bookings for all employees for that month to be (re-)transmitted to Personio.
0-Bookings for Days Without Time Entries in ZEP
Due to hour deductions in Personio, a so-called 0-booking (from 0:00 to 0:00 with 0 minutes of break) must be transmitted on days where no times were booked in ZEP, as well as on days of approved absence for compensatory time off. This triggers the deduction of the resulting minus hours from the time account in Personio.
During synchronization, 0-bookings are generated for all days (up to and including yesterday) on which work should have occurred according to the workday definition, but no working times were recorded in either ZEP or Personio.
The synchronization detects if working times were manually recorded in Personio after the fact. If a 0-booking was previously created by ZEP for that day, it is recognized and removed.
Synchronization of Absences
Both ZEP and Personio support the management of absences and leave with an approval process. What are referred to as "Fehlzeiten/Fehlgründe" (Absences/Absence reasons) in ZEP are called "Abwesenheiten/Abwesenheitsarten" (Absences/Absence types) in Personio.
Under Administration > Interfaces > Personio, you can control whether absences should be exchanged between ZEP and Personio and which system is the leading system:
Do not synchronize absences: No exchange of absences occurs.
Import Personio absences into ZEP: Personio is the leading system for absences and leave requests. ZEP imports the absences approved in Personio, where they can be visualized in the ZEP calendar, connected calendar clients, or smartphones.
Absences managed in Personio should not be edited in ZEP, as they will be automatically overwritten during the next synchronization.
Transfer ZEP absences to Personio: ZEP is the leading system for absences and absence requests. Absences approved in ZEP are transferred to Personio and mapped as Absences.
Mapping of Absence Reasons
To synchronize absences, they must be mapped to each other. This specifically concerns mapping ZEP absence reasons to the absence types in Personio.
In ZEP, an absence reason is defined by a Short name and a Designation (e.g., "UB" for "Paid Leave"). Absence types in Personio have a Name and an Internal ID.
During synchronization, only those absences are synchronized for which a corresponding absence type/reason exists in the other system.
This is the case when the Designation of the ZEP absence reason is identical to the Name of the absence type in Personio (see Personio: Settings > Absence). Absences with reasons that do not have a corresponding absence type—or vice versa—are ignored during synchronization.
Example:
Paid leave is called "Urlaub bezahlt" in ZEP and "Bezahlter Urlaub" in Personio. For absences to be synchronized using this reason/type, the designation must be identical in both systems.
Automatic Break Deduction
Through freely definable break regulations, ZEP supports a mechanism for specifying statutory or custom minimum breaks, fixed breaks, and maximum working hours (see Administration > Working Hours > Break Regulation). Multiple break regulations can be created for different requirements.
A break regulation is assigned to an employee within their regular working hours definition (see Employee > [Employee Name] > General > Regular Working Hours) and can also be modified over time.
Once a break regulation is assigned to an employee, it has no direct influence on the working hours booked by the employee—specifically, the booked times are not truncated to satisfy the break regulation. Instead, the employee is notified during time tracking if they violate their break regulation (e.g., because they did not take enough break time according to their assigned regulation).
However, you can configure an automatic deduction for breaks not taken within the break regulation settings. As a result, the break overview report and the end-of-month report (when using the Absences & Overtime module) will show the corresponding deductions, which are then transmitted to Personio accordingly.
Shift Work / Night Work
In both ZEP and Personio, working hours are recorded with a start and end time (0:00–24:00). When working past midnight, two separate time bookings must therefore be recorded: one before and one after midnight.
When transmitting time bookings to Personio, ZEP normally summarizes a day's entries into a single booking and transfers it with a start/end time and the total sum of breaks (in minutes). In the case of night or shift work spanning past midnight, this can lead to a confusing display in Personio, as it may generate time bookings from 0:00 to 24:00 with several hours of included breaks.
To address this, ZEP may transmit several time bookings per day to Personio. Specifically, gaps of more than 2 hours between time bookings are identified; the entries before and after these gaps are then grouped and transferred to Personio as individual time bookings.
Personio Task
The Personio task is scheduled in the ZEP Scheduler under Administration > System > Tasks.
Click the + Create new task button and select the "Personio Synchronization" task. Then, specify the time intervals at which the task should be executed.
If you have activated the option Match employee IDs via email address in the settings, you should start the task manually once now. This will determine and assign the Personio Employee IDs based on the email addresses; from that point forward, time bookings will be flagged and transferred for synchronization with Personio.
By clicking on the task name (e.g., "Personio Task") under Administration > System > Tasks, you can view the logs of the most recent task executions. These logs contain information about the task flow and provide details regarding any errors that may have occurred during synchronization.