Sie sind hier

Schnellstart der LiMS-Anbindung an Ihr Verbandssystem

Herzlich willkommen!

 

Sie sind nicht an einer Anbindung Ihres eigenen Systems interessiert, sondern wollen das DOSB-Lizenzmanagementsystem (LiMS) als Verwaltungssystem nutzen? Dann finden Sie die wichtigsten Dokumente und hilfreiche Screencasts hier.

Nachfolgend möchten wir Sie ausführlich darüber informieren, wie eine Anbindung an LiMS funktioniert, was man für das eigene System im Vorfeld bedenken muss, wie man Zugang zum Testsystem erhält etc. 

 

Einen ersten Einblick dazu, wie eine Anbindung Ihres verbandsinternen Verwaltungssystems an LiMS technisch vonstattengeht, finden Sie im neuen Webinar-Mitschnitt zum Vorgehen bei der Anbindung und Freischaltung der Schnittstelle. In der Online-Dokumentation http://www.ghostthinker.de/lims_connect/docu finden Sie stets die aktuellsten technischen Informationen.

 

 

Die häufigsten Fragen pflegt unser Team kontinuierlich im engen Austausch mit dem DOSB.

 

Bitte wenden Sie sich bei Rückfragen und Anmerkungen schriftlich an die E-Mail-Adresse support@bildungsnetz.dosb.de. Hier ist das gesamte DOSB-Wissensnetz-Team für Sie da und unterstützt Sie gerne bei der Anbindung Ihres verbandseigenen IT-Systems an das DOSB-Lizenzmanagementsystem (LiMS). Bitte haben Sie dafür Verständnis, dass unser Team aktuell nicht per Telefon verfügbar ist. Für den direkten Austausch bieten wir jedoch immer wieder Webinare an.

 

Erster Schritt: Zugang

Um Lizenzdaten über die Schnittstelle mit LiMS austauschen zu können benötigen Sie einen API-Zugang.

Diesen API-Zugang beantragt man im Live-System in der Organisation über den Button API-Zugang anfordern. Der Nutzer erhält eine Email zur Registrierung auf dem Live-System, hat dort aber noch keine API-Rechte (diese werden erst nach Freigabe des Abnahmeprotokolls freigeschaltet). Außerdem erhält er eine Einladung in die Gruppe „Wissensnetz - Tester (LiMS API User)“, diese bitte annehmen. Dort können Sie sich mit anderen Benutzern, die gerade eine Schnittstelle programmieren, austauschen.


Für alle User, die in der besagten Gruppe sind erfolgt eine automatische Kopie des Accounts ins Demo-System (mit gleichem Passwort etc.) inkl. API Rechte. Dort kann der Verband seine Schnittstelle dann ausprobieren und entwickeln.

 

 

Zweiter Schritt: Vorbereitung

Bitte arbeiten Sie sich als nächsten das Konzept der Schnittstelle in Verbindung mit der Architektur Ihres eigenen Systems ein. Alle notwendigen Details, wie z.B. Felddefinitionen, Anfragen und mehr finden Sie unter http://www.ghostthinker.de/lims_connect/docu.

 

Die für Ihren Verband relevanten IDs (training_course_id & organisation_id) können über die Web-Oberfläche des Wissensnetzes abgerufen werden. Loggen Sie sich dazu bitte auf (https://demo-dosb.wissensnetz.eu/) ein und klicken rechts oben auf Ihr Profil und anschließend auf den rot hinterlegten Namen Ihrer Organisation. Auf der nun erscheinenden Organisationsseite finden sie im orangenen Menü rechts die Button “Mitgliedsorganisationen IDs” und “Ausbildungsgänge IDs” zum Herunterladen der IDs.

https://www.youtube.com/watch?v=qTZkWNth7x8

 

 

Dritter Schritt: Ausprobieren 

Bevor Sie mit der technischen Umsetzung der Anbindung von LiMS an Ihr bestehendes Verbandssystem beginnen, empfehlen wir Ihnen dringend die wichtigsten Szenarien exemplarisch mit einigen Beispiellizenzen Ihrer Datenbasis durchzuspielen. Dafür haben wir für Sie unter https://lims.ghostthinker.de/ eine Art “Spielwiese” eingerichtet.

 

Probieren Sie jede Anfrage an LiMS (z.B. Request, Download) mehrfach aus. Gerne können Sie auch schon die im kommenden Schritt beschriebenen Szenarien im Hinterkopf haben und diese ausprobieren.

 

 

Vierter Schritt: Anbindung

In diesem Schritt finden die wichtigsten Entwicklungsarbeiten bei Ihnen statt. D.h. die Abbildung der zusätzlichen Datenfelder (Datenbank) und auch die Programmierung der Schnittstelle in Ihrem Verwaltungssystem selbst. Für Letzteres finden Sie unter https://gitlab.ghostthinker.de/pub/lims_connect/tree/master/ eine wachsenden Anzahl an Referenzimplentierung in verschiedenen Programmiersprachen und Technologien.

 

Wir haben für Sie die unten stehenden Szenarien für den Einsatz der Schnittstelle für Sie zusammengetragen. Bitte beachten Sie diese auch bei der technischen Umsetzung und anschließendem Testen der Anbindung.

 

Szenario I: Neuanlegen eines Lizenzinhabers und Erstausstellung einer Lizenz (Anfordern des Lizenz-PDFs)
Szenario II: Ändern von (Adress- oder sonstigen) Daten und Anfordern des aktualisierten Lizenz-PDFs
Szenario III: Bestandsimport (Import von (mehreren) Lizenzinhaberdaten und Abrufen der DOSB-Lizenznummer - kein PDF!)
Szenario IV: Verlängern einer bestehender Lizenz und Anfordern des aktualisierten Lizenz-PDFs
Szenario V: Löschen eines Lizenzdatensatzes (Verfügbar seit Juni 2017)

 

Wenn die Logik der Schnittstelle entsprechend programmiert wurde, sollten Sie die Funktionen (zusammen mit einem Verbandsvertreter) ausgiebig testen.

 

 

Fünfter Schritt: Produktive Nutzung

Wenn Sie die Schnittstelle fertig programmiert und ausgiebig getestet haben (d.h. alle oben genannten Szenarien lassen sich reibungslos durchführen!), kann Sie an das Live-System angeschlossen werden. Dazu müssen Sie bei Ihrem produktiven Verwaltungssystem

  • Die Zieladresse (Endpunkt) der Schnittstelle von https://demo-dosb.wissensnetz.eu/ auf https://wissensnetz.dosb.de/ setzen
  • die IDs (siehe 2.Schritt) sicherheitshalber noch einmal abgleichen (in seltenen Fällen kann es durch Überarbeitungen/ Ergänzungen zwischen Demo- und Live-System zu unterschiedlichen IDs kommen!)
  • Die API-Freischaltung für Ihr Benutzerprofil auf dem Live-System beantragen. Bitte bestätigen Sie dem DOSB schriftlich Ihre gewissenhafte Umsetzung der Anbindung mit diesem Abnahmeprotokoll. Senden Sie das vollständig ausgefüllte und unterzeichnete Formular an support@bildungsnetz.dosb.de).

 

Vor der produktiven Nutzung von LiMS über die Schnittstelle müssen auf dem Live-System außerdem einige Grundeinstellungen für den jeweiligen Verband getroffen werden. Dazu zählen u.a.:

  • Entscheidung für/ gegen die Datenhaltung auf LiMS
  • Hochladen von Verbandslogo und Unterschrift für die Lizenzen
  • Wenn Landesfachverbände über die gleiche Schnittstelle arbeiten sollen: Freischaltung der Einsicht und Bearbeitung der Lizenzdaten durch den Dachverband bzw. das Konto des API-Benutzers

Für weitere Informationen und Unterstützung sollte sich ein Verbandsvertreter mit Jonas Heck im DOSB (heck@dosb.de) in Verbindung setzen.

 

 

 

FAQs

In welcher Art unterstützt der DOSB die Organisation bzgl. des neuen Lizenzmanagementsystems?
Die Verbände, die das neue DOSB-Lizenzmanagementsystem als Verwaltungsprogramm nutzen möchten, erhalten vom DOSB eine Systemeinführung/-vorstellung und werden beim Datenimport online begleitet. Im Anschluss erhalten Sie ein Handbuch, in welchem die Funktionen noch einmal beschrieben und Prozesse erklärt werden.
Verbände, die eine Schnittstelle programmieren möchten, benötigen einen eigenen internen oder externen IT-Spezialisten. Für aufkommende technische Fragen oder spezielle Betreuung steht Ihnen die Ghostthinker GmbH (support@bildungsnetz.dosb.de) zur Verfügung.

Wer bezahlt die Schnittstellen und neuen Programmierungen?
Die Kosten für die grundlegenden Arbeiten der Datenbank-Erstellung werden selbstverständlich vom DOSB getragen. Auch stellen wir die Standard-Schnittstelle zur Datenübertragung sowie den Support durch unsere Programmierer kostenfrei zur Verfügung. Die Kosten für eine gezielte Anbindung der einzelnen unterschiedlichsten Softwarelösungen in den Verbänden können wir leider nicht übernehmen.

Steht uns ein Testsystem zur Verfügung, über das wir Programmerweiterungen (bei unserem Programm) testen können?
Ja. Das Demo-System des Wissensnetzes findet sich unter https://demo-dosb.wissensnetz.eu. Zur Beantragung eines Zugangs mit Schnittstellenzugriff schreiben Sie bitte an support@bildungsnetz.dosb.de

Gibt es für die API ein Anfrage Limit? Hintergrund: wir betreuen mehrere Verbände und demnach könnten auch viele Anfragen entstehen.
Es gibt keine Limitierung der Anfragen über die Schnittstelle / API - jedoch kann es bei einer sehr großen Anzahl an Anfragen in sehr kurzer Zeit zu einer Sperrung durch die Firewall und Sicherheitsvorkehrungen des Servers kommen. Bisher ist hier jedoch noch kein Fall bekannt.

Gibt es Beispielskripte in PHP für den Zugriff auf die API?
Ja. Das Beispielskript finden Sie unter https://gitlab.ghostthinker.de/gt/lims_connect/tree/master/php_sample_client.

Erhalten wir die detaillierte API Schnittstellenbeschreibung auch per E-Mail? Insbesondere bei Änderungen der Schnittstelle?
Nein. Aber Sie können unter https://gitlab.ghostthinker.de/gt/lims_connect/commits/master die Änderung über einen Newsfeed abonnieren und natürlich auch Projekt-Updates via Git einsehen.

Wie werden neue Versionen angekündigt? Und wie lange vorher? Wie läuft das Versionsmanagement?
In Absprache mit dem DOSB wird Ghostthinker eine Roadmap auf https://gitlab.ghostthinker.de/gt/lims_connect veröffentlichen. Diese ist dann für mind. 2 Monate bindend. Alle Änderungen an der Schnittstelle selbst, der Dokumentation und den Beispielskripten werden mit der Versionskontrolle GIT erfasst und verwaltet und können somit gut nachvollzogen werden.

Mit dem API-Zugang kann ich mir die Organisations_IDs und Ausbildungsgang_IDs herunterladen. Wozu brauche ich diese?
Die IDs müssen in Ihrem System hinterlegt werden, damit unser System weiß für welchen Verband und für welche Ausbildung eine Lizenz abgerufen wird.
Hinweis: vor der finalen Anbindung müssen die im Wissensnetz im Profil des jeweiligen Verbandes hinterlegten Ausbildungsgänge nochmal abgestimmt und ggf. korrigiert werden.

Brauche ich als LSB oder SV, der für seine LFV Lizenzen ausstellt, ein zusätzliches Feld für den Verband der Lizenz?

Wenn Ihr Verband nur seine eigenen Lizenzen pflegt reicht die Definition eines fixen Wertes in der Schnittstelle. Wenn Sie Lizenzen für Landesfachverbände ausstellen, müssen Sie in Ihrem System auch die ID des jeweiligen ausstellenden Verbandes (=organisation_id, siehe technische Dokumentation) hinterlegen, damit auf der Lizenz auch der entsprechende Absender abgedruckt wird, ja.

In meinem verbandseigenen System gibt es einen Personen-Stammdatensatz, in dem ggf. mehrere Lizenzen hinterlegt sind. Wie wird dies übertragen?
Das DOSB-Lizenzmanagementsystem vergibt pro Lizenz (nicht Lizenzinhaber!) eine eigene Lizenznummer. Die Vergabe erfolgt automatisch beim Bestandsdatenimport. Es muss bei der Schnittstellenprogrammierung sichergestellt werden, dass pro Lizenz einmal der Datensatz der Personen-Stammdaten mit überspielt wird. Des Weiteren benötigt Ihr System pro Lizenz ein zusätzliches Freifeld für den Rückfluss der DOSB-Lizenznummer.

Muss ich meine ca. 2000 Lizenzen manuell importieren?
Nein. Beim Einsatz der Schnittstelle übernimmt genau diesen Import Ihr verbandseigenes System im Austausch mit der Schnittstelle von LiMS. Dabei wird dem REST Paradigma folgend zwischen den beiden Systemen immer nur über eine Lizenz gesprochen. Dadurch ist eine Validierung und aussagekräftige Rückmeldung möglich. Bitte beachten Sie, dass eine Mehrfachanforderung von Lizenzen durch Ihr eigenes System umgesetzt werden muss. Dies sollte also bei der Entwicklung der Anbindung entsprechend mitgedacht werden (z.B. über Häkchen setzen, so dass X Lizenzen automatisch hintereinander übertragen werden).

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?

Dies können Sie sehr gerne über einen initialen Bestandsimport (hier ist das Erstausstellungsdatum = first_issue_date mit anzugeben) vornehmen. Dann erhalten Sie zu jeder Lizenz automatisch eine DOSB-Lizenznummer.

Was mache ich, wenn für den Bestandsdatenimport einzelne Datenfelder fehlen bzw. unvollständig sind?
Alle obligatorischen Datenfelder müssen gefüllt sein, sonst erhalten Sie beim Bestandsdatenimport eine Fehlermeldung. Bei fehlenden Daten arbeiten wir mit sog. Dummy-Daten, die dann mit der nächsten Verlängerung korrigiert werden. Eine entsprechende Anleitung, wie die Dummy-Daten einzusetzen sind, erhalten Sie hier

Bei Neuanlage einer Lizenz hat das issue_date den gleichen Wert, wie das first_issue_date. Welches Feld muss wann mit übergeben werden?

Bei Neuausstellung einer Lizenz darf nur das Ausstellungsdatum = issue_date angegeben werden. Das first_issue_date wird ausschließlich für den Bestandsimport benötigt.
Hinweis: Beim Bestandsdatenimport greift eine andere Validierung der Gültigkeitszeiträume als bei einer Neuanlage. Bereits ausgegebene Lizenzen sollten daher unbedingt per Bestandsdatenimport und nicht als Neuanlage eingespielt werden!

Welche Gültigkeits-Regelungen gelten für Lizenz-Neuausstellungen?
Neue Lizenzen haben eine maximale Gültigkeit von 4 bzw. 2 Jahren. D.h. eine C-Lizenz, die am 23.02.2016 ausgestellt wird, hat eine max. Gültigkeit bis 22.02.2020. Ein kürzerer Gültigkeitszeitraum (z.B. 31.12.2019) ist aber auch immer möglich.

Welche Gültigkeits-Regelungen gelten für Lizenz-Verlängerungen?
Lizenzen können zu jeder Zeit verlängert werden. Das max. Gültigkeitsdatum errechnet sich wieder anhand des neuen Ausstellungsdatums.
Hinweis: ausschließlich bei einer Verlängerung kann das max. Gültigkeitsdatum noch bis auf Ende des laufenden Quartals hochgesetzt werden (Bsp.: Verlängerung am 15.02.2017 -> max. neue Gültigkeit bis 31.03.2021). Damit ermöglichen wir, dass Lizenzen, die bspw. zum 31.12. ablaufen, bereits vor Ablauf auch wieder bis zum Stichtag 31.12. verlängert werden können.

Werden Falscheingaben (unplausible Zeiträume) bei der Gültigkeit der Lizenz vom System gefiltert?

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.

Kann ich mir die Lizenz auch über die Schnittstelle holen? Als einzelne PDFs oder als Stapel?
Durch Übermittlung der DOSB-Lizenznummer mit dem Befehl „download“ erhalten Sie das entsprechende PDF Dokument zurückgeliefert (siehe technische Dokumentation). Eine Mehrfachanforderung von Lizenzen ist möglich (automatisiert einzeln hintereinander), wenn dies entsprechend bei der Schnittstellenprogrammierung der verbandseigenen Systeme mitgedacht wird. Sie erhalten dann pro Lizenz eine einzelne PDF Datei. Diese wird in Ihrem System hinterlegt.

Gibt es Pläne, auch die Anlage der Lehrgänge per Schnittstelle aus der eigenen Lehrgangsverwaltung zu ermöglichen?
Die Hauptfunktionalität unseres Systems besteht darin die Lizenzen fertig generiert zum Ausdruck am eigenen Drucker zu erhalten. Die Option Lehrgänge anzulegen ist für Verbände ohne eigenes Verwaltungssystem hilfreich. Verbände, die mit einer eigenen Verwaltungssoftware arbeiten und darüber ihre Lehrgangsverwaltung machen, benötigen diese Funktion nicht. Sie fordern am Ende eines Lehrgangs über die Schnittstelle lediglich die Lizenzen an. Also nein, diese Pläne gibt es (bislang) nicht, da wir darin keinen Mehrwert sehen.

Kann ich Lizenzverlängerung nur pro Teilnehmer oder ganze Veranstaltungen komplett übertragen?
Die Lizenzverlängerung erfolgt in unserem System unabhängig von Veranstaltungen/Lehrgängen. Eine Mehrfachanforderung von Lizenzen ist möglich (automatisiert einzeln hintereinander), wenn dies entsprechend bei der Schnittstellenprogrammierung der verbandseigenen Systeme mitgedacht wird.

Laut Rahmenrichtlinien führt eine Verlängerung der oberen Lizenzstufe zu einer automatischen Mitverlängerung der darunterliegenden Lizenz. Wie wird das abgebildet?
Über das Online-System können Lizenzen manuell verknüpft werden, so dass durch eine Verlängerung der oberen Lizenz automatisch auch die untere mitverlängert wird. Über die Schnittstelle kann dies jedoch nicht abgebildet werden.
Die neuen Gültigkeiten müssen in diesem Fall für beide (alle) Lizenzen in Ihrem verbandseigenen System eingegeben und an unser System übertragen werden.

Ist es möglich, dass verbandseigene Systeme (z.B. eines LSBs) auch Lizenzinformationen aus dem DOSB-System beziehen?
Ein Abruf der Lizenzdaten aus unserem System über die Schnittstelle ist bislang noch nicht möglich. Wir haben es jedoch in der Planung für die weitere Entwicklung. Vor Mitte 2017 wird dies jedoch noch nicht umgesetzt sein.

Kann eine Lizenz auch per Schnittstelle gelöscht werden?

Ja. Weitere Infos dazu finden Sie in der technischen Beschreibung der schnittstelle.

Können meine Lizenzdaten nach Abschluss der Testphase aus dem Demo-System wieder entfernt werden?

Ja, das Demo-System wird regelmäßig wieder zurückgesetzt und damit die Beispieldaten automatisch verworfen.

Welche Schritte sind nun im Anschluss nötig, um im realen System zu arbeiten? Muss lediglich der Link der Schnittstelle angepasst werden?

Sie müssen lediglich die URL des Host / Service von Demo auf Live (https://wissensnetz.dosb.de/) umstellen und über support@bildungsnetz.dosb.de Ihr Benutzerkonto auf dem Live-System für die API-Nutzung freischalten lassen.

Was ist unter dem letzten Punkt auf der Checkliste "Konsistenzprüfung der Daten im eigenen System" zu verstehen?

Die Idee dahinter ist, dass bei der Nutzung der Schnittstelle inbs. beim Anlegen von Lizenzen überprüft wird ob alle Daten die Ihr nach LiMS gegeben habt auch dort korrekt ankommen. Praktisch kann die Konsistenzprüfung im Rahmen des Abnahmeprotokolls manuell (exemplarische) Lizenzen werde von Euch überprüft oder automatisiert (angelegt Lizenz wird via load abgefragt und dann direkt von Eurem System mit der dort hinterlegten Lizenz abgeglichen) erfolgen. Es reicht also, wenn Ihr im Protokoll vermerkt welche der beiden Varianten Ihr genutzt habt. In jedem Fall ist die Überprüfung wichtig!