API Funktionsreferenz

<< Klicken Sie, um das Inhaltsverzeichnis anzuzeigen >>

Navigation:  Technisches >

API Funktionsreferenz

Versionen und Historie abfragen - getversion

Sowohl EMIL als auch das EMIL-Plattform-API unterliegen einer stringenten Versionskontrolle. Da sich nicht mit jeder neuen EMIL-Version diese Schnittstelle verändert, haben wir für das API eine gesonderte Versionsführung etabliert. Versionen sind grundsätzlich abwärtskompatibel, sodass sicher gestellt ist, dass Systeme, die auf eine ältere API-Version aufsetzen, garantiert mit neueren API Versionen auch arbeiten können.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

getversion

X

Rückgabe:

Parameter

Datentyp

Inhalt

progversion

Text

Aktuelle EMIL-Version, z.B. "3.39.04"

apiversion

Text

Aktuelle API Version, wird getrennt nur bei Änderungen am API selbst  verändert, z.B. "1.3"

apihistory

Array of Text

Versionshistorie, z.B.
[

   "1.0 Initial release",

   "1.1 Added getvisits",

   "1.2 Fixed setitem",

   "1.3 Added getversion"

 ]

 

Übersetzung von IDs - convertid

Grundsätzlich erfolgt die sichere und eindeutige Identifikation einer Patientenakte in EMIL über die SUBJECT-ID, die in EMIL der Primärschlüssel der Patiententabelle ist. EMIL führt aber für Schnittstellen noch weitere IDs. Diese Funktion dient dazu, eine Fremdsystem-ID in eine EMIL-ID oder umgekehrt zu konvertieren.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

convertid

X

input

Text

Zu konvertierende ID

X

conversiontype

Integer

Durchzuführende Konvertierung:

1 = EMIL-ID zu EMIL-PVS-ID

2 = EMIL-PVS-ID zuEMIL-ID

3 = EMIL-ID zu EMIL-KIS-ID

4 = EMIL-KIS-ID zu EMIL-ID

5 = EMIL-ID zu EMIL-DMP-ID

6 = EMIL-DMP-ID zu EMIL-ID

Es die IDs sind in EMIL als Attribute hinterlegt und können unter Umständen für einen Patienten verändert werden, beispielsweise durch die Korrektur einer vorherigen Fehlzuordnung.

X

Rückgabe:

Parameter

Datentyp

Inhalt

id

Text

Konvertierte ID. Wird nichts gefunden, wird ein leerer String zurückgegeben.

 

Neue bzw. geänderte Patientenakten seit - getchanged

Diese Funktion ermittelt Patienten, bei denen Stammdaten und/oder mindestens eins der angegebenen Items seit dem angegebenen Datum verändert wurden. Sie kann gut für regelmäßige Synchronisationen verwendet werden, um nur die Änderungen seit der letzten Abfrage zu ermitteln.

Bitte beachten Sie, dass diese Abfrage komplex ist und Last erzeugt, insbesondere, wenn items abgefragt werden, da dies über den EMIL-Audittrail geschieht. Sie ist nicht dafür geeignet, in Dauerschleife in kurzen Abständen aufgerufen zu werden.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

getchanged

X

fromdate

Timestamp

Zeitstempel

X

checkitems

Text

Komma separierte Liste der Items, den neben den Stammdaten auf Änderungen überprüft werden sollen. Wenn alle geprüft werden sollen, ist statt dessen all anzugeben. Sollen nur Stammdaten geprüft werden, kann der Parameter leer sein oder weggelassen werden.


enrolled

Text

Komma separierte Liste der Studien-IDs, in zu selektierende Patienten eingeschlossen sein müssen. Wenn leer, erfolgt keine Filterung.

Hilfreich für die Selektion z.B. von Mitgliedern in bestimmten Versorgungsverträgen. Ermitteln der Studien-IDs siehe Referenzierung.


consented

Text

Komma separierte Liste der Studien-IDs, in den zu selektierende Patienten ihren Consent gegeben haben müssen. Wenn leer, erfolgt keine Filterung.


Rückgabe:

Parameter

Datentyp

Inhalt

subjectids

Text

Komma separierte Liste der EMIL-Subject-IDs. Wird nichts gefunden, wird ein leerer String zurückgegeben.

 

Existenz eines Patienten über Name/Geburtsdatum erfragen - getsubject

Diese Funktion ermittelt, ob in EMIL ein oder mehrere Patienten mit dem angegebenen Vor- und Nachnamen und dem angegebenen Geburtsdatum existieren. Der Namensvergleich erfolgt ohne Beachtung von Groß- und Kleinschreibung, bei der Datumsangabe wird nur Jahr, Monat und Tag verglichen, eine Zeitangabe wird weggerundet.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

getsubject

X

firstname

Text

Vorname

X

lastname

Text

Nachname

X

birthdate

Timestamp

Geburtsdatum (ohne Zeit)

X

Rückgabe:

Parameter

Datentyp

Inhalt

subjectid

Text

Komma separierte Liste der EMIL-Subject-IDs. In aller Regel wird nur einer gefunden. Wird keiner gefunden, wird ein leerer String zurückgegeben.

 

Patienten über Name/Geburtsdatum anlegen - createsubject

Diese Funktion legt einen Patienten an. Wenn bereits ein oder mehrere passende existieren, werden deren IDs zurückgeliefert, sonst die des neu angelegten Patienten. Der Namensvergleich erfolgt ohne Beachtung von Groß- und Kleinschreibung, bei der Datumsangabe wird nur Jahr, Monat und Tag verglichen, eine Zeitangabe wird weggerundet.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

createsubject

X

firstname

Text

Vorname

X

lastname

Text

Nachname

X

birthdate

Timestamp

Geburtsdatum (ohne Zeit)

X

Rückgabe:

Parameter

Datentyp

Inhalt

subjectid

Text

Komma separierte Liste der EMIL-Subject-IDs. Existiert der Patient noch nicht, wird er angelegt und die neue ID zurückgeliefert.

 

Stammdaten zu einem Patienten abfragen - getsubjectdata

Diese Funktion fragt die Stammdaten zu einem Patienten ab.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

getsubjectdata

X

subjectid

int64

EMIL Patientennummer.

X

Rückgabe:

Parameter

Datentyp

Inhalt

enrolled

Text

Komma separierte Liste der Studien-IDs, in die der Patient eingeschlossen ist

consented

Text

Komma separierte Liste der Studien-IDs, in die der Patient seinen Consent gegeben hat.

kis_ident

Text

Kliniksystem-ID

pvs_ident

Text

Praxissystem-ID

dmp_ident

Text

DMP-Identifikation

country

Text

Land

title

Text

Akademischer Titel

name_header

Text

Namensvorsatz

firstname

Text

Vorname

name_add

Text

Namenszusatz

lastname

Text

Nachname

maidenname

Text

Geburtsname

street

Text

Straße

address_country_code

Text

Wohnsitzländercode

zip

Text

Postleitzahl

city

Text

Stadt

address_add

Text

Zusatzangabe zur Adresse

work

Text

Arbeitsplatz

job

Text

Beruf

email

Text

Email-Adresse

phone

Text

Telefon

phone_work

Text

Telefon am Arbeitsplatz

vip_flag

Boolean

Patient ist VIP

relatives

Text

Angehörige

 

Stammdaten zu einem Patienten aktualisieren - setsubjectdata

Diese Funktion aktualisiert die Stammdaten zu einem Patienten. Es sind nur die zu aktualisierenden Felder anzugeben. Eine Aktualisierung für einen nicht existenten Patienten verursacht keinen Fehler, sondern wird ignoriert. Werden Felder mit NULL oder Leerstring angegeben, wird deren Inhalt gelöscht, sollen Felder unverändert bleiben, sind diese in der Anfrage nicht anzugeben.

Anfrage:

Parameter

Datentyp

Maximale Länge

Inhalt

Pflicht

request

Text

n/a

setsubjectdata

X

subjectid

int64

n/a

EMIL Patientennummer.

X

country

Text

10

Land (Code, z.B. DE für Deutschland)


title

Text

30

Akademischer Titel, z.B. Prof. Dr.


name_header

Text

40

Namensvorsatz, z.B. Gräfin


firstname

Text

70

Vorname, z.B. Hermione


name_add

Text

70

Namenszusatz, z.B. von und zu


lastname

Text

70

Nachname, z.B. Granger


maidenname

Text

70

Geburtsname, z.B. Flötzinger


street

Text

70

Straße


address_country_code

Text

10

Wohnsitzländercode


zip

Text

20

Postleitzahl


city

Text

70

Stadt


address_add

Text

120

Zusatzangabe zur Adresse


work

Text

70

Arbeitsplatz


job

Text

70

Beruf


email

Text

70

Email-Adresse


phone

Text

70

Telefon


phone_work

Text

70

Telefon am Arbeitsplatz


relatives

Text

1024

Angehörige


Rückgabe:

keine

Visits eines Patienten abfragen - getvisits

Diese Funktion fragt alle Visits zu einem Patienten aus einem Bereich ([V]erlauf/[L]abor) ab und gibt ein Array der Referenz-Zeitstempel zurück.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

getvisits

X

subjectid

int64

EMIL Patientennummer.

X

area

char

L für Labor, V für Verlauf

X

Rückgabe:

Parameter

Datentyp

Inhalt

visits

Array of timestamp

Zeitstempel der Visits des Patienten aufsteigend sortiert.

Dictionary Typen abfragen - gettypes

Diese Funktion fragt alle Visits zu einem Patienten aus einem Bereich ([V]erlauf/[L]abor) ab und gibt ein Array der Referenz-Zeitstempel zurück.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

gettypes

X

subjectid

int64

Type-ID, wenn nicht übergeben, werden alle Dictionary Items ausgegeben


Rückgabe:

Parameter

Datentyp

Inhalt

types

Array of objects

Die zurückgegebenen Typen werden als Objekte in diesem Array zurückgegeben.

Items in array types:

Parameter

Datentyp

Inhalt

typeid

int64

interne ID des Dictionary Items

title

Text

Name des Items, wie er in der Akte angezeigt wird

longtitle

Text

Langname bei manchen Types

kind

Text

Art des Datenfeldes:

number: Zahl

calc: Berechnetes Feld (nicht überschreibbar)

calcform: Berechneter Questionnaire

date: genaues Datum dd.mm.yyyy

datefuzm: Datum dd.mm.yyyy oder mm.yyyy

datefuz: Datum dd.mm.yyyy, mm.yyyyy oder yyyy

form: Formular(Questionnaire)

slist: Einzelauswahlliste

mlist: Mehrfachauswahl-Liste

text: Freitext

textdiag: Freitext mit Diagnosenerweiterung im Dialog

textcure: Freitext mit Heilmittelerweiterung im Dialog

textsupply: Freitext mit Hilfsmittelerweiterung im Dialog

textline: Einzeilige Texteingabe

textdrug: Freitext mit Medikationserweiterung im Dialog, ggf. Tabelle mit #200 Zeichen abgetrennt

custform: Kundenspezifisches Formular/Questionnaire

custhform: Kundenspezifisches Formular/Questionnaire als Liste

decimals

integer

Anzahl Dezimalstellen bei numerischen Angaben. Für die Anzeige, bei berechneten Feldern wird auf diese Nachkommastellenzahl gerundet.

units

Text

Unterstützte Einheiten als Komma separierte Liste

area

Char

Bereich des Datentyps: Labor/Verlauf haben immer ein Refdate, Feste Daten nicht.

coding

Text

Komma separierte Liste der decodes/codes in der Form

decode1: $code1,decode2: $code2, ... ,decoden: $coden

Datenitem zu einem Patienten abfragen - getitem

Diese Funktion fragt den Wert eines Item zu einem bestimmten Datum an. Felder, die zum jeweiligen Datettypen nicht passen, sind in der JSON Struktur nicht vorhanden.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

getitem

X

subjectid

int64

EMIL Patientennummer. Diese kann manuell im System ermittelt sein oder aus den Rückgabewerten der Methoden createsubject/getsubject.

X

refdate

Timestamp

Referenzdatum, optional mit Zeit, da Visits in EMIL auch einen Zeitpunkt tragen können.

Nur bei Verlauf- und Laboritems

tolerance

integer

Wenn hier ein Wert x <> 0 angegeben wird, sucht EMIL im Bereich +/- x Tage um das Referenzdatum herum den dichtesten Wert

Nur bei Verlauf- und Laboritems

typeid

int64

ID des gesuchten Items, siehe Referenzierung.

X

Rückgabe:

Parameter

Datentyp

Inhalt

textvalue

Text

Anzeigewert des Items wie in EMIL. Bei unscharfen Zeitpunkten (z.B. 2000 oder 5.2022) oder Zahlenbereichen (z.B. 4-8 oder <5) ist dieser Wert auszuwerten. Entfällt nur, wenn kein Satz gefunden wurde.

refdate

Timestamp

Refdate ist immer das Der Visitzeitpunkt des zurückgelieferten Items.

Wenn eine Toleranz im Parameter tolerance angegeben wurde, kann es sein, dass das gelieferte Item nicht genau vom gesuchten Zeitpunkt stammt.  Dies ist hilfreich, wenn ein vorhandener Wert wieder über setitem aktualisiert werden soll. Entfällt, wenn kein Satz gefunden wurde.

coded

Text

Bei kodierten Items die Kette der Codes, eingerahmt in $-Zeichen als Trenn und Begrenzungszeichn. Überführung der Codes in Decodes und umgekehrt  siehe Referenzierung. Entfällt bei nicht kodierten Items.

numvalue

Float

Numerischer Wert bei Zahlenwerten, wenn dieses einen definierten Wert hat. Entfällt bei nicht numerischen Items und auch dann, wenn ein numerisches Item z.B. den Wert "<5" hat.

unit

Text

Die in EMIL für den Zahlenwert eingestellte Einheit.  Entfällt, wenn keine Einheit definiert.

datetime

Timestamp

Datumsangabe, wenn es sich um ein definiertes Zeititem handelt. Entfällt bei nicht Zeitangaben und auch, wenn diese keinen tagesgenauen Zeitpunkt definieren wie z.B. 2000 oder 5.2022.

questionnaire

Text

JSON Struktur bei Questionnaires. Dies ist wieder eine eigene JSON Struktur. Hinweise dazu und zum Auslesen der einzelnen Questionnaire-Elemente siehe Referenzierung. Entfällt bei nicht Questionnaires.

 

Datenitem zu einem Patienten anlegen - setitem

Diese Funktion legt ein Item zu einem Patienten an. Wenn zum angegebenen Zeitpunkt bereits eines existiert, wird es mit dem neuen Wert überschrieben. Die Anlage/Änderung wird im Audittrail mit dem über das Token definierte System vermerkt. Berechnete Werte wie z.B. BMI oder solche, für die in EMIL eine Formel hinterlegt ist, können nicht überschrieben werden. Der Versuch, ein solches Item zu überschreiben, erzeugt einen Fehler.

Bitte beachten Sie, dass das Einfügen von Daten über diese Funktion, die Berechnungsgrundlage für Scores oder Formeln sind, nicht zu einer unmittelbaren Liveberechnung der kompletten Patientenakte und damit der abhängigen Scores führt, da dies bei jedem Aufruf zu einer erheblichen Systemlast führen würde. Dies geschieht automatisch beim nächsten Öffnen der jeweiligen Patientenakte und spätestens bei der nächtlichen Datenbankwartung.

Anfrage:

Parameter

Datentyp

Inhalt

Pflicht

request

Text

setitem

X

subjectid

int64

EMIL Patientennummer.

X

refdate

Timestamp

Referenzdatum

Nur bei Verlauf- und Laboritems

typeid

int64

ID des gesuchten Items, siehe Referenzierung

X

textval

Text

Einzufügender Wert. Abhängig vom Itemtyp

Textangaben bei Freitextfeldern .

Ein Code (Einfachauswahl) oder eine Codekette (Mehrfachauswahl) in der Form $<code-1>$<code-2>...$<code-n>$ bei kodierten Feldern

Eine Datumsangabe im Format dd.mm.yyyy bei Datumsfeldern

Eine unscharfe Datumsangabe im Format dd.mm.yyyy oder mm.yyyy oder yyyy abhängig von der erlaubten Unschärfe des jeweiligen Datentyps. Eine unscharfe Angabe für ein Feld, das genaues Datum erfordert, führt zur Ablehnung.

Ein Zahlenwert mit Komma oder Punkt als Dezimaltrenner ohne Tausendertrennzeichen

Bei Questionnaires kann dieser Parameter entfallen, da er durch das Questionnaire Kalkulationsmodul überschrieben würde

Die Angabe eines Leerstring oder Null als Textval löscht das Item.

X (außer bei  Questionnaires)

 

unit

Text

Name der Einheit. Leerzeichen sind zu vermeiden. Die Einheit muss eine von EMIL unterstützte Einheit sein. Unter Referenzierung ist beschrieben, wie man für ein Item die unterstützten Einheiten ermitteln kann.

Bei allen Zahlenwerten, die in EMIL eine Einheit haben (auch wenn es nur eine ist).

questionnaire

JSON

JSON Struktur mit den Questionnaire-Inhalt. Beispiel für Typ 104 (Krankenversicherung):

{

    "cmbAccount": "00",

    "edIK": "101575519",

    "cmbInsurance": "101575519",

    "edInsNum": "M123456789",

    "edValidFrom": "",

    "edValidThru": "",

    "edWOP": "",

    "edInsKind": "",

    "edPersGrp": "",

    "edDMP": ""

}

Leere Angaben (wie edValidFrom oder edValidThru) sollten weggelassen werden und nicht wie im Beispiel mit Leerstring angegeben sein. Nicht vorhandene JSON Elemente sind im Form leer und werden auch sonst als leer interpretiert.

Bei Checkboxen ist es ganz entscheidend, dass nur die angekreuzten Elemente mit dem Wert "1" übergeben werden und die nicht angekreuzten nicht im JSON vorhanden sind. Die Checkbox-Mechanismen in EMIL suchen im JSON  nur nach dem Vorhandensein eines Check-Elementes, nicht nach seinem expliziten Wert und setzen es bei Fund.

Des Weiteren führt EMIL keine Plausibilitätskontrolle der übergebenen Questionnaire Inhalte durch. Wird aus dem Questionnaire ein Score berechnet, führen fehlerhafte Forminhalte (z.B. mehrere Optionen einer Auswahl, in der nur eine Option gesetzt sein darf) möglicherweise zu einem völlig unsinnigen Score, da innerhalb EMIL solche Eingaben nicht möglich sind.

Namen der Felder in der JSON Struktur finden sich unter Referenzierung

Bei Questionnaires

Rückgabe:

keine

Entwickler-Tipp zu Questionnaires:

Eine gute Arbeitsbasis für die Arbeit mit Questionnaires ist, zunächst in EMIL mehrere davon auszufüllen und diese dann über diese Schnittstelle abzufragen, um eine Basisstruktur zu haben. Dies gilt insbesondere bei Questionnaires mit sich wiederholenden Unterstrukturen wie z.B. Medikation.