Personio Interface
The Personio Interface module serves to integrate the ZEP time recording with the HR system Personio.
The interface uses the Personio API and supports the following synchronizations:
Transfer of Time Bookings recorded in ZEP to Personio as Attendances. Via ZEP Break Regulations, the transferred Time Bookings can be trimmed to comply with the Working Hours Act (Maximum Working Time, compliance with legally required Minimum Breaks).
Synchronization of Absences. Optionally, both ZEP and Personio can be configured as the leading system for Absences and requests.
Transfer of Master Data from Personio. Thereby, Personio becomes the leading system for HR data; changes are automatically transferred to ZEP.
Automatic transfer of newly created employees in Personio to ZEP.
The synchronization is performed 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 the API Credentials (Client ID, Client Secret) from Personio and enter them into ZEP.
ZEP: Administration > System > Tasks
Create new Task with Personio Synchronization
Master Data Synchronization
Match Employee IDs using Email Address:
Select this option if users already exist in both ZEP and Personio. ZEP will then attempt to determine the corresponding Employee IDs using identical email addresses and assign them to the ZEP users.
Transfer User Data from Personio:
ZEP and Personio share a large number of identical employee attributes. To maintain these attributes only in Personio and subsequently transfer them to ZEP, this option must be activated.
User Transfer from Personio
Identify new Personio users and create them in ZEP:
Transfers users newly available in Personio to ZEP.
ZEP Compact/Professional: The transfer of users strictly requires a price group. Please define the price groups in Personio.
If not all employees from Personio should be transferred to ZEP, please refer to Excluding Personio Employees from Automatic Transfer.
In the settings, you can specify the format for generating the ZEP username (Username for new users – ZEP Username).
ZEP Clock: The transfer of users will lead to an increase in ZEP license costs due to the resulting higher user count.
ZEP Compact/Professional: Please ensure that your ZEP instance has a sufficient number of user licenses.
Time Booking Synchronization:
ZEP: Administration > Interfaces > Personio
Synchronization of Time Bookings: Select this option so that Time Bookings are transferred from ZEP to Personio.
Further Options:
ZEP Time Bookings transferred aggregated: Specifies whether ZEP should summarize the Time Bookings of one day and map them into a single Attendance entry in Personio, or whether every ZEP Time Booking should be transferred into a separate Attendance entry.
Merge ZEP and Personio Time Bookings: Specifies whether ZEP Time Bookings should be blended between existing, manually recorded Attendances in Personio, or whether days with Attendances recorded directly in Personio (which may still require approval) should be excluded from synchronization or the synchronization postponed.
Import Personio Time Bookings (ZEP Clock only): If this option is active, Time Bookings manually recorded in Personio will be transferred to ZEP.
The imported Attendances are considered by the ZEP Break Regulations and may therefore affect the breaks determined by ZEP.
Absence Synchronization:
ZEP: Administration > Interfaces > Personio
Do not synchronize absences: Absences are not synchronized.
Transfer Personio absences to ZEP: Personio is the leading system for absences; these are transferred to ZEP, displayed in the ZEP calendar, and overwrite manually recorded absences in ZEP.
Transfer ZEP absences to Personio: ZEP is the leading system for absences; these are transferred to Personio and overwrite absences in Personio.
After activating an option, the Personio Task should be started manually once, and its logs should be checked to determine which ZEP absence reasons have not yet been mapped to Personio absence types, after which a corresponding mapping must be performed.
Configuration
The configuration of the Personio Interface is performed in ZEP under Administration > Interfaces > Personio.
Date of Introduction of the Personio Interface module:
This date specifies when the module was introduced in ZEP.
The date is used to limit the Time Bookings and Absences that are synchronized with Personio chronologically. No Time Bookings or Absences that are prior to the set introduction date are synchronized. This ensures that data that did not exist in one system at an earlier time does not overwrite or delete the data in the other system.
The synchronization is performed for a maximum of 3 years into the past, even if the introduction date is set further back.
Personio Client ID and Client Secret:
For ZEP to be able to access Personio, the Personio Client ID and Client Secret must first be entered, which 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 Client Secret from Personio into the corresponding fields in ZEP Administration > Interfaces > Personio.
Personio-ID / Employee-ID:
In Personio, users are identified via the so-called Employee ID (hereinafter also Personio ID).
To ensure that a user's Time Bookings are correctly assigned in Personio during synchronization, the user's 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 every user in the Employee Data in the Settings tab.
Match Employee IDs using Email Address:
To minimize manual effort, the Personio Task supports the automatic determination and transfer of Personio IDs based on the email address. If a user is created in both ZEP and Personio with an identical email address, the Task automatically transfers the user's Personio ID to the ZEP user.
This automatic transfer can be activated or deactivated using the Match Employee IDs using Email Address option.
For the matching based on email addresses to occur, it must be ensured that the Email field is included in the list of attributes to be transferred in Personio under API > Access.
During synchronization, only Time Bookings from ZEP users with a set Personio ID are considered. Changes to Time Bookings are only registered for synchronization in ZEP from the moment the user's Personio ID was set in ZEP.
Transfer User Data from Personio
If the option Transfer User Data from Personio is activated, the attributes enabled by ZEP in the API definition will be transferred and used to update the respective user's data in ZEP.
The attributes delivered by the Personio API are enabled in Personio under Settings > API > Access.
If this option is active, the field Last Modified must also be enabled among the attributes to be transferred in Personio; otherwise, Personio delivers 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 is newer in Personio than in ZEP.
The attributes supported by ZEP are:
Personio ID
E-mail
Gender: is transferred to the salutation in ZEP.
First Name
Last Name
Date of Birth
Personnel Number
Cost Center: in Personio, one or more Cost Centers can be assigned to an employee. The first of these Cost Centers is transferred to ZEP (requires the Export for Accounting module).
Profile Picture: if a profile picture is stored in Personio, it is transferred to ZEP.
Mobile Phone Number (business)
Extension
Private Landline Number
Street and House Number
Postal Code
City
IBAN
BIC
Name of Bank
Termination Date: the end of the employment relationship; is transferred as the end of the Employment Period. Attention: the date is set in Personio by explicitly terminating the employment relationship and is not the contract end date.
Employment Type: (Permanent employment, student worker, etc.) A corresponding employee Category is sought and assigned to the employee. If the corresponding employee Category does not yet exist, it is automatically created in ZEP.
Work Schedule: the user's working hours can be assigned to them in Personio. These are transferred to ZEP into the employee's corresponding Regular Working Times.
Employment Type: specifies whether the employee is an internal or an external employee. Is transferred accordingly in ZEP (requires activating Freelance Employees in ZEP).
Price Group (ZEP Compact with Revenues & Costs module, ZEP Professional): by defining a ZEP Price Groupattribute, the information about the ZEP Price Group can be defined and assigned directly in Personio.
Username: by defining a ZEP Username attribute, the username that the user should receive in ZEP can be specified.
Upon creation of a new user, the following are additionally transferred:
Hire Date: the start of the Employment Period. If the date is not provided, ZEP defaults to today's date.
Team, Department, and Location (Office): if a Team, Department, or Location is assigned to the user in Personio, ZEP attempts to find a department with the corresponding short designation (in the order Team, Department, Location) and assign it to the user (only with the active Locations & Departments module).
Holiday Calendar: if a holiday calendar is assigned to the user in Personio, it is also assigned to the user in ZEP—provided a holiday calendar with an identical name exists in ZEP.
Vacation Entitlement per year: if the employee has defined an annual Vacation Entitlement in Personio, it is transferred to the user's Employment Period.
Identify new Personio users and create them in ZEP
If the option Identify new Personio users and create them in ZEP is active, the Task checks whether there are users in Personio who are not yet present in ZEP. If this is the case, the users are created in ZEP with a generated, unique username, and all attributes enabled in the Personio API are transferred.
Since email address, name, and first name are mandatory fields in ZEP, at least these attributes must be enabled among the attributes to be transferred in Personio. Otherwise, the creation/saving of a transferred user in ZEP will fail.
If the Personio Interface is used in ZEP Compact with the Revenues & Costs module or ZEP Professional, specifying a default Price Group during user creation is mandatory.
The use of this option is particularly recommended if ZEP is to be tested with an existing Personio account, in order to minimize the setup effort in ZEP by transferring the employees.
Since the rental fee for ZEP depends on the number of active employees, it must be checked whether this option should be 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 set for generating the Username from the data obtained from Personio (Example: Max Muster, E-mail: [email protected], ID in Personio: 123456):
Email_personioId: max.muster_123456
user_personioId: user_123456
firstname.lastname: max.muster
f lastname: mmuster
Name from email address: max.muster
If a Username generated in this way already exists in ZEP, a digit will be appended to the name until uniqueness is achieved.
The Email_personioId scheme is used by default. If an Employee in Personio does not have an email address assigned, they will be transferred as user_personioId.
Alternatively, it is possible to maintain the Username via a new Attribute ZEP-Username in Personio:
Define a new Attribute named "ZEP-Username" of type Standard under Settings > Employee Information (e.g., in the Public Profile area).
Then supplement the new Attribute "ZEP-Username" in Personio under Settings > API in the Access tab with the attributes to be transferred. This ensures that this Attribute is transferred to ZEP during synchronization.
Then set the appropriate ZEP Username for the individual employees. If the field is left empty, a standard Usernamewill be generated as described above upon creation.
The Username is used when creating new employees. If the Username is not unique or already exists in ZEP, it is counted up until uniqueness is achieved.
Exclude Personio Users from Transfer
By default, all Employees are transferred to ZEP when new Personio Employees are transferred.
If not all Employees should be transferred to ZEP, this can be achieved as follows:
Define a new Attribute named Transfer to ZEP of type Selection List with the options Yes and No in Personio under Settings > Employee Information. The section in which the Attribute is created can be chosen as desired.
For ZEP to evaluate this Attribute, it must be included in the list of attributes to be transferred in Personio under Settings > API in the Access tab.
To exclude users from the Transfer to ZEP, the Transfer to ZEP Attribute must be set to No for the Employees to be excluded.
The Transfer to ZEP Attribute must be set before the first Transfer of Employees. The Attribute only controls the Transfer to ZEP. Changing the field to No later will no longer delete an employee who has already been transferred to ZEP.
If the Transfer to ZEP Attribute is not created, or is set to Yes or not set at all for an employee, the employee will be transferred to ZEP.
Price Groups in ZEP and Personio
If the Personio Interface is used in ZEP Compact with the Revenues & Costs module or in ZEP Professional, the specification of a standard price group is mandatory during user creation. If this is not set, the user transfer will failwith a corresponding error message.
To be able to manage the relevant Price Groups directly in Personio, a new attribute must be defined in Personio as follows:
Define a new Attribute named "ZEP-Price Group" of type Selection List under Settings > Employee Information (e.g., in the Public Profile area).
Then specify the short forms of the Price Groups defined in your ZEP under Administration > Prices & Receipts > Price Groups as options/values.
Subsequently, add the new Attribute "ZEP-Price Group" in Personio under Settings > API in the Access tab among the attributes to be transferred. This ensures that this Attribute is transmitted to ZEP during synchronization.
Afterwards, set the respective appropriate ZEP Price Group for all employees.
The Price Group is transferred during the next synchronization (if activated) and is set accordingly during the transfer of employees.
Synchronization of Time Bookings
Under Administration > Interfaces > Personio, you can set whether Time Bookings should be transferred from ZEP to Personio.
Time Bookings are only marked for synchronization in ZEP once the employee's Personio ID has been assigned to them.
ZEP Time Bookings transferred aggregated:
If this setting is active, ZEP summarizes the Time Bookings of one day per employee and transfers them as a single Time Booking, i.e., from start of work to end of work; the breaks taken during the day are summed up and transferred as a break within the 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 recognizes when manually created Time Bookings exist in Personio for a working day and skips that day during synchronization. If the Time Bookings manually recorded in Personio still require approval, ZEP postpones the synchronization of that day with a note in the Log.
If the Merge Time Bookings option is activated, ZEP attempts to blend the Time Bookings from ZEP into the Time Bookings already existing in Personio. This succeeds as long as there are no overlaps between the Time Bookings from ZEP and the Time Bookings existing in Personio. If the day contains Time Bookings requiring approval in Personio, the Time Bookings from ZEP are also blended in with the approval identifier.
Import Time Bookings from Personio (ZEP Clock only):
If employees record working hours directly in Personio, there is the possibility, when using ZEP Clock, to import the Attendances created directly in Personio into ZEP. This ensures both systems have the same status and display the same totals.
If a Break Regulation is active in ZEP, it considers the entire day, including 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 overlaps with a Time Booking already existing in ZEP, the transfer of that Time Bookingfails.
Receive Times Changed in Personio:
All times for all days on which Time Bookings were created, changed, or deleted in ZEP are synchronized with Personio. In this process, all Time Bookings transferred from ZEP to Personio receive a Remark that begins with "ZEP."
The synchronization only modifies the Time Bookings/Attendances in Personio that were created by ZEP, meaning 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 recognized as a ZEP Time Booking in the next synchronization and not deleted or overwritten.
Suspending Synchronization – "Open Approvals":
In Personio, it can be set that times recorded there are first applied for and must be approved by a supervisor.
The synchronization recognizes days with pending or required-to-be-approved Time Bookings and suspends the synchronization for such days for a maximum of 7 days. If the Time Bookings have neither been approved nor rejected within these 7 days, a normal synchronization will occur on the 8th day, during which the Time Bookings currently recorded in ZEP (or a 0-booking) will be transferred to Personio.
Re-transferring a Month's Time Bookings to Personio:
If the Personio IDs are assigned to the ZEP employees, a month can be selected and the Time Bookings of all employees for that month can be (re-)transferred to Personio using the Synchronize now button under Administration > Interfaces > Personio.
0-Bookings for Days without Time Bookings in ZEP:
Due to hour deductions in Personio, on days when no time was booked in ZEP, as well as on days of approved absence of the type Time Off In Lieu, a so-called 0-booking from 0:00h to 0:00h with 0 minutes break must be transferred to trigger the deduction of the resulting deficit 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 been performed according to the working day definition, but no working hours were recorded in ZEP or Personio.
During synchronization, ZEP recognizes if working hours were subsequently recorded directly in Personio. If a 0-booking was previously created by ZEP, it is recognized and removed.
Synchronization of Absences and Leave
Both ZEP and Personio support the management of absences and leave with an approval process. The absences/reasons for absence in ZEP are referred to as leave/leave 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.
Transfer Personio absences to ZEP: Personio is the leading system for Absences and Leave Requests. ZEP transfers the Absences approved in Personio, where they can be visualized in the ZEP calendar, connected calendar clients, or smartphones.
The 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. The Absences approved in ZEP are transferred to Personio and mapped as Leave (Absences).
Mapping of Absence Reasons:
To synchronize absences and leave, they must be mapped to one another. This primarily concerns the mapping of ZEP Absence Reasons to the Leave Types in Personio.
In ZEP, an Absence Reason is defined by a Short Designation and a Designation, e.g., UB (Paid Leave). The Leave Types in Personio have a Name and an internal ID.
During synchronization, only the absences/leave entries are synchronized for which a corresponding Leave Type exists for the respective Absence Reason, or vice versa.
This is the case if the Designation of the ZEP Absence Reason is identical to the Name of the Leave Type in Personio (see Personio: Settings > Absences). Absences with Absence Reasons without a corresponding Leave Type, or leave entries without an Absence Reason matching the Leave Type, are ignored during synchronization.
Example:
Paid leave is called "Urlaub bezahlt" (Paid Leave) in ZEP and "Bezahlter Urlaub" (Paid Leave) in Personio. For absences/leave entries with this Absence Reason/Leave Type to be synchronized, the Designation must be identical.
Automatic Break Deduction:
ZEP supports a mechanism for specifying statutory or custom Minimum Breaks, fixed breaks, and Maximum Working Times via freely definable Break Regulations (see Administration > Working Hours > Break Regulation). Multiple Break Regulations can be created for different requirements.
A Break Regulation is assigned to an employee in their Regular Working Time definition (see Employees > [Employee Name] > General > Regular Working Time), and can thus also be changed chronologically.
If a Break Regulation has been assigned to an employee, it has no direct influence on the Working Hours booked by the employee – specifically, the booked times are not trimmed to comply with the Break Regulation. Instead, the employee is notified during Time Recording if they violate their Break Regulation, e.g., because they have not taken sufficient breaks according to the Break Regulation assigned to them.
However, you can set an automatic deduction for non-complied break times in the Break Regulation. This causes the Break Overview and Month-end Report (when using the Absences & Overtime module) Reports to display the corresponding deductions, which are then also transferred to Personio.
Shift / Night Work:
In ZEP and Personio, Time Bookings are recorded with a start/end time (0:00-24:00). For work extending over midnight, two Time Bookings must therefore be recorded, one before and one after midnight.
When Time Bookings are transferred to Personio, ZEP aggregates the Time Bookings of one day into a single booking and transfers it with the start/end time and the sum of the contained breaks (in minutes) to Personio. In the case of Shift/Night Work across midnight, this leads to a representation in Personio that is difficult to comprehend, as it generates Time Bookings from 0:00 to 24:00 with several hours of contained break.
ZEP therefore transfers multiple Time Bookings per day to Personio, if necessary. In this process, gaps of more than 2 hours between Time Bookings are identified, and the Time Bookings before and after these gaps are aggregated 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 button + Create New Task and select the "Personio Synchronization" Task. Afterwards, specify the time intervals at which the Task should be executed.
If you activated the option Match Employee IDs using Email Address in the settings, you should now start the Task manually once. This will determine and assign the Personio Employee IDs based on the email addresses; Time Bookings will be transferred for synchronization with Personio from that point onward.
By clicking on the Task name (e.g., Personio-Task) under Administration > System > Tasks, you see the Logs of the last Task executions. These contain information about the Task's process and notes on any errors that may have occurred during synchronization.