README.md 23.3 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


## 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.
26 27 28 29 30 31 32 33 34

----

**WICHTIGER HINWEIS ZUM BENUTZERNAME**
Bitte beachte Sie, dass der Benutzername hier nicht gleich Ihrer E-Mail-Adresse ist. In den meisten Fällen handelt es sich um die Zeichenfolge Ihrer E-Mail-Adresse bis zum "@" am besten Sie Fragen jedoch noch einmal beim Bildungs-Team nach, wenn Sie Probleme haben sollten sich zu authentifizieren.

----


Stefan Hörterer's avatar
Stefan Hörterer committed
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
```    
    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
50
Bitte verwenden Sie für die Anfragen immer **UTF-8** als Zeichenkodierung.
Stefan Hörterer's avatar
Stefan Hörterer committed
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78

## 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
79
 	 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
80 81
     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.
Lina Kuche's avatar
Lina Kuche committed
82 83
     Die Felder training_activity_1 und training_activity_2, falls sie angegeben sind, überschreiben z.B. beim Aktualisieren die Fortbildungsmaßnahmen.
     Es werden keine Haken "Berechtigt zur Verlängerung", wie bspw. bei der Weboberfläche, berücksichtigt.
Stefan Hörterer's avatar
Stefan Hörterer committed
84 85 86 87 88 89 90

   **Invalid:**

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

    `license_number_dosb` oder `lid`
   
91 92 93 94 95 96 97 98 99 100
### 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
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115

 **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:**

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

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

Sergej Naumenko's avatar
Sergej Naumenko committed
121

122 123 124 125 126
### Wertetabelle ###

|  Einzellizenz | Ausstellungsdatum | | | Gültigkeitsdatum | | |
|---|---|---|---|---|---|---|
|                                       | min|max|Vorschlag|min|max|Vorschlag|
Sergej Naumenko's avatar
Sergej Naumenko committed
127
|Standard (Neu)                         | Beliebig DP=aktuelles Jahr - 50 | +30 Tage | -     | Ausstellungsdatum | Ausstellungsdatum + Gültigkeitsdauer - 1d | Maximal gültiger Wert = Ausstellungsdatum + Gültigkeitsdauer - 1d |
128
|Bestandsdaten (Neu)                    | 13.12.1901 | +30 Tage | - | Ausstellungsdatum |19.01.2038 | Ausstellungsdatum + Gültigkeitsdauer - 1d |
Sergej Naumenko's avatar
Sergej Naumenko committed
129
|Standard / Bestandsdaten (Verlängerung)| Beliebig DP=aktuelles Jahr - 50 | +30 Tage | heute | Ausstellungsdatum | Ausstellungsdatum + Gültigkeitsdauer + 92d | Ausstellungsdatum + Gültigkeitsdauer - 1d |
130 131 132

*Quartalskulanz letzter Tag im Quartal

133
### Beispiele ###
Sergej Naumenko's avatar
Sergej Naumenko committed
134

Sergej Naumenko's avatar
Sergej Naumenko committed
135
Ausgangslage:
Sergej Naumenko's avatar
Sergej Naumenko committed
136

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

139 140
Die 1. Lizenzstufe hat einen Gültigkeitszeitraum von 4 Jahren.

Sergej Naumenko's avatar
Sergej Naumenko committed
141 142


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

145 146 147
neue Gültigkeit laut Vorschlag: 14.08.2024. 

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

149 150
neue Gültigkeit laut Vorschlag: 07.02.2027. 

151 152

#### Statuscodes ####
Stefan Hörterer's avatar
Stefan Hörterer committed
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

 **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 ###
----
187
  Aufruf eines Lizenzvordrucks im DinA4 Format andhand der DOSB Lizenznummer
Stefan Hörterer's avatar
Stefan Hörterer committed
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204

 **URL**

  /download

 **Method:**

  `POST`
  
  **URL Params**

   `license_number_dosb`
   

 **Data Params für vorhandene Lizenzen**

   **Required:**
205 206 207
    keine

  **Optional:**
208
    `format`, `file_url_only`<br /><br />
209
    `format` => `dina4`, `card` oder `signet`<br />
210
    `file_url_only`=> `1`
211 212
    
    Bitte beachten Sie, dass DinA4 und Card als PDF zurückgegeben werden und Signet als JPG.
213
    
214
## Aggregierten Lizenzenvordruck laden  ##
215

Sergej Naumenko's avatar
Sergej Naumenko committed
216
Aufruf mehrerer Lizenzvordrucker im DinA4 Format anhand meherer DOSB Lizenznummern
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236

 **URL**

  /download_multiple

 **Method:**

  `POST`
  
  **URL Params**

   keine
   

 **Data Params für vorhandene Lizenzen**

   **Required:**
    `license_numbers_dosb` kommaseparierte Liste mit DOSB Lizenznummern

  **Optional:**
237
    `format`, `file_url_only`<br /><br />
238
    `format` => `dina4` oder `card`<br />
239
    `file_url_only`=> `1`
240 241
    
    Bitte beachten Sie, dass DinA4 und Card als PDF zurückgegeben werden.
Stefan Hörterer's avatar
Stefan Hörterer committed
242

Stefan Hörterer's avatar
Stefan Hörterer committed
243 244

  
245
#### Statuscodes ####
Sergej Naumenko's avatar
Sergej Naumenko committed
246

Stefan Hörterer's avatar
Stefan Hörterer committed
247 248
 **Success Response:**
  
249
  Bei Erfolg wird die Lizenz im angegeben Format zurückgegeben.
Stefan Hörterer's avatar
Stefan Hörterer committed
250 251

  **Code:** 200 <br />
252
  **Content-Type:** application/pdf oder image/jpeg <br />
Sergej Naumenko's avatar
Sergej Naumenko committed
253
  **Content:** Lizenzen im angebenen Format
Stefan Hörterer's avatar
Stefan Hörterer committed
254 255 256 257
 
 **Error Response:**

   **Code:** 401 UNAUTHORIZED <br />
Stefan Hörterer's avatar
Stefan Hörterer committed
258
    **Content:** `[ Invalid login credentials" ]`
Stefan Hörterer's avatar
Stefan Hörterer committed
259 260

   **Code:** 403 ACCESS DENIED <br />
Stefan Hörterer's avatar
Stefan Hörterer committed
261 262 263 264
    **Content:** `["Access denied for user %username" ]`
    
   **Code:** 404 NOT FOUND <br />
    **Content:** `["License not found" ]`
Stefan Hörterer's avatar
Stefan Hörterer committed
265 266

 **Notes:** 
267
 Ein Beispiel dazu befindet sich hier: https://gitlab.ghostthinker.de/pub/lims_connect/blob/master/php_sample_client/sample_download_license.php
Lina Kuche's avatar
Lina Kuche committed
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
 
 
### Abruf von Lizenzen
----
Abruf von Lizenzen anhand der optionalen Parameter.

**URL**

/lookup

**Method:**

`POST`

**URL Params**
    keine

**Data Params für Lizenzen-Abruf**

 **Required:**
    keine

 **Optional:** `organisation_id` , `offset` , `limit` , `validation_status` , `is_obscured` , `ids_only`

  `offset` = Startwert der Abfrage

  `limit` = Anzahl der DOSB-Lizenzen für die Abfrage (max. 1000), bei DOSB-Lizenznummern (Lizenz-IDs) max. 20000

  `validation_status => 0` = Abgelaufene Lizenzen <br />
  `validation_status => 1` = Gültige Lizenzen
    
  Mögliche Werte für `is_obscured` => <br />
    `ja, Ja, j, 1, TRUE, true` = liefert nur anonymisierte DOSB-Lizenzen zurück <br />
    `nein, Nein, n, 0, FALSE, false` = liefert nur vollständige DOSB-Lizenzen zurück <br />
    
  `ids_only => TRUE` = liefert eine Liste von DOSB-Lizenznummern (Lizenz-IDs)

**Success Response:**

Bei Erfolg wird die Anzahl der enthaltenen Ergebnisse (size), der übermittelte Offset-Wert (offset), die Größe des Abfrage-Ergebnisses (total)
und die Lizenzen oder nur die Lizenz-IDs zurückgegeben.
Die Felder bzw Bezeichnung sind die selben wie beim Anfordern einer Lizenz.

**Code:** 200 <br />
  **Content-Type:** application/json <br />
  **Content:** size, offset, total mit Lizenz-IDs oder Lizenzen <br />

**Error Response:**

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

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

323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344

### 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 />
345
  **Content-Type:** application/json <br />
Stefan Hörterer's avatar
Stefan Hörterer committed
346
  **Content:** Felder der Lizenz
347 348 349 350 351 352 353 354 355
 
 **Error Response:**

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

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

356
 
357
## Sequenzdiagramm
358 359
 
![alt text](doc/sequence_diagram.jpg "Sequenz Diagramm")
Stefan Hörterer's avatar
Stefan Hörterer committed
360 361 362 363

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

Stefan Hörterer's avatar
Stefan Hörterer committed
364
Bitte beachten Sie, dass die Felder vom Typ "Date" als Unixzeit, also dem POSIX-Standard entsprechend (z.B. 497274993), übergeben werden müssen. Um auf Nummer sicher zu gehen, dass es zu keinem Winterzeitproblem kommt, sollten Sie eine Uhrzeit um 12:00Uhr Mittags wählen und nicht 00:00 Uhr. 
Stefan Hörterer's avatar
Stefan Hörterer committed
365 366 367 368 369

|  Feld | Beschreibung  | Typ  | input / min, max  |
|---|---|---|---|
| firstname  | Vorname   |  string |  1,255 |
| lastname  |  Nachname |  string |   1,255|
370
| academic_title*  | Titel  |  string | 1,255  |
Stefan Hörterer's avatar
Stefan Hörterer committed
371 372 373
| birthdate | Geburtsdatum  | date  |  -, NOW |
| gender | Geschlecht  | string  |  w,m,u |
| street  | Straße  | string  | 1,255 |
Sergej Naumenko's avatar
Sergej Naumenko committed
374
| postal  | PLZ  | string  | 5,8 - z.B. {12345} oder {AB}-{12345} z.B. für Österreich AT-1234 |
Stefan Hörterer's avatar
Stefan Hörterer committed
375 376 377
| city  | Ort  | string  | 1,255  |
| mail*  | E-Mail  | string  | 1,255  |
| phone*  | Telefon  | string  | 1,255  |
378 379
| issue_date  | Ausstellungsdatum  | date  | s. Wertetabelle  |
| first_issue_date*  | Erstausstellungsdatum  | date  | -, issue_date  |
Stefan Hörterer's avatar
Stefan Hörterer committed
380 381
| training_course_id  | Ausbildungsgang  | int  |   |
| issue_place  | Ausstellungsort  | string  | 1,255  |
382
| valid_until*  | Gültig bis | date  | s. Wertetabelle  |
Stefan Hörterer's avatar
Stefan Hörterer committed
383
| honor_code  | Ehrencodex  | int  | 1,0  |
384
| honor_code_date*  | Ehrencodex Datum  | date  | -, NOW  |
Stefan Hörterer's avatar
Stefan Hörterer committed
385
| first_aid  | Erste-Hilfe-Ausbildung  | int  | 1,0  |
386
| first_aid_date*  | Erste-Hilfe-Ausbildung Datum  | date  | -, NOW  |
Stefan Hörterer's avatar
Stefan Hörterer committed
387
| license_number_organisation  | Lizenznummer(Verband)  | string  | 1,255  |
388
| prequalification_type*  | Vorqualifikationsart  | string  | 1,255 - z.B. DOSB, Anderer LSB, Bundeswehr, Bundespolizei, International, Sonstiges |
Stefan Hörterer's avatar
Stefan Hörterer committed
389 390 391 392 393 394
| 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  |
Sergej Naumenko's avatar
Sergej Naumenko committed
395
| additional_info* | Ergänzungseintrag (wird auf der Lizenz ausgegeben) - Wichtig: Auf dem Lizenz-Vordruck wird dieser Wert auf 75 Zeichen gekürzt | string  | 0,1024  |
396 397
| training_activity_1* | Fortbildungsmaßnahme 1 | string  | 0,127 |
| training_activity_2* | Fortbildungsmaßnahme 2 | string  | 0,127 |
Stefan Hörterer's avatar
Stefan Hörterer committed
398 399 400

\* Felder mit sind optional. 

Johannes Metscher's avatar
Johannes Metscher committed
401 402
** Muss eine gültige DOSB-Lizenznummer sein

Stefan Hörterer's avatar
Stefan Hörterer committed
403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448
### Lizenzen löschen ###
----
 Aufruf zum Löschen einer Lizenz anhand der DOSB Lizenznummer.

 **URL**

  /delete

 **Method:**

  `POST`
  
  **URL Params**

   `license_number_dosb`
   

 **Data Params für vorhandene Lizenzen**

   **Required:**
    keine

  **Optional:**
    keine
    
#### Statuscodes ####

 **Success Response:**
  
  Bei Erfolg werden die ID-Felder (`lid`, `license_number_dosb`) der Lizenz zurückgegeben. 

  **Code:** 200 <br />
  **Content-Type:** application/json <br />
  **Content:** ID-Felder
 
 **Error Response:**

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

   **Code:** 403 ACCESS DENIED <br />
    **Content:** `["Access denied for user %username" ]`
    
   **Code:** 404 NOT FOUND <br />
    **Content:** `["License not found" ]`

449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475

## Umzugsanfrage stellen  ##

Umzugsanfrage stellen, um eine Lizenz in einen anderen Zielverband zu verschieben. 
Hinweis: Die Lizenz wird bei ausreichender Berechtigung direkt umgezogen.
(Nur möglich unter dem selben Dachverband)

 **URL**

  /migration_request

 **Method:**

  `POST`
  
  **URL Params**

   keine
   

 **Data Params für vorhandene Lizenzen**

   **Required:** `license_numbers_dosb`, `organisation_id`
   
  `license_numbers_dosb` = DOSB Lizenznummern
  
  `organisation_id`  = ID des Zielverbandes
Sergej Naumenko's avatar
Sergej Naumenko committed
476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501
  
#### Statuscodes ####

**Success Response:**

Bei Erfolg wird eine entsprechende Message zurückgegeben: 
"Your request has been submitted." oder "The license has been migrated.", wenn die Berechtigung für direkten Umzug vorliegen.

**Code:** 200 <br/>
 **Content-Type:** application/json <br/>
 **Content:** migration_status<br/>

**Error Response:**

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

**Code:** 403 ACCESS DENIED <br/>
   **Content:** `[Access has been denied.]`

**Code:** 403 ACCESS DENIED <br/>
   **Content:** `[Migration request already open for this license.]`
   
**Code:** 403 ACCESS DENIED <br/>
   **Content:** `[License [license_number_dosb] or target organisation [organisation_id] missing.]`
   
502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530
    
## Umzugsanfragen abholen ##

Umzugsanfragen für einen Verband abholen. 

 **URL**

  /migration_get

 **Method:**

  `POST`
  
  **URL Params**

 `organisation_id` 
 
 
 **Data Params für vorhandene Lizenzen**

**Required:**
   keine

**Optional:**
  `offset` , `limit` 

  `offset` = Startwert der Abfrage  (default: 0)

  `limit` = Anzahl der Umzugsanfragen für die Abfrage (default: 100)
Sergej Naumenko's avatar
Sergej Naumenko committed
531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556
  
  
#### Statuscodes ####

**Success Response:**

Bei Erfolg wird die Anzahl der enthaltenen Ergebnisse (size), der übermittelte Offset-Wert (offset), die Größe des Abfrage-Ergebnisses (total)
und die Migrationsanfragen (migrations) zurückgegeben.
Die Felder bzw Bezeichnung sind die selben wie beim Anfordern einer Lizenz.

**Code:** 200 <br/>
 **Content-Type:** application/json <br/>
 **Content:** size, offset, total, migrations<br/>

**Error Response:**

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

**Code:** 403 ACCESS DENIED <br/>
   **Content:** `[Access has been denied.]`

**Code:** 404 NOT FOUND  <br/>
   **Content:** `[No migration requests available!]`
   

557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572

## Umzugsanfrage ablehnen  ##

Umzugsanfrage ablehnen, um den Umzug einer Lizenz zu widersprechen. 

 **URL**

  /migration_decline

 **Method:**

  `POST`
  
  **URL Params**

  `migration_id` (Lizenz-Id)
Sergej Naumenko's avatar
Sergej Naumenko committed
573 574 575 576


#### Statuscodes ####

577 578 579
**Success Response:**

Bei Erfolg wird eine entsprechende Message (migration_status) zurückgegeben: 
Sergej Naumenko's avatar
Sergej Naumenko committed
580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597
"Migrate request has been declined."

**Code:** 200 <br/>
 **Content-Type:** application/json <br/>
 **Content:** migration_status<br/>

**Error Response:**

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

**Code:** 403 ACCESS DENIED <br/>
   **Content:** `[Access has been denied.]`

**Code:** 404 NOT FOUND  <br/>
   **Content:** `[Migrate request not found!]`
   

598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616

## Umzugsanfrage annehmen  ##

Umzugsanfrage annehmen, um eine Lizenz in einen Zielverband zu verschieben. 

 **URL**

  /migration_accept

 **Method:**

  `POST`
  
  **URL Params**

  `migration_id` (Lizenz-Id)
  
**Success Response:**

Sergej Naumenko's avatar
Sergej Naumenko committed
617 618
Bei Erfolg wird eine entsprechende Message (migration_status) zurückgegeben: <br />
"The license has been migrated successfully."
619

Sergej Naumenko's avatar
Sergej Naumenko committed
620 621 622
#### Statuscodes ####


Sergej Naumenko's avatar
Sergej Naumenko committed
623 624 625
**Code:** 200 <br/>
 **Content-Type:** application/json <br/>
 **Content:** migration_status<br/>
626 627 628

**Error Response:**

Sergej Naumenko's avatar
Sergej Naumenko committed
629 630
**Code:** 401 UNAUTHORIZED <br/>
   **Content:** `[Invalid login credentials]`
631

Sergej Naumenko's avatar
Sergej Naumenko committed
632 633
**Code:** 403 ACCESS DENIED <br/>
   **Content:** `[Access has been denied.]`
634

Sergej Naumenko's avatar
Sergej Naumenko committed
635 636
**Code:** 404 NOT FOUND  <br/>
   **Content:** `[Migrate request not found!]`
637 638
   

Johannes Metscher's avatar
Johannes Metscher committed
639 640 641 642 643 644 645 646
## 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.
647 648 649 650
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.
651 652 653 654 655
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?
656 657 658 659 660 661 662 663 664 665 666
  * 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.
667
14. Frage: Welche Schritte sind nun im Anschluss nötig, um im realen System zu arbeiten? Muss lediglich der Link der Schnittstelle angepasst werden?
Sergej Naumenko's avatar
Sergej Naumenko committed
668 669
  * Antwort: Die URL des Host / Service muss vom Demo-System auf das Live-System umgestellt werden.
  * Hinweis: Bitte überprüfen Sie im Zuge dessen auch die in Ihrem System hinterlegten IDs für DOSB-Lizenz Ausbildungsgänge und Verband inkl. Untergliederungen. In seltenen Fällen kann es zu unterschiedlichen Werten auf Live und Demo-System kommen.
670
15. Frage: Wie kann ich die Umlaute umwandeln?
671 672 673 674 675 676 677 678 679
  * Umlaute im Web-API-Aufruf müssen codiert werden, und zwar mit dem HEX-Wert der UTF8-Zeichentabelle.
  * Beispiele:
   * Ä -> %C3%84
   * Ö -> %C3%96
   * Ü -> %C3%9C
   * ä -> %C3%A4
   * ö -> %C3%B6
   * ü -> %C3%BC
  * Eine Beschreibung dazu finden Sie hier: http://www.andre-jochim.de/url-encode.htm
680 681 682
Die UFT8-Zeichentabele finden Sie hier: http://www.utf8-zeichentabelle.de/

Weitere FAQs und wichtige Infos https://bildungsnetz.dosb.de/schnellstart-lims-anbindung