README.md 14.9 KB
Newer Older
Stefan Hörterer's avatar
Stefan Hörterer committed
1 2 3 4 5 6 7 8 9
Dokumentation der LiMS Schnittstelle
====================================

## Allgemeine Informationen

Die LiMS Schnittstelle des DOSB Bildungsnetz ermöglicht Ihnen unter anderem Lizenzdaten aus Ihrem Bestandssystem in das LiMS zu importieren. Außedem können Sie

* neue Lizenzen anfordern,
* vorhandene Lizenzen verlängern und korrigieren,
10
* vorhandene Lizenz aus LiMs laden
Stefan Hörterer's avatar
Stefan Hörterer committed
11 12
* PDF Lizenzvordrucke laden

13
Alle Anfragen müssen im produktiv Betrieb an die URL *https://bildungsnetz.dosb.de/api/lims* gestellt werden. Bitte beachten Sie, dass es sich hier um produktive Daten handelt. Darum testen sie Ihre Implementierung am besten zunächst auf unserer Testumgebung. Diese kann analog zum Live-System über die URL *https://bildungsnetz.ghostthinker.de/api/lims* adressiert werden.
Stefan Hörterer's avatar
Stefan Hörterer committed
14 15 16 17 18

In der aktuellen Version 1.0 erfolgen die Anfragen via **REST**. *SOAP*, *WSDL* und *XML-RPC* können unter Umständen nachträglich bereitgestellt werden.

## Testumgebung und API Zugriff

19
In der Testumgebung haben Sie Zugriff auf alle Lizenzdaten Ihrer Organisation und können diese verändern, ohne dass die produktiven Datenbestände davon betroffen sind. Wenn sie Zugriff auf die API und auf unsere Demo Umgebung (Sandbox) benötigen, kontaktieren sie uns einfach über die Supportformular des Bildungsnetzes (Benutzerkonto im Bildungsnetz erforderlich) oder alternativ per E-Mail an support@bildungsnetz.dosb.de. Zum Ausprobieren der Schnittstelle können Sie das Testformular unter *https://lims.ghostthinker.de* nutzen.
Stefan Hörterer's avatar
Stefan Hörterer committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40


## Request Header und Authentifizierung

Die LiMS Schnittstelle verwendet eine HTTP-Authentifizierung, jede Anfrage muss mit einer Kombination aus "benutzername:passwort" ausgestattet sein. Diese Kombination muss base64 encodiert sein. Sessions/Cookies werden nicht unterstützt.
Bsp.
```    
    Authorization: Basic RXMgaGVpw590IE51a3VsYXIh
```
Zudem können Sie angeben, ob json oder xml geladen werden soll. Für den PDF download verwenden Sie application/pdf oder einfach */*
```
    Accept application/json
    Accept application/xml
    Accept application/pdf
```
Falls die Authentifizierung fehlschlägt, werden folgende Status Codes zurückgeliefert:
```
  400 Bad Request : Benutzername/Passwort sind falsch
  403 Forbidden : Ihre Benutzerdaten sind korrekt, Sie wurden jedoch nicht für den API Zugriff freigeschaltet
```

Stefan Hörterer's avatar
Stefan Hörterer committed
41
Bitte verwenden Sie für die Anfragen immer **UTF-8** als Zeichenkodierung.
Stefan Hörterer's avatar
Stefan Hörterer committed
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69

## Dienste ##

### Lizenz anfordern ###
----
  Aufruf zum Erstellen oder Aktualisieren einer Lizenz.

 **URL**

  /request

 **Method:**

  `POST`
  
  **URL Params**

   Keine

 **Data Params für Neue Lizenzen**

   **Required:**

     Alle nicht mit * markierte Felder aus der Felddefinitionsliste

   **Optional:**

 	 Alle mit * markierte Felder aus der Felddefinitionsliste
Sergej Naumenko's avatar
Sergej Naumenko committed
70
 	 Das Feld valid_until wird im Status "created" und "requested" automatisch auf den maximalmöglichen Wert gesetzt, falls das Feld leer übermittelt wird. 
Stefan Hörterer's avatar
Stefan Hörterer committed
71 72 73 74 75 76 77 78 79
     Das Feld first_issue_date kann gesetzt werden, falls es sich um Bestandsdaten handelt. 
     Ansonsten wird hierfür der selbe Wert wie für issue_date verwendet.

   **Invalid:**

    Folgende Felder können nicht gesetzt werden, wenn eine neue Lizenz erstellt werden soll

    `license_number_dosb` oder `lid`
   
80 81 82 83 84 85 86 87 88 89
### Lizenz verlängern ###
----
Werden geänderte Lizenzdaten übermittelt, erfolgt automatisch eine Verlängerung der Lizenz.


### Lizenz korrigieren ###
----
Werden ausschließlich geänderte Daten des Lizenzhalters übermittelt, erfolgt automatisch eine Korrektur der Lieznz.
Werden geänderte Lizenzdaten, übermittelt erfolgt automatisch eine Verlängerung der Lizenz (s. oben)

Stefan Hörterer's avatar
Stefan Hörterer committed
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104

 **Data Params für vorhandene Lizenzen**

   **Required:**

     Eine der beiden IDs muss angegeben werden

     `license_number_dosb` oder `lid`

   **Optional:**

 	 Alle Felder aus der Felddefinitionsliste, bzw. nur die Felder, die geändert werden sollen.

   **Invalid:**

105
     Folgende Felder können nicht gesetzt werden, wenn eine bestehende Lizenz verändert werden soll
Stefan Hörterer's avatar
Stefan Hörterer committed
106 107

     `organisation_id`
Sergej Naumenko's avatar
Sergej Naumenko committed
108
     `first_issue_date` Ausnahme: Das Erstausstellungsdatum kann bei Bestandsdaten über "Bearbeiten" und "Korrigieren" geändert werden.
109

Stefan Hörterer's avatar
Stefan Hörterer committed
110
  
111 112 113 114 115 116
### Wertetabelle ###

|  Einzellizenz | Ausstellungsdatum | | | Gültigkeitsdatum | | |
|---|---|---|---|---|---|---|
|                                       | min|max|Vorschlag|min|max|Vorschlag|
|Standard (Neu)                         | Beliebig DP=aktuelles Jahr - 50 | +30 Tage| -     | Ausstellungsdatum| Ausstellungsdatum plus Gültigkeitsdauer -1d| Maximal gültiger Wert = Ausstellungsdatum plus Gültigkeitsdauer -1d|
Sergej Naumenko's avatar
Sergej Naumenko committed
117
|Bestandsdaten (Neu)                    | Beliebig DP=aktuelles Jahr - 50 | +30 Tage| - | 13.12.1901|19.01.2038| Ausstellungsdatum plus Gültigkeitsdauer -1d |
118 119 120 121
|Standard / Bestandsdaten (Verlängerung)| Beliebig DP=aktuelles Jahr - 50 | +30 Tage| heute | max(Ausstellungsdatum, Vorhandenes Gültigkeitsdatum)| Quartalskulanz* (Ausstellungsdatum plus Gültigkeitsdauer -1d)|Ausstellungsdatum plus Gültigkeitsdauer -1d|

*Quartalskulanz letzter Tag im Quartal

Sergej Naumenko's avatar
Sergej Naumenko committed
122
### Beispiele ###
Sergej Naumenko's avatar
Sergej Naumenko committed
123

Sergej Naumenko's avatar
Sergej Naumenko committed
124
Beispiel: 
Sergej Naumenko's avatar
Sergej Naumenko committed
125

Sergej Naumenko's avatar
Sergej Naumenko committed
126
Eine C-Trainer-Lizenz (1. Lizenzstufe) ist gültig vom 28.03.2016 bis 27.03.2020. 
Sergej Naumenko's avatar
Sergej Naumenko committed
127

Sergej Naumenko's avatar
Sergej Naumenko committed
128 129 130
Die 1. Lizenzstufe hat einen Gültigkeitszeitraum von 4 Jahren.

Beispiel 1: Verlängerung am 15.08.2020:
Sergej Naumenko's avatar
Sergej Naumenko committed
131

Sergej Naumenko's avatar
Sergej Naumenko committed
132 133 134
neue Gültigkeit laut Vorschlag: 14.08.2024. 

Beispiel 2: Verlängerung am 08.02.2023
Sergej Naumenko's avatar
Sergej Naumenko committed
135

Sergej Naumenko's avatar
Sergej Naumenko committed
136 137
neue Gültigkeit laut Vorschlag: 07.02.2027. 

138 139

#### Statuscodes ####
Stefan Hörterer's avatar
Stefan Hörterer committed
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191

 **Success Response:**
  
  Bei Erfolg werden sowohl dei interne LiMS-ID (lid) als auch die DOSB-Lizenznummer (license_number_dosb) zurückgegeben

   **Code:** 200 <br />
    **Content:** `{ lid : 12, license_number_dosb: AB-CD-E-xxxxxxxxxx }`
 
 **Error Response:**


   **Code:** 401 UNAUTHORIZED <br />
    **Content:** `[ Invalid login credentials ]`

   **Code:** 403 ACCESS DENIED <br />
    **Content:** `[ Permission denied for organisation %og_nid ]`

   **Code:** 406 Not Acceptable <br />
    **Content:** `[ Missing  %fieldname ]`

   **Code:** 406 Not Acceptable <br />
      **Content:** `[ License number invalid or license not found ]`

   **Code:** 406 Not Acceptable <br />
      **Content:** `[ Training course id is not valid in this organisation ]`
      
   **Code:** 422 UNPROCESSABLE ENTRY  <br />
    **Content:** `[ Invalid input for %key: %val ]`


 **Notes:**

### Lizenzenvordruck laden mit DOSB Lizenznummer ###
----
  Aufruf laden einer Lizenz im DinA4 Format andhand der DOSB Lizenznummer

 **URL**

  /download

 **Method:**

  `POST`
  
  **URL Params**

   `license_number_dosb`
   

 **Data Params für vorhandene Lizenzen**

   **Required:**
192 193 194
    `fomat` mit einem der Werte `dina4`, `card` oder `signet`
    
    Bitte beachten Sie, dass DinA4 und Card als PDF zurückgegeben werden und Signet als JPG.
Stefan Hörterer's avatar
Stefan Hörterer committed
195 196

  **Optional:**
197
     keine
Stefan Hörterer's avatar
Stefan Hörterer committed
198

Sergej Naumenko's avatar
Sergej Naumenko committed
199

200
#### Statuscodes ####
Sergej Naumenko's avatar
Sergej Naumenko committed
201

Stefan Hörterer's avatar
Stefan Hörterer committed
202 203
 **Success Response:**
  
204
  Bei Erfolg wird die Lizenz im angegeben Format zurückgegeben.
Stefan Hörterer's avatar
Stefan Hörterer committed
205 206

  **Code:** 200 <br />
207 208
  **Content-Type:** application/pdf oder image/jpeg <br />
  **Content:** Lizennz im angebenen Format
Stefan Hörterer's avatar
Stefan Hörterer committed
209 210 211 212 213 214 215 216 217 218
 
 **Error Response:**

   **Code:** 401 UNAUTHORIZED <br />
    **Content:** `[ Invalid login credentials ]`

   **Code:** 403 ACCESS DENIED <br />
    **Content:** `["Access denied for user %username ]`

 **Notes:** 
219
 Ein Beispiel dazu befindet sich hier: https://gitlab.ghostthinker.de/gt/lims_connect/blob/master/php_sample_client/sample_download_license.php
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252

### Lizenz laden mit DOSB Lizenznummer ###
----
  Aufruf zu Laden aller Felder einer Lizenz anhand der DOSB Lizenznummer.

 **URL**

  /load

 **Method:**

  `POST`
  
  **URL Params**

   `license_number_dosb`

 **Success Response:**
  
  Bei Erfolg werden die Felder der Lizenz zurückgegeben. Die Felder bzw Bezeichnung sind die selben wie beim anfordern.

  **Code:** 200 <br />
  **Content-Type:** application/pdf <br />
  **Content:** Inhalt der pdf
 
 **Error Response:**

   **Code:** 401 UNAUTHORIZED <br />
    **Content:** `[ Invalid login credentials ]`

   **Code:** 403 ACCESS DENIED <br />
    **Content:** `["Access denied for user %username ]`

253
 
Johannes Metscher's avatar
Johannes Metscher committed
254
## Sequenzdiagramm
255 256
 
![alt text](doc/sequence_diagram.jpg "Sequenz Diagramm")
Stefan Hörterer's avatar
Stefan Hörterer committed
257 258 259 260 261 262 263 264 265 266

## Felddefinitionen
Diese Felder können beim Erstellen von Lizenzen ausgefüllt werden. 

Bitte beachten Sie, dass die Felder vom Typ "Date" als Unixzeit, also dem POSIX-Standard entsprechend (z.B. 497274993), übergeben werden müssen.

|  Feld | Beschreibung  | Typ  | input / min, max  |
|---|---|---|---|
| firstname  | Vorname   |  string |  1,255 |
| lastname  |  Nachname |  string |   1,255|
267
| academic_title*  | Titel  |  string | 1,255  |
Stefan Hörterer's avatar
Stefan Hörterer committed
268 269 270 271 272 273 274
| birthdate | Geburtsdatum  | date  |  -, NOW |
| gender | Geschlecht  | string  |  w,m,u |
| street  | Straße  | string  | 1,255 |
| postal  | PLZ  | string  | 5 |
| city  | Ort  | string  | 1,255  |
| mail*  | E-Mail  | string  | 1,255  |
| phone*  | Telefon  | string  | 1,255  |
275 276
| issue_date  | Ausstellungsdatum  | date  | s. Wertetabelle  |
| first_issue_date*  | Erstausstellungsdatum  | date  | -, issue_date  |
Stefan Hörterer's avatar
Stefan Hörterer committed
277 278
| training_course_id  | Ausbildungsgang  | int  |   |
| issue_place  | Ausstellungsort  | string  | 1,255  |
279
| valid_until*  | Gültig bis | date  | s. Wertetabelle  |
Stefan Hörterer's avatar
Stefan Hörterer committed
280
| honor_code  | Ehrencodex  | int  | 1,0  |
281
| honor_code_date*  | Ehrencodex Datum  | date  | -, NOW  |
Stefan Hörterer's avatar
Stefan Hörterer committed
282
| first_aid  | Erste-Hilfe-Ausbildung  | int  | 1,0  |
283
| first_aid_date*  | Erste-Hilfe-Ausbildung Datum  | date  | -, NOW  |
Stefan Hörterer's avatar
Stefan Hörterer committed
284 285 286 287 288 289 290 291 292 293 294
| license_number_organisation  | Lizenznummer(Verband)  | string  | 1,255  |
| prequalification_type*  | Vorqualifikationsart  | string  | 1,255  |
| prequalification_number**  | DOSB-Lizenznummer Vorqualifikation  | string  | 1,255  |
| organisation_id  | Auszustellender Verband | int  |  0,- |
| lid  | LiMS ID  | int  |  0,- |
| license_number_dosb | DOSB-Lizenznummer   | string  | 1,255  |
| custom_1* | Zusatzfeld 1   | string  | 0,1024  |
| custom_2* | Zusatzfeld 2   | string  | 0,1024  |

\* Felder mit sind optional. 

Johannes Metscher's avatar
FAQ  
Johannes Metscher committed
295 296 297 298 299 300 301 302 303 304
** Muss eine gültige DOSB-Lizenznummer sein

## FAQ

1. Frage: Wenn die Daten per Schnittstelle übertragen werden, wie gelangen dann die erstellten Lizenz-pdf-Dateien wieder zum absendenden Verband zurück (Mail, welche Mailadresse)? 
  * Antwort: Die Übermittlung der Daten erfolgt pro Lizenz und als Antwort des LiMS erhält dann der Verband direkt die PDF (siehe technische Dokumentation).
2. Frage: Brauche ich als LSB oder SV der für seine LFV Lizenzen ausstellt ein zusätzliches Feld für den Verband der Lizenz?
  * Antwort:  Sie sollten in Ihrem System auch die ID des auszustellender Verbandes (=organisation_id, siehe technische Dokumentation) hinterlegen, wenn Sie nicht nur für sich Lizenzn anfordern.  Wenn Ihr Verband _nur_ seine eigenen Lizenzen pflegt reicht die Definition eines fixen Wertes in der Schnittstelle.
3. Frage: D.h. ein Zusatzfeld für DOSB-Lizenznummer und eines für ausstellenden Verband? Ist das auch so aus der Schnittstellenbeschreibung herauszulesen?
  * Antwort: Im Grunde genommen ja - nämlich, wenn die MOs einen Abgleich ihrer eigenen Felder und der Liste Felddefinitionen in der technischen Dokumentation machen.
305 306 307 308
4. Frage: Wie genau gelange ich zur Testumgebung? Eingeloggt bin ich derzeit unter https://bildungsnetz.ghostthinker.de. Kann ich hier mit meinen Testdaten arbeiten?
  * Antwort: Ganz genau. Es handelt sich bei bildungsnetz.ghostthinker.de bereits um die Testumgebung.
5. Frage: Können diese nach Abschluss der Testphase wieder entfernt werden?
  * Antwort: Richtig. Das Test/Demosystem wird von zur Zeit zur Zeit wieder zurückgesetzt und damit die Beispieldaten automatisch weggeworfen.
309 310 311 312 313
6. Frage: Beim Anlegen einer neuen Lizenz wird unter Lizenzdaten der „DOSB-Lizenz Ausbildungsgang“ erfasst. Werden die Ausbildungsgänge für jeden ausbildenden Verband, entsprechend der beim DOSB bestätigten Ausbildungskonzeptionen, vorgegeben oder arbeiten wir Ihnen diese zu?
  * Antwort: Die DOSB-Lizenz Ausbildungsgänge werden initial vom DOSB für die jeweilige Mitgliedsorganisation festgelegt. Spitzenverbände und natürlich auch Sie als LSB können dann für Ihre Untergliederung wiederum die Auswahl bei Bedarf weiter begrenzen. Dies geschiehet direkt beim Bearbeiten der jeweiligen Organisation im Bildungsnetz.
7. Frage: Werden Falscheingaben (unplausible Zeiträume) bei der Gültigkeit der Lizenz vom System gefiltert
  * Antwort: Alle Daten werden wie in Spalte "input / min, max" unter https://gitlab.ghostthinker.de/gt/lims_connect#felddefinitionen vermerkt validiert. Dies betrifft insbesondere wichtige Zeiträume, wie Gültig bis.
8. Frage: Wir möchten langfristig gesehen ausschließlich mit den DOSB-Lizenznummern arbeiten. Ist es möglich, Ihnen ein Script mit allen aktuell gültigen Lizenzen zur Verfügung zu stellen, um diese im LIMS mit einer DOSB-Lizenznummer auszustatten, die dann zurückgeschickt und automatisch im eigenen System hinterlegt werden?
Johannes Metscher's avatar
Johannes Metscher committed
314 315 316 317 318 319 320 321 322 323 324 325 326 327
  * Antwort: Dies können Sie sehr gerne über einen initialen Bestandsimport (hier ist das Erstausstellungsdatum = first_issue_date mitanzugeben) vornehmen. Dann erhalten Sie zu jeder Lizenz automatisch eine DOSB-Lizenznummer.
9. Frage: 1.) Gibt es Ihrerseits eine Schnittstelle, über die wir von unserem System aus auf die Druckfunktion einer Lizenz zugreifen können?
  * Antwort: Genau diese Funktion bietet der zweite Aufruf "download" der Schnittstelle, siehe  https://gitlab.ghostthinker.de/gt/lims_connect#lizenzenvordruck-laden-mit-dosb-lizenznummer. Sie erhalten als Rückmeldung direkt die PDF als Datei.
10. Frage: Wie ist ein initialer Import bestimmter Lizenzen aus unserem System möglich wäre, um für alle eine DOSB-Lizenznummer zu generieren. Kann ich hierfür einfach ein PHP-Script auf unserem Server erstellen, welches alle Lizenzen einmal aus der Datenbank aufruft und an das Bildungsnetz über die bekannte Schnittstelle sendet? Oder ist hierfür eine andere Importfunktion vorgesehen?
  * Antwort: Das können Sie direkt über den Aufuf "request" der Schnittstelle machen. Für den Bestandsdatenimport dann bitte das Erstausstellungsdatum (=first_issue_date) angeben.
11. Frage: Welches Datum ist bei der Neuanlage einer Lizenz von Bedeutung?
  * Antwort: Das Feld Ausstellungsdatum = issue_date.
12. Frage: Wieso erscheint das Feld Erstausstellungsdatum nicht in der Auflistung der Lizenzdaten?
  * Antwort: Bisher wurde der Wert dort nicht benötigt, auch weil er ja nicht geändert werden kann.
13. Frage: Wieso muss das issue_date (welches bei Neueingabe den gleichen Wert hat wie das first_issue_date) noch mit übergeben werden?
  * Antwort: Bei einer Neueingabe (also keinem Bestandsimport) darf nur das issue_date angegeben werden, jedoch nicht first_issue_date.
14. Frage: Kann eine Lizenz auch per Schnittstelle gelöscht werden?
  * Antwort: Bisher ist das Löschen nur über die Weboberfläche möglich. Sicherlich wäre das für die Zukunft eine sinnvolle Erweiterung der Schnittstelle.
15. Frage: Welche Schritte sind nun im Anschluss nötig, um im realen System zu arbeiten? Muss lediglich der Link der Schnittstelle angepasst werden?
328
  * Antwort: Richtig. Einfach die URL des Host / Service von Demo auf Live umstellen.