Über die API können aus einem Fremdsystem in MHMeRECRUITING Organisationseinheiten wie Gesellschaften oder Standorte verwaltet werden. Die Organisationseinheiten lassen sich dabei anlegen, ändern, löschen und auch verknüpfen.

Eine detaillierte technische Dokumentation kann hier eingesehen werden:
https://demo.mhm.jobs/interfaces/v1/documentation.yaml

Sollte die Verwaltung der Organisationseinheiten auf Ihrem System aktiviert sein, so finden Sie diese Dokumentation auch unter Ihrer Domain:

https://ihre-domain.de/interfaces/v1/documentation.yaml

Der Zugriff erfolgt über ein Token, das aus dem Schlüssel und dem Geheimnis der API-Zugangsdaten erzeugt wird und anschließend bei allen weiteren Aufrufen übergeben wird. Das Token läuft derzeit nicht ab und sollte daher sicher aufbewahrt werden.

Welche Organisationseinheiten eine Anwendung unterstützt, liefert der Endpunkt org_unit_types - im Standard sind dies Gesellschaft und Standort. Da die Bezeichnungen der Organisationseinheiten pro Anwendung abweichen können, sollte ein anbindendes System die Typen immer über diesen Endpunkt ermitteln und nicht fest hinterlegen.

Über org_units stehen die eigentlichen Aktionen bereit. Ein Aufruf ohne weitere Angaben liefert alle Organisationseinheiten, optional eingeschränkt auf einen einzelnen Typ. Beim Anlegen werden der Typ und der Name übergeben; die Antwort enthält die neue ID, über die die Organisationseinheit anschließend adressiert wird. Beim Bearbeiten kann der Name geändert werden, der Typ hingegen nicht - eine Gesellschaft lässt sich also nachträglich nicht in einen Standort umwandeln. Der Name muss beim Bearbeiten nur dann mitgegeben werden, wenn er sich tatsächlich ändert.

Ergänzend lassen sich Organisationseinheiten direkt beim Anlegen oder Bearbeiten einander zuordnen, beispielsweise ein Standort zu einer oder mehreren Gesellschaften. Welche Typen dabei als übergeordnete Einheit zulässig sind, gibt der Endpunkt org_unit_types je Typ mit aus. Übergeben wird immer die vollständige Liste der Zuordnungen: Sie ersetzt die bisherigen Zuordnungen, eine leere Liste entfernt alle bestehenden Zuordnungen, und ohne Angabe bleiben die bestehenden Zuordnungen unverändert. Eine Organisationseinheit kann sich nicht selbst zugeordnet werden, und eine deaktivierte Organisationseinheit kann eine bestehende Zuordnung behalten, aber nicht neu zugeordnet werden.

Beim Löschen prüft die Anwendung, ob der Organisationseinheit noch Stellen zugeordnet sind. Ist dies der Fall, wird der Aufruf mit einer Fehlermeldung abgewiesen und die Organisationseinheit bleibt erhalten. Damit ist ausgeschlossen, dass über die Schnittstelle versehentlich Strukturen entfernt werden, an denen noch Daten hängen.

Der Zugriff wird über Geltungsbereiche an den API-Zugangsdaten gesteuert. Fehlt der passende Geltungsbereich, wird der Aufruf abgewiesen - auch dann, wenn das Token selbst gültig ist. Bestehende Zugangsdaten bleiben davon unberührt, der Bewerberimport und der Bewerbungsexport funktionieren unverändert weiter.

Benutzerimport

Über die API von MHMeRECRUITING lassen sich auch Benutzer verwalten (anlegen, ändern und löschen).

Über den neuen Endpunkt /users lassen sich Benutzer auflisten, einzeln abrufen, anlegen, bearbeiten und löschen. Der Aufbau folgt dabei dem bereits bestehenden Endpunkt für Organisationseinheiten. Ergänzend stehen zwei lesende Endpunkte zur Verfügung: /user_types gibt den über die API verwaltbaren Benutzertyp zusammen mit den Organisationseinheitstypen aus, denen dieser zugeordnet werden kann. /permission_groups liefert die Berechtigungsgruppen, die sich über die API zuweisen lassen – Systemgruppen mit administrativem Zugriff sind darin bewusst nicht enthalten.

Beim Anlegen und Bearbeiten eines Benutzers können Organisationseinheiten und Berechtigungsgruppen in derselben Anfrage übergeben werden. Es gelten dieselben Prüfregeln wie in der Oberfläche: Eine Organisationseinheit kann sich nicht selbst zugeordnet werden, eine deaktivierte Organisationseinheit kann lediglich bestehen bleiben und nicht neu zugewiesen werden, und Berechtigungsgruppen mit administrativem Zugriff lassen sich über die API nicht neu vergeben. Jede Anfrage wird als Transaktion verarbeitet - schlägt ein Teil der Zuweisung fehl, wird keine der Änderungen gespeichert.

Nachfolgend sind einige Benutzerattribute, darunter Anrede, Sprache, Adresse, benutzerdefinierte Felder und Personalnummer genauer beschrieben.

Die Felder werden beim Abruf über GET /users und GET /users/{userId} zurückgegeben. Sie können beim Anlegen über POST /users und beim Aktualisieren über PATCH /users/{userId} gesetzt werden:

• salutation – Anrede, zulässige Werte mr, ms und divers
  • mr = Herr
  • ms = Frau 
  • divers =  Neutrale Anrede
• role – Rolle als Freitext
• job_title – Jobbezeichnung als Freitext
• lang – Sprache des Benutzers. Zur Auswahl stehen de und en
  • en = Englisch
  • de = Deutsch
• custom_1 bis custom_4 – Freitextfelder am User
• address – Objekt mit street, zipcode, city, region, country_code, location_phone und intermediate_recipient_name
• account.employee_number – Personalnummer als Freitext

Nicht gesetzte Textfelder werden als leere Zeichenkette zurückgegeben, nicht als null.

Anrede: Der Wert wird unabhängig von Groß- und Kleinschreibung erkannt und in Kleinbuchstaben zurückgegeben. Ein nicht zulässiger Wert führt nicht zu einem Fehler; die Anrede wird stattdessen leer gesetzt.

Sprache: In der Regel stehen de und en zur Verfügung. Bei einigen Anwendungen existiert nur Deutsch. Ein nicht angebotener Wert wird mit dem Statuscode 422 abgelehnt. Eine leere Zeichenkette oder null setzt die Sprache auf den Standard der Anwendung zurück. Da die Sprache am Login-Konto hinterlegt ist, gilt eine Änderung für alle Benutzer, die sich mit demselben Konto anmelden.

Adresse: Die Postleitzahl besteht aus bis zu fünf Ziffern. country_code erwartet einen ISO-3166-1-alpha-2-Code in Kleinbuchstaben, z. B. de. Ein nicht angebotener Wert wird mit 422 abgelehnt.

Beim Aktualisieren wird jedes Adressfeld einzeln übernommen. Nicht übermittelte Felder bleiben unverändert, eine leere Zeichenkette oder null leert das jeweilige Feld. Eine einmal angelegte Adresse kann nicht vollständig entfernt werden. Teilt sich der Benutzer die Adresse mit einem anderen Benutzer, etwa nach „Mehrfachrolle hinzufügen" in der Benutzerverwaltung, wirkt sich eine Änderung auf beide Benutzer aus.

Aktualisieren: Beim Aktualisieren sind alle Felder optional, und es werden nur die übermittelten Felder geändert. So lässt sich beispielsweise die Personalnummer anpassen, ohne die E-Mail-Adresse erneut zu übermitteln. Ist account oder address kein Objekt oder leer, wird die Anfrage mit dem Statuscode 400 abgelehnt.