EBMeDS Basic Interface - Overview

Transcription

1 EBMeDS Basic Interface - Overview Duodecim Medical Publications Ltd Interface version: "EBMeDS Basic v1.1" Version of this document: a Introduction The Evidence-Based Medicine electronic Decision Support (EBMeDS) is a clinical decision support service (DSS), which receives structured patient data from an electronic health record (EHR) system and returns a structured decision support response message to the EHR. The request and response messages are formatted in XML and are exchanged using the HTTP protocol. The service is installed and maintained in the local network of the EHR. In this paper, the XML interface of the EBMeDS Basic v1.1 system is described in overview. The XML Schema "EBMeDS Basic" contains more specific structured information about the interface messages and is the formal interface description. Element names from the XML Schema are shown in italic in this paper. The EBMeDS Basic request message contains elements for the essential patient data needed by the DSS. The EBMeDS Extended Interface, which is under development, will enable the EHR to send additional and more granular data to the DSS. Main Structure The EBMeDS Basic Interface includes two message types, which are defined on the message schema root level: DSSRequest. Container for the request information sent from the EHR to the DSS DSSResponse. Container for the response information sent from the DSS to the EHR The request and response messages contain repetitive structures, which are defined in two shared groups on the message schema root level: CodeGroup TimeStampsGroup The shared structures will be described first, since they will be referenced to in the description of the request message. Shared Element Groups CodeGroup. The EBMeDS system receives its essential information as codes from numerous standard classification systems, which are specified in Appendix 4. Additional classification systems can be added after mapping. The CodeGroup is used throughout the query message as a container for declaring the coding system explicitly for each code value. CodeValue. A classification code in the form it appears in the coding system specified in the element CodeSystem. CodeSystem. A unique ID for the coding system, preferably an OID code. The code system version may be a part of the OID. CodeSystemVersion. The version of the code system (if not included in the OID). TimeStampsGroup. The group container for different forms of time stamps.

2 StartStamp.The start stamp for time stamp intervals (e.g. the start of a sick leave). Both the start date and start time can be specified. o StartDate o StartTime End Stamp. The end stamp for time stamp intervals (e.g. the end of an antibiotic medication). Both the end date and end time can be specified. o EndDate o EndTime PointStamp. A single time stamp for non-interval time stamps (e.g. the sampling date/time for most laboratory tests). o PointDate o PointTime The Request Message DSSRequest. Container for the request message sent from the EHR to the DSS. A sample request message is shown in Appendix 1. Some informative fractions of queries are shown in Appendix 3. The request message contains the two main child elements: Patient System Patient Patient. The container for health care-related, patient-specific data. Additional child elements (e.g. for certificates and other documents) will appear in the Extended interface. Properties. The container for patient characteristics relevant for health care. Additional child elements will appear in the Extended Interface. o BirthTimeStamp. The birth date expressed with a minimum precision of the birth year. For newborn infants, birth dates with a precision of hours/minutes may be relevant. Year. The year expressed as four digits. Month. The month expressed as two digits. "00" is also allowed. Day. The day expressed as two digits. "00" is also allowed. Hour. The hour expressed as two digits. Minute. The minute expressed as two digits. o Gender. The gender of the patient. Allowed values: male: "M" or "1" female: "F" or "2" unspecified: "U" or "9" (to be used e.g. in severe malformations where the gender cannot be determined without genetic tests) not known: "N" or "0" Risks. The container for risk information. Additional child elements (e.g. for alcohol habits and substance abuse) appear in the Extended Interface. o DrugsToAvoid. The container for repetitive sequences of the element DrugToAvoid DrugToAvoid. A drug that is not suitable for the patient (e.g. due to a previous allergic reaction) CodeGroup DrugName. A free text name used in the EHR for the drug (e.g. a trademark or the generic name). o Smoking. The container for smoking information. Additional child elements (e.g. for smoking pack years) appear in the Extended Interface. SmokingStatus. Allowed values: 0 = non-smoker 1 = smoker

3 2 = ex-smoker o Pregnancy. The container for pregnancy information. Additional child elements (e.g. for pregnancy week) appear in the Extended Interface. Pregnant. Boolean value for pregnancy Problems. The container for health problems. Additional child elements (e.g. for reason(s) for encounter) will appear in the Extended Interface. o Diagnoses. The container for repetitive sequences of the Diagnosis element. Diagnosis. Data related to diagnoses, including symptom diagnoses. CodeGroup TimeStampsGroup DiagnosisName. A free text name used in the EHR for the diagnosis Investigations. The container for health care-related investigations. Additional child elements (e.g. for diagnostic imaging) will appear in the Extended Interface. o Measurements. The container element for repetitive sequences of the Measurement element. Measurement. All kinds of measurements resulting in quantitative or qualitative results (e.g. laboratory tests, weight measurement, blood pressure measurement). CodeGroup TimeStampsGroup Ordered. Boolean element for measurements that have been ordered (= will be performed in the future) Result. The container for the result of the measurement. o Value. For example "100", if the result is "100 mmol/l" o Unit. For example "mmol/l", if the result is "100 mmol/l". Is not applicable in qualitative results. MeasurementName. A free text name used in the EHR for the measurement. Interventions. The container for health care-related interventions, such as drug therapy and therapeutic procedures. Additional child elements (e.g. for physical therapy) will appear in the Extended interface. o Medication. The container for repetitive sequences of the Drug element. Drug. Data related to drugs. Additional child elements (e.g. for dosage schema) appear in the Extended Interface. CodeGroup Strength. The numeric strength of a substance, e.g. "10" for a 10 mg tablet StrengthUnit. The unit for the strength, e.g. "mg" for a 10 mg tablet DailyDose. The numeric daily dose, as calculated from the dose strength and the dosage schema (e.g. 10 (mg) x 2 = 20) TimeStampsGroup DrugName. A free text name used in the EHR for the drug (e.g. the trademark) o Vaccinations. The container for repetitive sequences of the Vaccination element. Vaccine. Data related to a vaccination. CodeGroup Strength. The numeric strength of a vaccine, e.g. "10" for 10 mg/ml StrengthUnit. The unit for the strength, e.g. "ml" for 10 mg/ml Dose. The amount of vaccine given. TimeStampsGroup VaccineName. A free text name used in the EHR for the vaccine (e.g. the trademark) o Procedures. The container for repetitive sequences of the Procedure element.

4 System Procedure. Data related to diagnostic and therapeutic procedures. CodeGroup TimeStampsGroup Ordered. Boolean element for procedures that have been ordered (= will be performed in the future) ProcedureName. A free text name used in the EHR for the procedure System. The container for data describing the profile of the request sender. User. The container for data describing the person using the client system. o HealthCareRole. Role of the user. Allowed values: Physician Nurse Citizen o HealthCareOrganization. Health care organization(s) that the user belongs to (e.g. health district, health care unit) CodeGroup o HealthCareSpeciality. Health care speciality or specialities that the user belongs to CodeGroup o Language. Language of the user CodeGroup o Nation. Nation of the user CodeGroup Application. The container for data describing the user application (e.g. an electronic health record or a personal health account). QueryID. A unique ID (in free format) generated by the client application. DSSVersion. The version of the EBMeDS interface specification (this version is referenced to as "EBMeDS Basic v1.1"). ScriptSelection. Exclusion and inclusion criteria for scripts to be run by the decision support service. TestScripts. Script(s) under development to test. ScriptID ScriptsToRun. Script(s) outside the basic script set that should explicitly be run. ScriptID ScriptsToBlock. Script(s) in the basic script set that should be explicitly blocked from running. The EHR interface can use this element to offer possibilities for blocking certain scripts on the patient, user and/or organizational level. ScriptID FeedbackType. A code representing the structure of the response message. Allowed values: 0 = HTML 1 = HTML - short debug information 2 = HTML - longer debug information C = compact HTML S = structured Q = the structured query message CheckMoment. To be used, if the reference time stamp for the decision support execution is in the future (e.g. in virtual health checks) CheckDate CheckTime EventTypes. The container for the EventType element

5 EventType. The EHR event that has triggered the request message. Allowed values: onopenrecord oncloserecord onnewdiagnosis onewdrug onnewprocedure onnewconsultation onnewform onvirtualhealthcheck ExperimentalDataSets ExperimentalDataSets. The container for repetitive sequences of the ExperimentalData element. ExperimentalDataSet. The container for experimental request data not yet included in the XML Schema. o DataSetName. A descriptive name for the dataset o CodeGroup o TimeStampGroup o DataSetText. A text string o DataEHRName. A free text name used in the EHR for the data set DSSResponse DSSResponse. Container for the response message sent from the DSS to the EHR. A sample response example is shown in Appendix 2. Some informative fractions of queries are shown in Appendix 3. The structured response messages allows the EHR developers to tailor the appearance of the decision support messages in the EHR user interface in detail. Alternatively, the response message is also available in two forms (short/long) of pre-formatted HTML. Reminders. The container for repetitive sequences of the Reminder element. ScriptID. A unique ID for the script returning a reminder ReminderShort. The reminder text in a short format o a. Text to be used as a link. The link address is the href attribute as in HTML. ReminderLong. The reminder text in a long format o a. Text to be used as a link. The link address is the href attribute as in HTML. ReminderPatient. The reminder in a form that is understandable for laymen ReminderLevel. The importance level of a reminder. Allowed values: o 0 = reminder o 1 = prompt o 2 = alert Interactions. The container for repetitive sequences of the Interaction element. InteractionText. A text describing the interaction between two drugs (Drug1 and Drug2) InteractionLevel. A classification code (according to the SFINX classification) for the severity of the interaction. Allowed values: o C = clinically significant interaction o D = potentially dangerous interaction Drug1 o DrugCode o DrugName. The name of the drug (as it appears in the request message) Drug2 o DrugCode

6 o DrugName. The name of the drug (as it appears in the request message) Contraindications. The container for repetitive sequences of the Contraindication element. ContraindicationText. A text describing the contraindication (diagnosis) for a drug ContraindicationLevel. Allowed values: 0 = relative contraindication 1 = absolute contraindication Drug. The drug that is contraindicated DrugCode DrugName. The name of the drug (as it appears in the request message) Diagnosis. The diagnosis that is the contraindication DiagnosisCode DiagnosisName. The name of the diagnosis (as it appears in the request message) DrugsToAvoid. The container for repetitive sequences of the DrugToAvoid element. DrugCode DrugName. The name of the drug to avoid (as it appears in the request message) Indications. The container for repetitive sequences of the Indication element. Indication IndicationText. A text describing the indication for a drug Drug. A drug that may be used to treat the diagnosis DrugCode DrugName. The name of the drug (as it appears in the request message) Diagnosis. The diagnosis for which the drug treatment is indicated DiagnosisCode DiagnosisName. The name of the diagnosis (as it appears in the request message) IndicationLevel. The importance of the indication. Allowed values: 1 = first-hand treatment 0 = second-hand treatment GuidelineLinks. The container for repetitive sequences of the GuidelineLink element. GuidelineLink. The container for information about a web link GuidelineURL. The URL of the guideline GuidelineTitle. The title of the guideline GuidelinePriority. The priority of the guideline. Allowed values: 1 = first-line guideline 0 = second-line guideline GuidelineID. A unique ID for the guideline DiagnosisCode. The diagnosis code corresponding to the guideline DiagnosisName. The diagnosis name corresponding to the guideline (as it appears in the request message) System. The container for system response data. QueryID. The unique query ID generated by the client application (as it appears in the request message) ElapsedTime. Time elapsed for the script execution DebugMessages. The container for repetitive sequences of the DebugMessage element. DebugMessage. A message containing debug data Exceptions. The container for repetitive sequences of the Exceptions element. Exception. A description of an error

7 ExperimentalDataSets. The container for repetitive sequences of the ExperimentalData element. ExperimentalDataSet. The container for experimental response data not yet included in the XML Schema. o DataSetName. A descriptive name for the dataset o DataSetText. A text string Appendix 1: Request Example <?xml version="1.0" encoding="utf-8"?> <DSSRequest xmlns:xsi=" xsi:nonamespaceschemalocation=" Basic Interface v1.1.xsd"> <Patient> <Properties> <BirthTimeStamp> <Year>2000</Year> <Month>01</Month> <Day>01</Day> <Hour>00</Hour> <Minute>00</Minute> </BirthTimeStamp> <Gender>1</Gender> </Properties> <Risks> <DrugsToAvoid> <DrugToAvoid> <CodeSystemVersion>string</CodeSystemVersion> <DrugName>string</DrugName> </DrugToAvoid> </DrugsToAvoid> <Smoking> <SmokingStatus>1</SmokingStatus> </Smoking> <Pregnancy> <Pregnant>0</Pregnant> </Pregnancy> </Risks> <Problems> <Diagnoses> <StartStamp> <StartDate> </StartDate> <StartTime>00:00:00.00</StartTime> </StartStamp> <EndStamp> <EndDate> </EndDate> <EndTime>00:00:00.00</EndTime> </EndStamp> <PointStamp> <PointDate> </PointDate> <PointTime>00:00:00</PointTime> </PointStamp> <DiagnosisName>string</DiagnosisName> </Diagnoses> </Problems> <Investigations> <Measurements> <Measurement> <PointStamp> <PointDate> </PointDate> <PointTime>00:00:00</PointTime> </PointStamp> <Ordered>0</Ordered> <Result> <Value>string</Value>

8 <Unit>string</Unit> </Result> <MeasurementName>string</MeasurementName> </Measurement> </Measurements> </Investigations> <Interventions> <Medication> <Strength>12.5</Strength> <StrengthUnit>string</StrengthUnit> <DailyDose>25</DailyDose> <StartStamp> <StartDate> </StartDate> <StartTime>00:00:00</StartTime> </StartStamp> <EndStamp> <EndDate> </EndDate> <EndTime>00:00:00.00</EndTime> </EndStamp> <PointStamp> <PointDate> </PointDate> <PointTime>00:00:00</PointTime> </PointStamp> <DrugName>string</DrugName> </Medication> <Procedures> <Procedure> <PointStamp> <PointDate> </PointDate> <PointTime>00:00:00</PointTime> </PointStamp> <Ordered>1</Ordered> <ProcedureName>string</ProcedureName> </Procedure> </Procedures> </Interventions> </Patient> <System> <User> <HealthCareRole>Citizen</HealthCareRole> <HealthCareOrganization> <CodeSystemVersion>string</CodeSystemVersion> </HealthCareOrganization> <HealthCareSpeciality> <CodeSystemVersion>string</CodeSystemVersion> </HealthCareSpeciality> <Language> <CodeSystemVersion>string</CodeSystemVersion> </Language> <Nation> </Nation> </User> <Application> <QueryID>string</QueryID> <DSSVersion>string</DSSVersion> <ScriptSelection> <TestScripts> <ScriptID>string</ScriptID> </TestScripts> <ScriptsToRun> <ScriptID>string</ScriptID>

9 </ScriptsToRun> <ScriptsToBlock> <ScriptID>string</ScriptID> <ScriptID>string</ScriptID> </ScriptsToBlock> </ScriptSelection> <FeedbackType>C</FeedbackType> <CheckMoment> <CheckDate> </CheckDate> <CheckTime>00:00:00.01</CheckTime> </CheckMoment> <EventTypes> <EventType>onOpenRecord</EventType> </EventTypes> </Application> </System> </DSSRequest> Appendix 2: Response Example <?xml version="1.0" encoding="utf-8"?> <DSSResponse xmlns:xsi=" xsi:nonamespaceschemalocation=" Basic Interface v1.1.xsd"> <Reminders> <Reminder> <ScriptID>string</ScriptID> <ReminderShort>string</ReminderShort> <ReminderLong>string</ReminderLong> <ReminderPatient>string</ReminderPatient> <ReminderLevel>0</ReminderLevel> </Reminder> </Reminders> <Interactions> <Interaction> <InteractionText>string</InteractionText> <InteractionLevel>C</InteractionLevel> <Drug1> <DrugCode>string</DrugCode> <DrugName>string</DrugName> </Drug1> <Drug2> <DrugCode>string</DrugCode> <DrugName>string</DrugName> </Drug2> </Interaction> </Interactions> <Contraindications> <Contraindication> <ContraindicationText>string</ContraindicationText> <ContraindicationLevel>6339</ContraindicationLevel> <DrugCode>string</DrugCode> <DrugName>string</DrugName> <DiagnosisCode>string</DiagnosisCode> <DiagnosisName>string</DiagnosisName> </Contraindication> </Contraindications> <DrugsToAvoid> <DrugToAvoid> <DrugCode>string</DrugCode> <DrugName>string</DrugName> </DrugToAvoid> </DrugsToAvoid> <Indications> <Indication> <DrugCode>string</DrugCode> <DrugName>string</DrugName> <DiagnosisCode>string</DiagnosisCode>

10 <DiagnosisName>string</DiagnosisName> <IndicationLevel>0</IndicationLevel > </Indication> </Indications> <GuidelineLinks> <GuidelineLink> <GuidelineURL>string</GuidelineURL> <GuidelineTitle>string</GuidelineTitle> <GuidelinePriority>3635</GuidelinePriority> <GuidelineID>string</GuidelineID> <DiagnosisCode>string</DiagnosisCode> <DiagnosisName>string</DiagnosisName> </GuidelineLink> </GuidelineLinks> <System> <QueryID>string</QueryID> <ElapsedTime>1373</ElapsedTime> <DebugMessages> <DebugMessage>string</DebugMessage> </DebugMessages> <Exceptions> <Exception>string</Exception> </Exceptions> </System> </DSSResponse> Appendix 3: Examples Extracted From Request Messages Example 1 A male born on June 15 th, 1958 <Properties> <BirthTimeStamp> <Year>1958</Year> <Month>06</Month> <Day>15</Day> </BirthTimeStamp> <Gender>1</Gender> </Properties> Example 2 A patient with a diagnosis of asthma (ICD9-CM code 493.2) since March 28 th, 2000 <Diagnoses> <CodeValue>493.2</CodeValue> <CodeSystem> </CodeSystem> <StartStamp> <StartDate> </StartDate> <StartTime></StartTime> </StartStamp> </Diagnoses> Example 3 A patient with an episode of rheumatic fever with endocarditis (ICD-10 code I01.1) in the year 1959 <Diagnoses> <CodeValue>I01.1</CodeValue> <CodeSystem> </CodeSystem> <StartStamp> <StartDate> </StartDate> </StartStamp> <EndStamp> <EndDate> </EndDate> </EndStamp>

11 </Diagnoses> Example 4 A patient, who had an appointment on February 15 th, 2008 due to diffuse abdominal swelling symptoms (ICPC-2 code D25) <Diagnoses> <CodeValue>D25</CodeValue> <CodeSystem> </CodeSystem> <PointStamp> <PointDate> </PointDate> </PointStamp> </Diagnoses> Example 5 A patient with a hemoglobin value (KL code 1552) of 141 g/l <Measurements> <Measurement> <CodeValue>1552</CodeValue> <CodeSystem> </CodeSystem> <PointStamp> <PointDate> </PointDate> </PointStamp> <Result> <Value>141</Value> <Unit>g/l</Unit> </Result> </Measurement> </Measurements> Example 6 As in example 5, but with the measurement expressed as the LOINC code and the result with the measurement unit g/dl <Measurements> <Measurement> <CodeValue>718-7</CodeValue> <CodeSystem> </CodeSystem> <PointStamp> <PointDate> </PointDate> </PointStamp> <Result> <Value>14.1</Value> <Unit>g/dL</Unit> </Result> </Measurement> </Measurements> Example 7 A patient using one tablet of 10 mg simvastatin (ATC code C10AA01) daily <Medication> <CodeValue> C10AA01</CodeValue> <CodeSystem> </CodeSystem> <Strength>10</Strength> <StrengthUnit>mg</StrengthUnit> <DailyDose>10</DailyDose> <StartStamp> <StartDate> </StartDate> </StartStamp> </Medication>

12 Example 8 A patient who has been prescribed cephalexine (ATC code J01DB01) 500 mg twice daily for one week <Medication> <CodeValue>J01DB01</CodeValue> <CodeSystem> </CodeSystem> <Strength>500</Strength> <StrengthUnit>mg</StrengthUnit> <DailyDose>1000</DailyDose> <StartStamp> <StartDate> </StartDate> </StartStamp> <EndStamp> <EndDate> </EndDate> </EndStamp> </Medication> Example 9 A patient waiting for a bronchofiberoscopy (NSCP code UGC12) <Procedures> <Procedure> <CodeValue>UGC12</CodeValue> <CodeSystem> </CodeSystem> <Ordered>1</Ordered> </Procedure> </Procedures> Example 10 The system user is an English-speaking physician from the United States <User> <HealthCareRole>Physician</ HealthCareRole > <Language> <CodeValue>en-us</CodeValue> <CodeSystem>ISO 639</CodeSystem> </Language> <Nation> <CodeValue>846</CodeValue> <CodeSystem>ISO </CodeSystem> </Nation> </User> Example 11 The query is in the EBMeDS Basic v1.1 format and has been triggered by a new diagnosis event in the EHR. The script scr00005 is on the system blocking list, and the response message will be sent in compressed HTML. <Application> <QueryID>Q120577</QueryID> <DSSVersion>EBMeDS Basic v1.1</dssversion> <ScriptSelection> <ScriptsToBlock> <ScriptID>scr00005</ScriptID> </ScriptsToBlock> </ScriptSelection> <FeedbackType>C</FeedbackType> <EventType>onNewDiagnosis</EventType> </Application> Example 12 A reminder returned for a patient on thiazides with no recent value for plasma/serum creatinine.

13 <Reminders> <Reminder> <ScriptID>scr00005</ScriptID> <ReminderShort>Check creatinine?</remindershort> <ReminderLong> The patient is on thiazides (Hydrex) and there is no recent value for creatinine. Consider checking plasma or serum creatinine. </ReminderLong> <ReminderPatient/> <ReminderLevel>0</ReminderLevel> </Reminder> </Reminders> Example 13 A link to an first-line EBMG guideline returned for a patient with a new diagnosis of rosacea. <GuidelineLink> <GuidelineURL> <GuidelineTitle>Rosacea</GuidelineTitle> <GuidelinePriority>1</GuidelinePriority> <GuidelineID>ebm00286</GuidelineID> <DiagnosisCode>L71.9</DiagnosisCode> <DiagnosisName>Acne Rosacea</DiagnosisName> </GuidelineLink> Example 14 An alert returned due to the potentially dangerous interaction (SFINX class D) between warfarin and metronidazol. <Interactions> <Interaction> <InteractionText> Avoid the combination. If the the metronidazol is considered necessary, consider discontinuing the warfarin treatment or reducing the metronidazol dose </InteractionText> <InteractionLevel>D</InteractionLevel> <Drug1> <DrugCode>B01AA03</DrugCode> <DrugName >Warfarin</DrugName> </Drug1> <Drug2> <DrugCode>P01AB01</DrugCode> <DrugName >Metronidazol</DrugName> </Drug2> </Interaction> </Interactions> Example 15 An alert returned due to intended use of sibutramine in bipolar disorder (absolute contraindication). <Contraindications> <Contraindication> <ContraindicationText> Sibutramine is contraindicated in psychiatric disorders, especially bipolar disorder </ContraindicationText> <ContraindicationLevel>1</ContraindicationLevel> <DrugCode>A08AA10</DrugCode> <DrugName>Sibutramine</DrugName> <DiagnosisCode>F31</DiagnosisCode> <DiagnosisName>Bipolar disorder</diagnosisname> </Contraindication> </Contraindications>

14 Example 16 A drug treatment reminder returned for a patient with a hepatic cirrhosis with ascites. Spironolactone is recommended as first-line treatments (cardinality = 1), furosemide as second-hand treatment. <Indications> <Indication> <DrugCode>C03DA01</DrugCode> <DrugName>Spironolactone</DrugName> <DiagnosisCode>K7</DiagnosisCode> <DiagnosisName>Hepatic cirrhosis</diagnosisname> <Cardinality>1</Cardinality> <IndicationText>Treatment of ascites associated with hepatic cirrhosisu</indicationtext> </Indication> <Indication> <DrugCode> C03CA01</DrugCode> <DrugName>Furosemide</DrugName> <DiagnosisCode>K7</DiagnosisCode> <DiagnosisName>Hepatic cirrhosis</diagnosisname> <Cardinality>0</Cardinality> <IndicationText> Treatment of ascites associated with hepatic cirrhosis, when spironolactone alone is not sufficient or not suitable </IndicationText> </Indication> </Indications>