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.