Für Agenturen und Technische Dienstleister: Karriereseite und Stellenanzeigen über die Concludis API 2.0 anbinden
Mit der Concludis API 2.0 können Stellenangebote aus Concludis auf einer individuell entwickelten Karriereseite oder Stellenbörse dargestellt werden.
Die API richtet sich unter anderem an Webagenturen und technische Dienstleister, die Stellenlisten und Stellenanzeigen in das Design und die Struktur einer Unternehmenswebsite integrieren möchten.
Für den Zugriff ist ein entsprechender API-Account erforderlich. Über diesen Account steht auch das ausführliche API-Tutorial zur Verfügung. Dort sind alle verfügbaren Endpoints, Parameter und Rückgabewerte im Detail beschrieben.
Dieser Artikel beschreibt deshalb bewusst nur den grundsätzlichen Aufbau einer Stellenbörse.
Grundprinzip
Die Stellenangebote werden über den Projects-Endpoint aus Concludis abgerufen:
GET /api/2.0/de_DE/projects
Ein typischer Abruf für eine öffentliche Stellenbörse kann beispielsweise so aussehen:
GET /api/2.0/de_DE/projects
?published=2
&applicable=2
&show[0]=jobad_structured
&show[1]=locations
&page=1
&ipp=100
Die API liefert eine Liste von Projekten zurück. Über die Parameter lässt sich bestimmen, welche Projekte berücksichtigt und welche zusätzlichen Informationen ausgegeben werden.
Veröffentlichte und bewerbbare Stellen
Für den Aufbau einer Stellenbörse sind insbesondere die Parameter published und applicable wichtig.
published bestimmt den Veröffentlichungszustand:
0 = keine Einschränkung 1 = intern oder extern veröffentlicht 2 = extern veröffentlicht 3 = intern veröffentlicht
applicable bestimmt, ob eine Bewerbung auf das Projekt möglich ist:
0 = keine Einschränkung 1 = intern oder extern bewerbbar 2 = extern bewerbbar 3 = intern bewerbbar
Für eine klassische öffentliche Karriereseite wird daher in der Regel mit
published=2 applicable=2
gearbeitet.
Damit werden Projekte berücksichtigt, die extern veröffentlicht und für externe Bewerbungen freigegeben sind.
Für eine interne Stellenbörse kann entsprechend mit den internen Zuständen gearbeitet werden.
Wichtig ist die Unterscheidung zwischen Veröffentlichung und Bewerbbarkeit: Eine Stelle kann grundsätzlich veröffentlicht sein, ohne dass über diesen Bewerbungsweg aktuell eine Bewerbung möglich ist.
Stellen nach Stellenbörse filtern
Wenn innerhalb einer Concludis-Instanz mehrere Stellenbörsen verwendet werden, kann die Ausgabe über boards[] eingeschränkt werden.
Beispiel:
boards[0]=318
Damit werden nur Projekte berücksichtigt, die dieser Stellenbörse zugeordnet sind.
Ohne einen Board-Filter können alle Projekte berücksichtigt werden, die den übrigen angegebenen Kriterien entsprechen.
Die verfügbaren Stellenbörsen und deren IDs sind kundenspezifisch.
Welche Daten sollen ausgegeben werden?
Über den Parameter show[] kann der Detailgrad der Antwort erweitert werden.
Für den Aufbau einer Karriereseite sind insbesondere folgende Werte relevant.
Strukturierte Stellenanzeige
show[0]=jobad_structured
Damit wird die Stellenanzeige in strukturierter Form ausgegeben.
Das Projekt enthält dann unter anderem:
jobad.containers jobad.tracking_codes jobad.google_for_jobs_code
jobad_structured eignet sich besonders dann, wenn die Agentur die Stellenanzeige selbst aufbauen und die einzelnen Bestandteile in das eigene Layout integrieren möchte.
Vollständiges Markup
Alternativ kann die Stellenanzeige als vollständiges Markup angefordert werden:
show[0]=jobad_full_markup
Die Antwort enthält dann:
jobad.full_markup
Dieser Weg ist sinnvoll, wenn die bereits zusammengestellte Stellenanzeige möglichst vollständig übernommen werden soll.
Welche Variante verwendet wird, hängt daher von der geplanten Integration ab:
jobad_structured → einzelne Bestandteile der Anzeige stehen strukturiert zur Verfügung jobad_full_markup → vollständiges Markup der Stellenanzeige wird geliefert
Standorte
Mit
show[1]=locations
werden die vollständigen Location-Objekte der jeweiligen Projekte ausgegeben.
Diese Daten können beispielsweise für die Anzeige von Arbeitsorten oder für eigene Standortfilter verwendet werden.
Weitere show-Parameter
Darüber hinaus stehen weitere Erweiterungen zur Verfügung:
evaluators
liefert die dem Projekt zugeordneten Bewerter.
usergroups
liefert die zugeordneten Benutzergruppen.
ba_extended
liefert erweiterte Informationen zur Veröffentlichung bei der Bundesagentur für Arbeit.
indeed_extended
liefert erweiterte Informationen zur Veröffentlichung bei Indeed.
Für eine normale öffentliche Stellenbörse werden diese Informationen in der Regel nicht benötigt.
Die vollständige Beschreibung aller show[] -Optionen befindet sich im API-Tutorial.
Kundenindividuelle Projektfelder
Neben den Standardfeldern kann eine Concludis-Installation zusätzliche kundenindividuelle Projektfelder enthalten.
Diese werden als custom_fields innerhalb der Projektdaten ausgegeben.
Solche Felder können beispielsweise als
- Freitextfeld
- Auswahlfeld
angelegt sein.
Sie können zusätzliche Informationen enthalten, die der Kunde für seine Stellenanzeigen oder die Struktur seiner Stellenbörse verwendet.
Ein mögliches Beispiel wäre ein Projektfeld für Benefits, Kategorien oder weitere kundenindividuelle Merkmale.
Da Aufbau und Inhalt dieser Felder vom jeweiligen Kunden abhängen, sollte die Integration die tatsächlich gelieferten custom_fields der jeweiligen Concludis-Instanz berücksichtigen.
Es sollte nicht davon ausgegangen werden, dass bei allen Kunden dieselben Custom Fields oder dieselben Werte vorhanden sind.
Aufbau der Stellenübersicht
Aus der Projektliste kann die Agentur die gewünschte Stellenübersicht erstellen.
Typischerweise werden dabei beispielsweise verwendet:
- Projekt-ID
- Stellentitel
- Standort
- Unternehmen
- Veröffentlichungsinformationen
- kundenindividuelle Projektfelder
Welche Informationen tatsächlich dargestellt oder als Filter verwendet werden, kann entsprechend der Karriereseite individuell entschieden werden.
Darstellung einer einzelnen Stellenanzeige
Für die Detailseite kann entweder mit den bereits aus der Projektliste erhaltenen Daten gearbeitet oder ein einzelnes Projekt separat abgefragt werden.
Beispiel:
GET /api/2.0/de_DE/projects/project
?id=12345
&show[0]=jobad_structured
Alternativ kann auch hier beispielsweise jobad_full_markup verwendet werden.
Damit kann die Agentur entscheiden, ob die Anzeige aus den strukturierten Bestandteilen selbst aufgebaut oder das vollständige Markup verwendet werden soll.
Pagination
Bei einer größeren Anzahl von Projekten sollte der Projects-Endpoint seitenweise abgefragt werden.
Hierfür stehen die Parameter
page ipp
zur Verfügung.
Beispiel:
page=1 ipp=100
Anschließend werden die weiteren Seiten abgefragt, bis keine weiteren Projekte zurückgegeben werden.
Die geeignete Seitengröße kann abhängig vom Umfang der Projektdaten und den verwendeten show[] -Parametern gewählt werden.
Empfohlener technischer Aufbau
Für eine Karriereseite empfiehlt sich eine serverseitige Synchronisation.
Ein typischer Aufbau ist:
Concludis API
↓
Server der Karriereseite
↓
lokale Datenhaltung / Cache
↓
Stellenbörse und Stellenanzeigen
Der Server der Karriereseite ruft die Projektdaten regelmäßig aus Concludis ab und speichert die benötigten Informationen zwischen.
Die Besucher der Karriereseite greifen anschließend auf diese Datenbasis zu und lösen nicht bei jedem Seitenaufruf eine vollständige API-Abfrage aus.
Dies reduziert die Anzahl der API-Aufrufe und ermöglicht kurze Ladezeiten auf der Karriereseite.
Deeplinking und eigene URLs
Eine individuell entwickelte Karriereseite verwendet häufig eigene URLs für Stellenanzeigen.
Beispiel:
https://www.example.com/karriere/jobs/softwareentwickler
Für die Verbindung mit Concludis muss trotzdem eine eindeutige Zuordnung zwischen der Concludis Projekt-ID und der jeweiligen Stellenanzeige möglich sein.
Ein technisches URL-Schema könnte beispielsweise so aussehen:
https://www.example.com/karriere/job/12345
Die Website kann diese URL anschließend intern auf eine sprechende URL weiterleiten:
/job/12345
↓
/karriere/jobs/softwareentwickler
Entscheidend ist, dass anhand der von Concludis übergebenen Projekt-ID eindeutig die richtige Stellenanzeige aufgerufen werden kann.
Bewerbungsweg
Die Darstellung der Stellenanzeige und der eigentliche Bewerbungsweg sind getrennt voneinander zu betrachten.
Je nach Konfiguration kann nach Klick auf „Bewerben“ beispielsweise
- ein Concludis Bewerbungsformular
- ein anderer in Concludis konfigurierter Bewerbungsweg
- ein extern bereitgestelltes Bewerbungsformular
aufgerufen werden.
Der konfigurierte Bewerbungsweg sollte deshalb bei der Integration berücksichtigt und nicht unabhängig davon aus einzelnen Projektdaten nachgebaut werden.
Mehrsprachige Stellenbörsen
Die API 2.0 unterstützt sprachabhängige Abfragen über den jeweiligen Locale im API-Pfad.
Beispiel Deutsch:
/api/2.0/de_DE/projects
Für weitere Sprachen wird der entsprechende Locale verwendet.
Damit können auch mehrsprachige Stellenbörsen und Stellenanzeigen umgesetzt werden.
API-Tutorial als technische Referenz
Dieser Artikel soll den grundsätzlichen Aufbau einer Stellenbörse erklären und ersetzt nicht die technische API-Dokumentation.
Die vollständige Dokumentation steht über den jeweiligen API-Account zur Verfügung.
Dort finden sich unter anderem:
- Authentifizierung
- vollständige Beschreibung der Endpoints
- alle Filterparameter
- verfügbare
show[]-Parameter - Request- und Response-Strukturen
- Feldbeschreibungen
- weitere technische Beispiele
Für die konkrete Implementierung sollte daher immer das Tutorial des API-Accounts als technische Referenz verwendet werden.
Hinweis zur API 1.0
Für neue Integrationen ist die Concludis API 2.0 zu verwenden.
Die frühere API 1.0 und darauf basierende Integrationsanleitungen sind deprecated und sollten nicht mehr als Grundlage für neue Stellenbörsen oder Karriereportal-Integrationen verwendet werden.