Wie funktioniert die API Integration zwischen Staffomatic und Personio?

Das Einrichten der Schnittstelle zu Personio ist schnell gemacht, allerdings müssen in beiden Systemen Einstellungen vorgenommen werden. Hierfür benötigst Du Admin-Rechte in Personio und Staffomatic.


1. Was kann die Integration eigentlich?

2. Was benötige ich für die Integration?

3. Einstellungen in Personio

4. Einstellungen in Staffomatic

5. Abwesenheitskategorien in Staffomatic erstellen

6. FAQ

Was kann die Integration eigentlich?

Die Integration kann grob gesagt folgende Syncs durchführen:

  • User erstellen (Personio zu Staffomatic)
  • Abwesenheiten (in beide Richtungen)
  • Zeiterfassungen (Staffomatic zu Personio)
  • User sperren (Personio zu Staffomatic)

Näheres dazu erfährst Du bei den einzelnen Schritten der Einrichtung.

Was benötige ich für die Integration?

Natürlich benötigst Du ein Abonnement bei Personio, aber auch bei Staffomatic.

Versuche die Einrichtung möglichst innerhalb der Testphase bei Staffomatic durchzuführen.


Es muss nun entschieden werden, wie die Integration gemanagt werden soll.

Nur ein einziger User kann die Integration in Staffomatic betreuen!

Es könnte also Sinn machen einen User in Staffomatic zu haben, den sich, sofern es mehrere Bearbeiter geben soll, diese Bearbeiter teilen können. Zum Beispiel admin@deineFirma.de.

Sollte der Hauptbearbeiter nämlich gewechselt werden müssen, ist dies nur über mehrere Schritte möglich.
Hierfür muss die Einstellung Enable background sync, welche bei den Einstellungen zur API zu finden ist (siehe unten) beim derzeitigen verantwortlichen Admin deaktiviert und bei dem neuen verantwortlichen Admin aktiviert werden. 

Einstellungen in Personio:

1. Um die Schnittstelle zwischen Staffomatic und Personio einzurichten ist es zunächst notwendig, die dazu benötigten Anmeldedaten zu erstellen. 
Die Erstellung der Anmeldedaten kann über den Marketplace erfolgen.

2. Im Anschluss muss in Personio ein Credential erstellt werden. Das sind Informationen, die unsere Schnittstelle benötigt, um zu wissen, welche Accounts miteinander verbunden werden sollen.

Hier gibt es einmal die Möglichkeit, sich die beiden Informationen zu notieren und später manuell in Staffomatic einzutragen oder Du erstellst Dir eine Credentials-Datei, die später einfach in Staffomatic hochgeladen werden kann.

Hinweis: die Verbindung zu Staffomatic über den Marktplace kann dabei entweder über den Button "zum Marktplace" oder aber direkt bei den Zugriffsdaten hergestellt werden.


Bitte gehe hierfür in Personio auf Einstellungen > API -Zugriffsdaten

3. Der dritte Schritt ist die Definition, auf welche Informationen Zugriff über die Schnittstelle gewehrt wird. Hierfür müssen so genannte Attribute ausgewählt werden.
Bitte klicke hierfür in Personio auf "Neue Zugriffsdaten generieren" und fülle die Felder aus.




Insgesamt 13
Lesbare Mitarbeiterattribute > Erforderliche Attribute müssen hier aktiv sein, ansonsten kann es zu Fehlern in der Schnittstelle kommen:

- Abteilung
- Anstelldatum
- E-Mail
- Gesellschaft
- Letzter Arbeitstag
- Nachname
- Standort
- Status 
- Team
- Urlaubstage
- Vorname
- Wochenstunden
- Abwesenheitsanspruch



4. Der dritte Schritt: Kopiere deine API-Zugriffsdaten und Füge dies in der Integration bei Staffomatic ein 


WICHTIG: Bevor Du Staffomatic mit Personio einrichtest, überarbeite Deinen Testaccount bei Staffomatic!

  • Lösche alle Test-User, da diese von Personio in Staffomatic gepusht werden und hier sonst doppelte Mitarbeiter angezeigt werden können. Das System kann ggf. nicht erkennen, ob es sich um ein und dieselbe Person handelt, wenn hier etwa Email-Adressen fehlen oder eine Andere hinterlegt ist.
  • User, die unbedingt bleiben sollen (weil sie schon verplant sind), müssen die gleiche Mailadresse hinterlegt haben, wie bei Personio. Nur dann kann ein Matching stattfinden.
  • Lösche alle Abwesenheiten, die Du in Deiner Testphase erstellt hast, da sonst auch hier Abwesenheiten doppelt angelegt werden könnten. (Ausnahme: Du willst die Abwesenheiten in Staffomatic pflegen und zu Personio pushen)
  • Lösche alle Test-Timer, die Du in Deiner Testphase bei Staffomatic erstellt hast. Dadurch vermeidest Du, dass fehlerhafte Testdaten zu Personio gepusht werden.

Bitte buche Dir für die Implementierung der Schnittstelle einen Termin mit uns.
Nutze hierzu einfach den folgenden Link:

https://meetings.staffomatic.com/meetings/pawel/personio

Mach' es nicht alleine!


Einstellungen in Staffomatic:


1. Gehe in Staffomatic auf den Reiter Integrationen und wähle die Personio-Integration aus. Folge den Installationshinweisen.


2. Klicke bitte nun in die installierte Integration und starte das Setup. Das Setup besteht aus nur vier kleinen Schritten. Im ersten Schritt hast Du hier die Möglichkeit, die Credentials-Informationen einzutragen.
Damit die Synchronisation funktionieren kann, müssen an dieser Stelle die Personio Kunden ID und der Personio Kunden Secret eingegeben werden. 

Dieser Schritt darf bei der Einrichtung der API somit nicht übersprungen werden


3. Nun kommen wir zur Definition der Informationsquellen. (2. Synchronisierungsquelle auswählen

Die Mitarbeiter-Stammdaten können nur von Personio zu Staffomatic gesynct werden. Daher gibt es hier keine weitere Einstellmöglichkeit. Personio ist dabei das führende System.
Möchtest Du später Mitarbeiterstammdaten ändern, muss die Änderung in Personio durchgeführt werden. Falls eine Änderung der Stammdaten in Staffomatic getätigt wird, ist diese beim nächsten Sync sichtbar.

Bei dem zweiten Punkt kannst Du entscheiden, ob die Datensätze der Zeiterfassungen aus Staffomatic zu Personio gesynct werden sollen oder ob Du diese Funktionalität deaktivieren möchtest.

Der dritte Punkt definiert, aus welchem System die Abwesenheiten gepusht werden sollen. Hier hat man die Möglichkeit Personio, wie auch Staffomatic als führendes System einzustellen.

Bei den Punkten zwei und drei handelt es sich um eine bidirektionale Synchronisations-Einstellung. Hier muss somit ein System ausgewählt werden.


Klicke bitte nun auf Speichern und warte einen kleinen Augenblick.

Das System fragt die Mitarbeiter-Stammdaten über die Schnittstelle ab. Dies kann, abhängig von der Menge der Datensätze, einige Sekunden dauern.


Nun siehst Du alle User, die in Personio gefunden worden sind. Jetzt musst Du entscheiden, welche dieser Profile zu Staffomatic übertragen werden sollen. (3. Benutzersynchronisierung)
Darüber hinaus kannst Du dir nun auch mithilfe des Filters "Personio Mitarbeiterstatus" auch nur bestimmte Mitarbeiter in der Liste anzeigen lassen.

Wenn ein User-Profil nachträglich angelegt und synchronisiert werden soll, muss unter Punkt "3. Benutzersynchronisierung" die Datensynchronisation immer aktiviert werden d.h. der neue User muss auf "Yes" gestellt werden. 

Der letzte Schritt ist die individuelle Feinabstimmung. Im Folgenden erkläre ich Dir die wichtigsten Einstellungen (4. Synchronisations-Einstellungen)

 

Enable background sync
Diese Funktion ist elementar und sollte auf Yes gestellt werden. Erst dann kann die Schnittstelle die Daten synchronisieren.

Enable personio hire date
Diese Funktion ist sinnvoll, wenn Du möchtest, dass User erst Zugang zu Staffomatic bekommen, sobald der erste Arbeitstag (hire date) erreicht ist.

Enable personio last working day
Ähnlich wie bei der Funktion oben geht es hier aber um den letzten Arbeitstag. Wenn ein Mitarbeiter Dein Unternehmen verlässt bzw. "last working day" erreicht ist, wird er automatisch gesperrt und kann sich nicht mehr in Staffomatic einloggen. (Achtung: Er wird weiterhin berechnet)

Only approved staffomatic absences
Diese Einstellung greift nur, wenn Du bei Punkt 2 Select sync sources Staffomatic als führendes System für Abwesenheiten ausgewählt hast. Hier kannst Du entscheiden, ob alle Anträge zu Personio übertragen werden sollen oder nur die, die genehmigt und abgelehnt worden sind.

Wichtig an diesem Punkt ist auch, dass nur die Abwesenheitsanträge vom laufendem Jahr übertragen werden. 
Ist eine Abwesenheit vorhanden, die über das Jahr hinausgeht, so muss diese zunächst aufgeteilt werden.

Only verified staffomatic work timers
Diese Einstellung ermöglicht Dir entweder alle abgeschlossenen Datensätze aus der Zeiterfassung zu Personio zu übertragen oder nur die, die den Status Bestätigt haben. Du hast nämlich die Möglichkeit in der Auswertung der Zeiterfassung die Datensätze als Bestätigt zu markieren, wenn Du diese geprüft hast. Diese Funktion minimiert das Risiko fehlerhafte Datensätze zu Personio zu übertragen.

Sollen nur die bestätigten Timer synchronisiert werden, muss darauf geachtet werden, dass die erstellten Timer innerhalb von drei Monaten auch bestätigt werden müssen. 
Ansonsten kann es dazu kommen, dass diese Timer nicht synchronisiert werden.

Invite Saffomatic User
Diese Einstellung verschickt beim ersten Sync Einladung an die E-Mail-Adressen aller User, die Du bei Punkt 3. Benutzersynchronisierung auf Ja gestellt hast. Bitte stelle sicher, dass Deine Mitarbeiter darüber informiert sind und die Einladung auch annehmen. Solltest Du noch Zeit benötigen, kannst Du Deine Mitarbeiter auch noch später manuell einladen.

Die weiteren Einstellungen sind vorerst nicht wichtig für Dich und können übersprungen werden.

Bitte klicke abschließend auf Speichern. Die Schnittstelle ist eingerichtet.

Der erste Sync wird morgens oder abends stattfinden.

Fallback personio time off type ids for entitlements
Diese Einstellung ermöglicht es Dir zu differenzieren, welche Abwesenheitskategorien in ihrer Summe addiert & synchronisiert werden sollen.
Wähle hier also individuell aus, welches Urlaubskontingent bei der Synchronisation von Personio berücksichtigt werden soll

Personio time off type ids for vacation days deduction
Diese Einstellung ermöglicht es Dir im Vorfeld festzulegen, ob & für welche Abwesenheitskategorie der Status "Urlaub" mit synchronisiert werden soll.

Personio time off type ids for paid vacations
Diese Einstellung ermöglicht es Dir im Vorfeld festzulegen, ob & für welche Abwesenheitskategorie der Status "Bezahlt" mit synchronisiert werden soll.

Abwesenheitskategorien in Staffomatic erstellen

Der letzte Schritt ist die manuelle Erstellung der Abwesenheitskategorien in Staffomatic. Hierbei ist es wichtig dasselbe Wording zu nutzen, wie in Personio.

Hier ein Beispiel: Heißt eine Abwesenheitskategorie in Personio Bezahlter Urlaub, so muss diese auch Bezahlter Urlaub in Staffomatic heißen. Nur dann kann das System die beiden Kategorien matchen.

 

FAQ

Wie starte ich die Integration in Staffomatic?

Klicke auf Integrationen und dann auf den Blauen Button " Staffomatic <> Personio Sync". Ein neues Fenster öffnet sich wo die Schnittstelle gestartet werden kann.


Werden alle Timer zum Zeitpunkt der Sync übertragen?

Je nach Einstellung (sollen nur bestätigte Timer gesynct werden?), sollten alle Timer, die zu Zeitpunkt der Sync minus einer Stunde (tendenzieller Beginn der Sync) abgeschlossen bzw. bestätigt wurden, gesynct werden.

Werden nachträgliche Änderungen synchronisiert?

Grundsätzlich gilt: Ja Änderungen werden gepushed. Dies gilt aber nur für die Zeiterfassung.
Wird ein Datensatz bei der Zeiterfassung geändert, wird dieser als neuer Datensatz erkannt und beim nächsten Sync erneut gepushed.
Wichtig hierbei ist, dass nur die Änderung in dem Tool stattfindet, welches auch als Datenbasis ausgewählt wurde. 
Wird eine Änderung im anderen Tool getätigt, wird diese Änderung nicht berücksichtigt. 
In dem Fall, erfolgt auch kein erneuter Sync. 
Beispiel: Datenbasis für die Zeiterfassung ist Staffomatic. Ändere ich einen synchronisierten Timer in Personio hat dies keine Auswirkungen.

Werden gelöschte Abwesenheiten oder Timer synchronisiert?

Nein. Wenn ein Datensatz bereits übertragen wurde, wird er als "übertragen" markiert und nicht erneut synchronisiert. Daher werden gelöschte Datensätze nicht automatisch wieder übertragen und müssen manuell entfernt werden.

Wie kann ich die Sync auslösen?

Grundsätzlich gilt hier:
Die Synchronisationen sind teilweise festgelegt. Bei der Synchronisation zwischen Staffomatic & Personio erfolgt ein insgesamter Sync (Mitarbeiter-Daten, Zeiterfassungen, Abwesenheiten) der sog. "Full Sync" i.d.R. um 06.30 Uhr. Abweichungen aufgrund der Serverkapazität können jedoch auftreten. 
Darüber hinaus, findet zudem auch alle zwei Stunden ein partieller Sync statt. Hier werden die Änderungen der letzten vier Stunden synchronisiert.

Zusätzlich ist es möglich, nach Bedarf einen Sync manuell in der API durchzuführen. 

Es können in allen Bereichen (Mitarbeiter-, Zeiterfassung-, & Abwesenheiten) ein Sync angestoßen werden. Klicke hierfür auf den dafür vorgesehenen Button "Sync Now".


Bis wie viele Tage in die Vergangenheit werden Daten gesynct?

An dem Tag, an dem eine Änderung in Staffomatic vorgenommen wurde, wird 7 Tage lang versucht diese Änderung nach Personio zu syncen. Mit anderen Worten, alle Änderungen in Staffomatic sollten entsprechend auch zu Personio synchronisiert werden.
Wenn Personio erstmalig eingerichtet wird, werden bei der Zeiterfassung nur die letzten 7 Tage synchronisiert. Bei Abwesenheiten werden alle Daten synchronisiert.

Werden im Protokoll der API alle Timer und Abwesenheiten angezeigt?

Im Protokoll zu den Timern und Abwesenheiten der API von Staffomatic werden nur die letzten zwei Monate angezeigt.

Wird eine Abwesenheit inkl. Status (bestätigt/unbestätigt) synchronisiert? 

Die Synchronisation von Abwesenheiten hängt von den Einstellungen in der Schnittstelle ab. Wenn nur bestätigte Abwesenheiten synchronisiert werden sollen, werden diese auch als bestätigt übertragen. Falls alle Abwesenheiten, auch unbestätigte, synchronisiert werden sollen, müssen diese später genehmigt werden.