RECIP-E INTEGRATION SPECIFICATION DRAFT

Transcription

1 RECIP-E INTEGRATION SPECIFICATION DRAFT

2 DOCUMENT CONTROL Document revision history Version Date Author Comments /06/2010 Thibaut Henry Draft /06/2010 Thibaut Henry Version for review /06/2010 Thibaut Henry Update for authentication /07/2010 Thibaut Henry Update following TSC of 1/7/ /07/2010 Jos Van Dorpe Review /07/2010 Jos Van Dorpe Update with barcode format /07/2010 Thibaut Henry Review for module delivery /07/2010 Thibaut Henry Review remarks from Jos Van Dorpe /07/2010 Thibaut Henry Review remarks from TSC and from software vendors /08/2010 Jos Van Dorpe Added new Kmehr example + added remark concerning the responsibility of the pharmacy software to check the validity of the prescribing doctor /08/2010 Martin Kwee Integrated WSDL specs exposed by ehealth /08/2010 Thibaut Henry Review remarks from TSC of the 26/08/ /09/2010 Jos Van Dorpe Final updates for SSC validated version + included FAQ /09/2010 Jos Van Dorpe Incorporated additional remarks Marc Buckens /09/2010 Jos Van Dorpe Added - correct definition of P0, P1, P2 - clarification surrounding access rights based on prescription type - clarification surrounding the requirements for the creation of a fallback session /09/2010 Thibaut Henry Added further clarifications around the access to the keystore + changed pharmacy access rights: eid needs to be of a pharmacist /09/2010 Thibaut Henry Add extra information regarding KMEHR in the FAQ /11/2010 Thibaut Henry Take into account remarks following testing stages /05/2011 Yannick Landuyt Add information about MyCareNet and requesting insurability information of a patient for the Executor.. Approval / Signatures Version Date Approved By Signature

3 TABLE OF CONTENT Table of Content... 1 Table of Figures List of Tables External References Introduction Recip-e solution Description and Purpose of the integration specifications Responsibility for this Document Document Scope Additional information Integration Options Responsibilities Identification of the Patient Prescription Format Kmehr XSD Validation Additional Validation Sample Prescription Checking/setting the author of the prescription Prescription Type Notification Format XSD validation Sample File Feedback Format XSD validation Sample File Authentication & Authorization Definition Session creation Session creation Fallback Session Stop Access to keystore Barcode specification Format Recip-ID Format barcode Print Prescription (For Prescribers) Barcode Strictly confidential For Recip-e project member use only Page 1

4 4.7.2 Medications Archiving (For Executor software) Performance Metrics Upload Integration Option 1: Modules Overview Prescriber software Executor Software Integration Detail Approach Java DLL Module configuration Mycarenet Certificates WSDLs Logs Sevice Inventory "createsession" [Prescriber Integration Module, Executor Integration Module] "loadsession" [Prescriber Integration Module, Executor Integration Module] "unloadsession" [Prescriber Integration Module, Executor Integration Module] "createfallbacksession" [Prescriber Integration Module, Executor Integration Module] "hasvalidsession" [Prescriber Integration Module, Executor Integration Module] "preparecreateprescription" [Prescriber Integration Module] "createprescription" [Prescriber Integration Module] "sendnotificaiton" [Prescriber Integration Module] "revokeprescription" [Prescriber Integration Module, Executor Integration Module] "getprescription" (for Prescriber) [Prescriber Integration Module] "listfeedback" [Prescriber Integration Module] "setpersonalpassword" [Prescriber Integration Module] "listopenprescription" [Prescriber Integration Module] "updatefeedbackflag" [Prescriber Integration Module] "getprescription" (for Executor) [Executor Integration Module] "markasundelivered" [Executor Integration Module] "markasdelivered" [Executor Integration Module] "markasarchived" [Executor Integration Module] "createfeedback" [Executor Integration Module] "listnotifications" [Executor Integration Module] Integration Option 2: Webservices Overview Prescriber software Strictly confidential For Recip-e project member use only Page 2

5 6.1.2 Executor Software Implementation Detail Authentication of the care provider Messaging and encryption Prescriber Services Executor Services (Pharmacist, Nurse ) Error Management ehealth Services Sevice Inventory Administrative Information Party Identification "createprescription" [Prescriber Services] "sendnotification" [Prescriber Services] "revokeprescription" [Prescriber Services, Executor Services] "getprescription" (for Prescriber) [Prescriber Services] "listfeedback" [Prescriber Services] "listopenprescription" [Prescriber Services] "updatefeedbackflag" [Prescriber Services] "getprescription" (for Executor) [Executor Services] "markasundelivered" [Executor Services] "markasdelivered" [Executor Services] "markasarchived" [Executor Services] "createfeedback" [Executor Services] "listnotifications" [Executor Services] APPENDIX: Recip-e Client Package Content APPENDIX : Frequently asked Questions APPENDIX: E-Health Certificate Creation Table of Content... 1 Table of Figures... 4 List of Tables External References Introduction Recip-e solution Description and Purpose of the integration specifications Responsibility for this Document Document Scope Additional information... 8 Strictly confidential For Recip-e project member use only Page 3

6 3 Integration Options Responsibilities Identification of the Patient Prescription Format Kmehr XSD Validation Additional Validation Sample Prescription Checking/setting the author of the prescription Prescription Type Notification Format XSD validation Sample File Feedback Format XSD validation Sample File Authentication & Authorization Definition Session creation Session creation Fallback Session Stop Access to keystore Barcode specification Format Recip-ID Format barcode Print Prescription (For Prescribers) Barcode Medications Archiving (For Executor software) Performance Metrics Upload Integration Option 1: Modules Overview Prescriber software Executor Software Integration Detail Approach Java DLL Module configuration Mycarenet Certificates Strictly confidential For Recip-e project member use only Page 4

7 5.2.3 WSDLs Logs Sevice Inventory "createsession" [Prescriber Integration Module, Executor Integration Module] "loadsession" [Prescriber Integration Module, Executor Integration Module] "unloadsession" [Prescriber Integration Module, Executor Integration Module] "createfallbacksession" [Prescriber Integration Module, Executor Integration Module] "hasvalidsession" [Prescriber Integration Module, Executor Integration Module] "preparecreateprescription" [Prescriber Integration Module] "createprescription" [Prescriber Integration Module] "sendnotificaiton" [Prescriber Integration Module] "revokeprescription" [Prescriber Integration Module, Executor Integration Module] "getprescription" (for Prescriber) [Prescriber Integration Module] "listfeedback" [Prescriber Integration Module] "setpersonalpassword" [Prescriber Integration Module] "listopenprescription" [Prescriber Integration Module] "updatefeedbackflag" [Prescriber Integration Module] "getprescription" (for Executor) [Executor Integration Module] "markasundelivered" [Executor Integration Module] "markasdelivered" [Executor Integration Module] "markasarchived" [Executor Integration Module] "createfeedback" [Executor Integration Module] "listnotifications" [Executor Integration Module] Integration Option 2: Webservices Overview Prescriber software Executor Software Implementation Detail Authentication of the care provider Messaging and encryption Prescriber Services Executor Services (Pharmacist, Nurse ) Error Management ehealth Services Sevice Inventory Administrative Information Party Identification "createprescription" [Prescriber Services] "sendnotification" [Prescriber Services] "revokeprescription" [Prescriber Services, Executor Services] Strictly confidential For Recip-e project member use only Page 5

8 6.3.6 "getprescription" (for Prescriber) [Prescriber Services] "listfeedback" [Prescriber Services] "listopenprescription" [Prescriber Services] "updatefeedbackflag" [Prescriber Services] "getprescription" (for Executor) [Executor Services] "markasundelivered" [Executor Services] "markasdelivered" [Executor Services] "markasarchived" [Executor Services] "createfeedback" [Executor Services] "listnotifications" [Executor Services] APPENDIX: Recip-e Client Package Content APPENDIX : Frequently asked Questions APPENDIX: E-Health Certificate Creation Table of Content... 1 Table of Figures... 4 List of Tables External References Introduction Recip-e solution Description and Purpose of the integration specifications Responsibility for this Document Document Scope Additional information Integration Options Responsibilities Identification of the Patient Prescription Format Kmehr XSD Validation Additional Validation Sample Prescription Checking/setting the author of the prescription Prescription Type Notification Format XSD validation Sample File Feedback Format Strictly confidential For Recip-e project member use only Page 6

9 4.4.1 XSD validation Sample File Authentication & Authorization Definition Session creation Session creation Fallback Session Stop Access to keystore Barcode specification Format Recip-ID Format barcode Print Prescription (For Prescribers) Barcode Medications Archiving (For Executor software) Performance Metrics Upload Integration Option 1: Modules Overview Prescriber software Executor Software Integration Detail Approach Java DLL Module configuration MYCARENET Certificates WSDLs Logs Sevice Inventory "createsession" [Prescriber Integration Module, Executor Integration Module] "loadsession" [Prescriber Integration Module, Executor Integration Module] "unloadsession" [Prescriber Integration Module, Executor Integration Module] "createfallbacksession" [Prescriber Integration Module, Executor Integration Module] "hasvalidsession" [Prescriber Integration Module, Executor Integration Module] "preparecreateprescription" [Prescriber Integration Module] "createprescription" [Prescriber Integration Module] "sendnotificaiton" [Prescriber Integration Module] "revokeprescription" [Prescriber Integration Module, Executor Integration Module] "getprescription" (for Prescriber) [Prescriber Integration Module] Strictly confidential For Recip-e project member use only Page 7

10 5.3.7 "listfeedback" [Prescriber Integration Module] "setpersonalpassword" [Prescriber Integration Module] "listopenprescription" [Prescriber Integration Module] "updatefeedbackflag" [Prescriber Integration Module] "getprescription" (for Executor) [Executor Integration Module] "markasundelivered" [Executor Integration Module] "markasdelivered" [Executor Integration Module] "markasarchived" [Executor Integration Module] "createfeedback" [Executor Integration Module] "listnotifications" [Executor Integration Module] Integration Option 2: Webservices Overview Prescriber software Executor Software Implementation Detail Authentication of the care provider Messaging and encryption Prescriber Services Executor Services (Pharmacist, Nurse ) Error Management ehealth Services Sevice Inventory Administrative Information Party Identification "createprescription" [Prescriber Services] "sendnotification" [Prescriber Services] "revokeprescription" [Prescriber Services, Executor Services] "getprescription" (for Prescriber) [Prescriber Services] "listfeedback" [Prescriber Services] "listopenprescription" [Prescriber Services] "updatefeedbackflag" [Prescriber Services] "getprescription" (for Executor) [Executor Services] "markasundelivered" [Executor Services] "markasdelivered" [Executor Services] "markasarchived" [Executor Services] "createfeedback" [Executor Services] "listnotifications" [Executor Services] APPENDIX: Recip-e Client Package Content APPENDIX : Frequently asked Questions Strictly confidential For Recip-e project member use only Page 8

11 9 APPENDIX: E-Health Certificate Creation Table of Content... 1 Table of Figures... 4 List of Tables External References Introduction Recip-e solution Description and Purpose of the integration specifications Responsibility for this Document Document Scope Additional information Integration Options Responsibilities Identification of the Patient Prescription Format Kmehr XSD Validation Additional Validation Sample Prescription Checking/setting the author of the prescription Prescription Type Notification Format XSD validation Sample File Feedback Format XSD validation Sample File Authentication & Authorization Definition Session creation Session creation Fallback Session Stop Access to keystore Barcode specification Format Recip-ID Format barcode Print Prescription (For Prescribers) Barcode Strictly confidential For Recip-e project member use only Page 9

12 4.7.2 Medications Archiving (For Executor software) Performance Metrics Upload Integration Option 1: Modules Overview Prescriber software Executor Software Integration Detail Approach Java DLL Module configuration Certificates WSDLs Logs Sevice Inventory "createsession" [Prescriber Integration Module, Executor Integration Module] "loadsession" [Prescriber Integration Module, Executor Integration Module] "unloadsession" [Prescriber Integration Module, Executor Integration Module] "createfallbacksession" [Prescriber Integration Module, Executor Integration Module] "hasvalidsession" [Prescriber Integration Module, Executor Integration Module] "preparecreateprescription" [Prescriber Integration Module] "createprescription" [Prescriber Integration Module] "sendnotificaiton" [Prescriber Integration Module] "revokeprescription" [Prescriber Integration Module, Executor Integration Module] "getprescription" (for Prescriber) [Prescriber Integration Module] "listfeedback" [Prescriber Integration Module] "listopenprescription" [Prescriber Integration Module] "updatefeedbackflag" [Prescriber Integration Module] "getprescription" (for Executor) [Executor Integration Module] "markasundelivered" [Executor Integration Module] "markasdelivered" [Executor Integration Module] "markasarchived" [Executor Integration Module] "createfeedback" [Executor Integration Module] "listnotifications" [Executor Integration Module] Integration Option 2: Webservices Overview Prescriber software Executor Software Implementation Detail Strictly confidential For Recip-e project member use only Page 10

13 6.2.1 Authentication of the care provider Messaging and encryption Prescriber Services Executor Services (Pharmacist, Nurse ) Error Management ehealth Services Sevice Inventory Administrative Information Party Identification "createprescription" [Prescriber Services] "sendnotification" [Prescriber Services] "revokeprescription" [Prescriber Services, Executor Services] "getprescription" (for Prescriber) [Prescriber Services] "listfeedback" [Prescriber Services] "listopenprescription" [Prescriber Services] "updatefeedbackflag" [Prescriber Services] "getprescription" (for Executor) [Executor Services] "markasundelivered" [Executor Services] "markasdelivered" [Executor Services] "markasarchived" [Executor Services] "createfeedback" [Executor Services] "listnotifications" [Executor Services] APPENDIX: Recip-e Client Package Content APPENDIX : Frequently asked Questions Table of Content... 1 Table of Figures... 4 List of Tables External References Introduction Recip-e solution Description and Purpose of the integration specifications Responsibility for this Document Document Scope Additional information Integration Options Responsibilities Identification of the Patient Strictly confidential For Recip-e project member use only Page 11

14 4.2 Prescription Format Kmehr XSD Validation Additional Validation Sample Prescription Checking/setting the author of the prescription Prescription Type Notification Format XSD validation Sample File Feedback Format XSD validation Sample File Authentication & Authorization Definition Session creation Session creation Fallback Session Stop Access to keystore Barcode specification Format Recip-ID Format barcode Print Prescription (For Prescribers) Barcode Medications Archiving (For Executor software) Performance Metrics Upload Integration Option 1: Modules Overview Prescriber software Executor Software Integration Detail Approach Java DLL Module configuration Certificates WSDLs Logs Sevice Inventory "createsession" [Prescriber Integration Module, Executor Integration Module] Strictly confidential For Recip-e project member use only Page 12

15 5.3.2 "loadsession" [Prescriber Integration Module, Executor Integration Module] "unloadsession" [Prescriber Integration Module, Executor Integration Module] "createfallbacksession" [Prescriber Integration Module, Executor Integration Module] "hasvalidsession" [Prescriber Integration Module, Executor Integration Module] "preparecreateprescription" [Prescriber Integration Module] "createprescription" [Prescriber Integration Module] "sendnotificaiton" [Prescriber Integration Module] "revokeprescription" [Prescriber Integration Module, Executor Integration Module] "getprescription" (for Prescriber) [Prescriber Integration Module] "listfeedback" [Prescriber Integration Module] "listopenprescription" [Prescriber Integration Module] "updatefeedbackflag" [Prescriber Integration Module] "getprescription" (for Executor) [Executor Integration Module] "markasundelivered" [Executor Integration Module] "markasdelivered" [Executor Integration Module] "markasarchived" [Executor Integration Module] "createfeedback" [Executor Integration Module] "listnotifications" [Executor Integration Module] Integration Option 2: Webservices Overview Prescriber software Executor Software Implementation Detail Authentication of the care provider Messaging and encryption Prescriber Services Executor Services (Pharmacist, Nurse ) Error Management ehealth Services Sevice Inventory Administrative Information Party Identification "createprescription" [Prescriber Services] "sendnotification" [Prescriber Services] "revokeprescription" [Prescriber Services, Executor Services] "getprescription" (for Prescriber) [Prescriber Services] "listfeedback" [Prescriber Services] "listopenprescription" [Prescriber Services] "updatefeedbackflag" [Prescriber Services] "getprescription" (for Executor) [Executor Services] Strictly confidential For Recip-e project member use only Page 13

16 "markasundelivered" [Executor Services] "markasdelivered" [Executor Services] "markasarchived" [Executor Services] "createfeedback" [Executor Services] "listnotifications" [Executor Services] APPENDIX: Recip-e Client Package Content APPENDIX : Frequently asked Questions Strictly confidential For Recip-e project member use only Page 14

17 TABLE OF FIGURES Figure 1 Recip-e Solution Overview Figure 2 Sample prescription Figure 3 Integration Option 1 (Integration Modules) - Prescriber Figure 4 Integration Option 1 (Integration Modules) - Executor Figure 5 Integration Option 2 (Webservices) - Prescriber Figure 6 Integration Option 2 (Webservices) - Executor Figure 7 Addressed Encryption for Message transport Figure 8 Non-addressed encryption for Storage, Addressed Encryption for Message transport Figure 9 Addressed encryption for Storage, Addressed Encryption for Message transport Strictly confidential For Recip-e project member use only Page 15

18 LIST OF TABLES Table 1 External references Table 2 Kmehr validation checks Table 3 Authorization combinations Table 4 Sample SAML Strictly confidential For Recip-e project member use only Page 16

19 1 EXTERNAL REFERENCES Ref ID Name URL 1. Barcode Symbology Specified in ISO/IEC 15417: Non addressed Encryption -0.pdf 3. Addressed Encryption pdf 4. STS Cookbook Document is in attachment. Final URL will be included once available on ehealth portal. 5. ehealth certificates pdf 6. emed-ecare Use cases Barcode print guideline Specified in ISO/IEC Table 1 External references Strictly confidential For Recip-e project member use only Page 17

20 2 INTRODUCTION 2.1 RECIP-E SOLUTION The Recip-e solution concerns the generic (i.e. valid for all types of prescription: pharmaceutical, physiotherapist, nursing...) transfer of prescriptions from the prescriber to the care provider, for example from the general practitioner (GP) to the pharmacist, chosen freely by the patient or from the specialist to the physiotherapist. With the Recip-e solution, data can be sent between various actors with a high level of security. This technological innovation also offers improvements for everyone involved in the project. Below is a list of the added value that the Recip-e solution offers: Ensure roles and responsibilities of everyone; Integration with medical platforms for the identification of the actors, the security of the data and the control of the insurability of patients to ensure (eg ehealth, MyCareNet) Improving the administrative process and reduce administrative burdens Reduce erroneous prescriptions (errors in prescriptions) Relationship between the electronic and the paper stream is guaranteed Traceability of the data between the different actors. Traceability of the data access (consult) for privacy logging There are also immeasurable positive impacts foreseen thanks to the solution: Enhancing of the process (less fraud by avoiding patients to create fake prescriptions); Technically speaking Recip-e is not only a system that manages non-addressed messages in the health sector. Recip-e is also a system that provides advanced functionality such as prescription state, prescription validation, unique document numbering MyCareNet diensten MyCareNet diensten Prescriber (bijv. arts) Zorgverlener (bijv. apotheker) Software Voorschrijver Recip-e Module ehealth systeem Recip-e WS ehealth systeem Recip-e Module Software Zorgverlener Paper prescription Recip-e Web portaal Paper prescription Legende Beveiligde communicatie via Internet Patiënt Recip-e perimeter Software voor de professionele medewerkers van de gezondheid Diensten gebruikt door Recip-e Figure 1 Recip-e Solution Overview Strictly confidential For Recip-e project member use only Page 18

21 2.2 DESCRIPTION AND PURPOSE OF THE INTEGRATION SPECIFICATIONS This document establishes a set of requirements for the interface between Prescription Software/Executor Software and the RECIP-E system. It identifies agreed-upon design requirements and constraints that must be satisfied by the interfacing software. This document is intended for use by the developers of the applications identified, and by the test organizations responsible for the testing of these applications. 2.3 RESPONSIBILITY FOR THIS DOCUMENT This document is created and maintained by the RECIP-E team. 2.4 DOCUMENT SCOPE This document outlines the interface requirements to support the following business events for Prescription Software (doctors, dentists ) [P] and Execution software (pharmacist, nurses ) [E]: Create Prescription [P] (Un)Deliver a prescription [P E] Cancel a prescription [P E] Create[E]/Read [P] a feedback for a prescription AddressSend[P]/Read[E] a prescription notification List/Read Prescription [P E] The document also details the requirements to support the following technical events: Encryption Authentication Changes are required in Prescription/Executor software to integrate with RECIP-E. This document will detail integration procedure expected to be implemented by the Software Providers of said software. Note: The scope of this document will be extended in the near future to include an insurability check of the patient coming from MyCarenet services. 2.5 ADDITIONAL INFORMATION This document mainly presents technical information regarding integration with Recip-e. A clear view of the functional scope of Recip-e can be had by reading the use cases found in Ref 6 Furthermore, the management of electronic prescription has strong dependencies with generic services provided by ehealth platform. More information can be found in documents Ref : 2, 3, 4 and 5. Strictly confidential For Recip-e project member use only Page 19

22 3 INTEGRATION OPTIONS Software providers have two options to integrate with Recip-e: Option 1: integration modules: Recip-e provides a reference implementation of a full client able to achieve the different functionalities in scope (including authentication and encryption). These modules are delivered as JAR/DLL libraries. The code of the modules is Open Source (Java code delivered with Apache V2 License) Option 2: web services: Recip-e exposes a set of standard web services that allow achieving the different functionalities in scope. This option implies that some technical processing must be performed on client side (such as encryption, authentication at ehealth). This technical processing must be implemented by software providers. Note: The option 1 should be the default option. Strictly confidential For Recip-e project member use only Page 20

23 4 RESPONSIBILITIES The software provider will have to make sure that his application fulfils a set of requirements and thus whatever the integration option chosen. 4.1 IDENTIFICATION OF THE PATIENT The Patient must be identified by his INSS number (also named NISZ, NISS, and SSIN). Therefore, the health care software has the responsibility to provide a verified/validated INSS number. 4.2 PRESCRIPTION FORMAT A prescription is defined as being a specific XML KMEHR message (Kind Message for Electronic Healthcare Record) of type pharmaceutical prescription. This format is further described on ehealth website: On the one hand, the prescription software has the responsibility to generate a valid KMEHR prescription. On the other hand, executor software must be able to load such valid prescription. The validation of the prescription consists in a two-step validation process: XSD validation Additional validation The validation is automatically performed by Recip-e Integration Modules (Integration Option 1) KMEHR XSD VALIDATION The XML schema defining the KMEHR standard (XSD file) is provided in the Recip-e-client package and can be found on ehealth website at this URL: At this moment, the prescription must be compliant with the version kmehr of the XSD definition (XSD can be downloaded at this URL: ADDITIONAL VALIDATION The kmehr standard defines many different type of message regarding the healthcare sector. In the first stage of Recipe (pilot), only pharmaceutical prescription is accepted. However, in the next phases, the system will accept other kind of prescription (new version of this document will be available). For pharmaceutical prescription, additional verifications must be performed before uploading the prescription in Recipe system. The table bellow describes the different checks to be performed. For each check, a XML XPATH is defined. The result of the XPATH query must return the result defined in column "Expected Number of record" Description XPATH Expected Number of record Must contain 1 prescription /kmehrmessage/folder/transaction/cd[@s='cd- TRANSACTION' and text()='pharmaceuticalprescription'] 1 Must contain between 1 and 10 items /kmehrmessage/folder/transaction/heading/item/cd[@s='cd- ITEM' 1 to 10 (included) Strictly confidential For Recip-e project member use only Page 21

24 Valid Patient First name /kmehrmessage/folder/patient/firstname 1 Valid Patient Family /kmehrmessage/folder/patient/familyname 1 name Valid Patient ID /kmehrmessage/folder/patient/id[@s='id-patient' and Valid Prescriber /kmehrmessage/header/sender/hcparty//firstname 1 First name Valid Prescriber Family /kmehrmessage/header/sender/hcparty//familyname 1 name Valid Prescriber ID /kmehrmessage/header/sender/hcparty/id[@s='id-hcparty' 1 Table 2 Kmehr validation checks For more information about XPATH queries, please refer to SAMPLE PRESCRIPTION <?xml version="1.0" encoding="utf-8" standalone="no"?> <kmehrmessage xmlns=" <header> <standard> <cd S="CD-STANDARD" SV="1.1"> </cd> </standard> <id S="ID-KMEHR" SV="1.0"> </id> <id S="LOCAL" SL="ID-RECIPE" SV="1.0">8e1c4ea e4-bcc2b8cadfa7a897</id> <date> </date> <time>09:00:00</time> <sender> <hcparty> <id S="ID-HCPARTY" SV="1.0"> </id> <cd S="CD-HCPARTY" SV="1.0">persphysician</cd> <name>dr. Duck Donald</name> </hcparty> </sender> <recipient> <hcparty> <id S="ID-HCPARTY" SV="1.0">RECIPE</id> <cd S="CD-HCPARTY" SV="1.0">orgpublichealth</cd> <name>recip-e</name> </hcparty> </recipient> </header> <folder> <id S="ID-KMEHR" SV="1.0">1</id> <patient> <id S="ID-PATIENT" SV="1.0"> </id> <firstname>fred</firstname> <familyname> Flintstone</familyname> <birthdate> <date> </date> </birthdate> <sex> <cd S="CD-SEX" SV="1.0">male</cd> </sex> </patient> <transaction> <id S="ID-KMEHR" SV="1.0">1</id> <cd S="CD-TRANSACTION" SV="1.1">pharmaceuticalprescription</cd> <date> </date> <time>09:00:00</time> <author> <hcparty> <id S="ID-HCPARTY" SV="1.0"> </id> <cd S="CD-HCPARTY" SV="1.0">persphysician</cd> <name>dr. Duck Donald</name> </hcparty> Strictly confidential For Recip-e project member use only Page 22

25 </author> <iscomplete>true</iscomplete> <isvalidated>true</isvalidated> <expirationdate> </expirationdate> <heading> <id S="ID-KMEHR" SV="1.0">1</id> <cd S="CD-HEADING" SV="1.1">prescription</cd> <item> <id S="ID-KMEHR" SV="1.0">1</id> <cd S="CD-ITEM" SV="1.1">medication</cd> <content> <medicinalproduct> <intendedcd S="CD-DRUG-CNK" SV="2.0"> </intendedcd> <intendedname>adalat Oros 30 (c) 30mg </intendedname> </medicinalproduct> </content> <lifecycle> <cd S="CD-LIFECYCLE" SV="1.0">prescribed</cd> </lifecycle> <quantity> <decimal>1</decimal> </quantity> <frequency> <periodicity> <cd S="CD-PERIODICITY" SV="1.0">D</cd> </periodicity> </frequency> <dayperiod> <cd S="CD-DAYPERIOD" SV="1.0">evening</cd> </dayperiod> <posology> <text L="nl">1x</text> </posology> </item> <item> <id S="ID-KMEHR" SV="1.0">2</id> <cd S="CD-ITEM" SV="1.1">medication</cd> <content> <medicinalproduct> <intendedcd S="CD-DRUG-CNK" SV="2.0"> </intendedcd> <intendedname>actrapid HM Penfill (c) 100IU/ml </intendedname> </medicinalproduct> </content> <lifecycle> <cd S="CD-LIFECYCLE" SV="1.0">prescribed</cd> </lifecycle> <quantity> <decimal>1</decimal> </quantity> <posology> <text L="nl">2x/d 12E voor de maaltijd SC</text> </posology> </item> <item> <id S="ID-KMEHR" SV="1.0">3</id> <cd S="CD-ITEM" SV="1.1">medication</cd> <content> <medicinalproduct> <intendedcd S="CD-DRUG-CNK"S V="2.0"> </intendedcd> <intendedname>insulatard HM Penfill (c) 100IU/m </intendedname> </medicinalproduct> </content> <lifecycle> <cd S="CD-LIFECYCLE" SV="1.0">prescribed</cd> </lifecycle> <quantity> <decimal>1</decimal> </quantity> <posology> <text L="nl">1x/d 7E voor het slapen</text> </posology> </item> <item> <id S="ID-KMEHR" SV="1.0">4</id> Strictly confidential For Recip-e project member use only Page 23

26 <cd S="CD-ITEM" SV="1.1">medication</cd> <content> <medicinalproduct> <intendedcd S="CD-DRUG-CNK" SV="2.0"> </intendedcd> <intendedname>spironolactone E.G. (c) 100mg </intendedname> </medicinalproduct> </content> <lifecycle> <cd S="CD-LIFECYCLE" SV="1.0">prescribed</cd> </lifecycle> <quantity> <decimal>1</decimal> </quantity> <frequency> <periodicity> <cd S="CD-PERIODICITY" SV="1.0">D</cd> </periodicity> </frequency> <dayperiod> <cd S="CD-DAYPERIOD" SV="1.0">morning</cd> </dayperiod> <posology> <text L="nl">1x/d</text> </posology> </item> </heading> </transaction> </folder> </kmehrmessage> Example of a 'product' medication item: <item> <id SV="1.0" S="ID-KMEHR">1</id> <cd SV="1.2" S="CD-ITEM">medication</cd> <content> <medicinalproduct> <intendedcd SV=" " S="CD-DRUG-CNK"> </intendedcd> <intendedname>panadol tab 50x 1 g</intendedname> </medicinalproduct> </content>... </item> Example of a 'substance' medication item: <item> <id SV="1.0" S="ID-KMEHR">1</id> <cd SV="1.2" S="CD-ITEM">medication</cd> <content> <substanceproduct> <intendedcd SV=" " S="CD-INNCLUSTER"> </intendedcd> <intendedname>paracetamol 1 g</intendedname> </substanceproduct> </content>... </item> Magistral prescription : non-standardized (textual description) <item> <id SV="1.0" S="ID-KMEHR">1</id> <cd SV="1.2" S="CD-ITEM">medication</cd> <content> <compoundprescription L="FR">Prescription magistrale</compoundprescription> </content>... </item> Strictly confidential For Recip-e project member use only Page 24

27 4.2.1 CHECKING/SETTING THE AUTHOR OF THE PRESCRIPTION For prescription software, the prescriber defined in the KMEHR prescription must be the same as the user owner of the session (SAML session created by the service createsession()). For executor software, since the Recip-e system does not see the content of the prescription itself, it is up to the software of the executor to check that the name of the prescriber corresponds with the author as entered in the Kmehr message PRESCRIPTION TYPE When the prescription software is creating a prescription, the attribute prescription type must be correctly defined. During the pilot phase, only pharmaceutical prescriptions are in scope. Currently we have defined following 4 types of pharmaceutical prescriptions - P0 or PP: Pharmaceutical prescription - P1 : Pharmaceutical prescription that necessitates information on the patient s insurability P2 : Pharmaceutical prescription that necessitates attestation information The PP pharmaceutical prescription is only a temporary one, and will be dropped in the future in favor of the P0, P1 and P2 types. The software providers are encouraged to already implement the distinction between P0, P1, and P2. This distinction can be made by looking at the BCFI database and the prescribed medication. In general is expected from software provider to implement a solution open to any future updates of this prescription type. Note: this prescription type is important because it is used by the Recip-e system to define access rights for executors. The executor will only be able to read (decrypt) messages of types to which he has access. (e.g. a pharmacist has access to pharmaceutical prescriptions) 4.3 NOTIFICATION FORMAT When a prescriber creates a complex prescription, he has the possibility to send a notification message to a specific executor containing indication regarding the content of the prescription to be prepared or ordered (however, a notification message does not guarantee that the patient will come to this dedicated pharmacy). The notification can also contain a copy of the prescription itself. The Notification message before encryption is a XML message that must be compliant with following description XSD VALIDATION The File Notification.xsd provided in the Recip-e client package describes the format of a feedback. Content of the file: <xs:schema xmlns:xs=" xmlns:km=" xmlns=" targetnamespace=" <xs:import namespace=" schemalocation="../ kmehr/ehealth-kmehr/xsd/kmehr_elements.xsd"/> <xs:element name="notification"> Strictly confidential For Recip-e project member use only Page 25

28 <xs:complextype> <xs:sequence> <xs:element name="text" type="xs:string" maxoccurs="1" minoccurs="0"/> <xs:element name="kmehrmessage" type="km:kmehrmessagetype" maxoccurs="1" minoccurs="0"/> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> SAMPLE FILE <?xml version="1.0" encoding="iso "?> <p:notification xmlns:p=" xmlns:xsi=" xsi:schemalocation=" notification.xsd"> <text>this is a notification</text> <kmehrmessage>[the Kmehr prescription] </kmehrmessage> </p:notification> 4.4 FEEDBACK FORMAT When requested by the prescriber, a Feedback may be sent back by the prescription executor (pharmacist) once prescription is delivered. The Feedback before encryption is a XML message that must be compliant with following description XSD VALIDATION The File Feedback.xsd provided in the Recip-e client package describes the format of a notification. Content of the file: <xs:schema xmlns:xs=" xmlns=" targetnamespace=" <xs:element name="feedback"> <xs:complextype> <xs:sequence> <xs:element name="text" type="xs:string" maxoccurs="1"/> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> SAMPLE FILE <?xml version="1.0" encoding="iso "?> <p:feedback xmlns:p=" xmlns:xsi=" xsi:schemalocation=" feedback.xsd"> <text>this is a feedback</text> </p:feedback> Strictly confidential For Recip-e project member use only Page 26

29 4.5 AUTHENTICATION & AUTHORIZATION DEFINITION In this document, what is named the Recip-e session is in practice a SAML token generated by ehealth. Once obtained by the care provider, this token allows calling each one of the Recip-e services. The validity of this token is limited in time SESSION CREATION The authentication must be done at session start-up and uses eid of a physical user (+ PIN code) organizational ehealth Certificate, linked to a particular software installation and containing a responsible person This authentication is validated by ehealth and a work session (by means of a SAML token) is generated. The validity of the session is sector dependant. This should be a variable defined with default and maximum values as 5H for Prescribers and 12H for Executors. This also means that the prescribers and executors will have not have to enter their eid and pin more than once or twice per day (i.e. after their session token expires) Following combinations will be allowed to access the Recip-e system: Care Provider eid Certificate Prescriber (e.g. doctor) e-id of prescriber ehealth certificate containing a responsible (does not have to be a pharmacist; e.g. doctor himself when single doctor, main doctor in doctors practice, main responsible in hospital, director in retirement home ) Pharmacist e-id of pharmacist EHealth certificate linked to the pharmacy (identified by the NIHII-PHARMACY). This certificate also contains a responsible (does not have to be a pharmacist; e.g. owner of pharmacy). Non-Pharmacist Executor (e.g. physiotherapist, nurse ) e-id of executor ehealth certificate containing a responsible (does not have to be an executor; e.g. director in retirement home ) Table 3 Authorization combinations For prescriber, as stated in the Certificate column, the certificate can be of different types: 1. A private practice certificate (dentist, specialist, ) 2. A group practice certificate : group practice identification number (provided by ehealth) 3. A Retirement home certificate : identified by a NIHII-RETIREMENT 4. A Hospital certificate: identified by NIHII-HOSPITAL. This is also valid for nurses. For Pharmacists: The certificate must be the one linked to the pharmacy (identified by NIHII-PHARMACY). The software provider has the responsibility to make sure that the care provider: Strictly confidential For Recip-e project member use only Page 27

30 - Has a valid card reader setup on his machine, this reader must be able to read Belgium EID card (card reader requirement are described on web site - Has a valid ehealth certificate stored in a secured Keystore (p12 file). Refer to doc [5] SESSION CREATION FALLBACK A fallback exists to create the session in case of the care provider does not have his EID with him, his EID is broken,... This fallback uses the personal encryption key of the prescriber or executor (used for addressed encryption), instead of using the EID. The session created with the fallback mechanism is limited in time to 1H (this time is configurable, and will be further refined during the course of the pilot). This means that every hour, the care provider will have to enter is user (his nihii id) and his password (the passphrase of the keystore containing the ehealth certificates). This fallback shall not be the default authentication solution. On top of that, it is expected from software vendors that they does not automate the user/password input (no password recording possible). Technical details of the fallback function are being further worked out, and any further requirements to do with the fallback solution, will be defined in a later version of this document. In order not to delay delivery of integration with the Recip-e solution, at this time, the integration module already foresees an interface for the creation of the fallback session. Refer to function createfallbacksession() for more information SESSION STOP Once authenticated, modules keep in memory the SAML token. This SAML token is a key element is authentication mechanism and therefore must be destroyed if the care provider does not need to use Recip-e services any more. It is expected from software provider that this session is correctly destroyed (See API unloadsession) once the care provider shutdown his software/computer. Software providers also have the possibility to secure even more this token by unloading it in case of care provider inactivity. Ex: if the prescriber do not use his software for a defined period (ex: 30 minutes), the session is automatically unloaded. If the prescriber wishes to use a Recip-e service again, he will have to enter his PIN code ACCESS TO KEYSTORE Since the keystore contains the different certificates and public/private keys of all people using the pc, special attention should be put on the protection and access to this keystore. The software vendors are expected to adhere to following points: The software should allow the end-user to easily delete his personal keys from the keystore. The taken approach should be user-friendly (e.g. without the user having to enter the different keystore commands) The software should allow an administrative person (e.g. the owner of the pharmacy, the main doctor ) to easily delete any of the personal keys from the keystore. The taken approach should be user-friendly (e.g. without the user having to enter the different keystore commands) The software should enforce that only the user to which the keys belong, has access to his personal keys. This to prevent for instance the case where a user would be able to start an emergency session in the name of another user whose keys reside in the same keystore. This can for instance be done by linking the concept of a user account to the password which is used to access the private keys of a particular user. 4.6 BARCODE SPECIFICATION On top of the prescription, a new barcode will be found that contains the Recip-e ID of the prescription. This barcode needs to be compatible with the current barcode readers found in pharmacies. Strictly confidential For Recip-e project member use only Page 28

31 4.6.1 FORMAT RECIP-ID The Recip-ID (or RID) has format BEPPXXXXXXXX where BE is a 2-character alphanumerical id that stands for the country (BE = Belgium) PP is a 2-character alphanumerical id that stands for the type of prescription (PP = general pharmaceutical prescription). Refer to Prescription Type section for more information on available prescription types. XXXXXXXX an 8-character alphanumerical sequence ID The alphanumerical characters can be numbers or uppercase letters: o o Possible characters are ABCDEFGHKLMNPRSTVWXYZ Due to possible ambiguity letters O, Q, I, J, U and V are not used The Recip-ID will be provided by ehealth during the creation of a prescription FORMAT BARCODE The 128A format is used for the barcode. The barcode symbology is specified in ISO/IEC 15417:2007 Example: 4.7 PRINT PRESCRIPTION (FOR PRESCRIBERS) BARCODE The Prescription software must print the prescription ID as a barcode on the paper prescription. The prescription layout is defined on inami/riziv portal: - NL : - FR : This barcode must be printed in the upper part of the prescription. The print quality of the barcode must be compliant with the ISO15416 specification (Bar Code Print Quality Guideline: this specification describes requirement in term of quiet zones, reflectance, contrast ). Strictly confidential For Recip-e project member use only Page 29

32 Figure 2 Sample prescription MEDICATIONS Strictly confidential For Recip-e project member use only Page 30

33 The list of medications must be printed on the prescription (middle right area). This printable area is limited in term of lines and characters per line. The limit is currently set to 10 lines with each 80 characters. Each medication must be printed on a dedicated line. If a medication is printed on two lines, the prescription software must make sure that the overall prescription does not exceed 10 lines. If this is the case, a new prescription with a new RID must be created. 4.8 ARCHIVING (FOR EXECUTOR SOFTWARE) The executor has the responsibility to archive the prescription and its meta-data once delivered. Recip-e recommends that the archive contain for each delivered Prescription: - The prescription in format SealedForUnknown (this format is further described in the Encryption part of the document). It contains digital signature of the prescriber. - The time stamp ID provided by Recip-e. It gives the proof that the prescription has existed at a specific point in time. The timestamp contains the Hash of the prescription and the creation date in an envelope signed by e- health. - The Encryption Key for the prescription, provided by ehealth. When using the integration modules all required information is returned by the getprescription function (see "getprescription" (for Executor) [Executor Integration Module]): - Prescription: variable sealedcontent in the return of the getprescription function - Time stamp ID: variable timestampingid in the return of the getprescription function - e-health encryption key: variable encryptionkey in the return of the getprescription function When using the web services, part of the information is returned by the getprescription action of the ExecutorServices webservice (see "getprescription" (for Executor) [Executor Services]), part of the information is returned by the getkey operation of the e-health KGSS web service (see KGSS): - Prescription: element prescription in the decrypted content of element securedcontent of getprescription - Time stamp ID: element timestampingid in the decrypted content of element securedcontent of getprescription - e-health encryption key: element key in the decrypted content of element sealedcontent of getkey Furthermore, Recip-e recommends that - the archiving happens in a secure way (e.g. secure communication, secure storage, )since the information stored in the archive allows insight into the prescription data, access to the archive should be restricted to the pharmacist responsible for the archived prescription, and parties having rights to the information for a particular need (e.g. legal investigations, ) - each archiving is linked to a unique key, and the executor software stores the link between the archiving unique key and the Recip-e ID Besides this, the executor software has the responsibility to notify Recip-e when the prescription has been archived by using the MarkAsArchived functionality (see "markAsArchived" [Executor Integration Module] when using the integration module, and "markasarchived" [Executor Services] when using the web services). From this moment on, the prescription can be deleted in the central Recip-e system. 4.9 PERFORMANCE METRICS UPLOAD During the pilot, Recip-e needs to receive information about performances of services used in the solution (such as ehealth response time, create Prescription response time). These performance metrics do not contain information regarding care provider work (only response times of technical services). The care provider must be warned that such metrics are collected on his workstation. Recip-e expects that software providers warned their care provider before the activation of the collect. Strictly confidential For Recip-e project member use only Page 31

34 Depending on the Integration Option: Option 1 with modules: the collect of performance measures is included in the module. A CSV file is generated under the execution directory folder. This file is uploaded on a regular basis on Recip-e server (Activation and frequency is defined in the log4j.xml configuration file, by default is is uploaded once day in background). Option 2 - with web services: software providers must store in a local CSV file all services response times. This file should be uploaded on Recip-e server on a regular basis (application start-up, during the night...). The file structure should be the default perf4j structure (See Sample: start[ ] time[1945] tag[executorintegrationmodule#getprescription.success] start[ ] time[50] tag[executorintegrationmodule#createsession.success] Where o Start : is the start date of the service call (universal date as a long) o Time is the time to call the service in ms o Tag is the name of the function you have called suffixed by.success,.failure depending on the response you receive from the service. Once collected, the file should be compressed (gzip) and uploaded with the service [Pescriber/Executor]Service.upload(). Strictly confidential For Recip-e project member use only Page 32

35 5 INTEGRATION OPTION 1: MODULES 5.1 OVERVIEW PRESCRIBER SOFTWARE The section below describes the technical scope of the development work, concerning functionalities to foresee by the Software Provider in the software of the Software Provider to integrate with the Recip-e system and ehealth. The figure below shows all the actions to be performed by the Software Provider s software and the way it is to be integrated with the Recip-e system. A C B createsession() SAML Token ehealth Services createprescription (KmehrMessage) RID D SendNotification (RID) RevokePrescription (RID) ehealth ESB Doctor Software E ListFeedbacks() Recip-E Integration Module GetPrescription(RID) Recip-e Central System F G ListOpenPrescriptions() H UpdateFeedbackFlag() Figure 3 Integration Option 1 (Integration Modules) - Prescriber The red rectangle represents the software of the Software Provider for Prescribers. The green rectangle represents the Recip-e integration module which allows interacting with the Recip-e central system and ehealth common services. We consider two types of functionalities: Strictly confidential For Recip-e project member use only Page 33

36 Communication functionality provided by the Recip-e integration module (or, if the Software Provider opts not to use the Integration module, to be implemented by the Software Provider, based on this document) - arrows between the green and red rectangles Internal functionality within the Software Provider software circle-arrows within the rectangle Communication functionality: 1. Session Management : a. Create Session : Send a session creation request to ehealth b. Load Session: Load a previously loaded session c. Unload Session : Unload the current session 2. Create Prescription: Send a prescription to the Recip-e Integration module. The software receives in return the RID (Recip-e ID). The prescriber can decide if want to get a feedback from the executor. 3. Send Notification: The prescriber has the option to send a notification directly to an executor. This could for instance contain a prescription to prepare or a personal message 4. List Feedback: Ask for feedback sent by executor. In return the software receives all feedbacks addressed to him. 5. Revoke Prescription: If the prescriber chooses so, he can revoke/cancel a prescription. The cancellation of a prescription by the prescriber should be communicated to the Recip-e system. The cancellation request is sent to the module with the Recip-e unique identification number (RID). The prescriber receives a confirmation that the prescription has been cancelled. 6. List Open Prescriptions: The Software Provider software requests an update from the Recip-e central system concerning the status of its prescriptions. It obtains a list of prescriptions with their status. 7. Get Prescription: The Software Provider can retrieve a prescription previously created. 8. Update Feedback Flag: the software provider change the feedback flag set previously (Action 1) Internal functionality A. Identify the patient through the NISS/NISZ number found on the patients ID card information on the patients SIS card information on the patients mutuality sticker directly into the system the executor (if the patient is already in the system) B. Use MyCareNet services such as patient rights such as insurability (this is currently not in scope of the integration specifications, but is included here for clarity sake) C. Create a prescription in the Software Provider software and attach it to the patient record in the Software Provider software D. Add the unique identification number (Recip-e ID) of the electronic prescription (received from Recip-e) to the prescription, and print the prescription with RID on it in barcode format E. The prescriber has the option to send a message directly to an executor. This could for instance contain a recipe to prepare or a personal message. The Service Supplier software needs to allow the prescriber to input such a message F. Insert the received feedback into the patient record in the Software Provider software G. Cancel the prescription from the patient record in the Software Provider software (only when requested by the prescriber) H. Consult Open Prescription (prescription that are still in status NotDelivered ). For performance reasons, the list of open prescription can be updated in batch mode (e.g. once a day). Strictly confidential For Recip-e project member use only Page 34

37 5.1.2 EXECUTOR SOFTWARE The figure below shows all the actions to be performed by the Software Provider s for executor (Executor/Pharmacist) and the way it is to be integrated with the Recip-e system and ehealth services. createsession() SAML Token A B C ehealth Services GetPrescription(RID) ehealth ESB Recip-E Integratio n Module MarkAs(Un)Delivered(RID) D Pharmacist Software MarkAsArchived(RID) E Recip-e Central System CreateFeedback(XMLFeedback) F ListAddressedPrescriptions() G Figure 4 Integration Option 1 (Integration Modules) - Executor Communication functionality 1. Session Management : a. Create Session : Send a session creation request to ehealth b. Load Session: Load a previously loaded session c. Unload Session : Unload the current session 2. Get Prescription: Get the prescription using the Recip-e ID found in barcode format on the prescription provided by the patient. FAlso for P1 prescriptions there is also the possibility to request the insurability can be requested.of the patient. 3. Mark Prescription As (un)delivered: Software Provider software signals the Recip-e system that the prescription (or at least one item on the prescription) has been delivered. The Integration module returns a Confirmation 4. Mark Prescription As archived: Software Provider software signals the Recip-e system that the prescription has been archived. The Integration module returns a Confirmation 5. Send feedback: Send feedback on the prescription to the prescriber system (the feedback must contain the name of prescriber, patient name and prescription to which it relates). The Integration module returns a Confirmation. 6. List Notifications: Get all notifications from prescribers directed to this executor (The prescriber can send a text message to a specific executor. (e.g. could contain a recipe to be prepared)). The Integration module returns a Confirmation Get Insurability: retrieve the patients insurability information. The integration module returns a string representation of the xml. Strictly confidential For Recip-e project member use only Page 35

38 Internal functionality A. Identify the patient through the NISS/NISZ number found on the patients ID card information on the patients SIS card information on the patients mutuality sticker directly into the system the executor (if the patient is already in the system) B. Identify the prescription by reading the barcode containing the prescription number on the paper prescription C. Check the insurability of the patient on MyCareNet (this is currently not in scope of the integration specifications, but is included here for clarity sake) D. Translate the prescription returned from the Recip-e system into the internal format of the Software Provider software, save the prescription in the Software Provider software, and show the prescription to the pharmacist E. Create feedback for the prescription - providing an additional screen that allows the introduction of feedback for a prescription. Multiple feedbacks on the same prescription are possible. F. Get all notifications The prescriber can send a text message to a specific executor. (e.g. could contain a prescription to be prepared). The pharmacist software needs to be able to show this. G. Archiving of the prescription: once archived (out of scope of the specification), the executor software notifies recip-e system. 5.2 INTEGRATION DETAIL APPROACH The approach suggested to use Recip-e integration modules is: 1. Integrate the mock API in your software (no Recip-e backend needed). 2. Configure the modules to use Recip-e Acceptance web services (basic authentication) via the Belgacom VPN (ask Accenture for url/user & passwords) 3. Configure the modules to use ehealth platform (ESB, SAML Services and EID authentication) MOCK Each integration module has a mock version of the API. This mock version has the same API footprint than the real API. This mock version allows software vendors to update their application without needing a real Recip-e back-end. For prescriber, the mock module is be.recipe.client.mock.prescriberintegrationmodulemock. For executors, the mock module is be.recipe.client.mock.executorintegrationmodulemock. Sample instanciation of the mock module: BASIC AUTHENTICATION Strictly confidential For Recip-e project member use only Page 36

39 Recip-e web services can be used in test environment using basic http authentication (user, password). To enable the basic authentication, define a user & password property in your configuration file. Send a request to Recip-e team to get a test login/password and the web service URL of the services EHEALTH SERVICES Once you have successfully integrated Recip-e API, you can replace the integrationmodulemock by the e-health connected moduleservices, you will need to update your configuration to use eheath platform: Authentication: ehealth SAML services should be use to create a user session (SAML token). To enable SAML authentication: remove the password property of the configuration file. Update the property wsdl.sts with the ehealth STS URLs (line in comment to be uncommented) ESB: Send a request to Recip-e team to get the URL of Recip-e services via the ehealth ESB (an update of the integration module may be required), this request should include SSIN of your test users (thoses SSIN will be declared as Prescriber/Pharmacist in the STS configuration).. This module are available : - For Prescriber : in the class be.recipe.client.prescriberintegrationmodule - For Executor : in the class be.recip.client.executorintegrationmodule Both modules take in argument the path to the Recip-e configuration file JAVA The JAR files contained in the folder jar/. of the Recip-e-client.zip package must be added to your class path. Then, add following import in your code: Prescriber/Executor APIs can then be invoked using code: Sample Code for Prescriber: Sample code for Executor: Strictly confidential For Recip-e project member use only Page 37

40 Refer to Service Inventory for the full list of all available functions and their associated input/output parameters. For performance reasons, the initialization of the class xxxxintegrationmodule() should be done once at application start-up DLL The DLL files contained in the folder dotnet/. of the Recip-e-client.zip package must be added to your project dependencies. Then, add an import statement in your code. Sample code in VB.NET : Imports be.recipe.client Then, the Recip-e client can be used with the code (VB.NET): Strictly confidential For Recip-e project member use only Page 38

41 5.2.4 MODULE CONFIGURATION In next section, following notation is used: - ${INSTALL_DIR}: represents the folder containing the recipe client binary files (Jars or Dlls). -.. Configuration parameters for Integration Modules are defined in the file ${INSTALL_DIR}/conf/recipe-client.properties The Path to the configuration file should be defined in argument of the module constructor MYCARENETYCARENET As pharmacist there is the possibility to request information about the insurability of the patient. To request this information it will be necessary to add the following property in the configuration file. niss.mycarenet= This parameter represents the pharmacy holder, it is mandatory to create your session with ehealth and MyCarenet. The executor module provides two ways to request insurability: - When requesting a prescription (orchestration) - Directly with MyCareNet thru ehealth ESB ORCHESTRATION When the getprescription functionality is called, from the Executor module, there is the possibility to request more information about the insurability of a patient. ( This can only be done for P1 prescriptions. ). The insurability can only be requested for P1 prescriptions. With the following parameter in the configuration file you can enable and disable the insurability retrieval. patient.insurability.disable=false The following properties should be defined in the configuration file. niss.mycarenet= patient.insurability.disable=false Where : niss.mycarenet is the NISS number of the pharmacy owner DIRECT CONNECTION There is also the possibility to call MyCareNet insurability directly. There is an API integrated into the Executor module to call the MyCareNet directly. The following steps need to be done to use the direct connection : - Request User, password and packagename to MyCareNet support - Create a e-health STS session with the module (normal or fallback) Strictly confidential For Recip-e project member use only Page 39

42 - Use the getinsurability() method of the Executor module to request the insurability. More information on the input parameters can be found on MyCarenet sharepoint ( ) Sample Insurability response <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ns3:getinsurabilityforpharmacistresponse xmlns:ns2="urn:be:fgov:ehealth:insurability:core:v1" xmlns:ns4="urn:be:fgov:ehealth:recipe:protocol:v2" xmlns:ns3="urn:be:fgov:ehealth:insurability:protocol:v1"> <Status> <Code>200</Code> <Message>Success</Message> </Status> <ns3:commonoutput> <ns2:reference> </ns2:reference> </ns3:commonoutput> <ns3:recordcommonoutput> <ns2:reference>278</ns2:reference> <ns2:ioreference>0</ns2:ioreference> <ns2:userreference> </ns2:userreference> </ns3:recordcommonoutput> <ns3:returninfo> <ns2:returncode> <ns2:major>01</ns2:major> <ns2:minor>00</ns2:minor> <ns2:detail>00000</ns2:detail> </ns2:returncode> </ns3:returninfo> <ns3:insurabilityresponse> <ns2:carereceiver> <ns2:ssin> </ns2:ssin> <ns2:regnrwithmut> </ns2:regnrwithmut> <ns2:mutuality>111</ns2:mutuality> <ns2:firstname>yannick ERIK</ns2:FirstName> <ns2:lastname>landuyt</ns2:lastname> <ns2:birthday> </ns2:birthday> <ns2:sex>male</ns2:sex> </ns2:carereceiver> <ns2:coverage> <ns2:communicated> </ns2:communicated> <ns2:period> <ns2:begindate> </ns2:begindate> <ns2:enddate> </ns2:enddate> </ns2:period> <ns2:entitlement> <ns2:code1>110</ns2:code1> <ns2:code2>110</ns2:code2> <ns2:thirdpartypayerregime>standard</ns2:thirdpartypayerregime> </ns2:entitlement> </ns2:coverage> <ns2:verification> <ns2:paymentapproval>f321c0fe9a63a5ec144d5c790df33290</ns2:paymentapproval> <ns2:paymentapprovalseed> </ns2:paymentapprovalseed> <ns2:invoicingofficecheckdigit>sh</ns2:invoicingofficecheckdigit> </ns2:verification> </ns3:insurabilityresponse> </ns3:getinsurabilityforpharmacistresponse> CERTIFICATES Pre-requisite: the care provider owns ehealth certificates (See Document Ref 5). These certificates are stored in a key store. The document Ref 5 describes in detail how to generate and register the certificates in ehealth and then store it in a key store (a p12 file). For the moment, this procedure requires two steps : - Administrative: the care provider needs to sign a certificate request. Strictly confidential For Recip-e project member use only Page 40

43 - Technical: a set of commands to run with the tool openssl. EHealth has foreseen to change this technical procedure into an online procedure. The properties of the key store must be defined in the configuration file as following: - KEYSTORE_FILE: Name & PATH of the system key store file (absolute PATH starts from ${INSTALL_DIR} folder. The keystore must be a PKCS12 keystore ( *.p12 ). The authentication certificate must have the alias authentication. - KEYSTORE_TYPE: The type of key store (such as: JKS, PKCS12 ) - KEYSTORE_PASSWORD: the passphrase/password of the system key store. This password is defined during the certificate generation procedure. - KEYSTORE_AUTH_ALIAS: alias of the EHealth authentication certificate Overview of a system keystorekey store opened with Keystore explorer: Sample key store section of the recipe-client.properties configuration file: KEYSTORE_FILE=%CONF%/p12/CBE= , MEDISOFT p12 KEYSTORE_FILE =%CONF% /Doctor1.p12 KEYSTORE_TYPE = PKCS12 KEYSTORE_PASSWORD = doctor1 KEYSTORE_AUTH_ALIAS = doctor1_auth For multi-user access or fall-back session creation (e.g.: several doctors sharing the same workstation), it is possible to define those parameters for each one of the care provider. If so, the NISS id of the doctor should be suffixed to the property namecopy the personal key pair in a specific folder identified by the configuration parameter KEYSTORE_AUTH_P12_FOLDER. The naming convention for the keypair is SSIN=<niss of the care provider>_<creation time>.p12. (Same name then the one generated by e-health procedur). See Annex Certificate Creation. Example of content of the KEYSTORE_AUTH_P12_FOLDER : Strictly confidential For Recip-e project member use only Page 41

44 #Default values KEYSTORE_FILE = /Doctor1.p12 KEYSTORE_TYPE = PKCS12 KEYSTORE_PASSWORD = doctor1 KEYSTORE_AUTH_ALIAS = doctor1_auth # Specific values for doctor KEYSTORE_FILE_ = /Doctor1_ p12 KEYSTORE_TYPE_ = PKCS12 KEYSTORE_PASSWORD_ = other_password KEYSTORE_AUTH_ALIAS_ = doctor2_auth WSDLS Recip-e integration modules are connected to different web services. The URL of each service can be customized if needed. Indeed, for test purpose, it can be interesting to use services of acceptance platform. Only change these parameters if it is requested by Recip-e team. Following WSDLs URL are defined in the configuration file: - wsdl.ehealth.prescriber WSDL_PRESCRIBER: Recip-e web services URL that should be used by Prescriber (for CreatePrescription ) - wsdl.ehealth.executorwsdl_executor: Recip-e web services URL that should be used by Prescription executor (for Prescription Delivery ) - wsdl.stswsdl_sts : EHealth secure token service URL (SAML assertion generator) - wsdl.etkwsdl_etk : EHealth ETK Depot URL (public key repository) - wsdl.kgsswsdl_kgss: EHealth Encryption key generator & storage service URL. - wsdl.ehealth.insurability: MyCareNet service URL LOGS The log configuration parameters are defined in the file ${INSTALL_DIR}/log4j.xml. Refer to log4j documentation for the customization of logging parameters. The default parameters are: - The Log level is set to DEBUG - The default Log file is set to recipe-client.log - A new file is created each new day; the previous file is then renamed and zipped in recipeclient.log.yyyymmdd.zip. - A history of 7 days is stored on the file system, older files are removed. Strictly confidential For Recip-e project member use only Page 42

45 5.3 SEVICE INVENTORY This section lists all available API in the integration modules "CREATESESSION" [PRESCRIBER INTEGRATION MODULE, EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description When to be triggered createsession PrescriberIntegrationModule,ExecutorIntegrationModule This function creates a user session based on the EID of the user (PIN code is then required) and his ehealth certificate. The session created is an XML SAML token; this token is not linked to a particular machine. Therefore, on the one hand, it must be protected to prevent malicious system to stole this token, on the other hand, the token can be shared in multi computer environment (such as pharmacy).see loadsession When the user starts his application When the stored token has exceeded his validity period Errors Technical Services Exception such as Connection failure, Encryption failure EID card reader issue (no card, unreadable card). Inputs Integration Module Order Type Name Description Output Integration Module Type Name Description String xmlsamltoken SAML response obtained from ehealth STS service. The SAML token has a validity of 5H for prescribers, 12H for executors. (This time is configurable, and will be further refined during the course of the pilot). This SAML token can be stored by the software provider (in a file or in a database). The function "loadsession" should be use to restore the session. Implementation Detail Step Description 1 The module initializes the BEId framework. Read the EID card 2 PIN code of the end-user is requested 3 A SAML Request is created and signed with the certificate and sent to ehealth STS Strictly confidential For Recip-e project member use only Page 43

46 4 The module returns the SAML token as an XML message. This XML message can be stored on the hard disk (Cookie like) "LOADSESSION" [PRESCRIBER INTEGRATION MODULE, EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description loadsession PrescriberIntegrationModule,ExecutorIntegrationModule This function should be used to reload a stored session When to be triggered When the prescriber wants to reload an active session (after a computer shutdown) Errors Technical Services Exception such as Connection failure, Encryption failure EID card reader issue (no card, unreadable card). Inputs Integration Module Order Type Name Description 1 String xmlsamltoken The SAML token received by "createsession" Output Integration Module Type Name Description Implementation Detail Step Description 1 The module is initialized with the given SAML token, all WS exchanges with Recip-e will use this token. Strictly confidential For Recip-e project member use only Page 44

47 5.3.3 "UNLOADSESSION" [PRESCRIBER INTEGRATION MODULE, EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description unloadsession PrescriberIntegrationModule,ExecutorIntegrationModule Unload the current session. When to be triggered When the user is shutting down his application After a long period of inactivity (definition of this period of inactivity under the responsibility of software providers). Errors Inputs Integration Module Order Type Name Description Output Integration Module Type Name Description Implementation Detail Step Description 1 The module destroys is current SAML token. Strictly confidential For Recip-e project member use only Page 45

48 5.3.1 "CREATEFALLBACKSESSION" [PRESCRIBER INTEGRATION MODULE, EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description createfallbacksession PrescriberIntegrationModule,ExecutorIntegrationModule Create a session using ehealth certificates (EID is not needed) When to be triggered When the user does not have his EID with him. Errors Invalid password Inputs Integration Module Order Type Name Description 1 String userid The NIHII Id of the care provider (INAMI/RIZIV for prescriber, NIHII-PHARMACY for pharmacists) 2 String passphrase The passphrase of the Keystore containing ehealth certificates. Output Integration Module Type Name Description String xmlsamltoken SAML response obtained from ehealth STS service. The SAML token has a validity of 4H for prescribers, 12H for executors. This SAML token Strictly confidential For Recip-e project member use only Page 46

49 can be stored by the software provider (in a file or in a database). The function "loadsession" should be use to restore the session. Implementation Detail Step Description 1 A SAML Request is created and signed with the certificate and sent to ehealth STS 2 The module returns the SAML token as an XML message. This XML message can be stored on the hard disk (Cookie like) "HASVALIDSESSION" [PRESCRIBER INTEGRATION MODULE, EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description hasvalidsession PrescriberIntegrationModule, ExecutorIntegrationModule Check if the current session (SAML token) is valid. When to be triggered Before calling a Recip-e service, this method check that session has not expired.this method can be called at any time to check the validity of the SAML token. Errors Inputs Integration Module Order Type Name Description Strictly confidential For Recip-e project member use only Page 47

50 Output Integration Module Type Name Description Boolean sessionvalidity A Boolean that states if the session is still valid. Implementation Detail Step Description 1 The module checks if the current session is still valid "PREPARECREATEPRESCRIPTION" [PRESCRIBER INTEGRATION MODULE] Operation Name Class Name Description preparecreateprescription PrescriberIntegrationModule Optional API. This API should be used to improve performances of "createprescription". It retrieves the different encryption keys to be used for "createprescription". When to be triggered When the prescriber has identified his patient. (This API can be invoked while he is typing the content of the prescription) Errors Inputs Integration Module Order Type Name Description Strictly confidential For Recip-e project member use only Page 48

51 1 Long patientid The ID of the patient Output Integration Module Type Name Description Implementation Detail Step Description 1 Retrieves Encryption keys of KGSS, Recip-e. Create the symmetric key for addressed encryption "CREATEPRESCRIPTION" [PRESCRIBER INTEGRATION MODULE] Operation Name Class Name Description When to be triggered createprescription PrescriberIntegrationModule This action stores the prescription (Kmehr format) in Recip-e central system. This function takes care of the encryption (transport and storage). It returns the RID (Recipe ID) to be printed on the paper prescription (RID = "BEYYXXXXXXXX" where Be is the country, YY is the prescription type (ex : PP : pharmaceutical prescription) and XXX the ALPHANUM sequence ID) When the prescriber has generated a local prescription (XML Kmehr format), this function must be used to store it in Recip-e secured storage. Errors Technical Services Exception such as Connection failure, Encryption failure Encryption Error : when Recip-e can't decrypt the message Inputs Integration Module Order Type Name Description Strictly confidential For Recip-e project member use only Page 49

52 1 boolean feedbackrequested Set to true if the prescriber wants to receive a feedback from the executor 2 Long patientid INSS number of the patient 3 byte[] prescription Prescription content as a Validated XML Kmehr message. If the Prescription Type is set to PP, the prescription must contain a valid pharmaceutical prescription. (See XSD KMEHR Validation) 4 String prescriptiontype Type of prescription, will be used to generate the prescription ID and define what the allowed profiles for the delivery are. Refer to Prescription Type section for available prescription types Output Integration Module Type Name Description String rid RID of the prescription (size = 12 chars) Implementation Detail Step Description 1 The module checks the SAML token. 2 The module requests the Encryption Token (Signed Public Key) of the KGSS service to ETK Depot (ehealth service) 3 The module generates a "Symmetric Key request" (including the key access control list) 4 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (Recipient is KGSS) 5 The Sealed Response is received from Kgss, the module decrypt it. It contains the secured encryption key 6 The KMEHR Prescription is ciphered with the "sealforunknown" function of the ETE framework using the symmetric key 7 The message is enriched with meta data (recipient id ) 8 A ciphered message is generated with the "seal" function of the ETE framework (Recipient : Recip-e), the message is sent to Recip-e 9 The message is decrypted. (Method "unseal()" of the ETEE framework is used). The response contains The RID of The prescription "SENDNOTIFICAITON" [PRESCRIBER INTEGRATION MODULE] Operation Name Class Name Description sendnotification PrescriberIntegrationModule This function sends a notification to a specific executor. The notification indicates that a client is likely to retrieve/execute his prescription with him. Strictly confidential For Recip-e project member use only Page 50

53 When to be triggered - When a patient has habits in a specific pharmacy - When the product requires an ordering, Errors Technical Services Exception such as Connection failure, Encryption failure ETK not present: the executor does not have a registered public Key at ehealth Inputs Integration Module Order Type Name Description 1 byte[] notificationtext Xml message containing the notification. Must be validated by the provided XSD 2 Long patientid INSS number of the patient 2 Long executorid NIHII-PHARMACY (APB+check digit) id of the recipient. Output Integration Module Type Name Description Implementation Detail Step Description 1 The module checks the SAML token. 2 The module requests the Encryption Token (Signed Public Key) of recipient to ETK Depot (ehealth service) 3 The module generates an XML request. 4 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is the prescriber) 5 The message is enriched with meta data (recipient id ) 6 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 7 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "REVOKEPRESCRIPTION" [PRESCRIBER INTEGRATION MODULE, EXECUTOR INTEGRATION MODULE] Operation Name Class Name revokeprescription PrescriberIntegrationModule, ExecutorIntegrationModule Strictly confidential For Recip-e project member use only Page 51

54 Description Revoke the prescription (the prescription is removed from Recip-e system). It is then not possible to deliver it any more. When to be triggered Errors When prescriber has done a mistake, he can use this function to revoke the bad prescription and then create a new one with the function "createprescription". An executor can also decide to revoke a prescription. For instance in the case where the patient request the executor to delete the prescription without delivering the prescribed items. Technical Services Exception such as Connection failure, Encryption failure Inputs Integration Module Order Type Name Description 1 String rid RID of the prescription (size = 12 chars) 2 String reason Revoke reason to be used in the audit trail Output Integration Module Type Name Description Implementation Detail Step Description 1 The module checks the SAML token. 2 The module generates an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "GETPRESCRIPTION" (FOR PRESCRIBER) [PRESCRIBER INTEGRATION MODULE] Operation Name getprescription (for Prescriber) Strictly confidential For Recip-e project member use only Page 52

55 Class Name Description PrescriberIntegrationModule This action returns the content of the prescription (KMEHR Standard) When to be triggered When the prescriber has lost a prescription from his local storage (ex : computer crash), he can use this function to retrieve the content (XML KMEHR) Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has been revoked, archived, is in Process Inputs Integration Module Order Type Name Description 1 String Rid RID of the prescription (size = 12 chars) Output Integration Module Type Name Description GetPrescription prescription Structure containing meta-data + Prescription ForPrescriberResult content as a Validated XML Kmehr message. Attributes of the structure : - creationdate : Calendar - encryptionkeyid : String - patientid : Long - prescription : byte[] - insurability : String - rid : String Implementation Detail Step Description 1 The module checks the SAML token. 2 The module generates an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 Message is sent to Recip-e, Recip-e returns the result as a SOAP message 5 The message is decrypted. (Method "unseal()" of the ETEE framework is used). 6 The module requests the Encryption Token (Signed Public Key) of the KGSS service to ETK Depot (ehealth service) 7 The module generates a "Symmetric Key request" 8 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (Recipient is KGSS) Strictly confidential For Recip-e project member use only Page 53

56 9 The Sealed Response is received from Kgss, the module decrypts it. It contains the secured encryption key 10 the message is decrypted using unsealforunknown() "LISTFEEDBACK" [PRESCRIBER INTEGRATION MODULE] Operation Name Class Name Description When to be triggered listfeedback PrescriberIntegrationModule This action list all the feedbacks sent by prescription executors. This action requires that you have your personal private key (SSIN=<niss>.p12) enabled in the module. There is different configuration possible : - Single practice: system certificate = personal certificate : the private key is already enabled. No additional step required! - Fallback Session: the fallback session automatically enable the private key (using the personal password). No additional step required! - Shared workstation: system certificate is a group practice certificate or a the certificate of a legal responsible different of the care provider. The private key of the care provider must be enabled using the API setpersonalpassword(). It should only be done once per session. There are different options: - can be invoked on a regular basis (ex : 2x per day) and display incoming messages as popup to the prescriber. - can be invoked on demand by the prescriber (ex : when the prescriber open a specific screen) Errors Technical Services Exception such as Connection failure, Encryption failure Encryption Error : ex: if available private keys do not match the public key used for the encryption Inputs Integration Module Order Type Name Description Output Integration Module Type Name Description List<ListFeedbackItem> listfeedback List of feedbacks. ListFeedbackItem is a structure containing following fields : - content : byte[] - rid : String - sentby : Long - sentdate : Calendar Implementation Detail Step Description 1 The module checks the SAML token. 2 The module generates an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) Strictly confidential For Recip-e project member use only Page 54

57 4 Message is sent to Recip-e, Recip-e returns the result as a SOAP message 5 The message is decrypted. (Method "unseal()" of the ETEE framework is used). 6 Each single feedback is then decrypted using unseal() method "SETPERSONALPASSWORD" [PRESCRIBER INTEGRATION MODULE] Operation Name Class Name setpersonalpassword PrescriberIntegrationModule Description This action unlock the personal private key stored in the folder KEYSTORE_AUTH_P12_FOLDER. This function is optional and is only required if the user aims to unseal messages addressed to him (ex : lisfeedbacks) When to be triggered can be invoked once per session before ListFeedbacks Errors Technical Exception such as Wrong password, File not found Inputs Integration Module Order Type Name Description Output Integration Module Type Name Description String password The password of the keystore Implementation Detail Step Description 1 The module scan the folder KEYSTORE_AUTH_P12_FOLDER for file named SSIN=<ssin>*.p12. 2 If password matches, the module add the private encryption key to the current keystore Strictly confidential For Recip-e project member use only Page 55

58 "LISTOPENPRESCRIPTION" [PRESCRIBER INTEGRATION MODULE] Operation Name Class Name Description listopenprescription PrescriberIntegrationModule This action Lists prescriptions created by the prescriber that are still in state "NotDelivered" When to be triggered There are different options: - can be invoked on a regular basis (ex : 2x per day) and update the local storage. - can be invoked on demand by the prescriber (ex : when the prescriber open a specific screen) Errors Technical Services Exception such as Connection failure, Encryption failure Inputs Integration Module Order Type Name Description Output Integration Module Type Name Description List<String> List of rid Implementation Detail Step Description 1 The module checks the SAML token. Strictly confidential For Recip-e project member use only Page 56

59 2 The module generates an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 Message is sent to Recip-e, Recip-e returns the result as a SOAP message 5 The message is decrypted. (Method "unseal()" of the ETEE framework is used) "UPDATEFEEDBACKFLAG" [PRESCRIBER INTEGRATION MODULE] Operation Name Class Name Description updatefeedbackflag PrescriberIntegrationModule Action to be used to change the "feedback flag". When to be triggered The feedback flag is already set during the "CreatePrescription" step. This specific operation should be used by the prescriber if he changes his mind Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has another status than "NotDelivered" Inputs Integration Module Order Type Name Description 1 String rid RID of the prescription (size = 12 chars) 2 boolean feedbackrequested Should be set to true, if the prescriber don't want a feedback from the executor, this flag should be set to false Output Integration Module Type Name Description Implementation Detail Step Description Strictly confidential For Recip-e project member use only Page 57

60 1 The module checks the SAML token. 2 The module generates an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "GETPRESCRIPTION" (FOR EXECUTOR) [EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description When to be triggered getprescription (for Executor) ExecutorIntegrationModule This action returns the content of the prescription (KMEHR Standard) When the executor receives the prescription, Recip-e locks it. The executor MUST notify Recip-e of taken actions (MarkAsDelivered, MarkAsUnDelivered()) Also there is the possibility to received the insurability of the patient. When the barcode of the prescription has been read Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has been revoked, archived, is in Process Inputs Integration Module Order Type Name Description 1 String rid RID of the prescription (size = 12 chars) Output Integration Module Type Name Description GetPrescription prescription A structure containing : ForExecutorResult - creationdate : Calendar - encryptionkeyid : String - encryptionkey : byte[] Strictly confidential For Recip-e project member use only Page 58

61 - feedbackallowed : boolean - patientid : Long - prescriberid : long - prescription : byte[] (The XML clear content) - sealedcontent : byte[] (The sealed content to be archived) - prescriptiontype : String - rid : String - timestampingid : String Implementation Detail Step Description 1 The module checks the SAML token. 2 A XML request is generated 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. 4 Adding parameter to message to request insurability or not 54 Message is sent to Recip-e, Recip-e returns the result as a SOAP message 65 The message is decrypted. (Method "unseal()" of the ETEE framework is used). 76 The module requests the Encryption Token (Signed Public Key) of the KGSS service to ETK Depot (ehealth service) 87 The module generates a "Symmetric Key request" 98 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (Recipient is KGSS) 109 The Sealed Response is received from Kgss, the module decrypt it. It contains the secured encryption key 110 The message is decrypted using unsealforunknown() "MARKASUNDELIVERED" [EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description markasundelivered ExecutorIntegrationModule Update the status of the prescription in the central system. Set it back to Not delivered. This action unlocks the prescription. When to be triggered When no items have been delivered Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has been revoked, archived, is in Process Strictly confidential For Recip-e project member use only Page 59

62 Inputs Integration Module Order Type Name Description 1 String rid RID of the prescription (size = 12 chars) Output Integration Module Type Name Description Implementation Detail Step Description 1 The module checks the SAML token. 2 The module generates an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "MARKASDELIVERED" [EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description markasdelivered ExecutorIntegrationModule Update the status of the prescription in the central system. Set it to delivered. Once delivered, the prescription won't be delivered by another pharmacist When to be triggered When at least one item of the overall prescription is delivered. Strictly confidential For Recip-e project member use only Page 60

63 Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has been revoked, archived, is in Process Inputs Integration Module Order Type Name Description 1 String rid RID of the prescription (size = 12 chars) Output Integration Module Type Name Description Implementation Detail Step Description 1 The module checks the SAML token. 2 The module generates an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "MARKASARCHIVED" [EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description markasarchived ExecutorIntegrationModule This action allows Recip-e to remove the prescription from the central storage. Encryption key is also removed from ehealth. Strictly confidential For Recip-e project member use only Page 61

64 When to be triggered When the pharmacist has successfully archived the prescription with external back-up system. The prescription must be archived in his encrypted version including signature + encryption keys Errors Technical Services Exception such as Connection failure, Encryption failure Inconsitant Status : when the prescription has not been delivered Invalid Prescription : when the prescription does not exist Access Rights : when the executor does not have rights for an update (ex : pharmacist that want to deliver a nurse prescription) Inputs Integration Module Order Type Name Description 1 String rid RID of the prescription (size = 12 chars) Output Integration Module Type Name Description Implementation Detail Step Description 1 The module checks the SAML token. 2 The module generates an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "CREATEFEEDBACK" [EXECUTOR INTEGRATION MODULE] Operation Name Class Name createfeedback ExecutorIntegrationModule Strictly confidential For Recip-e project member use only Page 62

65 Description This action creates a feedback for the prescriber about a specific prescription. When to be triggered When something special about the delivery should be notified to the Prescriber (ex : generic medicine delivery, dosage change) Errors Technical Services Exception such as Connection failure, Encryption failure Inputs Integration Module Order Type Name Description 1 Long prescriberid NIHII id of the recipient (the same one as the one received by GetPrescription.prescriberId). 2 String rid RID of the prescription (size = 12 chars) 3 byte[] feedbacktext Xml message containing the feedback Output Integration Module Type Name Description Implementation Detail Step Description 1 The module checks the SAML token. 2 The module requests the Encryption Token (Signed Public Key) of recipient to ETK Depot (ehealth service) 3 The module generates an XML request. 4 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is the prescriber) 5 The message is enriched with meta data (recipient id ) 6 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 7 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "LISTNOTIFICATIONS" [EXECUTOR INTEGRATION MODULE] Strictly confidential For Recip-e project member use only Page 63

66 Operation Name Class Name Description listnotifications ExecutorIntegrationModule This function returns a list of notifications Prescriptions coming from Prescribers. When notifications are retrieved, they are automatically marked in the system as read, they stay in the system for a defined period of time (ex : 7 days). When to be triggered There are different options: - can be invoked on a regular basis (2x per day) and display the messages as popup to the executor - can be invoked on demand by the prescriber (when he opens a specific screen) Errors Technical Services Exception such as Connection failure, Encryption failure Inputs Integration Module Order Type Name Description Output Integration Module Type Name Description List<ListNotificationsItem> List of notifications ListNotificationsItem is structure containing : - content : byte[] - sentby : Long - sentdate : Calendar Implementation Detail Step Description 1 The module checks the SAML token. 2 The module generates an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 Message is sent to Recip-e, Recip-e returns the result as a SOAP message 5 The message is decrypted. (Method "unseal()" of the ETEE framework is used). Strictly confidential For Recip-e project member use only Page 64

67 "GETINSURABILITY" [EXECUTOR INTEGRATION MODULE] Operation Name Class Name Description When to be triggered Errors getinsurability ExecutorIntegrationModule This function retrieves the insurability of the patient at a specific date After a prescription delivery. Refer to Mycarenet documentation Inputs Integration Module Order Type Name Description Strictly confidential For Recip-e project member use only Page 65

68 String String String String String String String String String String String the user name the password the pharmacy holder the pharmacy ssin the pharmacy nihii the date the type the care receiver ssin the package name the reference the user reference Output Integration Module Type Name Description String Insurability The XML Insurability (including e-health ESB service status) Implementation Detail Step Description 1 The module retrieves the insurability from Mycarenet. Strictly confidential For Recip-e project member use only Page 66

69 6 INTEGRATION OPTION 2: WEBSERVICES 6.1 OVERVIEW PRESCRIBER SOFTWARE The section below describes the technical scope of the development work, concerning functionalities to foresee by the Software Provider in the software of the Software Provider to integrate with the Recip-e system and ehealth. The figure below shows all the actions to be performed by the Software Provider s software and the way it is to be integrated with the Recip-e system. A B createsession() SAML Token C getetk() getnewkey() ehealth Services D createprescription (KmehrMessage) Doctor Software E RID SendNotification (RID) F RevokePrescription (RID) ListFeedbacks() Recip-e Central System G GetPrescription(RID) H ListOpenPrescriptions() I J UpdateFeedbackFlag() Figure 5 Integration Option 2 (Webservices) - Prescriber The red rectangle represents the software of the Software Provider for Prescribers. The green/blue rectangle represents the Recip-e central system and ehealth common services. We consider two types of functionalities: Strictly confidential For Recip-e project member use only Page 67

70 Communication functionality to be implemented by the Software Provider, based on this document - arrows between the green/blue and red rectangles Internal functionality within the Software Provider software circle-arrows within the rectangle Communication functionality: 1. Create Session (STS) : Send a SAML request to ehealth and receive a SAML token. 2. Encryption Key Retrieval for addressed encryption (ETKDepot): retrieve encryption keys in ETK depot of messages recipient. 3. Encryption Key Generation (KGSS): request encryption keys. 4. Create Prescription: Send a prescription to the Recip-e Integration module. The software receives in return the RID (Recip-e ID). The prescriber can decide if want to get a feedback from the executor. 5. Send Notification: The prescriber has the option to send a prescription directly to an executor. This could for instance contain a prescription to prepare or a personal message 6. List Feedback: Ask for feedback sent by executor. In return the software receives all feedbacks addressed to him. 7. Revoke Prescription: If the prescriber chooses so, he can revoke/cancel a prescription. The cancellation of a prescription by the prescriber should be communicated to the Recip-e system. The cancellation request is sent to the module with the Recip-e unique identification number (RID). The prescriber receives a confirmation that the prescription has been cancelled. 8. List Open Prescriptions: The Software Provider software requests an update from the Recip-e central system concerning the status of its prescriptions. It gets returned a list of prescription with their status. 9. Get Prescription: The Software Provider can retrieve prescription previously created. 10. Update Feedback Flag: the software provider change the feedback flag set previously (Action 1) Internal functionality A. Identify the patient through the NISS/NISZ number found on the patients ID card information on the patients SIS card information on the patients mutuality sticker directly into the system the executor (if the patient is already in the system) B. Encrypt messages using addressed encryption framework provided by ehealth C. Encrypt/decrypt prescription using non-addressed encryption framework provided by ehealth D. Use MyCareNet services such as patient insurability (this is currently not in scope of the integration specifications, but is included here for clarity sake) E. Create a prescription in the Software Provider software and attach it to the patient record in the Software Provider software F. Add the unique identification number (Recip-e ID) of the electronic prescription (received from Recip-e) to the prescription, and print the prescription with RID on it in barcode format G. The prescriber has the option to send a message directly to an executor. This could for instance contain a prescription to prepare or a personal message. The Service Supplier software needs to allow the prescriber to input such a message H. Insert the received feedback into the patient record in the Software Provider software I. Cancel the prescription from the patient record in the Software Provider software (only when requested by the prescriber) J. For performance reasons, the prescriptions and their status (in process, delivered...) need to be stored in the Service Supplier software. The prescription status (and the content of the prescription) can be updated in batch mode (e.g. once a day). Strictly confidential For Recip-e project member use only Page 68

71 6.1.2 EXECUTOR SOFTWARE The figure below shows all the actions to be performed by the Software Provider s for executor (Executor/Pharmacist) and the way it is to be integrated with the Recip-e system and ehealth services. createsession() SAML Token A B ehealth Services getetk() GetKey() C D Recip-e Central System GetPrescription(RID) MarkAs(Un)Delivered(RI D) MarkAsArchived(RID) Pharmacist Software E CreateFeedback(XMLFe edback) F ListAddressedPrescript ions() G Figure 6 Integration Option 2 (Webservices) - Executor Communication functionality 1. Create Session (STS) : Send a SAML request to ehealth and receive a SAML token. 2. Encryption Key Retrieval for addressed encryption (ETKDepot): retrieve encryption keys in ETK depot of messages recipient. 3. Encryption Key Generation (KGSS): request encryption keys. 4. Get Prescription: Get the prescription using the Recip-e ID found in barcode format on the prescription provided by the patient. 5. Mark Prescription As (un)delivered: Software Provider software signals the Recip-e system that the prescription (or at least one item on the prescription) has been delivered. The Integration module returns a Confirmation 6. Mark Prescription As archived: Software Provider software signals the Recip-e system that the prescription has been archived. The Integration module returns a Confirmation 7. Send feedback: Send feedback on the prescription to the prescriber system (the feedback must contain the name of prescriber, patient name and prescription to which it relates). The Integration module returns a Confirmation. 8. List Notifications: Get all notifications from prescribers directed to this executor (The prescriber can send a text message to a specific executor. (e.g. could contain a prescription to be prepared)). The Integration module returns a Confirmation. 9. Revoke Prescription: If the patient request so, the executor can revoke/cancel a prescription. The cancellation of a prescription by the executor should be communicated to the Recip-e system. The cancellation request is Strictly confidential For Recip-e project member use only Page 69

72 sent to the module with the Recip-e unique identification number (RID). The executor receives a confirmation that the prescription has been cancelled. Internal functionality A. Identify the patient through the NISS/NISZ number found on the patients ID card information on the patients SIS card information on the patients mutuality sticker directly into the system the executor (if the patient is already in the system) B. Encrypt messages using addressed encryption framework provided by ehealth C. Encrypt/decrypt prescription using non-addressed encryption framework provided by ehealth D. Identify the prescription by reading the barcode containing the prescription number on the paper prescription E. Check the insurability of the patient on MyCareNet (this is currently not in scope of the integration specifications, but is included here for clarity sake) F. Translate the prescription returned from the Recip-e system into the internal format of the Software Provider software, save the prescription in the Software Provider software, and show the prescription to the executor G. Create feedback for the prescription - providing an additional screen that allows the introduction of feedback for a prescription. Multiple feedbacks on the same prescription are possible. H. Get all notifications The prescriber can send a text message to a specific executor. (e.g. could contain a prescription to be prepared). The executor software needs to be able to show this. I. Archiving of the prescription: the prescription should be archived in his encrypted version together with the encryption key and the time stamping id. 6.2 IMPLEMENTATION DETAIL AUTHENTICATION OF THE CARE PROVIDER Authentication of the care provider (prescriber, nurse, pharmacist,) is performed by ehealth thanks to the Secure Token Service (STS). This service takes as an input the EID of the care provider and his certificate to generate a SAML token that can be used for Single Sign On. Refer to doc Ref 4 for the integration specification with STS. Sample SAML request Sample SAML response example.hok.request.xml Table 4 Sample SAML example.hok.response.xml Once the SAML assertion is retrieved from STS, it must be added to the SOAP header of each outgoing message addressed to Recip-e. Refer to the document for more information about SAML and WS-Security. Strictly confidential For Recip-e project member use only Page 70

73 6.2.2 MESSAGING AND ENCRYPTION OVERVIEW OF MESSAGE CREATION Health Care Software must communicate with Recip-e using message based communications. These messages must be highly secured with encryption. Three different types of encryption must be implemented: - Encryption for transport: this kind of encryption concerns all type of messages. This encryption is based on the ETEE encryption framework provided by ehealth. It consists in encrypting the message so that on Recip-e can read it. This is based on Public key/private key encryption. - Encryption for storage: this encryption type is used to secure the storage of the message in Recip-e. Only allowed systems/recipients can decrypt these messages (Recip-e can t decrypt them), There is two type of storage encryption : o Non-addressed Encryption for Prescriptions: Prescriptions are encrypted using the non-addressed encryption framework. o Addressed Encryption for Feedbacks/Notifications: these messages are encrypted, only the recipient can encrypt the message. Following section describes the different type of encryption needed to create messages in Recip-e. The steps to decrypt messages are identical (except the reverse order) ENCRYPTION FOR TRANSPORT Following diagram illustrates the different steps of the transformation process to be implemented: Encryption for Transport ETKDepot GetETK(Recip-e) HEADER SAML ASSERTION HOK SIGNED BY EH TIMESTAMP (MESSAGE- TTL) SIGN BODY, ASS, TIMESTAMP [proof-of-possession HOK] BODY Admin Part (Recip-e) Admin Part (Recip-e) Message Content [1] Message Content SymmKey (Sender) [2] Message Content ETEE : SIGN SymmKey (Sender) ETEE: ASYM. ENCRYPT ETEE: SIGN ETEE : SIGN ETEE: ASYM. ENCRYPT ETEE: SIGN Figure 7 Addressed Encryption for Message transport Admin Part (ehealth) Strictly confidential For Recip-e project member use only Page 71

74 1. Message Content is encrypted using the public Key of Recipe (ETK: encryption token), this ETK is retrieved from ehealth service ETK depot. 2. Message is sent to Recip-e including the aetk random SymmKey that only theof the sender know. This ETK SymmKey will be used by Recip-e to encrypt the response. This ETK SymmKey should only be provided when a response is expected (optional for void API) NON-ADDRESSED MESSAGE ENCRYPTION FOR STORAGE (ONLY FOR PRESCRIPTION) Encryption For Storage Encryption For Transport KGSS GetNewKey() ETKDepot GetETK(Recip-e) HEADER SAML ASSERTION HOK SIGNED BY EH TIMESTAMP (MESSAGE- TTL) KMEHR PRESCRIPTION Admin Part (Recip-e) - PrescriberId* - PatientId* - Executor Id* -... KMEHR PRESCRIPTION (GZIP) KMEHR KMEHR PRESCRIPTION [1] PRESCRIPTION (GZIP) [2] SIGN NON-REPUDIATION [3] (GZIP) [4] SIGN BODY, ASS, TIMESTAMP [proof-of-possession HOK] BODY Admin Part (Recip-e) - PrescriberId* - PatientId* - Executor Id* -... ETEE: SIGN ETEE: SYM. ENCRYPT ETEE: SIGN SIGN NON-REPUDIATION (NA) ETEE: SIGN (NA) ETEE: SYM. ENCRYPT (NA) ETEE: SIGN KMEHR PRESCRIPTION (GZIP) SIGN NON-REPUDIATION ETEE : SIGN ETEE: ASYM. ENCRYPT ETEE: SIGN (NA) ETEE: SIGN (NA) ETEE: SYM. ENCRYPT (NA) ETEE: SIGN SymmKey (Sender) Admin Part (ehealth) - NIHII, Document ID*, Key Id* ETEE : SIGN ETEE: ASYM. ENCRYPT ETEE: SIGN Figure 8 Non-addressed encryption for Storage, Addressed Encryption for Message transport 1. Private Message Content (kmehr prescription) is compressed using GZIP algorithm 2. Private Message is sealed using non-addressed encryption, the symmetric encryption key is retrieved from ehealth service KGSS.get[New]Key(). (The message will be stored as-is by Recip-e) 3. The message is enriched with non-confidential data (patient ID, Prescriber ID), Encryption for Transport described in previous section is then applied to secure the data transfer between the care provider workstation and the Recip-e central server. The overall is then included in a SOAP message secured by SAML authentication ADDRESSED ENCRYPTION FOR STORAGE (ONLY FOR FEEDBACKS AND NOTIFICATIONS) Strictly confidential For Recip-e project member use only Page 72

75 Encryption For Storage Encryption for Transport ETKDepot GetETK(Recipient) ETKDepot GetETK(Recip-e) HEADER SAML ASSERTION HOK SIGNED BY EH TIMESTAMP (MESSAGE- TTL) SIGN BODY, ASS, TIMESTAMP [proof-of-possession HOK] Message Admin Part (Recip-e) - PrescriberId* - PatientId* - Executor Id* -... KMEHR PRESCRIPTION (GZIP) KMEHR PRESCRIPTION [1] Message (GZIP) [2] SIGN NON-REPUDIATION [3] (GZIP) [4] BODY Admin Part (Recip-e) - PrescriberId* - PatientId* - Executor Id* -... ETEE: SIGN ETEE: SYM. ENCRYPT ETEE: SIGN SIGN NON-REPUDIATION (NA) ETEE: SIGN (NA) ETEE: SYM. ENCRYPT (NA) ETEE: SIGN KMEHR PRESCRIPTION (GZIP) SIGN NON-REPUDIATION ETEE : SIGN ETEE: ASYM. ENCRYPT ETEE: SIGN (NA) ETEE: SIGN (NA) ETEE: SYM. ENCRYPT (NA) ETEE: SIGN SymmKey (Sender) ETEE : SIGN ETEE: ASYM. ENCRYPT ETEE: SIGN Figure 9 Addressed encryption for Storage, Addressed Encryption for Message transport 1. Private Message Content (xml) is compressed using GZIP algorithm 2. Private Message is sealed using addressed encryption, the public encryption key of the recipient is retrieved from ehealth service ETKdepot.getETK(). (The message will be stored as-is by Recip-e) 3. The message is enriched with non-confidential data (patient ID, Prescriber ID), Encryption for Transport described in previous section is then applied to secure the data transfer between the care provider workstation and the Recip-e central server. The overall is then included in a SOAP message secured by SAML authentication FOCUS ON COMPRESSION To decrease bandwidth consumption, xml messages are compressed using GZIP standard. (Only XML KMEHR prescription, XML notification & XML feedbacks are concerned). Following Java code illustrates how the message must be compress: This compression is specified by standards RFC 1950; RFC 1951 and RFC 1952 (Refer to for more information about these specifications) FOCUS ON NA ENCRYPTIONS See Ref 2 for generic information about NA Encryption. Strictly confidential For Recip-e project member use only Page 73

76 As defined in previous mentioned document, the Process for NA Encryption is defined as follow: 1. The ETK (public Key) of KGSS system is retrieved from ETK depot ( Key Id CBE= , Application ID : KGSS ) 2. The New Key Request is created defining the Access Control List 3. The New Key Request is sealed using addressed encryption (public key of KGSS used) 4. The KGSS.GetNewKey() service is invoked, the In Recip-e specific case, the Access Control List (AllowedReader attribute of the GetNewKeyReequestContent message) must be defined as an Encrypted XML document. Only those three types of parties must be defined in the Access Control List: - The Prescriber - The Patient - All the Pharmacists (for pharmaceutical prescriptions). (This list is used later on to allow a physical person reading the content of a prescription) Sample Access Control List before encryption: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ns2:getnewkeyrequestcontent xmlns:ns2="urn:be:fgov:ehealth:etee:kgss:1_0:protocol"> <allowedreader> <name>urn:be:fgov:ehealth:doctor-nihii</name> <namespace>urn:be:fgov:ehealth:certified-namespace</namespace> <value> </value> </allowedreader> <allowedreader> <name>urn:be:fgov:ehealth:pharmacy-nihii</name> <namespace>urn:be:fgov:ehealth:certified-namespace</namespace> <value></value> </allowedreader> <allowedreader> <name>urn:be:fgov:identification-namespace</name> <namespace>urn:be:fgov:ehealth:certified-namespace</namespace> <value> </value> </allowedreader> <etksymmkey>[base64 ETKsymmKey]</etksymmKey> </ns2:getnewkeyrequestcontent> FOCUS ON END TO END ENCRYPTIONS See Ref 3 for generic information about ETE Encryption. As defined in previous mentioned document, the process for ETE Encryption follows three steps: 1. The Public Key (ETK) of Recip-e is retrieved from ETK depot. (This step can pre-fetch, result can be cached) 2. The message is sealed using the Recip-e ETK 3. The Recip-e createprescription() service is invoked Recip-e ETK is retrieved from ETKDepot using KeyID CBE= Addressed encryption process has to be applied to all outgoing messages addressed to Recip-e. To allow Recip-e to unseal the message, the ETK (signed public key) of the care provider must be attached to the message (only if a response from Recip-e is expected). That is why all messages addressed to recipe defined in the WSDL have the same structure: RequestMessage: - SealedContent : the crypt request - ETK : the Encryption Token of the sender to be used by Recip-e to encipher the message Strictly confidential For Recip-e project member use only Page 74

77 ResponseMessage: - SealedContent: the crypt response (to be decrypted) PRESCRIBER SERVICES Prescriber Web service has following properties: EXECUTOR SERVICES (PHARMACIST, NURSE ) Executor Web service has following properties: Service Name PrescriberServices Message Type SOAP Target Namespace urn:be:fgov:ehealth:recipe:protocol:v1http://services.recipe.be Service URL Service WSDL (integration) Host : TBC, Port : TBC Service WSDL (acceptance) Host : services-acpt.ehealth.fgov.betbc, Port : TBC 443 Service WSDL (production) Host : services.ehealth.fgov.betbc, Port : TBC443 Prescriber Services WSDL Refer to SDK (folder XSD) Prescriber Services Input/output definitions after encryption process Prescriber Services Input/output definitions before encryption process Prescriber Services Input/output definitions before encryption process Service Name ExecutorServices Message Type SOAP Target Namespace urn:be:fgov:ehealth:recipe:protocol:v1http://services.recipe.be Service URI Service WSDL (integration) Host : TBC, Port : TBC Service WSDL (acceptance) Host : services-acpt.ehealth.fgov.be, Port : 443Host : TBC, Port : TBC Service WSDL (production) Host : services.ehealth.fgov.betbc, Port : TBC443 Executor Services WSDL Refer to SDK (folder XSD) Executor Services Input/output definitions after encryption process Executor Services Input/output definitions before encryption process Executor Services Input/output definitions before encryption process ERROR MANAGEMENT Each service may throw different type of error. SOAP Fault Exceptions. TThe two types declared types are: Strictly confidential For Recip-e project member use only Page 75

78 Business error for Functional Exception : indicates a functional error (such as missing information) SOAP Fault for Technical Exception: indicates a technical error due to the infrastructure (such as database unavailable, communication protocol issue). For more information about SOAP Fault, please refer to These specific SOAP Fault are customized to allow the software package to better handle the exception and display the appropriate error message to the end-user. Sample SOAP Business errorfault : <?xml version="1.0" encoding="utf-8"?> <n1:alivecheckresponse xmlns:n1="urn:be:fgov:ehealth:recipe:protocol:v1" xmlns:xsi=" xsi:schemalocation="urn:be:fgov:ehealth:recipe:protocol:v1..\ehealth-recipeservices\xsd\recipeservices_protocol-1_0.xsd"> <Status> <Code>500</Code> <Message Lang= FR >Erreur inattendue</message> <Message Lang= EN >Unexpected error</message> </Status> </n1:alivecheckresponse> The message part contains the reference to the error message. The list of all possible error messages is provided in the file label.properties provided in the package. The label associated to the error message is also added in the detail of the fault in 4 languages (En, Fr, NL, and Ge). The software provider can then choose the appropriate language for the error message EHEALTH SERVICES ETK DEPOT This service shall be used to retrieve public keys of recipient to be used for addressed encryption. Integration specification is described in Document Ref KGSS This service shall be used to generate/retrieve symmetric keys to be used for non-addressed encryption. Integration specification is described in Document Ref SEVICE INVENTORY This section lists all available API in the integration modules. For each API, the part Implementation specification lists the different steps implemented in the integration module. Inputs/Outputs are also described for each service: - Input XML of the WS (Crypt Part of the message - Before Encryption process): corresponds to the XML message to be generated before the encryption process. - Output XML of the WS (Encrypted Part of the message - After decryption process) : corresponds to the output that the Health Care Software will receive after decryption of the message. Strictly confidential For Recip-e project member use only Page 76

79 6.3.1 ADMINISTRATIVE INFORMATION Several requests should contain an AdministrativeInformation part next to the crypted content. This administrative part will be described in for each action (if applicable). E.g. <xs:complextype name="createprescriptionrequesttype"> <xs:complexcontent> <xs:extension base="protocol:requesttype"> <xs:sequence> <xs:element name="securedcreateprescriptionrequest" type="rc:securedcontenttype"/> <xs:element name="administrativeinformation" type="rc:createprescriptionadministrativeinformationtype"/> </xs:sequence> </xs:extension> </xs:complexcontent> </xs:complextype> PARTY IDENTIFICATION Several outgoing messages addressed to Recip-e require an IdentifierType (i.e identification of a party) as part of the AdministrativeInformation, this should be defined as follow: <xs:complextype name="identifiertype"> <xs:sequence> <xs:element name="id" type="xs:string"/> <xs:element name="type" type="xs:string"/> <xs:element name="subtype" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Where : - Id is the unique identification number of the party - Type is the type of the identification number (NIHII, SSIN) This part of the message is used by ehealth for different purpose: - Logging: the information is logged by ehealth. - Orchestration: ehealth can start complex processing based on those IDs (such as retrieving patient insurability). Even if that information is not mandatory, Software vendors are encouraged to fill in those IDs when the information is known (ex : patientid and prescriberid should be filled in for the message createprescription ). Remark: At this step of the project, the health care sector has not yet decided if ehealth is allowed to see that private information. (Decision expected for the end of August 2010) "CREATEPRESCRIPTION" [PRESCRIBER SERVICES] Operation Name WSDL createprescription Strictly confidential For Recip-e project member use only Page 77

80 Description When to be triggered This action stores the prescription (Kmehr format) in Recip-e central system. This function takes care of the encryption (transport and storage). It returns the RID (Recipe ID) to be printed on the paper prescription (RID = "BEPPXXXXXXXX" where Be is the country, PP is the prescription type (pharmaceutical prescription) and XXX the ALPHANUM sequence ID) When the prescriber has generated a local prescription (XML Kmehr format), this function must be used to store it in Recip-e secured storage. Errors Technical Services Exception such as Connection failure, Encryption failure Encryption Error : when Recip-e can't decrypt the message Input Parameter Description Order Type Name Description (Before Encryption process) 1 Boolean feedbackrequested Set to true if the prescriber wants to receive a feedback from the executor 2 Long patientid INSS number of the patient 3 byte[] prescription Prescription content as a Validated XML Kmehr message. If the Prescription Type is set to PP, the prescription must contains a valid pharmaceutical prescription. (See XSD KMEHR Validation) 4 String prescriptiontype Type of prescription, will be used to generate the prescription ID and define what the allowed profiles for the delivery are. If prescription type is set to 'PP' (pharmaceutical prescription), only pharmacist will be allowed to retrieve the prescription. Other types of prescription will be available after the pilot project (ex : nurse, care act) 5 Long PrescriberID INSS number of the real prescriber (can be different from the authenticated user) Administrative Information 1 IdentifierType PatientIdentifier 2 IdentifierType PrescriberIdentifier 3 String PrescriptionType 4 Base64binary KeyIdentifier Output Parameter Description Type Name Description (After decryption Process) String rid RID of the prescription (size = 12 chars) Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="createprescriptionparam"> <xs:sequence> <xs:element name="feedbackrequested" type="xs:boolean"/> <xs:element name="patientid" type="xs:long" minoccurs="0"/> <xs:element name="prescription" type="xs:base64binary" minoccurs="0"/> Strictly confidential For Recip-e project member use only Page 78

81 <xs:element name="prescriptiontype" type="xs:string" minoccurs="0"/> <xs:element name="keyid" type="xs:string" minoccurs="0"/> <xs:element name="etk" type="xs:base64binary" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <createprescription xmlns=" <CreatePrescriptionParam xmlns=""> <feedbackrequested>true</feedbackrequested> <patientid> </patientid> <prescriberid> </prescriberid> <prescription>c3ryaw5n</prescription> <prescriptiontype>pp</prescriptiontype> <keyid>abdeabdeabde</keyid> <ETK>ABDEABDEABDE</ETK> </CreatePrescriptionParam> </createprescription> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD <xs:complextype name="createprescriptionresult"> <xs:sequence> <xs:element name="rid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <createprescription xmlns=" <CreatePrescriptionResult xmlns=""> <rid>beppaaaaaaaa</rid> </CreatePrescriptionResult> </createprescription> Implementation Specification Step Description 1 Check the SAML token. 2 Request the Encryption Token (Signed Public Key) of the KGSS service to ETK Depot (ehealth service) 3 Generate a "Symmetric Key request" (including the key access control list) 4 The message should be ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (Recipient is KGSS) 5 The Sealed Response is received from Kgss, decrypt it. It contains the secured encryption key 6 The KMEHR Prescription is ciphered with the "sealforunknown" function of the ETE framework using the symmetric key 7 The message is enriched with meta data (recipient id ) 8 A ciphered message is generated with the "seal" function of the ETE framework (Recipient : Recip-e), the message is sent to Recip-e 9 The message is decrypted. (Method "unseal()" of the ETEE framework is used). The response contains The RID of The prescription "SENDNOTIFICATION" [PRESCRIBER SERVICES] Operation Name sendnotification Strictly confidential For Recip-e project member use only Page 79

82 WSDL Description This function addresses sends a notification to a specific executor. The notification indicates that a client is likely to retrieve/execute his prescription with him. When to be triggered - When a patient has habits in a specific pharmacy - When the product requires an ordering, Errors Technical Services Exception such as Connection failure, Encryption failure ETK not present: the executor does not have a registered public Key at ehealth Input Parameter Description Order Type Name Description (Before Encryption process) 1 byte[] notificationtext Xml message containing the notification. Must be validated by the provided XSD 2 Long executorid INSS id of the recipient. Must be a valid INSS ID. Administrative Information 1 IdentifierType executoridentifiern/a 2 IdentifierType PrescriberIdentifier Output Parameter Description Type Name Description (After decryption Process) Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="addressprescriptionparam"> <xs:sequence> <xs:element name="content" type="xs:base64binary" minoccurs="0"/> <xs:element name="executorid" type="xs:long" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <addressprescription xmlns=" <AddressPrescriptionParam xmlns=""> <content>c3ryaw5n</content> <executorid> </executorid> </AddressPrescriptionParam> </addressprescription> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD Sample Strictly confidential For Recip-e project member use only Page 80

83 Implementation Specification Step Description 1 Check the SAML token. 2 request the Encryption Token (Signed Public Key) of recipient to ETK Depot (ehealth service) 3 Generate an XML request. 4 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is the prescriber) 5 The message is enriched with meta data (recipient id ) 6 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 7 Send the message to Recip-e, nothing is returned if the action is processed successfully (otherwise, a SOAP fault is thrown) "REVOKEPRESCRIPTION" [PRESCRIBER SERVICES, EXECUTOR SERVICES] Operation Name WSDL Description revokeprescription Revoke the prescription (the prescription is removed from Recip-e system). It is then not possible to deliver it any more. When to be triggered When prescriber has done a mistake, he can use this function to revoke the bad prescription and then create a new one with the function "createprescription". If the patient ask the executor to revoke the prescription Errors Technical Services Exception such as Connection failure, Encryption failure Input Parameter Description Order Type Name Description (Before Encryption process) 1 String rid RID of the prescription (size = 12 chars) 2 String reason Revoke reason to be used in the audit trail Strictly confidential For Recip-e project member use only Page 81

84 Administrative Information 1 IdentifierType PrescriberIdentifier/ ExecutorIdentifier Output Parameter Description Type Name Description (After decryption Process) Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="revokeprescriptionparam"> <xs:sequence> <xs:element name="reason" type="xs:string" minoccurs="0"/> <xs:element name="rid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <revokeprescription xmlns=" <RevokePrescriptionParam xmlns=""> <reason>mistake</reason> <rid>bppaaaaaaaa</rid> </RevokePrescriptionParam> </revokeprescription> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD Sample Implementation Specification Step Description 1 Check the SAML token. 2 Generate an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 Send the message to Recip-e, nothing is returned if the action is processed successfully (otherwise, an SOAP fault is thrown) Strictly confidential For Recip-e project member use only Page 82

85 6.3.6 "GETPRESCRIPTION" (FOR PRESCRIBER) [PRESCRIBER SERVICES] Operation Name WSDL Description getprescription (for Prescriber) This action returns the content of the prescription (KMEHR Standard) When to be triggered When the prescriber has lost a prescription from his local storage (ex : computer crash), he can use this function to retrieve the content (XML KMEHR) Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has been revoked, archived, is in Process Input Parameter Description Order Type Name Description (Before Encryption process) 1 String rid RID of the prescription (size = 12 chars) Adminstrative Information 1 IdentifierType PatientIdentifier 2 IdentifierType PrescriberIdentifier Output Parameter Description Type Name Description (After decryption Process) byte[] prescription Prescription content as a Validated XML Kmehr message. Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="getprescriptionforprescriberparam"> <xs:sequence> <xs:element name="etk" type="xs:base64binary" minoccurs="0"/> <xs:element name="rid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <getprescriptionforprescriber xmlns=" <GetPrescriptionForPrescriberParam xmlns=""> <ETK>c3RyaW5n</ETK> <rid>beppaaaaaaaa</rid> </GetPrescriptionForPrescriberParam> </getprescriptionforprescriber> Strictly confidential For Recip-e project member use only Page 83

86 Output XML of the WS (Encrypted Part of the message - After decryption process) XSD <xs:complextype name="getprescriptionforprescriberresult"> <xs:sequence> <xs:element name="creationdate" type="xs:datetime" minoccurs="0"/> <xs:element name="encryptionkeyid" type="xs:string" minoccurs="0"/> <xs:element name="patientid" type="xs:long" minoccurs="0"/> <xs:element name="prescription" type="xs:base64binary" minoccurs="0"/> <xs:element name="rid" type="xs:string" minoccurs="0"/> <xs:element name="timestampingid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <getprescriptionforprescriber xmlns=" <GetPrescriptionForPrescriberResult xmlns=""> <creationdate> t09:00:00</creationdate> <encryptionkeyid>abcdeeabcde</encryptionkeyid> <patientid> </patientid> <prescription>1234aertzzz</prescription> <timestampingid> </timestampingid> </GetPrescriptionForPrescriberResult> </getprescriptionforprescriber> Implementation Specification Step Description 1 Check the SAML token. 2 Generate an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 Message is sent to Recip-e, Recip-e returns the result as a SOAP message 5 The message is decrypted. (Method "unseal()" of the ETEE framework is used). 6 Request the Encryption Token (Signed Public Key) of the KGSS service to ETK Depot (ehealth service) 7 Generate a "Symmetric Key request" 8 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (Recipient is KGSS) 9 The Sealed Response is received from Kgss, the module decrypt it. It contains the secured encryption key 10 the message is decrypted using unsealforunknown() "LISTFEEDBACK" [PRESCRIBER SERVICES] Operation Name WSDL Description listfeedback This action list all the feedbacks sent by prescription executors Strictly confidential For Recip-e project member use only Page 84

87 When to be triggered There are different options: - can be invoked on a regular basis (ex : 2x per day) and display incoming messages as popup to the prescriber. - can be invoked on demand by the prescriber (ex : when the prescriber open a specific screen) Errors Technical Services Exception such as Connection failure, Encryption failure Encryption Error : ex: if available private keys do not match the public key used for the encryption Input Parameter Description Order Type Name Description (Before Encryption process) Adminstrative Information 1 IdentifierType PrescriberIdentifier Output Parameter Description Type Name Description (After decryption Process) List<ListFeedbackItem> listfeedback List of feedbacks (See XML Response for the description of this complex type) Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="listfeedbacksparam"> <xs:sequence> <xs:element name="etk" type="xs:base64binary" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <listfeedbacks xmlns=" <ListFeedbacksParam xmlns=""> <ETK>aaaaa</ETK> </ListFeedbacksParam> </listfeedbacks> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD <xs:complextype name="listfeedbackitem"> <xs:sequence> <xs:element name="rid" type="xs:string" minoccurs="0"/> <xs:element name="sentby" type="xs:long" minoccurs="0"/> <xs:element name="sentdate" type="xs:datetime" minoccurs="0"/> <xs:element name="content" type="xs:base64binary" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <listfeedbacks xmlns=" <ListFeedResult> <ListFeedbackItem> <rid>beppaaaaaaaa</rid> <sentby> </sentby> <sentdate> :00:00</sentdate> <content>abcdeabcde</content> </ListFeedbackItem> </ListFeedResult> Strictly confidential For Recip-e project member use only Page 85

88 </ListFeedbackItem> Implementation Specification Step Description 1 Check the SAML token. 2 Generate an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 Send the Message to Recip-e, Recip-e returns the result as a SOAP message 5 The message should be decrypted. (Method "unseal()" of the ETEE framework is used). 6 Each single feedback should then be decrypted using unseal() method "LISTOPENPRESCRIPTION" [PRESCRIBER SERVICES] Operation Name WSDL Description listopenprescription This action Lists prescriptions created by the prescriber that are still in state "NotDelivered" When to be triggered There are different options: - can be invoked on a regular basis (ex : 2x per day) and update the local storage. - can be invoked on demand by the prescriber (ex : when the prescriber open a specific screen) Errors Technical Services Exception such as Connection failure, Encryption failure Input Parameter Description Order Type Name Description (Before Encryption process) Adminstrative Information 1 IdentifierType PrescriberIdentifier Output Parameter Description Type Name Description Strictly confidential For Recip-e project member use only Page 86

89 (After decryption Process) List<String> List of rid Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="listopenprescription"> <xs:sequence> <xs:element name="etk" type="xs:base64binary" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <listopenprescription xmlns=" <ListOpenPrescriptionParam xmlns=""><etk>aaa</etk></listopenprescriptionparam> </listopenprescription> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD <xs:complextype name="getlistopenprescriptionresult"> <xs:sequence> <xs:element name="prescriptions" type="xs:string" minoccurs="0" maxoccurs="unbounded"/> </xs:sequence> </xs:complextype> Sample <listopenprescription xmlns=" <ListOpenPrescriptionResult xmlns=""> <rid>bepp12345aaa</rid> <rid>bepp1d345aaa</rid> </ListOpenPrescriptionResult> </listopenprescription> Implementation Specification Step Description 1 Check the SAML token. 2 Generate an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 Send the message to Recip-e, Recip-e returns the result as a SOAP message 5 Decrypt the message. (Method "unseal()" of the ETEE framework is used). Strictly confidential For Recip-e project member use only Page 87

90 6.3.9 "UPDATEFEEDBACKFLAG" [PRESCRIBER SERVICES] Operation Name WSDL Description updatefeedbackflag Action to be used to change the "feedback flag". When to be triggered The feedback flag is already set during the "CreatePrescription" step. This specific operation should be used by the prescriber if he changes his mind Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has another status than "NotDelivered" Input Parameter Description Order Type Name Description (Before Encryption process) 1 String rid RID of the prescription (size = 12 chars) 2 boolean feedbackrequested Should be set to true, if the prescriber don't want a feedback from the executor, this flag should be set to false Administrative Information 1 IdentifierType PrescriberIdentifier Output Parameter Description Type Name Description (After decryption Process) Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="updatefeedbackflagparam"> <xs:sequence> <xs:element name="allowfeedback" type="xs:boolean"/> <xs:element name="rid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <updatefeedbackflag xmlns=" <UpdateFeedbackFlagParam xmlns=""> <allowfeedback>true</allowfeedback> <rid>beppaaaaaaaa</rid> </UpdateFeedbackFlagParam> </updatefeedbackflag> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD Strictly confidential For Recip-e project member use only Page 88

91 Sample Implementation Specification Step Description 1 Check the SAML token. 2 Generate an XML request. 3 Ciphered the message is using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 Send the message to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "GETPRESCRIPTION" (FOR EXECUTOR) [EXECUTOR SERVICES] Operation Name WSDL Description getprescription (For Executor) This action returns the content of the prescription (KMEHR Standard) When the executor receives the prescription, Recip-e locks it. The executor MUST notify Recip-e of taken actions (MarkAsDelivered, MarkAsUnDelivered()) When to be triggered When the barcode of the prescription has been read Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has been revoked, archived, is in Process Input Parameter Description Order Type Name Description (Before Encryption process) 1 String rid RID of the prescription (size = 12 chars) Strictly confidential For Recip-e project member use only Page 89

92 Administrative Information 1 IdentifierType ExecutorIdentifier Output Parameter Description Type Name Description (After decryption Process) date creationdate Creation date of the prescription string encryptionkeyid Kgss key ID boolean feedbackallowed Flag indicating if the feedback is allowed long patientid INSS of the patient byte[] prescription The sealed prescription string prescriptiontype The prescription Type string rid The rid of the prescription string timestampingid The timestamping ID Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="getprescriptionforexecutorparam"> <xs:sequence> <xs:element name="etk" type="xs:base64binary" minoccurs="0"/> <xs:element name="rid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <getprescription xmlns=" <GetPrescriptionForExecutorParam xmlns=""> <ETK>c3RyaW5n</ETK> <rid>beppaaaaaaaaaaa</rid> </GetPrescriptionForExecutorParam> </getprescription> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD <xs:complextype name="getprescriptionforexecutorresult"> <xs:sequence> <xs:element name="creationdate" type="xs:datetime" minoccurs="0"/> <xs:element name="encryptionkeyid" type="xs:string" minoccurs="0"/> <xs:element name="feedbackallowed" type="xs:boolean"/> <xs:element name="patientid" type="xs:long" minoccurs="0"/> <xs:element name="prescription" type="xs:base64binary" minoccurs="0"/> <xs:element name="prescriptiontype" type="xs:string" minoccurs="0"/> <xs:element name="rid" type="xs:string" minoccurs="0"/> <xs:element name="timestampingid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <getprescriptionforexecutor xmlns=" <GetPrescriptionForExecutorResult xmlns=""> <creationdate> t09:00:00</creationdate> <encryptionkeyid>abcdeeabcde</encryptionkeyid> <patientid> </patientid> <prescription>1234aertzzz</prescription> <timestampingid> </timestampingid> <prescriberid> </prescriberid> </GetPrescriptionForExecutorResult> </getprescriptionforexecutor> Strictly confidential For Recip-e project member use only Page 90

93 Implementation Specification Step Description 1 Check the SAML token. 2 Generate a XML request 3 Ciphered the message using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. 4 Send the Message to Recip-e, Recip-e returns the result as a SOAP message 5 Decrypt the message. (Method "unseal()" of the ETEE framework is used). 6 Request the Encryption Token (Signed Public Key) of the KGSS service to ETK Depot (ehealth service) 7 Generate a "Symmetric Key request" 8 Cipher the message using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (Recipient is KGSS) 9 The Sealed Response is received from Kgss, the module decrypt it. It contains the secured encryption key 10 The message is decrypted using unsealforunknown() "MARKASUNDELIVERED" [EXECUTOR SERVICES] Operation Name WSDL Description markasundelivered Update the status of the prescription in the central system. Set it back to Not delivered. This action unlocks the prescription. When to be triggered When no items have been delivered Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has been revoked, archived, is in Process Input Parameter Description Order Type Name Description (Before Encryption process) 1 String rid RID of the prescription (size = 12 chars) Administrative Information 1 IdentifierType ExecutorIdentifierN/A 2 IdentifierType PatientIdentifier#N//A 3 IdentifierType PrescriberIdentifierN/A Output Parameter Description Type Name Description Strictly confidential For Recip-e project member use only Page 91

94 (After decryption Process) Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="markasundeliveredparam"> <xs:sequence> <xs:element name="rid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <markasundelivered xmlns=" <MarkAsUndeliveredParam xmlns=""> <rid>beppaaaaaaaa</rid> </MarkAsUndeliveredParam> </markasundelivered> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD Sample Implementation Specification Step Description 1 Check the SAML token. 2 Generate an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) Strictly confidential For Recip-e project member use only Page 92

95 "MARKASDELIVERED" [EXECUTOR SERVICES] Operation Name WSDL Description markasdelivered Update the status of the prescription in the central system. Set it to delivered. Once delivered, the prescription won't be delivered by another executor When to be triggered When at least one item of the overall prescription is delivered. Errors Technical Services Exception such as Connection failure, Encryption failure Inconsistent Status : when the prescription has been revoked, archived, is in Process Input Parameter Description Order Type Name Description (Before Encryption process) 1 String rid RID of the prescription (size = 12 chars) Administrative Information 1 IdentifierType PrescriberIdentifierN/ 2 IdentifierType PatientIdentifier#N/ 3 IdentifierType ExecutorIdentifierN/ Output Parameter Description Type Name Description (After decryption Process) Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="markasdeliveredparam"> <xs:sequence> <xs:element name="rid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <markasdelivered xmlns=" <MarkAsdeliveredParam xmlns=""> <rid>beppaaaaaaaa</rid> </MarkAsdeliveredParam> </markasdelivered> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD Strictly confidential For Recip-e project member use only Page 93

96 Sample Implementation Specification Step Description 1 Check the SAML token. 2 Generate an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "MARKASARCHIVED" [EXECUTOR SERVICES] Operation Name WSDL Description markasarchived This action allows Recip-e to remove the prescription from the central storage. Encryption key is also removed from ehealth. When to be triggered When the executor has successfully archived the prescription with external back-up system. The prescription must be archived in his encrypted version including signature + encryption keys Errors Technical Services Exception such as Connection failure, Encryption failure Inconsitant Status : when the prescription has not been delivered Invalid Prescription : when the prescription does not exist Access Rights : when the executor does not have rights for an update (ex : pharmacist that want to deliver a nurse prescription) Input Parameter Description Order Type Name Description (Before Encryption process) 1 String rid RID of the prescription (size = 12 chars) Administrative Information 1 IdentifierType PrescriberIdentifierN/#/A 2 IdentifierType PatientIdentifier#N//A Strictly confidential For Recip-e project member use only Page 94

97 3 IdentifierType ExecutorIdentifierN/#/A Output Parameter Description Type Name Description (After decryption Process) Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="markasarchivedparam"> <xs:sequence> <xs:element name="rid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <markasarchived xmlns=" <MarkAsArchivedParam xmlns=""> <rid>beppaaaaaaaa</rid> </MarkAsArchivedParam> </markasarchived> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD Sample Implementation Specification Step Description 1 Check the SAML token. 2 Generate an XML request. 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) Strictly confidential For Recip-e project member use only Page 95

98 "CREATEFEEDBACK" [EXECUTOR SERVICES] Operation Name WSDL Description createfeedback This action creates a feedback for the prescriber about a specific prescription. When to be triggered When something special about the delivery should be notified to the Prescriber (ex : generic medicine delivery, dosage change) Errors Technical Services Exception such as Connection failure, Encryption failure Input Parameter Description Order Type Name Description (Before Encryption process) 1 Long prescriberid INSS id of the recipient 2 String rid RID of the prescription (size = 12 chars) 3 byte[] feedbacktext Xml message containing the feedback Administrative Information 1 IdentifierType PrescriberIdentifier 2 IdentifierType PatientIdentifier#N//A 3 IdentifierType ExecutorIdentifier Output Parameter Description Type Name Description (After decryption Process) Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="createfeedbackparam"> <xs:sequence> <xs:element name="content" type="xs:base64binary" minoccurs="0"/> <xs:element name="prescriberid" type="xs:long" minoccurs="0"/> <xs:element name="rid" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <createfeedback xmlns=" <CreateFeedbackParam xmlns=""> <content>c3ryaw5n</content> <prescriberid>10</prescriberid> <rid>beppaaaaaaaa</rid> </CreateFeedbackParam> </createfeedback> Strictly confidential For Recip-e project member use only Page 96

99 Output XML of the WS (Encrypted Part of the message - After decryption process) XSD Sample Implementation Specification Step Description 1 Check the SAML token. 2 Request the Encryption Token (Signed Public Key) of recipient to ETK Depot (ehealth service) 3 Generate an XML request. 4 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is the prescriber) 5 The message is enriched with meta data (recipient id ) 6 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 7 The message is sent to Recip-e, nothing is returned if the action is processed successfully (otherwise, an exception is thrown) "LISTNOTIFICATIONS" [EXECUTOR SERVICES] Operation Name WSDL Description listnotifications This function returns a list of notifications/addressed Prescriptions coming from Prescribers. When notifications are retrieved, they are automatically marked in the system as read, they stay in the system for a defined period of time (ex : 7 days). When to be triggered There are different options: - can be invoked on a regular basis (2x per day) and display the messages as popup to the executor - can be invoked on demand by the prescriber (when he opens a specific screen) Strictly confidential For Recip-e project member use only Page 97

100 Errors Technical Services Exception such as Connection failure, Encryption failure Input Parameter Description Order Type Name Description (Before Encryption process) Administrative Information 1 IdentifierType ExecutorIdentifier Output Parameter Description Type Name Description (After decryption Process) List<NotificaitionsItem> List of addressed Prescription Input XML of the WS (Encrypted Part of the message - Before Encryption process) XSD <xs:complextype name="listnotification"> <xs:sequence> <xs:element name="etk" type="xs:base64binary" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <listnotification xmlns=" <listnotificationparam xmlns=""> <ETK>aaaa</ETK> </ listnotificationparam > </listnotification> Output XML of the WS (Encrypted Part of the message - After decryption process) XSD <xs:complextype name="listnotificationsitem"> <xs:sequence> <xs:element name="prescriberid" type="xs:long" minoccurs="0"/> <xs:element name="sentdate" type="xs:datetime" minoccurs="0"/> <xs:element name="content" type="xs:base64binary" minoccurs="0"/> </xs:sequence> </xs:complextype> Sample <listnotifications xmlns=" <listnotificationsitem xmlns=""> <prescriberid > </prescriberId > <sentdate> t09:00:00</sentdate> <content>aaddsdfq</content> </ listnotificationsitem> </ listnotifications> Implementation Specification Step Description 1 Check the SAML token. 2 Generate an XML request. Strictly confidential For Recip-e project member use only Page 98

101 3 The message is ciphered using the Encryption Token of the recipient (seal()), the personal Encryption Token of the sender is attached to the request. (The recipient is Recip-e) 4 Message is sent to Recip-e, Recip-e returns the result as a SOAP message 5 The message is decrypted. (Method "unseal()" of the ETEE framework is used). Strictly confidential For Recip-e project member use only Page 99

102 7 APPENDIX: RECIP-E CLIENT PACKAGE CONTENT The package "Recip-e-client.zip" contains following files: - conf: Recip-e sample configuration files. - examples : sample application using Recip-e integration modules - src : source files in Java of the integration modules - wsdl : wsdl & xsd files for input/output of Recip-e web services - lib/dotnet : The integration modules in dotnet (See examples/gui for sample use) - lib/java : The integration modules in java (See examples/command-line for sample use) - log : folder containing the logs of the examples. Strictly confidential For Recip-e project member use only Page 100

103 8 APPENDIX : FREQUENTLY ASKED QUESTIONS Following is a list of frequently asked questions concerning the implementation of the integration specifications and the use of the integration modules. Question How do we change the default prescription used in the mock version of the integration modules? Doesn t it make more sense to add a string in front of the Recipe ID to indicate it is a Recip-e ID (instead of immediately beginning with BEPP) Which doctor id should we use, the one in the Kmehr message, or the one in the header? Is it possible to store more than one prescription in the same Kmehr message? Can we create our own prescriptions to use during testing? Since there is no archiving currently foreseen, what has to happen with the MarkAsArchived function during the pilot? Should we always call it? Can e-health provide a service to get public keys of doctors? How do we implement during the time when the e-health ETK service is not yet up? Please explain more in detail the certificate request procedure. Are there any tools we can use? Could you provide us with an example of a certificate? Do we need to resign responsibility document for each certificate renewal? Please provide more information on the 10 items limitation. How use the mock functionality in Windev? If a physical prescription contains more than 10 items, and we thus have to split it up over more than one electronic one, can we reuse ehealth keys for both prescriptions? In the notification, do we have to encapsulate the full Kmehr message in notification xml message? Can dll modules be used to do end to end encryption? (For other purpose than Recip-e communication). Answer The prescription, notification and feedback used in the mock version are found in the \examples\resources folder. You can update these files. This is currently not foreseen. During the course of the pilot this will be evaluated. The INAMI/RIZIV number No Yes, using the sample prescriber application or, when using the mock version, by updating the example xmls. This should only be called when the prescription has been archived. For testing purposes, we will have test cases where this functionality needs to be called. Use the ETK depot service. The service is already up. e-health will create a tool to automate this procedure. A sample certificate is provided in the conf folder of the module. The printable area of the prescription is limited to 80 chars wide on 10 lines height. If the prescription requires more space, the content should be split on multiple prescription having each one its own RID Declare the PrescriberIntegrationModuleMock class. This is valid for all programming languages. For Windev implementation specific questions please refer to your Windev documentation. No, each prescription has its own encryption key. The field is optional Yes Strictly confidential For Recip-e project member use only Page 101

104 The feedback is in text (without code CNK?). In our application, we need to flag delivered drugs. How can make something with text when receiving the feedback? Should the software provider maintain a list of executors (pharmacists) with correct IDs or are they available on e- Health? Where do we need to pass the SAML token in the different functions of the integration module? When do we need to signal the prescription as delivered? After one of the items has been delivered, or after all of the items have been delivered? The feedback is linked to the overall prescription. No link is foreseen with delivery items. Currently neither Recip-e nor e-health provides a pharmacist inventory. So at this time, implement it in the software itself. The SAML token is stored in memory by the module itself. You do not need to pass it as an input. If 1 of the items is delivered, the complete prescription is considered as delivered, and the MarkAsDelivered functionality should be called. Strictly confidential For Recip-e project member use only Page 102

105 9 APPENDIX: E-HEALTH CERTIFICATE CREATION 1. Use the ETEE requestor tool fase 1 to create an ehcsr. ( Please fill in the correct contact information (personal and group ). Strictly confidential For Recip-e project member use only Page 103

106 Strictly confidential For Recip-e project member use only Page 104

107 Strictly confidential For Recip-e project member use only Page 105

108 2. Send an to - [email protected] - [email protected] - [email protected] - [email protected] This must contains the generated ehcsr in step 1 and also the additional NIHII number needed for searching the ETK. 3. You will recieve an , using the contact information in step 1, from ehealth (AccessCoordination) with in this e- mail the public key and root CA. 4. Use the ETEE requestor tool fase 2 to generate and register the ETK's. Strictly confidential For Recip-e project member use only Page 106

109 Strictly confidential For Recip-e project member use only Page 107

110 Strictly confidential For Recip-e project member use only Page 108