Beschreibung der Schnittstelle

Automatische Übertragung von Stellenanzeigen

1. Schnittstellen-Beschreibung

Stellenanzeigen können durch eine REST-Schnittstelle automatisch übertragen werden. Um die Schnittstelle benutzen zu können, muss zunächst eine vertragliche Zusammenarbeit abgeschlossen werden. Für die vertraglichen Bedingungen kontaktieren Sie bitte unseren Vertrieb: Tel. +49 231 / 914488-77 oder senden Sie uns eine Nachricht.

Anschließend wird ein Benutzerkonto freigeschaltet, mit dem über eine REST-Schnittstelle die Stellenanzeige übertragen werden kann.

1.1. Die REST-Schnittstelle

Die Schnittstelle basiert aus einfachen HTTP-Post und -Get-Request-Aufrufen. Dabei werden - sofern notwendig - im Body des Requests die notwendigen Daten als JSON kodiert übertragen. Das Ergebnis liegt ebenfalls als JSON zurück. Es wird keine detailierte Fehlerbeschreibung zurückgeliefert, da in der Regel diese erfahrungsgemäß nicht ausgewertet werden. In dem folgenden Beispiel wird das Tool curl und jq eingesetzt. Es kann natürlich jeder beliebiger HTTP-Client in beliebiger Sprache verwendet werden.

1.2. Der Übertragungsworkflow

Zur Übertragung einer Anzeige sind mehrere Aufrufe notwendig. Im ersten Aufruf meldet man sich mit dem Schnittstellen-Account an. Diesen Account erhält man nach der vertraglichen Vereinbarung. Dazu gibt es auch ein Passwort. Mit den Anmeldedaten werden auch die Daten der Stellenanzeigen übertragen. Das ganze Paket wird als JSON in UTF-8 mit UNIX-LF übertragen. Optional kann man anschließend Anhänge (z.B. für HTML-Anzeigen die Bilder, CSS-Resourcen etc) sukzessiv hochladen. Liegen alle Informationen vor, so kann der Übertragungsworkflow durch einen abschließenden Request fertiggestellt werden. Die Anzeige liegt nun im System vor und wird für die Öffentlichung weiter verarbeitet.

2. Initialisierungsaufruf

Im ersten Auruf wird ein POST-Request mit dem Content-Type vom Typ application/json gesendet. D.h. im Body des Requests befindet sich ein JSON-Objekt.

Das JSON-Objekt hat folgenden Aufbau:

{
"account" : {
"email" : "info@test-name.vivai.de",
"pw" : "geheimes-passwort"
},            
"job" : {
"title": "Facharzt für Dortmund",
"ref": "Optionale Referenznummer",
"message": "Optionale Nachrichten, Infos, Hinweise",          
"employer" : {
"name" : "Name des Arbeitgebers"
"address": {
"street": "Straße des Arbeitgebers"
"city" : "Ort des Arbeitgebers",
"zip" : "PLZ des Arbeitergebers",
"country": "DE" 
},
"contact" : {
"fax" : "0231 / 914488-00",
"telephone" : "0231 / 914488-77",
"email" : "info@kliniken.de"
} 
},
"contact" : {
"name" : "Herr Mustermann",
"contact" : {
"fax" : "0231 / 914488-00",
"telephone" : "0231 / 914488-77",
"email" : "info@kliniken.de"
}
},
"location" : {
"countryCode" : "DE",
"zip" : "44137",
"city" : "Dortmund" 
},
"description" : {
"area" : "Ärztin/Arzt",
"domain" : "Allgemeinmedizin",
"level" : "Chefarzt",
"hiringType" : "Befristete Stelle",
"jobScope" : "Vollzeit",
"plainText": "Dies ist nun die Beschreibung der Anzeige als reinen Text!",
"firstDay" : "2017-01-20T12:00:00Z",
"onlineApplicants" : true 
}
}
}

2.1. account

 
"account" : {
"email" : "info@test-name.vivai.de",
"pw" : "geheimes-passwort"
}

Hier werden in den Feldern email und pw mit den bereitgestellten Daten gefüllt.

2.2. job

            
"title": "Facharzt für Dortmund",
"ref": "Optionale Referenznummer",
"message": "Optionale Nachrichten, Infos, Hinweise",
"employer" : { },
"contact" : { },
"location" : { },
"description" : { }

Hier werden die einzeln Job-Informationen detailiert festgelegt:

  • title: Stellenbezeichnung
  • ref, optional: Referenz-Informationen, die z.B. bei Bewerbungen angegeben werden soll.
  • message, optional: Nachricht oder Hinweise an die Mitarbeiter, die die Anzeige weiterverarbeiten.
  • employer, optional: Arbeiter-Informationen
  • contact: Kontaktperson für diese Stellenanzeige
  • location: Einsatzort mit unterschiedlichen Ortsangaben
  • description: Weitere Beschreibung der Stellenanzeige

2.2.1. employer

Hier können optional Angaben über den Arbeitgeber geliefert werden. In einigen Fällen ist dies jedoch nicht gewünscht, daher kann dieses Feld komplett weggelassen werden. Soll der Arbeitgeber angezeigt werden, dann wird der Arbeitergeber wie folgt angegeben:

{
"name" : "Name des Arbeitgebers"
"address": {
"street": "Straße des Arbeitgebers"
"city" : "Ort des Arbeitgebers",
"zip" : "PLZ des Arbeitergebers",
"country": "DE" },

"contact" : {
"fax" : "0231 / 914488-00",
"telephone" : "0231 / 914488-77",
"email" : "info@kliniken.de"
}
}
  • name: Der Name des Arbeitgebers
  • address: Anschrift des Arbeitgebers
  • contact: Kontaktdaten des Arbeitgebers

2.2.1.1. address

Beschreibung der Anschrift des Arbeitgebers:

  • street: Straße
  • city: Ort
  • zip: PLZ
  • country: Ländercode, z.B. DE für Deutschland (Wikipedia)

2.2.1.2. contact

Kontaktdaten des Arbeitgebers. Diese Angaben können auch vollständig entfallen.

  • fax, optional: Fax-Nummer des Arbeitgebers
  • telephone, optional: Telefonnnummer des Arbeitgebers
  • email, optional: E-Mail-Adresse des Arbeitgebers

2.2.2. contact

Die Kontaktperson der Stellenanzeige:

{
"name" : "Herr Mustermann",
"contact" : {
"fax" : "0231 / 914488-00",
"telephone" : "0231 / 914488-77",
"email" : "info@kliniken.de"
}
}
  • name: Name der Kontaktperson
  • contact: Kontaktdaten

2.2.2.1. contact

Kontaktdaten der Kontaktperson. Diese Angaben können auch vollständig entfallen.

  • fax, optional: Fax-Nummer der Kontaktperson
  • telephone, optional: Telefonnnummer der Kontaktperson
  • email, optional: E-Mail-Adresse der Kontaktperson

2.2.3. Location

Beschreibung des Einsatzortes. Wird für mehrere Orte gesucht, dann wird das Feld zip frei gelassen und in city werden die Orte, jeweils durch ein Komma und Leerzeichen getrennt, eingetragen. Alternativ können auch die ersten Ziffern einer Postleitzahl verwenden, um mehrere Orte zu erfassen. Die Orte, deren Postleitzahl mit der Eingabe beginnen, werden als Einsatzort verwendet. Dann wird natürlich city nicht befüllt.

{
"countryCode" : "DE",
"zip" : "44137",
"city" : "Dortmund"
}
  • countryCode: Ländercode (Wikipedia)
  • zip, optional: ‘44137’ oder auch ‘44’
  • city, optional: ‘Dortmund’ oder auch ‘Recklinghausen, Dorsten, Marl, Herne’

2.2.4. description

Eine detailierte Beschreibung der Stellenanzeige. Der individuelle Inhalt der Anzeige kann als reinen Text oder als HTML übertragen werden. Bei HTML werden in der Regel noch andere Ressourcen wie Bilder und CSS-Anweisungen benötigt. Diese können als Anhang hochgeladen werden. Das Hochladen erfolgt durch weitere Aufrufe des REST-Schnittstelle.

{
"area" : "Ärztin/Arzt",
"domain" : "Allgemeinmedizin",
"level" : "Chefarzt",
"hiringType" : "Befristete Stelle",
"jobScope" : "Vollzeit",
"plainText": "Dies ist nun die Beschreibung der Anzeige als reinen Text!",
"firstDay" : "2017-01-20T12:00:00Z",
"onlineApplicants" : true }
}
  • area, optional: Berufsfeld
  • domain, optional: Berufsbereich
  • level, optional: Hierarchiestufe
  • hiringType, optional: Anstellungsform
  • jobScope, optional: Stellenumfang
  • firstDay, optional: Antrittsdatum, wird es weggelassen, ist das Antrittsdatum ‘sofort’, ansonsten wird ein Wert im folgenden Format erwartet: yyyy-MM-ddTHH:mm:ssZ, Beispiel: 2017-01-20T12:00:00Z
  • onlineApplicants, boolescher Wert: Online-Bewerbungen sind möglich
  • plainText, optional: Inhalt der Stellenanzeige als reinen Text oder als HTML-Text

Berufsfeld, Berufsbereich und Hierarchiestufe sind in Kliniken vorgegeben. Diese Angaben dienen nur als Information, da die korrekte Einordnung die Schnittstelle unnötigt verkompliziert. Diese Werte werden daher vom Mitarbeiter festgelegt.

2.2.4.1 hiringType

Folgende Werte sind möglich:

  • “Keine Angaben”
  • “Befristete Stelle”
  • “Festanstellung”
  • “Freie Mitarbeit”
  • “Selbstständig”
  • “Praktikum”
  • “Ausbildungsplatz”

2.2.4.2 jobScope

Folgende Werte sind möglich:

  • “Keine Angaben”
  • “Aushilfe”
  • “Teilzeit”
  • “Vollzeit”
  • “Vollzeit/Teilzeit”
Beispiel

In der Datei ‘data.json’ befindet sich nun der oben beschriebene JSON-Inhalt mit den gewünschten Daten. Dann erfolgt der Aufruf mit curl wie folgt:

curl -X POST -H "Content-Type:application/json" -d @data.json https://jobs.kliniken.de/api/job/create

Das Ergebnis ist im positiven Fall:

{
"result":"ok",
"id":"58089674d3fa73a0a457b72c"
}

Wir erhalten ein ok im Feld result und eine id. Diese ID wird nun für die folgenden REST-Aufrufe benötigt.

Testfälle

Wenn man die Schnittstelle zunächst testen möchte, dann kann man das machen, in dem man eine andere URL verwendet. In diesem Fall wird die Übertragung nicht weitergeleitet und verarbeitet. Die restlichen Aufrufe folgen in gewohnter Weise. Nur der erste Aufruf muss mit einer anderen URL aufgerufen werden:

curl -X POST -H "Content-Type:application/json" -d @data.json https://jobs.kliniken.de/api/job/test

3. Anhänge hochladen

Optional können Anhänge hochgeladen werden. Dazu werden die Dateien einzeln und nacheinander hochgeladen. Es werden nur Bilder, Texte und PDF-Dokumente unterstützt. Archive können nicht hochgeladen werden. Das Hochladen erfolgt in zwei Schritten. Im ersten Schritt der wird Upload mit Namen und Mime-Typ angekündigt und als Ergebnis wird eine weitere ID zurückgeliefert. Im zweiten Schritt wird die Datei hochgeladen.

3.1 Anhang ankündigen

Dazu wird ein JSON-Objekt mit dem folgenden Aufbau übermittelt:

{
"filename": "message.txt",
"mimeType": "text/plain"
}
  • filename:Der Dateiname der Datei.
  • mimeType:Der Mime-Type der hochzuladenen Datei. (Übersicht)
Beispiel

In der Datei ‘attachment.json’ befindet sich nun der oben beschriebene JSON-Inhalt mit den gewünschten Daten. Dann erfolgt der Aufruf mit curl wie folgt. Wir geben die ID (58089674d3fa73a0a457b72c) zusätzlich zur URL an:

curl -X POST -H "Content-Type:application/json" -d @attachment.json https://jobs.kliniken.de/api/job/prepare-upload/58089674d3fa73a0a457b72c

Das Ergebnis ist im positiven Fall:

{
"result":"UFNUTUNWBN"
}

Wir haben nun zwei IDs, mit denen wir nun die Ressource hochladen können:

3.2 Anhang hochladen

Beispiel

Die Datei ‘message.txt’ ist die angekündigte Ressource. Wir geben zusätzlich die beiden IDs (58089674d3fa73a0a457b72c und UFNUTUNWBN) in der URL an. Dann erfolgt der Aufruf mit curl wie folgt.

curl -X POST -H "Content-Type:text/plain" --data-binary @message.txt https://jobs.kliniken.de/api/job/upload/58089674d3fa73a0a457b72c/UFNUTUNWBN

Das Ergebnis ist im positiven Fall:

{
"result":"ok"
}

Für weitere Anhänge werden beide Schritte nacheinander wiederholt! Natürlich gibt es für die angekündigten Ressourcen stets eine neue ID.

4. Abschluß

Wenn alle Ressourcen hochgeladen wurden, kann die Verarbeitung abgeschlossen werden. Damit ist die Stellenanzeige erfolgreich übertragen worden und befindet sich somit in weiterer Verarbeitung.

Beispiel

Wir geben die ID (58089674d3fa73a0a457b72c) zusätzlich zur URL an, um die Übertragung abzuschließen:

curl -X GET https://jobs.kliniken.de/api/job/publish/58089674d3fa73a0a457b72c

Das Ergebnis ist im positiven Fall:

{
"result":"ok"
}

5 Fehlerfälle

Führt ein Aufruf zu einem beliebigen Fehler, dann wird dieser ohne nähere Angaben mit folgenden Ergebnis quitiert:

{
"result":"error"
}

Beispiel als Shell-Script

#!/bin/bash

#
# curl: https://curl.haxx.se
# jq: https://stedolan.github.io/jq/
#

JOBID=$(curl -X POST -H "Content-Type:application/json" -d @data.json https://jobs.kliniken.de/api/job/create | jq -r '.id')
ATTID=$(curl -X POST -H "Content-Type:application/json" -d @attachment.json https://jobs.kliniken.de/api/job/prepare-upload/$JOBID | jq -r '.result')
curl -X POST -H "Content-Type:text/plain" --data-binary @message.txt https://jobs.kliniken.de/api/job/upload/$JOBID/$ATTID
curl -X GET http://localhost:8086/api/job/publish/$JOBID

echo $JOBID
echo $ATTID

Zwei Beispiele zum Aufbau des JSON-Objektes:

Erstes Beispiel
{
"account" : {
"email" : "info@test-name.vivai.de",
"pw" : "geheimes-passwort"
},

"job" : {
"title": "Facharzt für Dortmund",

        "contact" : {
            "name" : "Herr Mustermann",
        }

      "location" : {
        "countryCode" : "DE" },

      "description" : {
        "hiringType" : "Befristete Stelle",
        "jobScope" : "Vollzeit",
        "onlineApplicants" : true }
      }
}
Zweites Beispiel
{
"account" : {
"email" : "info@test-name.vivai.de",
"pw" : "geheimes-passwort"
},
"job" : {
"title": "Facharzt für Dortmund",
      "employer" : {
        "name" : "Name des Arbeitgebers"
        "address": {
            "street": "Betenstraße 13-15"
            "city" : "Dortmund",
            "zip" : "44137",
            "country": "DE" },
         },
        "contact" : {
            "name" : "Herr Mustermann",
        },
      "location" : {
        "countryCode" : "DE",
        "city" : "Dortmund, Marl, Recklinghausen" },
      "description" : {
        "hiringType" : "Befristete Stelle",
        "jobScope" : "Vollzeit",
        "plainText": "Dies ist nun die Beschreibung der Anzeige als reinen Text!",
        "firstDay" : "2017-01-01T12:00:00Z",
        "onlineApplicants" : true }
      }
}