Zum Hauptinhalt gehen

Finden Sie die Antworten, die Sie brauchen

Fehlerbehebung bei Integrationen und APIs

Dieser Artikel hilft Ihnen beim Beheben von Problemen mit Integrationen und APIs in Personio. Welche Schritte Sie ausführen müssen, hängt davon ab, wer die Integration erstellt hat. Personio entwickelt und wartet nicht jede Integration. Erkundigen Sie sich, wer Ihre Integration entwickelt hat, bevor Sie mit der Fehlerbehebung beginnen.

Dieser Artikel befasst sich mit folgenden Themen:

Problem bei der Einrichtung

Probleme nach der Einrichtung

Bevor Sie beginnen

Die Schaltfläche Weiter im Integrations-Einrichtungsassistenten reagiert nicht

Fehler

Beim Einrichten einer Integration im Marketplace passiert beim Klicken auf Weiter im Einrichtungsassistenten nichts. Dieses Problem wird in der Regel dadurch verursacht, dass eine Browsererweiterung, ein Proxy oder die Konfiguration eines Unternehmensnetzwerks das JavaScript der Seite blockiert.

Mögliche Lösung

  1. Öffnen Sie Personio in einem privaten oder Inkognito-Browserfenster und starten Sie den Einrichtungsassistenten neu. Dadurch werden Browsererweiterungen deaktiviert, die möglicherweise die Seite beeinträchtigen.
  2. Wenn die Schaltfläche immer noch nicht reagiert, versuchen Sie, sich über ein anderes Netzwerk zu verbinden – zum Beispiel über einen mobilen Hotspot anstelle Ihres Unternehmensnetzwerks.

Ermitteln, wer eine Integration entwickelt hat

Bevor Sie mit der Fehlerbehebung beginnen, stellen Sie fest, wer Ihre Integration entwickelt hat. Davon hängt ab, welche Schritte Sie ausführen müssen und wer Ihnen helfen kann. So können Sie es herausfinden:

  1. Gehen Sie zum Marketplace und suchen Sie nach der Integration.
  2. Wenn die Integration angezeigt wird, öffnen Sie sie und überprüfen Sie das Feld Entwickelt von in den App Details:
  3. Falls die Integration nicht im Marketplace angezeigt wird, handelt es sich um die Fehlerbehebung bei einer Integration, die nicht zum Marketplace gehört.

Eine von Personio entwickelte Marketplace-Integration funktioniert nicht

Fehler

Die von Personio entwickelten Integrationen sind die einzigen Marketplace-Integrationen mit dem Reiter Überwachung. Falls Ihre Anwendung nicht mehr funktioniert oder nicht mehr synchronisiert wird, sollten Sie als Erstes den Reiter Überwachung überprüfen.

Mögliche Lösung

  1. Gehen Sie zu Marketplace > Verbundene Integrationen und vergewissern Sie sich, dass die Integration noch als verbunden angezeigt wird.
  2. Dem Reiter Überwachung können Sie den Status und eventuelle Fehlerdetails entnehmen.
  3. Sollte sich das Problem dadurch nicht behoben lassen, können sich Kontoinhabende an den Support wenden. 

Eine von Dritten entwickelte Marketplace-Integration funktioniert nicht

Fehler

Externe Partner, nicht Personio, entwickeln und pflegen Marketplace-Integrationen Dritter. Personio fungiert als Empfänger von API-Aufrufen: Die Integration des Partners sendet Anfragen, um Daten abzurufen oder mit Personio zu synchronisieren. Wenn Daten nicht oder nur teilweise synchronisiert werden oder dabei Fehler auftreten, liegt die Ursache in der Regel in fehlenden oder fehlerhaften Anfragen auf Seiten des Partners. Personio hat keinen Einblick in die Konfiguration der Integration durch den Partner oder in mögliche Änderungen auf dessen Seite. Sollte Ihre Integration nicht mehr funktionieren oder synchronisiert werden, ist das Support-Team des Partners für die Fehlerbehebung zuständig.

Mögliche Lösung

  1. Wenden Sie sich an das Support-Team des Partners. Die Kontaktdaten finden Sie in der rechten Leiste der Integrationsseite im Marketplace.
  2. Meldet der Partner keine Probleme, bitten Sie dessen Technikteam, die Protokolle für die betroffenen Datensätze zu überprüfen. Personio speichert keine Protokolle der Partner-API-Aktivitäten. Daher sind die Protokolle des Partners die einzige Möglichkeit, zu bestätigen, ob der Partner die API-Anfrage gesendet und welche Antwort Personio zurückgegeben hat.
  3. Wenn das Technikteam des Partners der Ansicht ist, dass das Problem auf Seiten von Personio liegt, bitten Sie es, einen Bericht zu erstellen, der folgende Informationen enthält:
    • den vollständigen API-Aufruf, einschließlich Header und Body
    • die verwendete Client-ID
    • die vollständige API-Antwort

Die kontoinhabende Person reicht diesen Bericht anschließend beim Personio Support ein und bittet um Eskalation an das Partnermanagement-Team von Personio.

Eine von Dritten entwickelte Marketplace- oder individuelle Integration gibt Fehlercodes zurück, wenn Abwesenheitsdaten synchronisiert werden

Fehler

Eine verbundene Integration gibt API-Fehlercodes zurück, wenn versucht wird, Abwesenheitsdaten mit Personio zu synchronisieren. Die Fehlercodes geben an, warum Personio die Anfrage abgelehnt hat.

Mögliche Lösung

Nutzen Sie den Fehlercode und die Nachricht Ihres Integrationstools, um die Ursache zu ermitteln und die entsprechende Lösung unten anzuwenden.

422 – Dem Mitarbeiter ist keine Richtlinie zugewiesen

Für die Abwesenheitsart, die die Integration synchronisieren möchte, ist dem Mitarbeiter keine Abwesenheitsrichtlinie zugewiesen. Gehen Sie zum Mitarbeitendenprofil, öffnen Sie den Reiter Abwesenheit, und vergewissern Sie sich, dass für die entsprechende Abwesenheitsart eine Richtlinie zugewiesen ist. Falls keine zugewiesen ist, fügen Sie die richtige hinzu, und fordern Sie die Integration auf, es erneut zu versuchen.

400 – Überschneidung von Abwesenheitszeiträumen

Personio erlaubt nicht, dass zwei Abwesenheitseinträge denselben Zeitraum für denselben Mitarbeiter abdecken. Entfernen Sie die vorhandene Abwesenheit in Personio, bevor die Integration versucht, den Überschneidungszeitraum zu synchronisieren.

404 – Mitarbeiter nicht gefunden

Dies kann darauf hindeuten, dass die Integration eine Mitarbeitenden-ID sendet, die in Personio nicht existiert. Überprüfen Sie, ob die von der Integration übermittelten Mitarbeitenden-IDs mit den Mitarbeitenden-IDs in Ihrem Personio Account übereinstimmen. Bei anderen Ursachen für einen 404-Fehler wenden Sie sich an das Support-Team des Integrationspartners.

Eine Integration, die nicht zum Marketplace gehört, funktioniert nicht

Fehler

Eine Integration, die nicht im Marketplace aufgeführt ist, ist eine individuelle Integration. Personio hat sie nicht entwickelt und pflegt sie auch nicht. Ihr IT-Team oder eine externe entwickelnde Person, kein Personio Partner, hat sie direkt über die API eingerichtet. Die Fehlerbehebung liegt in der Verantwortung der jeweiligen Person.

Mögliche Lösung

  1. Wenden Sie sich an Ihr IT-Team oder an die entwickelnde Person, die die Integration erstellt hat. Sie sind für die Fehlerbehebung zuständig und haben Zugriff auf die technischen Details, die Personio nicht einsehen kann.
  2. Personio fungiert als Empfänger von API-Aufrufen. Ihre Integration sendet Anfragen an Personio, um Daten abzurufen oder zu synchronisieren. Wenn das nicht oder nur teilweise geschieht oder dabei Fehler auftreten, liegt die Ursache in der Regel in fehlenden oder fehlerhaften Anfragen Ihrerseits.
  3. Ihr IT- Team oder Entwickler sollte die fehlgeschlagene Anfrage und Antwort beurteilen :
    • den vollständigen API-Aufruf einschließlich Header und gegebenenfalls Body
    • die verwendete Client-ID
    • die vollständige API-Antwort

Der Greenhouse-Webhook wird ausgelöst, aber Personio erstellt kein Mitarbeitendenprofil

Fehler

Der Greenhouse-Webhook wird ausgelöst, aber Personio erstellt kein Mitarbeitendenprofil.

Lösung

Arbeiten Sie diese Schritte durch.

  1. Bestätigen Sie, dass die sich bewerbende Person in Greenhouse den Status „Eingestellt“ hat. Die Integration erstellt nur dann ein Personio Profil, wenn die sich bewerbende Person in Greenhouse explizit auf „Eingestellt“ gesetzt wird. Wenn Sie die Person auf eine andere Phase setzen oder sie durch einen Angebots-Workflow weiterleiten, ohne die Greenhouse-Phase zu aktualisieren, wird das Profil nicht erstellt.
  2. Prüfen Sie, ob die Pflichtfelder im Greenhouse-Datensatz der sich bewerbenden Person ausgefüllt sind. Für die Synchronisierung der Anstellung sind der Vorname, der Nachname und die E-Mail-Adresse im Greenhouse-Datensatz der sich bewerbenden Person erforderlich. Wenn eines dieser Felder leer ist, erstellt Personio kein Profil. Überprüfen Sie den Datensatz der sich bewerbenden Person direkt in Greenhouse – dies ist eine Überprüfung der Datenvollständigkeit, keine Überprüfung der Zuordnung von Attributen.
  3. Prüfen Sie in Personio, ob eine duplizierte E-Mail-Adresse vorhanden ist. Existiert in Personio bereits ein Mitarbeitendenprofil mit der gleichen E-Mail-Adresse wie die eingestellte sich bewerbende Person, kann Personio kein zweites Profil erstellen. Gehen Sie zu Unternehmen > Personalliste und suchen Sie nach der E-Mail der sich bewerbenden Person, um sicherzustellen, dass diese von keinem vorhandenen Profil verwendet wird.

Bei der Entra ID-Integration wird der Fehler „Unzureichende Berechtigungen zum Abschließen des Vorgangs“ (403) angezeigt

Fehler

Bei der Entra ID-Integration kann die Synchronisierung von bestimmten Mitarbeitenden nicht durchgeführt werden. Die Fehlermeldung 403 Zugriff verboten oder „Unzureichende Berechtigungen zum Abschließen des Vorgangs“ wird angezeigt, während die Synchronisierung anderer Mitarbeitender korrekt funktioniert. 

Lösung

Personio kann nicht feststellen, welche dieser Optionen zutrifft. Sie müssen die Ursache direkt in Microsoft Entra ID untersuchen.

  1. Beginnen Sie mit der erneuten Authentifizierung der Integration. Gehen Sie zu Marketplace > Verbundene Integrationen. Wählen Sie Microsoft Entra ID aus, und klicken Sie auf Authentifizierung wiederholen.
  2. Wenn der Fehler nach der erneuten Authentifizierung weiterhin besteht, verfügen die betroffenen Accounts in Microsoft Entra ID möglicherweise über eine Konfiguration, die den Zugriff der Integration einschränkt. Besprechen Sie mit Ihrem IT-Team die folgenden möglichen Ursachen:
    • Privilegierte Rollen: Der Account verfügt über eine globale Adminrolle, eine privilegierte Adminrolle oder eine ähnlich privilegierte Rolle. Weisen Sie der Integrations-App eine höhere Rolle zu, damit sie diese Accounts aktualisieren kann. Weitere Informationen zu Admin-Rechten finden Sie in der Microsoft-Dokumentation zu Rollen und Berechtigungen.
    • Notfall-Accounts: Der Account ist ein geschützter Account für den Notfallzugriff und ist absichtlich von automatischen Aktualisierungen ausgeschlossen.
    • Lokale AD-Synchronisierung: Der Account wird von einem lokalen Active Directory verwaltet. Einige Attribute können nur in der lokalen Umgebung, nicht aber in der Cloud geändert werden.
    • Gast- vs. Mitgliedsstatus: Der Account ist als Gastnutzender und nicht als Mitglied konfiguriert. Er kann auch eine andere Lizenzzuweisung als andere Accounts haben.
    • Verwaltungseinheiten: Der Account gehört zu einer eingeschränkten Verwaltungseinheit, die die Anzahl der Apps, die ihn ändern können, begrenzt.
    • Richtlinien für bedingten Zugriff: Eine Richtlinie blockiert Änderungen an diesem spezifischen Account.

Die Google Directory Sync-Integration deaktiviert immer wieder den Google-Account eines erneut angestellten Mitarbeiters

Fehler

Wenn Sie einen Mitarbeiter erneut anstellen, erstellt Personio ein neues Profil mit einer neuen Mitarbeitenden-ID. Das Feld externalID in Google Directory kann den vorhandenen Google-Account des Mitarbeiters weiterhin mit der alten, jetzt inaktiven Personio Mitarbeitenden-ID verknüpfen. Da die Integration das Feld externalID ausliest und ein inaktives Profil findet, deaktiviert sie den Google-Account bei jeder Synchronisierung. Dies geschieht, auch wenn der Mitarbeiter in Personio aktiv ist. 

Lösung

Entfernen Sie die alte Personio Mitarbeitenden-ID aus dem Feld externalID des Google-Accounts, bei dem dieses Problem auftritt. Dies muss über die Google Directory API erfolgen.

Sobald Sie das Feld externalID leeren, verknüpft die Integration den Google-Account wieder mit dem neuen aktiv Personio Profil des Mitarbeiters. Dies geschieht beim nächsten Synchronisierungsvorgang.

Eine Marketplace-Integration verbleibt im Status Ausstehend, obwohl sie im Partnertool als aktiv angezeigt wird

Fehler

Die Integration wird in Personio als Ausstehend angezeigt, das Partnertool zeigt sie jedoch als aktiv an. Dies bedeutet in der Regel, dass die Integration mit manuell erstellten individuellen Zugriffsdaten verbunden wurde anstatt mit den vordefinierten Zugriffsdaten, die Personio generiert, wenn Sie die Verbindung über den Marketplace herstellen. Manche Integrationen – beispielsweise Recruiting-Tools – erfordern diese vordefinierten Zugriffsdaten, um eine gültige Verbindung herzustellen.

Lösung

  1. Gehen Sie zu Marketplace > Verbundene Integrationen.
  2. Wählen Sie die Integration aus.
  3. Klicken Sie auf Trennen.
  4. Gehen Sie zum Marketplace, und suchen Sie nach der Integration.
  5. Klicken Sie auf Verbinden.
  6. Klicken Sie auf Neue Zugriffsdaten generieren, um neue API-Zugriffsdaten mit den Berechtigungen zu generieren, die die Integration benötigt.

Die Übertragung eines bestimmten Mitarbeitendenattributs an eine verbundene Integration wurde gestoppt

Fehler

Ein bestimmtes Mitarbeitendenattribut wird nicht mehr an eine verbundene Integration eines Drittanbieters übertragen, obwohl die Integration weiterhin verbunden ist.

Mögliche Lösung

Prüfen Sie, ob das Attribut in der Liste der lesbaren Mitarbeitendenattribute der Integration aufgeführt ist:

  1. Gehen Sie zu Marketplace > Verbundene Integrationen.
  2. Öffnen Sie die Integration, die das Attribut nicht mehr empfängt.
  3. Suchen Sie die Liste Lesbare Mitarbeitendenattribute.
  4. Verwenden Sie die Suchleiste, um das fehlende Attribut zu finden, oder scrollen Sie durch die Liste.
  5. Wählen Sie die Checkbox neben dem Attribut aus.
  6. Klicken Sie auf Aktualisieren.

Die Integration sollte das Attribut zukünftig übertragen. Wenn das Problem nach Aktivierung des Attributs weiterhin besteht, wenden Sie sich bitte an das Support-Team des Integrationspartners. Personio empfängt die API-Anfragen des Partners, hat aber keine Kontrolle darüber, wie das System des Partners die abgerufenen Daten verarbeitet.

HTTP 410-Fehler „Falsche Zugriffsdaten“ am Authentifizierungsendpunkt

Wenn Sie von POST /v1/auth die HTTP 410-Fehlermeldung „Falsche Zugriffsdaten“ erhalten, überprüfen Sie, wie Sie Ihre Zugriffsdaten senden. Sie müssen die Zugriffsdaten im Anfragetext und nicht als URL-Abfrageparameter senden:

POST https://api.personio.de/v1/auth
Inhaltstype: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Personio unterstützt das Senden von Zugriffsdaten als Abfrageparameter für neue API-Zugriffsdaten nicht mehr. Die Unterstützung für die Authentifizierung von Abfrageparametern endet für alle Zugriffsdaten im Dezember 2026. Wenn Sie Ihre API-Zugriffsdaten vor Inkrafttreten dieser Änderung erstellt haben, funktioniert die Authentifizierung von Abfrageparametern noch bis zum Datum der Deaktivierung.

Personio beschränkt den API-Zugriff nicht auf Basis von IP-Adressen. Wenn Ihre API-Aufrufe fehlschlagen, liegt das Problem im Anfrageformat oder in den Zugriffsdaten und nicht in einer Blockierung auf Netzwerkebene.

Helfen Sie uns, uns zu verbessern. Ist diese Seite hilfreich?