<< Klicken Sie, um das Inhaltsverzeichnis anzuzeigen >> Navigation:  Technisches > EMIL Plattform API

Das EMIL Platform API ist eine HTTP/POST basierte Schnittstelle, die Fremdsystemen eine direkte Kommunikation mit dem EMIL-Applikationsserver ermöglicht. Die Funktionsreferenz finden Sie hier.

Beachten Sie unbedingt die Netzwerkhinweise unter Netzwerk, DMZ und Firewall wenn der Zugriff auf das EMIL-API von außerhalb des lokalen Netzwerks erfolgen soll!

Einstellungen dazu werden unter werden unter Administration|Schnittstellen unter dem Punkt EMIL Plattform API vorgenommen. Für diese Funktionen ist keine Plus-Funktionalität erforderlichten.

Für die Nutzung des API benötigt man ein für jedes Fremdsystem erstelltes und eindeutiges Token), das ausschließlich von ITC ausgestellt wird. Es ist nicht zu verwechseln mit dem Abfragetoken der der Query Schnittstelle (1)!. Anwendungen, die über das API andocken wollen, müssen zudem sicherheitshalber explizit vom EMIL-Administrator einmalig freigegeben werden um zu verhindern, dass unbemerkt andere Systeme auf EMIL zugreifen und Daten lesen, ändern oder hinzufügen.

Wichtiges zur Datenstruktur

Um sinnvoll mit der Query-Schnittstelle zu arbeiten, ist ein Verständnis der EMIL-Datenstrukturen sehr wichtig. Dies gilt gleichermaßen als Grundlage für die Nutzung der Abfrageschnittstelle und für das API für Softwareentwickler. Grundprinzip der Datenhaltung ist das Single Point of Truth Prinzip.

Datenbereiche

EMIL teilt die Daten in drei Datenbereiche ein.

•Stammdaten sind zusammen mit dem Patienten (Subject) in einer Tabelle gespeichert und haben vorwiegend informativen und identifizierenden Charakter. Beispiele sind Wohnort, Name, Telefonnummer

•Feste Daten sind Daten, die pro Patient nur einmal vorkommen. Sie haben deshalb auch kein Datum. Beispiele sind Anamnese, Geschlecht, Geburtsdatum, Krankenversicherung.

•Verlaufs- und Labordaten sind Daten, die pro Patient mehrfach vorkommen können. Dabei gilt, dass eine Information zu einem Patient und einem Zeitpunkt immer nur einmal existiert. Obwohl dies selbstverständlich klingt, erlauben viele andere Systeme, die selbe Information an verschiedenen Stellen zu speichern und erlauben damit widersprüchliche Datensituationen. Beispiele für Verlaufs- und Labordaten sind Bludruck, behandelnder Arzt, CRP, HbA1C.

Da sich feste Daten von den Verlaufs- und Labordaten nur insofern unterscheiden, dass sie kein Datum haben, werden sie technisch gemeinsam als Items betrachtet. Items in EMIL können verschiedene Datentypen beherbergen wie Zahlenwerte, Text, Listen, Datumsangaben und auch Formulare.

Formulare ermöglichen es, zu einem Item mehrere Detailinformationen zu speichern. Das Item WHO5 beispielsweise repräsentiert einen Score als Itemwert. Die Fragen, aus denen dieser Score berechnet wird, machen das Formular aus und werden technisch als Subitems betrachtet. Sie werden am Item in einer JSON Datenstruktur gespeichert. Für die Query-Schnittstelle werden diese Subitems in eine zusätzliche Tabelle ausgelagert, da Statistiksysteme erfahrungsgemäß mit JSON Werten in Tabellenspalten nicht gut umgehen können.

Für die Entwicklung allgemeingültiger Schnittstellen, die in ein Produkt integriert werden sollen, sollte als Referenzsystem eine aktuelle aber nicht mit eigenen Strukturen angepasste Version verwendet werden, damit man nur Strukturen referenziert, die verlässlich in allen Systemen vorhanden sind. Entwickelt man hingegen eine einrichtungsspezifische Schnittstelle, sollte dies natürlich gegen ein Entwicklungssystem geschehen, das die gleichen Datenstrukturen aufweist, um alle Daten referenzieren zu können.

Auditing

Alle über diese Schnittstelle geschriebenen Daten werden im EMILAudit-Trail protokolliert. Dazu wird für jedes API Token im System ein interner Benutzer angelegt, unter dem diese Änderungen im Audit-Trail ganz klar dem jeweiligen System zugeordnet werden können (1) - hier der Systemname API-Developing. Als Quellrechner wird immer der EMIL-Server angegeben (2).

Die bidirektionale Schnittstelle wird über den URL

https://<EMIL-Server>:8450/api

angesprochen. Wurde der EMIL-Serverport verändert, so gilt hier der gleiche Port, der für den Client festgelegt wurde. Er kann im Zweifelsfall aus der Datei CONFIG.INI im EMIL-Serververzeichnis entnommen werden. Anfragen werden als Multipart-Form gestellt und generieren entweder HTTP-Fehler oder eine JSON Antwort. Die Zeichenkodierung ist durchgängig UTF-8.

Die Anfrage benötigt immer zwei Felder im Multipart-Form:

•token -> Das von ITC zugeteilte Token (base64)

•payload -> Die Anfrage an den EMIL-Applikationsserver in JSON

Token

Das Token wird von ITC an den Hersteller ausgegeben. Die Token sind grundsätzlich ein Jahr gültig. Systeme, die das Token verwenden, sollten einen Updatemechanismus für das Token berücksichtigen. In jedem Fall wird das Token nur auf der Seite des andockenden Systems gebraucht. Es gibt drei verschiedene Tokenarten

•Entwicklertoken (Schutzgebühr).
Kann nur mit einer benannten EMIL-Instanz und einer fiktiven, von ITC zugeteilten BSNR betrieben werden.

•Kundentoken (Jährliche Lizenzkosten, für eigene Schnittstellenkreationen in einer Einrichtung).
Kann nur mit einer benannten EMIL-Instanz und einer realen BSNR betrieben werden.

•Systemtoken (Jährliche Lizenzkosten, für Systeme, die an beliebige EMIL-Instanzen andocken sollen).
Kann mit beliebig vielen unterschiedlichen EMIL-Instanzen betrieben werden. Ist für die Integration in Systeme gedacht, die dauerhaft mit EMIL kommunizieren.

Technische Fragen und Fragen zu Lizenzgebühren richten Sie bitte an service@itc-ms.de.

Payload

Alle relevanten Daten einer Anfrage an den EMIL-Applikationsserver sind in der payload JSON Struktur kodiert. Werden nicht benötigte Felder in der JSON Struktur angegeben, so werden diese ignoriert. Im Folgenden findet sich eine Spezifikation aller möglichen Anfragen jeweils mit einem Beispiel. Parameter wir Type-IDs etc. sind vor der Konstruktion einer Abfrage über die unter Referenzierung beschriebenen Methoden zu ermitteln. Sofern es sich nicht um kundenspezifische Items (Selbst angelegte Items, selbst definierte Studien) handelt, kann man sich dabei darauf verlassen, dass diese ID und Codes für alle EMIL-Instanzen durchgängig gleichermaßen gültig sind.

Die payload-Struktur sieht grundsätzlich so aus. Der request Parameter ist immer erforderlich, die anderen richten sich nach der Art der Anfrage, dort ist jeweils angegeben, ob ein Parameter optional oder erforderlich ist.

{ 

 "request": "getchanged",

 "fromdate": "2021-12-10T13:45:00.000Z",

 "enrolled": "1001,1002",

 "checkitems": "101,102,104"

}

Die Antwort auf diese Anfrage könnte so aussehen:

{ 

 "subjectids": "1,2,444,665,43,567,678,7,888,23123,33,4454,3322",

}

Ein weiteres Beispiel für die Aktualisierung eines Questionnaires, hier Versichertendaten (TypID 104) für Patient 33647 zum Zeitpunkt 10.12.2021:

{

    "request": "setitem",

    "subjectid": 33647,

    "refdate": "2021-12-10T00:00:00.000Z",

    "typeid": 104,

    "textvalue": "Techniker Krankenkasse",

    "questionnaire": {

        "cmbAccount": "00",

        "edIK": "101575519",

        "cmbInsurance": "101575519",

        "edInsNum": "M123456789",

        "edValidFrom": "",

        "edValidThru": "",

        "edWOP": "",

        "edInsKind": "",

        "edPersGrp": "",

        "edDMP": ""

    }

}

Alle Angaben innerhalb der Questionnaire-Struktur sind optional und können - wenn sie leer sein sollen - weggelassen werden. Wichtiger Hinweis: Es können immer nur gesamte Items überschrieben werden, da diese immer einen Itemzustand repräsentieren und dieser Stand mit dem Autor im Audittrail protokolliert wird. Um ein einzelnes Subitem, z.B. die Versichertenart im KV-Questionnaire zu aktualisieren, muss der aktuelle Inhalt zunächst gelesen werden, die Information im gelieferten JSON aktualisiert und das Item wieder zurückgeschrieben werden.

 

Zeitzone von Datums- und Zeitangaben

Das EMIL Plattform-API erwartet und überträgt alle Datums- und Zeitangaben in der lokalen Zeitzone, da davon auszugehen ist, dass beide Systeme immer in der gleichen Zeitzone betrieben werden.

Aus dem 5.7.2019 12:15 Uhr wird also "2019-07-05T12:15:00.0Z" und umgekehrt.

 

Funktionsreferenz

Die Funktionsreferenz des API finden Sie unter Technisches/API Funktionsreferenz.

 

Fehlerbehandlung

Grundsätzlich werden alle Anfragen verarbeitet und mit dem HTTP Ergebniscode 200 quittiert. Tritt dabei ein Fehler auf, wird eine Nachricht in form eines JSON Objekts zurückgeliefert. Nur dann, wenn der Fehler eine Antwort des Applikationsservers verhindert, wird HTTP Fehler 500 geliefert. In diesem Fall kann die Ursache des Fehlers im EMIL-Applikationsserverprotokoll nachgesehen werden. Übliche Fehler führen zu dieser zu einer gültigen JSON Struktur mit Informationen über den Fehler:

{

  "errorcode": 1011,

  "errordetails": "lastname exeeds length (max 69)"

}

Errorcode ist einer der Codes in der folgenden Tabelle. Bei manchen Codes werden Details zur Eingrenzung des Fehlers im Feld errordetails geliefert. Errordetails ist nur vorhanden, wenn es einen Inhalt hat.