Ü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.
Als nächster Schritt ist ein Endpunkt für die Benutzerverwaltung geplant. Darüber sollen Benutzer über die Schnittstelle abgefragt, angelegt, bearbeitet und gelöscht beziehungsweise deaktiviert werden können.