INTEGRATION SPE IFI ATION - GF-Homeminf.vub.ac.be/~marc/Recip-e_Integration_Specification_v2_1_2.pdf · This document mainly presents technical information regarding integration with

RECIP-E

INTEGRATION SPECIFICATION

DOCUMENT CONTROL

Document revision history

Version Date Author Comments

0.1 01/06/2010 Thibaut Henry Draft

1.0 21/06/2010 Thibaut Henry Version for review

1.1 30/06/2010 Thibaut Henry Update for authentication

1.2 01/07/2010 Thibaut Henry Update following TSC of 1/7/2010

1.3 01/07/2010 Jos Van Dorpe Review

1.3.1 13/07/2010 Jos Van Dorpe Update with barcode format

1.4.0 19/07/2010 Thibaut Henry Review for module delivery

1.4.1 26/07/2010 Thibaut Henry Review remarks from Jos Van Dorpe

1.4.2 30/07/2010 Thibaut Henry Review remarks from TSC and from software vendors

1.4.3 12/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

1.4.4 19/08/2010 Martin Kwee Integrated WSDL specs exposed by eHealth

1.4.5 26/08/2010 Thibaut Henry Review remarks from TSC of the 26/08/2010

1.5 01/09/2010 Jos Van Dorpe Final updates for SSC validated version + included FAQ

1.5.1 03/09/2010 Jos Van Dorpe Incorporated additional remarks Marc Buckens

1.5.2 06/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

1.6.0 10/09/2010 Thibaut Henry Added further clarifications around the access to the keystore + changed pharmacy access rights: eID needs to be of a pharmacist

1.6.1 28/09/2010 Thibaut Henry Add extra information regarding KMEHR in the FAQ

1.7.0 15/11/2010 Thibaut Henry Take into account remarks following testing stages.

1.8.0 20/05/2011 Yannick Landuyt Add information about MyCareNet and requesting insurability information of a patient for the Executor.

1.9.0 25/10/2011 Yannick Landuyt Added information for mandate MyCareNet

2.0.0 13/07/2012 Yannick Landuyt Add extra information on lowering the amount of logging. Added information related to new features:

- retrieving old notifications/feedbacks - setting system keystore properties

2.1.0 31/10/2013 Yannick Landuyt Information added about the usage of 1 certificate as prescriber.

2.1.1 11/12/2013 Development team Added information about the eHealth technical connector implementation. Added information about new properties.

Application Analysis External References

Strictly confidential – For Recip-e project member use only Page | 1

Approval / Signatures

Version Date Approved By Signature



TABLE OF CONTENT

Table of Content ............................................................................................................................................................ 2

Table of Figures ............................................................................................................................................................. 5

List of Tables .................................................................................................................................................................. 6

1 External References ............................................................................................................................................... 7

2 Introduction ........................................................................................................................................................... 8

2.1 Recip-e solution .................................................................................................................................................... 8

2.2 Description and Purpose of the integration specifications ................................................................................... 9

2.3 Responsibility for this Document .......................................................................................................................... 9

2.4 Document Scope ................................................................................................................................................... 9

2.5 Additional information ......................................................................................................................................... 9

3 Integration Options .............................................................................................................................................. 10

4 Responsibilities .................................................................................................................................................... 11

4.1 Identification of the Patient ............................................................................................................................... 11

4.2 Prescription Format ............................................................................................................................................ 11

4.2.1 Kmehr XSD Validation ................................................................................................................................ 11

4.2.2 Additional Validation ................................................................................................................................. 11

4.2.3 Sample Prescription ................................................................................................................................... 12

4.2.1 Checking/setting the author of the prescription ....................................................................................... 15

4.2.2 Prescription Type ....................................................................................................................................... 15

4.3 Notification Format ............................................................................................................................................ 15

4.3.1 XSD validation ............................................................................................................................................ 15

4.3.2 Sample File ................................................................................................................................................ 16

4.4 Feedback Format ................................................................................................................................................ 16

4.4.1 XSD validation ............................................................................................................................................ 16

4.4.2 Sample File ................................................................................................................................................ 16

4.5 Authentication & Authorization ......................................................................................................................... 17

4.5.1 Definition ................................................................................................................................................... 17

4.5.2 Session creation ......................................................................................................................................... 17

4.5.3 Session creation Fallback ........................................................................................................................... 17

4.5.4 Session Stop ............................................................................................................................................... 18

4.5.1 Access to keystore ..................................................................................................................................... 18

4.6 Barcode specification ......................................................................................................................................... 18

4.6.1 Format Recip-ID ......................................................................................................................................... 18

4.6.1 Format barcode ......................................................................................................................................... 19

4.7 Print Prescription (For Prescribers) ..................................................................................................................... 19

4.7.1 Barcode ...................................................................................................................................................... 19



4.7.2 Medications ............................................................................................................................................... 20

4.8 Archiving (For Executor software) ...................................................................................................................... 21

4.8.1 When using the integration modules all required information is returned by the getPrescription function (see 5.3.3 Executor Integration Module ...................................................................................................................... 21

4.8.2 When using the web services, part of the information is returned by the getPrescription action of the ExecutorServices webservice (see 6.3.4 Executor Services ......................................................................................... 22

4.9 Performance Metrics Upload ............................................................................................................................. 22

5 Integration Option 1: Modules ............................................................................................................................. 23

5.1 Overview............................................................................................................................................................. 23

5.1.1 Prescriber software ................................................................................................................................... 23

5.1.2 Executor Software ..................................................................................................................................... 25

5.2 Integration Detail ............................................................................................................................................... 26

5.2.1 Approach ................................................................................................................................................... 26

5.2.2 Java ............................................................................................................................................................ 27

5.2.3 DLL ............................................................................................................................................................. 28

5.2.4 Module configuration ................................................................................................................................ 28

5.2.1 Mycarenet ................................................................................................................................................. 28

5.2.2 Certificates ................................................................................................................................................. 30

5.2.3 WSDLs ........................................................................................................................................................ 36

5.2.4 Logs ............................................................................................................................................................ 36

5.2.5 Properties .................................................................................................................................................. 37

5.3 Sevice Inventory.................................................................................................................................................. 38

5.3.1 Common Integration Module .................................................................................................................... 39

5.3.2 Prescriber Integration Module .................................................................................................................. 45

5.3.3 Executor Integration Module .................................................................................................................... 55

6 Integration Option 2: Webservices....................................................................................................................... 64

6.1 Overview............................................................................................................................................................. 64

6.1.1 Prescriber software ................................................................................................................................... 64

6.1.2 Executor Software ..................................................................................................................................... 66

6.2 Implementation Detail ....................................................................................................................................... 67

6.2.1 Authentication of the care provider .......................................................................................................... 67

6.2.2 Messaging and encryption ........................................................................................................................ 68

6.2.3 Prescriber Services .................................................................................................................................... 72

6.2.4 Executor Services (Pharmacist, Nurse…) ................................................................................................... 72

6.2.5 Error Management .................................................................................................................................... 72

6.2.6 eHealth Technical Connector .................................................................................................................... 73

6.3 Sevice Inventory.................................................................................................................................................. 73

6.3.1 Administrative Information ....................................................................................................................... 73

6.3.2 Party Identification .................................................................................................................................... 74

6.3.3 Prescriber Services .................................................................................................................................... 74



6.3.4 Executor Services ....................................................................................................................................... 86

7 APPENDIX: Recip-e Client Package Content.......................................................................................................... 98

8 APPENDIX: Release notes ..................................................................................................................................... 99

8.1 SDK version 1.0.0 ................................................................................................................................................ 99

8.2 SDK version 1.1.0 ................................................................................................................................................ 99

9 APPENDIX : Frequently asked Questions ............................................................................................................ 100



TABLE OF FIGURES

Figure 1 – Recip-e Solution Overview .................................................................................................................................... 8 Figure 2 – Sample prescription ............................................................................................................................................ 20 Figure 3 – Integration Option 1 (Integration Modules) - Prescriber .................................................................................... 23 Figure 4 – Integration Option 1 (Integration Modules) - Executor ...................................................................................... 25 Figure 5: Launch certificate request link. ............................................................................................................................. 31 Figure 6: Certificate request application. ............................................................................................................................ 31 Figure 7: Certificate choice screen....................................................................................................................................... 32 Figure 8: Key store location. ................................................................................................................................................ 33 Figure 9: Open key store password screen. ......................................................................................................................... 34 Figure 10 – Integration Option 2 (Webservices) - Prescriber .............................................................................................. 64 Figure 11 – Integration Option 2 (Webservices) - Executor................................................................................................. 66 Figure 12 – Addressed Encryption for Message transport .................................................................................................. 68 Figure 13 – Non-addressed encryption for Storage, Addressed Encryption for Message transport ................................... 69 Figure 14 – Addressed encryption for Storage, Addressed Encryption for Message transport .......................................... 70



LIST OF TABLES

Table 1 – External references ................................................................................................................................................ 7 Table 2 – Kmehr validation checks ...................................................................................................................................... 12 Table 3 – Authorization combinations ................................................................................................................................. 17 Table 4 – Sample SAML ........................................................................................................................................................ 67



1 EXTERNAL REFERENCES

Ref ID

Name URL

1. Barcode Symbology Specified in ISO/IEC 15417:2007

2. Non addressed Encryption

https://www.ehealth.fgov.be/binaries/website/en/Cookbook_Unknown_Recipientsv1-0.pdf

3. Addressed Encryption https://www.ehealth.fgov.be/binaries/website/en/Cookbook_ETEE_knownrecipient_v2-1.pdf

4. STS Cookbook Document is in attachment. Final URL will be included once available on eHealth portal.

5. eHealth certificates https://www.ehealth.fgov.be/binaries/website/en/requesting_eHealth_Certificates_v-2-0.pdf

6. eMed-ecare Use cases https://www.ehealth.fgov.be/binaries/website/fr/pdf/eMed-eCare_fr.pdf https://www.ehealth.fgov.be/binaries/website/nl/pdf/eMed-eCare_nl.pdf

7. Barcode print guideline Specified in ISO/IEC 15416 Table 1 – External references



https://www.ehealth.fgov.be/binaries/website/en/Cookbook_ETEE_knownrecipient_v2-1.pdf

https://www.ehealth.fgov.be/binaries/website/en/Cookbook_ETEE_knownrecipient_v2-1.pdf

https://www.ehealth.fgov.be/binaries/website/en/requesting_eHealth_Certificates_v-2-0.pdf

https://www.ehealth.fgov.be/binaries/website/en/requesting_eHealth_Certificates_v-2-0.pdf

https://www.ehealth.fgov.be/binaries/website/fr/pdf/eMed-eCare_fr.pdf

https://www.ehealth.fgov.be/binaries/website/nl/pdf/eMed-eCare_nl.pdf

Application Analysis Introduction


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…

Software

Voorschrijver

Prescriber

(bijv. arts)

eHealth systeem Recip-e WS

eHealth systeem Software

Zorgverlener

Recip-eWeb portaal

Patiënt

MyCareNet

diensten

Zorgverlener

(bijv. apotheker)

Paper

prescription

Paper

prescription

Beveiligde communicatie

via Internet

Recip-e perimeter

Software voor de professionele

medewerkers van de

gezondheid

Re

cip

-e M

od

ule

Re

cip

-e M

od

ule

Legende

Diensten gebruikt door

Recip-e

MyCareNet

diensten

Figure 1 – Recip-e Solution Overview

Application Analysis Introduction


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

Send[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.

Application Analysis Integration Options


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.

Application Analysis Responsibilities


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: https://www.ehealth.fgov.be/standards/kmehr/.

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).

4.2.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: https://www.ehealth.fgov.be/standards/kmehr/.

At this moment, the prescription must be compliant with the version “20100601-kmehr” of the XSD definition (XSD packaged in a zip can be downloaded at this URL: https://www.ehealth.fgov.be/standards/kmehr/sites/default/files/assets/kmehr/20100601/20100601-kmehr.zip).

4.2.2 ADDITIONAL VALIDATION

The kmehr standard defines many different type of message regarding the healthcare sector. In the first stage of Recip-e (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 Recip-e system.

The table below 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 @SV='1.0' and text()='pharmaceuticalprescription']

1

Must contain between 1 and 10 items

/kmehrmessage/folder/transaction/heading/item/cd[@S='CD-ITEM' and @SV='1.0']

1 to 10 (included)

https://www.ehealth.fgov.be/standards/kmehr/

https://www.ehealth.fgov.be/standards/kmehr/

https://www.ehealth.fgov.be/standards/kmehr/sites/default/files/assets/kmehr/20100601/20100601-kmehr.zip



Valid Patient First name /kmehrmessage/folder/patient/firstname 1

Valid Patient Family name

/kmehrmessage/folder/patient/familyname 1

Valid Patient ID /kmehrmessage/folder/patient/id[@S='ID-PATIENT' and @SV='1.0']

1

Valid Prescriber First name

/kmehrmessage/header/sender/hcparty//firstname 1

Valid Prescriber Family name

/kmehrmessage/header/sender/hcparty//familyname 1

Valid Prescriber ID /kmehrmessage/header/sender/hcparty/id[@S='ID-HCPARTY' and @SV='1.0']

1

Table 2 – Kmehr validation checks

For more information about XPATH queries, please refer to http://www.w3.org/TR/xpath/ .

4.2.3 SAMPLE PRESCRIPTION

<?xml version="1.0" encoding="UTF-8" standalone="no" ?> <kmehrmessage xmlns="http://www.ehealth.fgov.be/standards/kmehr/schema/v1"> <header> <standard> <cd S="CD-STANDARD" SV="1.1">20100601</cd> </standard> <id S="ID-KMEHR" SV="1.0">14675011004.20090110090000000</id> <id S="LOCAL" SL="ID-RECIPE" SV="1.0">8e1c4ea4-3825-48e4-bcc2b8cadfa7a897</id> <date>2010-08-01</date> <time>09:00:00</time> <sender> <hcparty> <id S="ID-HCPARTY" SV="1.0">14675011004</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">87990949113</id> <firstname>Fred</firstname> <familyname> Flintstone</familyname> <birthdate> <date>1933-10-23</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>2010-08-01</date> <time>09:00:00</time> <author> <hcparty> <id S="ID-HCPARTY" SV="1.0">14675011004</id> <cd S="CD-HCPARTY" SV="1.0">persphysician</cd> <name>Dr. Duck Donald</name> </hcparty>

http://www.w3.org/TR/xpath/



</author> <iscomplete>true</iscomplete> <isvalidated>true</isvalidated> <expirationdate>2013-08-01</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">0318717</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">1085885</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">1077718</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>



<cd S="CD-ITEM" SV="1.1">medication</cd> <content> <medicinalproduct> <intendedcd S="CD-DRUG-CNK" SV="2.0">1057959</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="2010-07" S="CD-DRUG-CNK">1484229</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="2010-07" S="CD-INNCLUSTER">8038747</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>



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.

4.2.2 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.

4.3.1 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="http://www.w3.org/2001/XMLSchema" xmlns:km="http://www.ehealth.fgov.be/standards/kmehr/schema/v1" xmlns="http://services.recipe.be" targetNamespace="http://services.recipe.be"> <xs:import namespace="http://www.ehealth.fgov.be/standards/kmehr/schema/v1" schemaLocation="../20100601-kmehr/ehealth-kmehr/XSD/kmehr_elements.xsd"/> <xs:element name="notification">



<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>

4.3.2 SAMPLE FILE

<?xml version="1.0" encoding="ISO-8859-1"?> <p:notification xmlns:p="http://services.recipe.be" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://services.recipe.be 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.

4.4.1 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="http://www.w3.org/2001/XMLSchema" xmlns="http://services.recipe.be" targetNamespace="http://services.recipe.be"> <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>

4.4.2 SAMPLE FILE

<?xml version="1.0" encoding="ISO-8859-1"?> <p:feedback xmlns:p="http://services.recipe.be" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://services.recipe.be feedback.xsd"> <text>this is a feedback</text> </p:feedback>



4.5 AUTHENTICATION & AUTHORIZATION

4.5.1 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.

4.5.2 SESSION CREATION

The authentication must be done at session start-up and uses

• eID of a physical user (+ PIN code) • organizational (Executor) or personal (Prescriber) 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 Personal eHealth certificate (identified by the SSIN)

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

The software provider has the responsibility to make sure that the care provider:

- 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 http://eid.belgium.be)

- Has a valid eHealth certificate stored in a secured Keystore (p12 file). Refer to doc [5].

4.5.3 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).



Important: 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.

4.5.4 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.

4.5.1 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.

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 Possible characters are 0123456789ABCDEFGHKLMNPRSTVWXYZ o 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.



4.6.1 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)

4.7.1 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 : http://www.inami.fgov.be/drug/nl/pharmacists/papers/prescriptions/index.htm

- FR : http://www.inami.fgov.be/drug/fr/pharmacists/papers/prescriptions/index.htm 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 …).

http://www.inami.fgov.be/drug/nl/pharmacists/papers/prescriptions/index.htm

http://www.inami.fgov.be/drug/fr/pharmacists/papers/prescriptions/index.htm



Figure 2 – Sample prescription

4.7.2 MEDICATIONS



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 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.

4.8.1 WHEN USING THE INTEGRATION MODULES ALL REQUIRED INFORMATION IS RETURNED BY THE GETPRESCRIPTION FUNCTION (SEE 5.3.3 EXECUTOR INTEGRATION MODULE

Once authenticated, the common integration module keeps the SAML token in memory and the executor functionalities

can be called.

Interface be.connector.executor.recipe.ExecutorIntegrationModule

Implementation: be.connector.executor.recipe.ExecutorIntegrationModuleImpl

The module is constructed using the above implementation class, it requires the following parameters (there are extra

helper constructors available, see source code):

Signature public ExecutorIntegrationModuleImpl(String propertyfile, RequestorProvider requestorIntegrationModule, CommonIntegrationModule commonIntegrationModule) throws IntegrationModuleException

Parameters Propertyfile: path to property file containing configuration for the connector module.

This path can either be absolute (e.g. “C:\config.properties”) or relative to the class

path of the application (e.g. “/config.properties”). If using IKVM, some experimentation

may be needed to find out this class path.

CommonIntegrationModule: module that contains the information related to

the SAML and has to be initialized before using the prescriber functionalities.

RequestorProvider: module that contains specific information related to the

requestor.

getPrescription):

- Prescription: variable ‘sealedContent’ in the return of the getPrescription function

- Time stamp: variable ‘timestampingId’ in the return of the getPrescription function

- e-Health encryption key: variable ‘encryptionKey’ in the return of the getPrescription function



4.8.2 WHEN USING THE WEB SERVICES, PART OF THE INFORMATION IS RETURNED BY THE GETPRESCRIPTION ACTION OF THE EXECUTORSERVICES WEBSERVICE (SEE 6.3.4 EXECUTOR SERVICES

getPrescription), part of the information is returned by the getKey operation of the e-Health KGSS web service (see 6.2.6.3 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 5.3.3.4markAsArchived when using the integration module, and 6.3.4.5 markAsArchived 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. 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 http://perf4j.codehaus.org/) Sample:

start[1280418692984] time[1945] tag[ExecutorIntegrationModule#getPrescription.success] start[1280418695489] 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().

http://perf4j.codehaus.org/

Application Analysis Integration Option 1: Modules


5 INTEGRATION OPTION 1: MODULES

5.1 OVERVIEW

5.1.1 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.

Recip-e

Central

System

Doctor

Software

Recip-E

Integration

Module

createPrescription

(KmehrMessage)

RID

A B

F

C

D

G

H

SendNotification

(RID)

E

eHealth

Services

createSession()

SAML Token

RevokePrescription

(RID)

ListOpenPrescriptions()

GetPrescription(RID)

UpdateFeedbackFlag()

ListFeedbacks()

eH

ea

lth

ES

B

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:



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).



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.

Recip-e

Central

System

Pharmacist

Software

Recip-E

Integratio

n Module


MarkAs(Un)Delivered(RID)

CreateFeedback(XMLFeedback)

A B

E

C

D

ListAddressedPrescriptions()

F

eHealth

Services

createSession()

SAML Token

MarkAsArchived(RID)

G

eH

ea

lth

ES

B

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. For P1 prescriptions there is also the possibility to request the insurability 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.

7. Get Insurability: retrieve the patients insurability information. The integration module returns a string representation of the xml.









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

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

5.2.1 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).

5.2.1.1 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:

5.2.1.2 EHEALTH SERVICES

Once you have successfully integrated Recip-e API, you can replace the integrationModuleMock by the e-health connected module. This module are available :



- For Prescriber : in the class PrescriberIntegrationModule

- For Executor : in the class ExecutorIntegrationModule Both modules take in argument the path to the Recip-e configuration file.

5.2.2 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:

Import be.connector.common.CommonIntegrationModule Import be.connector.executor.recipe .ExecutorIntegrationModuleImpl Import be.connector.prescriber.recipe.PrescriberIntegrationModule

Important: In the future this class will be deprecated.

Import be.recipe.client.PrescriberIntegrationModule

Prescriber/Executor APIs can then be invoked using code: Sample Code for Prescriber:

Sample code for Executor:



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.

5.2.3 DLL

The DLL files contained in the folder “dotNet/.” of the Recip-e-client.zip package must be added to your project dependencies. Then, the Recip-e client can be used with the code (VB.NET):

5.2.4 J2PCSC.DLL

The j2pcsc.dll needs to be placed in the working directory (the folder where you start the application .exe, .bat or …).

5.2.5 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/connector-client.properties” The Path to the configuration file should be defined in argument of the module constructor.

5.2.1 MYCARENET

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.

pharmacy-holder.ssin=86041036109

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

5.2.1.1 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. . The insurability can only be requested for P1 prescriptions. With the following parameters in the configuration file you can enable and disable the insurability retrieval. The “pharmacy-holder.ssin=86041036109” is the NISS number of the pharmacy holder.

pharmacy-holder.ssin=86041036109

patient.insurability.disable=false

5.2.1.2 DIRECT CONNECTION

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 package name to MyCareNet support

- Create a e-Health STS session with the module (normal or fallback or mandate)

- Use the getInsurability() method of the Executor module to request the insurability. More information on the input parameters can be found on MyCarenet sharepoint ( http://share.intermut.be/home/MyCareNet/pharmacist/default.aspx ) 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>12345123451234</ns2:Reference> </ns3:CommonOutput> <ns3:RecordCommonOutput> <ns2:Reference>278</ns2:Reference> <ns2:IoReference>0</ns2:IoReference> <ns2:UserReference>86041036109</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>86041036109</ns2:Ssin> <ns2:RegNrWithMut> </ns2:RegNrWithMut> <ns2:Mutuality>111</ns2:Mutuality> <ns2:FirstName>YANNICK ERIK</ns2:FirstName> <ns2:LastName>LANDUYT</ns2:LastName> <ns2:Birthday>1986-04-10</ns2:Birthday> <ns2:Sex>male</ns2:Sex> </ns2:CareReceiver>

http://share.intermut.be/home/MyCareNet/pharmacist/default.aspx



<ns2:Coverage> <ns2:Communicated>2011-05-23</ns2:Communicated> <ns2:Period> <ns2:BeginDate>2011-01-01</ns2:BeginDate> <ns2:EndDate>2011-01-31</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>1461301420</ns2:PaymentApprovalSeed> <ns2:InvoicingOfficeCheckDigit>Sh</ns2:InvoicingOfficeCheckDigit> </ns2:Verification> </ns3:InsurabilityResponse> </ns3:GetInsurabilityForPharmacistResponse>

5.2.2 CERTIFICATES

Recip-e is an end-to-end secured system using the eHealth platform. Before any interaction with eHealth can be

established, the system and user must be able to identify themselves:

One eHealth certificates must be configured for the prescribers and at least 2 eHealth certificates have to be

configured for executor.

o The personal certificate, specific to the user/pharmacist/prescriber.

o The system or organization certificate, specific to the pharmacy.

Both can be requested on the eHealth website as explained next.

Next to the personal certificate, the eID is used for user authentication and session negotiation with eHealth,

preferably at software startup. After 12 hours, the session is invalidated and must be established again.

o Consequently a correctly installed eID reader is required.

o If there is a problem with the eID or the reader, a fallback session can be created using only the personal

certificate and corresponding password. However to discourage this less secure authentication method, the

fallback sessions only have a validity of one hour before needing renewal.

Keep in mind that a certificate request is a two-step process. Any request will be evaluated and approved individually.

Between the initial request and completion, a few business days may pass.

5.2.2.1 ENVIRONMENTS

Certificates are only valid for a specific runtime environment (integration, acceptance, production).

The link below requests certificates for the acceptance environment. For production, only real pharmacists are

able to request certificates. For integration, one must request the URL to eHealth.

Which environment is used is configured by changing the end-point URLs for the web services.

o In the connector module, the end-points for eHealth services are configurable in the connector properties.

5.2.2.2 SOFTWARE REQUIREMENTS

Java must be installed (http://www.java.com/en/download/manual.jsp).

For Microsoft Windows, refer to http://support.microsoft.com/kb/827218 to find out what platform is running.

o On a 32-bit platform, one can only install the 32-bit edition of Java, this is fine.

o On a 64-bit platform, the 32-bit edition of Java must be used as well. The 64-bit edition of Java does not

support reading eID cards (which uses PKCS#11 cryptography) as explained here:

http://docs.oracle.com/javase/6/docs/technotes/guides/security/p11guide.html#Requirements

http://www.java.com/en/download/manual.jsp

http://support.microsoft.com/kb/827218

http://docs.oracle.com/javase/6/docs/technotes/guides/security/p11guide.html#Requirements



If both 32-bit and 64-bit versions of Java are installed on Windows, one must make sure the certificate request module

and the connector module are run on the 32-bit version. Remove the 64-bit version to remove this complexity – all java

programs will continue to run.

The eID middleware (http://eid.belgium.be) must be installed and an eID reader must be connected with the eID of the

requestor inserted.

5.2.2.3 INITIATE CERTIFICATE CREATION

1. Visit the website https://www.ehealth.fgov.be/nl/support/basisdiensten/ehealth-certificaten and click on the

link “Please use this application”, above the download table (see figure below).

Figure 5: Launch certificate request link.

2. Click "Run” on the java dialog box that pops up.

3. Click the “Create new request” button (see figure).

Figure 6: Certificate request application.

4. Read and accept the terms and conditions.

http://eid.belgium.be/

https://www.ehealth.fgov.be/nl/support/basisdiensten/ehealth-certificaten



5. The eID card is read, click “next” (this button is only active when the eID can properly be read).

6. On the next screen (see figure), pick the option that displays your name for the personal certificate.

Figure 7: Certificate choice screen.

7. Fill your personal coordinates, only the email and telephone number are required.

8. A summary is displayed, click next.

9. Enter the pin for your eID when prompted.

10. Choose a password for your personal certificate. This password is needed for the fallback session so

remember it well.

11. The next screen shows the location of the newly created key store. This key store must be configured in the

connector module in a later stage, so make sure to remember the location.



Figure 8: Key store location.

12. As a final step, the certificate request is sent to eHealth.

For pharmacies in particular, the NIHII number. Steps 1 – 6 and 9 – 13 are identical as for the personal certificate, on

step 7 choose the second option instead.

8. Fill the information as requested of your organization. Leave the application ID empty.

If there is a problem with the certificate request, contact the eHealth helpdesk. A direct link is present within the

certificate request application. Alternatively, the helpdesk can be contacted on the following phone number: 02 788 51

55 or via the website https://www.ehealth.fgov.be/nl/contact.

5.2.2.4 COMPLETE CERTIFICATE CREATION

When the requestor is contacted through one of the coordinates included in the certificate request, he/she must open

the eHealth application again as explained in the previous section.

4. Click on the “Complete request” button.

5. Browse for and select the key store as created in the request.

6. Fill the password as chosen for the request.

https://www.ehealth.fgov.be/nl/contact



Figure 9: Open key store password screen.

7. Confirm certificate completion.

More documentation and other procedures such as revocation can be found on the eHealth website.

5.2.2.5 KEYSTORE PROPERTIES DEFINED IN CONFIGURATION FILE

The properties of the key store can be defined in the configuration file as follow:

- KEYSTORE_DIR: PATH of the p12 folder where the keystores has been stored. The keystore must be a PKCS12 keystore (“*.p12”). The authentication certificate must have the alias “authentication”. This folder also contains the caCertificateKeystore.jks used for connection to eHealth services.

Executor:

- sessionmanager.holderofkey.keystore: name of the pharmacist certificate.

- sessionmanager.encryption.keystore: name of the pharmacist certificate.

- sessionmanager.identification.keystore: personal certificate in case of a fallback session. Prescriber:

- sessionmanager.holderofkey.keystore: name of personal certificate from the prescriber.

- sessionmanager.encryption.keystore: name of personal certificate from the prescriber.

- sessionmanager.identification.keystore: name of personal certificate in case of a fallback session. Overview of a system key store opened with Keystore explorer:



Sample key store section of the connector-client.properties configuration file:

KEYSTORE_DIR=%CONF%/p12/ sessionmanager.holderofkey.keystore=NIHII-PHARMACY=66666219 20130502-144031.p12 sessionmanager.encryption.keystore=NIHII-PHARMACY=66666219 20130502-144031.p12 sessionmanager.identification.keystore=SSIN=86041036109 20131030-155419.p12

For multi-user access or fall-back session creation (e.g.: several doctors sharing the same workstation), it is possible to copy 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_DIR:

5.2.2.6 KEYSTORE PROPERTIES PROVIDED WITH METHOD SETSYSTEMKEYSTOREPROPERTIES

The method setsystemkeystoreproperties makes it possible to set your system keystore properties in code and not with the configuration file.

setSystemKeystoreProperties(String systemKeystorePassword, String systemKeystorePath, String systemKeystoreDirectory, String systemKeystoreRizivKBO){

The minimal information that needs to be provided is

- The system keystore password.

5.2.2.7 PREVIOUS KEYSTORE PROPERTIES PROVIDED WITH METHOD SETOLDSYSTEMKEYSTOREPROPERTIES



The method setOldSystemKeystoreProperties makes it possible to provide a previous system keystore to unseal notifications or feedbacks that were sealed with an older certificate.

setOldSystemKeystoreProperties(String systemKeystorePassword, String systemKeystorePath, String systemKeystoreDirectory, String systemKeystoreRizivKBO){

The minimal information that needs to be provided is

- The system keystore password. This method will need to be set when a user requests a new certificate. If the method is not set and a notification/feedback, sealed with the old certificate, is retrieved you will receive the exception :

[ERR200004] An error occurred while unsealing the data. If the problem persists, please contact the helpdesk.

5.2.3 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 : Recip-e web services URL that should be used by Prescriber (for “CreatePrescription”…)

- wsdl.ehealth.executor: Recip-e web services URL that should be used by Prescription executor (for Prescription Delivery…)

- wsdl.sts: EHealth secure token service URL (SAML assertion generator)

- wsdl.etk: EHealth ETK Depot URL (public key repository)

- wsdl.kgss: EHealth Encryption key generator & storage service URL.

- wsdl.ehealth.insurability: MyCareNet service URL

5.2.4 LOGS

The log configuration parameters are defined in the file “${INSTALL_DIR}/conf/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 “connector.log”

- A new file is created each new day; the previous file is then renamed and zipped in “connector-YYYYMMDD.log”.

- A history of 7 days is stored on the file system, older files are removed. The possible log levels are:

Level Description

DEBUG The DEBUG Level designates fine-grained informational events that are most useful to debug an application.

INFO The INFO level designates informational messages that highlight the progress of the application at coarse-grained level.

WARN The WARN level designates potentially harmful situations.

ERROR The ERROR level designates error events that might still allow the application to continue



running.

FATAL The FATAL level designates very severe error events that will presumably lead the application to abort.

To change the log level you need to change the following value <priority value="DEBUG"></priority> to one of the above log levels. <?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">

…

<root>

<priority value="DEBUG"></priority>

<appender-ref ref="FILE"/>

</root>

</log4j:configuration>

5.2.5 PROPERTIES

Since we use the eHealth technical connector, a lot of properties has been changed. If it is possible, we use the same properties that the eHealth technical connector needs to manage the calls to their services. We will list all the properties that can be changed. If the properties are not listed here, no change is needed.

5.2.5.1 PRESCRIBER & EXCECUTOR PROPERTIES:

# Path to the log file. LOG4J=%CONF%/log4j.xml

# WSDL locations (needs to be changed according the environment) wsdl.ehealth.technical=%CONF%/wsdl/Technical_v1_preprod.wsdl

# Endpoint locations (needs to be according the environment changes) endpoint.sts=https://wwwacc.ehealth.fgov.be/sts_1_1/SecureTokenService endpoint.etk=https://wwwacc.ehealth.fgov.be/etkdepot_1_0/EtkDepotService endpoint.kgss=https://services-acpt.ehealth.fgov.be/Kgss/v1

# Location of the p12 folder KEYSTORE_DIR=%CONF%/p12/

# The proxy settings http.proxyHost= http.proxyPort= http.proxyUser= http.proxyPassword= https.proxyHost= https.proxyPort= https.proxyUser= https.proxyPassword=

# The the user information, inss is used in the SAML attributes user.firstname= user.lastname= user.inss=86041036109

# Session validation (in hours)

sessionmanager.validity.token=5



# The keystores file names sessionmanager.holderofkey.keystore=SSIN=86041036109 20131030-155419.p12 sessionmanager.encryption.keystore=SSIN=86041036109 20131030-155419.p12 sessionmanager.identification.keystore=SSIN=86041036109 20131030-155419.p12

5.2.5.2 EXECUTOR SPECIFIC PROPERTIES

# WSDL locations (needs to be changed according the environment) wsdl.ehealth.insurability=%CONF%/wsdl/MyCareNet-1.0.wsdl wsdl.ehealth.executor=%CONF%/wsdl/Executor_v2_preprod.wsdl # ID’s of the tip, tipsystem, pcdh default.tip.id=0406753266 pcdhsystem.id=0406753266 tipsystem.id=0406753266

# The message queue of the GFD DPP project MESSAGE_QUEUE_FOLDER= %CONF%/msg_queue

# The time, in seconds, between each check if there is something on the queue MESSAGE_QUEUE_TIMER=5 # The status message queue of the GFD DPP project STATUS_MESSAGE_QUEUE_FOLDER=%CONF%/status_msg_queue

# Folder of all the returned TIP System configuration files. TIP_CONFIGURATION_PATH=%CONF%/update

# Folder of the productfilter files. PRODUCT_FILTER_PATH=%CONF%/update/productfilter # Folder of the system services files. SYSTEM_SERVICES_PATH=%CONF%/update/systemservices # Number of threads started to decrypt the getData products (important: if you change this number it will have an impact on the performance) thread.number.limit=10 # The pharmacy nihii and pharmacy-holder ssin used in the SAML attributes pharmacy.nihii=66666219 pharmacy-holder.ssin=86041036109

#Activation/deactivation of the insurability when retrieving a prescription. patient.insurability.disable=false

5.2.5.3 PRESCRIBER SPECIFIC PROPERTIES

# WSDL locations (needs to be changed according the environment

wsdl.ehealth.prescriber=%CONF%/wsdl/Prescriber_v1_preprod.WSDL

5.3 SEVICE INVENTORY

This section lists all available API in the integration modules.



Important: Previous integration of the prescriber module is deprecated and will be discontinued in next releases.

5.3.1 COMMON INTEGRATION MODULE

Once the certificates are available, the connector module must be pointed to the key stores containing them using one

of the configuration options A session can be started using the start session operation.

Because of the decoupling of the technical connector and the business connector, session management is

different from previous versions and is contained in its own component. This component is consulted by each

business integration module, achieving single-sign-on for every service provided, not just recipe/mycarenet.

Once authenticated, the integration module keeps the SAML token in memory. This SAML token is a key element in

authentication mechanism and therefore must be destroyed if the care provider does not need to use any service any

more.

Interface be.connector.common.CommonIntegrationModule

Implementation: be.connector.common.CommonIntegrationModuleImpl



Signature CommonIntegrationModuleImpl(String propertyfile) throws IntegrationModuleException

Parameters Propertyfile (required): path to property file containing configuration for the connector

module. This path can either be absolute (e.g. “C:\config.properties”) or relative to the

class path of the application (e.g. “/config.properties”). If using IKVM, some

experimentation may be needed to find out this class path.

Signature CommonIntegrationModuleImpl(String propertyfile , String urlConfig) throws

IntegrationModuleException

Parameters Propertyfile (required): path to property file containing configuration for the connector

module. This path can either be absolute (e.g. “C:\config.properties”) or relative to the

class path of the application (e.g. “/config.properties”). If using IKVM, some

experimentation may be needed to find out this class path.

urlConfig (required): URL that replace the %CONF% in the property file that contains

the configuration for the connector module.

The property “PERSONAL_KEYSTORE” is required in the property file to use the fallback session.

5.3.1.1 CREATESESSION

Operation Name createSession

Class name CommonIntegrationModule

Description 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 to be triggered 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

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

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 used 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

4 The module returns the SAML token as an XML message. This XML message can be stored on the hard disk (Cookie like)

#N/A

5.3.1.2 LOADSESSION"

Operation Name loadSession


Description 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).


1 String xmlSamlToken The SAML token received by "createSession"

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


#N/A #N/A #N/A


1 The module is initialized with the given SAML token, all WS exchanges with Recip-e will use this token.

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

5.3.1.3 UNLOADSESSION

Operation Name unloadSession


Description 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 #N/A


#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


#N/A #N/A #N/A


1 The module destroys is current SAML token.

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

5.3.1.4 CREATEFALLBACKSESSION

Operation Name createFallbackSession


Description 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


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.

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


String xmlSamlToken SAML response obtained from eHealth STS service. The SAML token has a validity of 1H. This SAML token can be stored by the software provider (in a file or in a database). The function "loadSession" should be used to restore the session.


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)

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

5.3.1.5 HASVALIDSESSION



Operation Name hasValidSession


Description 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



Boolean sessionValidity A Boolean that states if the session is still valid.


1 The module checks if the current session is still valid.

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A



5.3.2 PRESCRIBER INTEGRATION MODULE

Once authenticated, the common integration module keeps the SAML token in memory and the prescriber

functionalities can be called.

Interface be.connector.prescriber.recipe.PrescriberIntegrationModule

Implementation: be.connector.prescriber.recipe.PrescriberIntegrationModuleImpl



Signature public PrescriberIntegrationModuleImpl(String propertyFile, CommonIntegrationModule commonIntegrationModule, RequestorProvider requestorIntegrationModule) throws IntegrationModuleException








requestor.

5.3.2.1 PREPARECREATEPRESCRIPTION

Operation Name prepareCreatePrescription

Class Name PrescriberIntegrationModule

Description 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 #N/A


1 Long patientId The ID of the patient

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A




#N/A #N/A #N/A


1 Retrieves Encryption keys of KGSS, Recip-e. Create the symmetric key for addressed encryption

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

5.3.2.2 CREATEPRESCRIPTION

Operation Name createPrescription


Description 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 to be triggered 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


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


String rid RID of the prescription (size = 12 chars)


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.

#N/A

5.3.2.3 REVOKEPRESCRIPTION

Operation Name revokePrescription


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 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.

Errors Technical Services Exception such as Connection failure, Encryption failure




1 String rid RID of the prescription (size = 12 chars)

2 String reason Revoke reason to be used in the audit trail

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


#N/A #N/A #N/A



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)

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

5.3.2.4 SENDNOTIFICAITON

Operation Name sendNotification


Description This function 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


1 byte[] notificationText Xml message containing the notification. Must be validated by the provided XSD


2 Long executorId NIHII-PHARMACY (APB+check digit) id of the recipient.

#N/A #N/A #N/A

#N/A #N/A #N/A


#N/A #N/A #N/A



2 The module requests the Encryption Token (Signed Public Key) of recipient to ETK Depot (eHealth service)


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)




#N/A

#N/A

#N/A

5.3.2.5 GETPRESCRIPTION

Operation Name getPrescription (for Prescriber)


Description 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


1 String Rid RID of the prescription (size = 12 chars)

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


GetPrescription ForPrescriberResult

prescription Structure containing meta-data + Prescription content as a Validated XML Kmehr message. Attributes of the structure :

- creationDate : Calendar

- encryptionKeyId : String

- patientId : Long

- prescription : byte[]

- insurability : String

- rid : String





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).


7 The module generates a "Symmetric Key request"


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()



5.3.2.6 LISTFEEDBACK

Operation Name listFeedback


Description 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.

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


#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


List<ListFeedbackItem> listFeedback List of feedbacks. ListFeedbackItem is a structure containing following fields :

- content : byte[]

- rid : String

- sentBy : Long

- sentDate : Calendar









6 Each single feedback is then decrypted using unseal() method

#N/A

#N/A

#N/A

#N/A

5.3.2.7 SETPERSONALPASSWORD

Operation Name setPersonalPassword


Description This action unlock the personal private key stored in the folder “KEYSTORE_DIR”. 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


#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


String password The password of the keystore


1 The module scan the folder KEYSTORE_DIR for file named “SSIN=<ssin>*.p12.

2 If password matches, the module add the private encryption key to the current keystore



#N/A

#N/A

#N/A

#N/A

5.3.2.8 LISTOPENPRESCRIPTION

Operation Name listOpenPrescription


Description 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)



#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


List<String> List of rid









#N/A

#N/A

#N/A

#N/A

#N/A

5.3.2.9 UPDATEFEEDBACKFLAG

Operation Name updateFeedbackFlag


Description 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"



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

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


#N/A #N/A #N/A








#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

5.3.3 EXECUTOR INTEGRATION MODULE

Once authenticated, the common integration module keeps the SAML token in memory and the executor functionalities

can be called.

Interface be.connector.executor.recipe.ExecutorIntegrationModule

Implementation: be.connector.executor.recipe.ExecutorIntegrationModuleImpl



Signature public ExecutorIntegrationModuleImpl(String propertyfile, RequestorProvider requestorIntegrationModule, CommonIntegrationModule commonIntegrationModule) throws IntegrationModuleException








requestor.


Operation Name getPrescription (for Executor)

Class Name ExecutorIntegrationModule

Description 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 to be triggered When the barcode of the prescription has been read




#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


GetPrescription ForExecutorResult

prescription A structure containing :

- creationDate : Calendar

- encryptionKeyId : String

- encryptionKey : byte[]

- 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



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




8 The module generates a "Symmetric Key request"





11 The message is decrypted using unsealForUnknown()

5.3.3.2 MARKASUNDELIVERED

Operation Name markAsUnDelivered


Description 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




#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


#N/A #N/A #N/A






#N/A

#N/A

#N/A



#N/A

#N/A

#N/A

5.3.3.3 MARKASDELIVERED

Operation Name markAsDelivered


Description 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.




#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


#N/A #N/A #N/A






#N/A

#N/A



#N/A

#N/A

#N/A

#N/A

5.3.3.4 MARKASARCHIVED

Operation Name markAsArchived


Description 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 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)



#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


#N/A #N/A #N/A






#N/A



#N/A

#N/A

#N/A

#N/A

#N/A

5.3.3.5 CREATEFEEDBACK

Operation Name createFeedback


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)



1 Long prescriberId NIHII id of the recipient (the same one as the one received by GetPrescription.prescriberId).


3 byte[] feedbackText Xml message containing the feedback

#N/A #N/A #N/A

#N/A #N/A #N/A


#N/A #N/A #N/A



2 The module requests the Encryption Token (Signed Public Key) of recipient to ETK Depot (eHealth service)








#N/A

#N/A

#N/A

5.3.3.6 LISTNOTIFICATIONS

Operation Name listNotifications


Description 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)



#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


List<ListNotificationsItem> List of notifications

ListNotificationsItem is structure containing :

- content : byte[]

- sentBy : Long

- sentDate : Calendar









#N/A

#N/A

#N/A

#N/A

#N/A

5.3.3.7 GETINSURABILITY

Operation Name getInsurability


Description This function retrieves the insurability of the patient at a specific date

When to be triggered After a prescription delivery.

Errors Refer to Mycarenet documentation




String String String String String String String String String String String

#N/A 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

#N/A


String Insurability The XML Insurability (including e-health ESB service status)


1 The module retrieves the insurability from Mycarenet.

#N/A

#N/A

#N/A

#N/A

#N/A

Application Analysis Integration Option 2: Webservices


6 INTEGRATION OPTION 2: WEBSERVICES

6.1 OVERVIEW

6.1.1 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.

Recip-e

Central

System

Doctor

Software

createPrescription

(KmehrMessage)

RID

A B

F

C

D

G

H

SendNotification

(RID)

E

eHealth

Services

createSession()

SAML Token

RevokePrescription

(RID)

ListOpenPrescriptions()


UpdateFeedbackFlag()

ListFeedbacks()

getETK()

getNewKey()

I J

Figure 10 – 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:



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)







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).



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.

Recip-e

Central

System

Pharmacist

Software


MarkAs(Un)Delivered(RI

D)

CreateFeedback(XMLFe

edback)

A B

E

C

D

ListAddressedPrescript

ions()

F

eHealth

Services

MarkAsArchived(RID)

G

createSession()

SAML Token

getETK()

GetKey()

Figure 11 – 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



sent to the module with the Recip-e unique identification number (RID). The executor receives a confirmation that the prescription has been cancelled.







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

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

6.2.1 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

example.hok.request.xml

Sample SAML response

example.hok.response.xml

Table 4 – Sample SAML

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 http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf for more information about SAML and WS-Security.

http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf



6.2.2 MESSAGING AND ENCRYPTION

6.2.2.1 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).

6.2.2.2 ENCRYPTION FOR TRANSPORT

Following diagram illustrates the different steps of the transformation process to be implemented:

Encryption for Transport

ETEE: SIGN

ETEE: ASYM. ENCRYPT

ETEE : SIGN

BODY

HEADER

SAML ASSERTION HOK

SIGNED BY EH

TIMESTAMP (MESSAGE- TTL)

SIGN BODY, ASS, TIMESTAMP

[proof-of-possession HOK]

Message Content

[2]

ETKDepot

GetETK(Recip-e)

ETEE: SIGN

ETEE: ASYM. ENCRYPT

ETEE : SIGN

Message Content

Message Content [1]

SymmKey (Sender)

Admin Part (Recip-e)

SymmKey (Sender)

Admin Part (Recip-e)

Admin Part (eHealth)

Figure 12 – Addressed Encryption for Message transport

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 a random SymmKey that only the sender know. This SymmKey will be used by Recip-e to encrypt the response. This SymmKey should only be provided when a response is expected (optional for “void” API).

6.2.2.3 NON-ADDRESSED MESSAGE ENCRYPTION FOR STORAGE (ONLY FOR PRESCRIPTION)

Encryption For Storage Encryption For Transport

ETEE: SIGN

ETEE: ASYM. ENCRYPT

ETEE : SIGN

BODY

HEADER

SAML ASSERTION HOK

SIGNED BY EH




KMEHR

PRESCRIPTION

KMEHR

PRESCRIPTION (GZIP)

ETEE: SIGN

ETEE: SYM. ENCRYPT

ETEE: SIGN

SIGN NON-REPUDIATION

KMEHR PRESCRIPTION

(GZIP)

(NA) ETEE: SIGN

(NA) ETEE: SYM. ENCRYPT

(NA) ETEE: SIGN


KMEHR PRESCRIPTION

(GZIP)

Admin Part (Recip-e)- PrescriberId*

- PatientId*

- Executor Id*

- ...

[1] [2] [3] [4]

KGSS

GetNewKey()

ETKDepot

GetETK(Recip-e)

ETEE: SIGN

ETEE: ASYM. ENCRYPT

ETEE : SIGN

(NA) ETEE: SIGN


(NA) ETEE: SIGN


KMEHR PRESCRIPTION

(GZIP)


- PatientId*

- Executor Id*

- ...

SymmKey (Sender)

Admin Part (eHealth)- NIHII, Document ID*, Key Id*

Figure 13 – 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.

6.2.2.4 ADDRESSED ENCRYPTION FOR STORAGE (ONLY FOR FEEDBACKS AND NOTIFICATIONS)



Encryption For Storage Encryption for Transport

ETEE: SIGN

ETEE: ASYM. ENCRYPT

ETEE : SIGN

BODY

HEADER

SAML ASSERTION HOK

SIGNED BY EH




Message Message (GZIP)

ETEE: SIGN

ETEE: SYM. ENCRYPT

ETEE: SIGN


KMEHR PRESCRIPTION

(GZIP)

(NA) ETEE: SIGN


(NA) ETEE: SIGN


KMEHR PRESCRIPTION

(GZIP)[1] [2] [3] [4]

ETKDepot

GetETK(Recipient)

ETKDepot

GetETK(Recip-e)

ETEE: SIGN

ETEE: ASYM. ENCRYPT

ETEE : SIGN

(NA) ETEE: SIGN


(NA) ETEE: SIGN


KMEHR PRESCRIPTION

(GZIP)

SymmKey (Sender)


- PatientId*

- Executor Id*

- ...


- PatientId*

- Executor Id*

- ...

Figure 14 – 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.

6.2.2.5 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: import java.util.zip.GZIPOutputStream;

This compression is specified by standards RFC 1950; RFC 1951 and RFC 1952 (Refer to http://www.ietf.org/ for more information about these specifications)

http://www.ietf.org/



6.2.2.6 FOCUS ON NA ENCRYPTIONS

See Ref 2 for generic information about NA Encryption. 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=0809394427”, 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>12659389004</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>84071230581</value> </allowedReader> <symmKey>[base64 symmKey]</symmKey> </ns2:getNewKeyRequestContent>

6.2.2.7 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=0823257311” 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 ResponseMessage:

- SealedContent: the crypt response (to be decrypted).

6.2.3 PRESCRIBER SERVICES

Prescriber Web service has following properties:

Service Name PrescriberServices

Message Type SOAP

Target Namespace urn:be:fgov:ehealth:recipe:protocol:v1

Service URL https://<host>:<port>/Recip-e/v1/Prescriber_v1

Service WSDL (acceptance) Host : services-acpt.ehealth.fgov.be, Port : 443

Service WSDL (production) Host : services.ehealth.fgov.be, Port : 443

Prescriber Services WSDL Refer to SDK (folder XSD)

6.2.4 EXECUTOR SERVICES (PHARMACIST, NURSE…)

Executor Web service has following properties:

Service Name ExecutorServices

Message Type SOAP

Target Namespace urn:be:fgov:ehealth:recipe:protocol:v1

Service URI https://<host>:<port>/Recip-e/v1/Executor_v1

Service WSDL (acceptance) Host : services-acpt.ehealth.fgov.be, Port : 443

Service WSDL (production) Host : services.ehealth.fgov.be, Port : 443

Executor Services WSDL Refer to SDK (folder XSD)

6.2.5 ERROR MANAGEMENT

Each service may throw different type of error. The two types are:

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 http://www.w3.org/TR/soap12-part1/#soapfault

Sample Business error :

<?xml version="1.0" encoding="UTF-8"?>

<n1:AliveCheckResponse xmlns:n1="urn:be:fgov:ehealth:recipe:protocol:v1"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="urn:be:fgov:ehealth:recipe:protocol:v1 ..\ehealth-recipe-

http://www.w3.org/TR/soap12-part1/#soapfault



services\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.

6.2.6 EHEALTH TECHNICAL CONNECTOR

From version 1.1.0 we have implemented the eHealth technical connector. We use this connector to manage the session (sts), ETK calls and KGSS calls.

6.2.6.1 SESSION SERVICE

This service shall be used to manage the session (create session, load session, create fallbacksession,…). Integration specification is described in the eHealth documentation: https://www.ehealth.fgov.be/nl/support/connectors.

6.2.6.2 ETK DEPOT

This service shall be used to retrieve public keys of recipient to be used for addressed encryption. Integration specification is described in the eHealth documentation: https://www.ehealth.fgov.be/nl/support/connectors.

6.2.6.3 KGSS

This service shall be used to generate/retrieve symmetric keys to be used for non-addressed encryption. Integration specification is described in the eHealth documentation: https://www.ehealth.fgov.be/nl/support/connectors.

6.3 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.

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>

https://www.ehealth.fgov.be/nl/support/connectors





<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>

6.3.2 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).

6.3.3 PRESCRIBER SERVICES

6.3.3.1 CREATEPRESCRIPTION

Operation Name createPrescription

WSDL https://<host>:<port>/Recip-e/v1/Prescriber_v1?WSDL

Description 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 to be triggered 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


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"/> <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="http://services.recipe.be"> <CreatePrescriptionParam xmlns=""> <feedbackRequested>true</feedbackRequested> <patientId>10000000000</patientId> <prescriberId>11111111111</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="http://services.recipe.be"> <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


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.

#N/A

6.3.3.2 SENDNOTIFICATION

Operation Name sendNotification


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


(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.

#N/A #N/A #N/A

Administrative Information 1 IdentifierType executorIdentifierN/A

2 IdentifierType#N/A PrescriberIdentifier#N/A


(After decryption Process) #N/A #N/A #N/A


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="http://services.recipe.be"> <AddressPrescriptionParam xmlns=""> <content>c3RyaW5n</content> <executorId>01234567890</executorId> </AddressPrescriptionParam> </addressPrescription>


XSD #N/A

Sample #N/A





2 request the Encryption Token (Signed Public Key) of recipient to ETK Depot (eHealth service)

3 Generate an XML request.




7 Send the message to Recip-e, nothing is returned if the action is processed successfully (otherwise, a SOAP fault is thrown)

#N/A

#N/A

#N/A





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



(Before Encryption process) 1 String rid RID of the prescription (size = 12 chars)


#N/A #N/A #N/A

Administrative Information 1 IdentifierType PrescriberIdentifier/ ExecutorIdentifier

#N/A

#N/A #N/A #N/A






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="http://services.recipe.be"> <RevokePrescriptionParam xmlns=""> <reason>Mistake</reason> <rid>BPPAAAAAAAA</rid> </RevokePrescriptionParam> </revokePrescription>


XSD #N/A

Sample #N/A





4 Send the message to Recip-e, nothing is returned if the action is processed successfully (otherwise, an SOAP fault is thrown)

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A




Operation Name getPrescription (for Prescriber)


Description 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)




#N/A #N/A #N/A

Adminstrative Information 1 IdentifierType PatientIdentifier #N/A

2 IdentifierType PrescriberIdentifier #N/A

#N/A #N/A #N/A


(After decryption Process) byte[] prescription Prescription content as a Validated XML Kmehr message.


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="http://services.recipe.be"> <GetPrescriptionForPrescriberParam xmlns=""> <ETK>c3RyaW5n</ETK> <rid>BEPPAAAAAAAA</rid> </GetPrescriptionForPrescriberParam> </getPrescriptionForPrescriber>


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="http://services.recipe.be"> <GetPrescriptionForPrescriberResult xmlns=""> <creationDate>2002-05-30T09:00:00</creationDate> <encryptionKeyId>ABCDEEABCDE</encryptionKeyId> <patientId>0123456789</patientId> <prescription>1234AERTZZZ</prescription> <timestampingId>7845233</timestampingId> </GetPrescriptionForPrescriberResult> </getPrescriptionForPrescriber>








7 Generate a "Symmetric Key request"



10 the message is decrypted using unsealForUnknown()

6.3.3.5 LISTFEEDBACK

Operation Name listFeedback


Description This action list all the feedbacks sent by prescription executors

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


(Before Encryption process) #N/A #N/A #N/A

#N/A #N/A #N/A

Adminstrative Information 1 IdentifierType PrescriberIdentifier #N/A

#N/A #N/A #N/A


(After decryption Process) List<ListFeedbackItem> listFeedback List of feedbacks (See XML Response for the description of this complex type)


XSD <xs:complexType name="listFeedbacksParam"> <xs:sequence> <xs:element name="ETK" type="xs:base64Binary" minOccurs="0"/> </xs:sequence> </xs:complexType>

Sample <listFeedbacks xmlns="http://services.recipe.be"> <ListFeedbacksParam xmlns=""> <ETK>aaaaa</ETK> </ListFeedbacksParam> </listFeedbacks>


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="http://services.recipe.be"> <ListFeedResult> <ListFeedbackItem> <rid>BEPPAAAAAAAA</rid> <sentBy>0123456789</sentBy> <sentDate>2010-01-01-00:00:00</sentDate> <content>ABCDEABCDE</content> </ListFeedbackItem> </ListFeedResult> </ListFeedbackItem>







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

#N/A

#N/A

#N/A

#N/A

6.3.3.6 LISTOPENPRESCRIPTION

Operation Name listOpenPrescription


Description 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)




#N/A #N/A #N/A

Adminstrative Information 1 IdentifierType PrescriberIdentifier #N/A

#N/A #N/A #N/A

#N/A #N/A #N/A


(After decryption Process) List<String> List of rid




XSD <xs:complexType name="listOpenPrescription"> <xs:sequence> <xs:element name="ETK" type="xs:base64Binary" minOccurs="0"/> </xs:sequence> </xs:complexType>

Sample <listOpenPrescription xmlns="http://services.recipe.be"> <ListOpenPrescriptionParam xmlns=""><ETK>AAA</ETK></ListOpenPrescriptionParam> </listOpenPrescription>


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="http://services.recipe.be"> <ListOpenPrescriptionResult xmlns=""> <rid>BEPP12345AAA</rid> <rid>BEPP1D345AAA</rid> </ListOpenPrescriptionResult> </listOpenPrescription>





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).

#N/A

#N/A

#N/A

#N/A

#N/A

6.3.3.7 UPDATEFEEDBACKFLAG

Operation Name updateFeedbackFlag




Description 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"



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

#N/A #N/A #N/A

Administrative Information 1 IdentifierType PrescriberIdentifier #N/A




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="http://services.recipe.be"> <UpdateFeedbackFlagParam xmlns=""> <allowFeedback>true</allowFeedback> <rid>BEPPAAAAAAAA</rid> </UpdateFeedbackFlagParam> </updateFeedbackFlag>


XSD #N/A

Sample #N/A






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)

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

6.3.4 EXECUTOR SERVICES


Operation Name getPrescription (For Executor)

WSDL https://<host>:<port>/Recip-e/v1/Executor_v1?WSDL

Description 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




#N/A #N/A #N/A

Administrative Information 1 IdentifierType ExecutorIdentifier#N/A



#N/A #N/A #N/A


(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


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="http://services.recipe.be"> <GetPrescriptionForExecutorParam xmlns=""> <ETK>c3RyaW5n</ETK> <rid>BEPPAAAAAAAAAAA</rid> </GetPrescriptionForExecutorParam> </getPrescription>


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="http://services.recipe.be"> <GetPrescriptionForExecutorResult xmlns=""> <creationDate>2002-05-30T09:00:00</creationDate> <encryptionKeyId>ABCDEEABCDE</encryptionKeyId> <patientId>0123456789</patientId> <prescription>1234AERTZZZ</prescription> <timestampingId>7845233</timestampingId> <prescriberId>123456789</prescriberId> </GetPrescriptionForExecutorResult> </getPrescriptionForExecutor>





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).


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)


10 The message is decrypted using unsealForUnknown()





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





#N/A #N/A #N/A

Administrative Information 1 IdentifierType PrescriberIdentifier/ ExecutorIdentifier

#N/A

#N/A #N/A #N/A






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="http://services.recipe.be"> <RevokePrescriptionParam xmlns=""> <reason>Mistake</reason> <rid>BPPAAAAAAAA</rid> </RevokePrescriptionParam> </revokePrescription>


XSD #N/A

Sample #N/A





4 Send the message to Recip-e, nothing is returned if the action is processed successfully (otherwise, an SOAP fault is thrown)

#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

6.3.4.3 MARKASUNDELIVERED

Operation Name markAsUnDelivered




Description 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




#N/A #N/A #N/A

Administrative Information 1 IdentifierType ExecutorIdentifierN/A

2 IdentifierType PatientIdentifier#N//A

3 IdentifierType PrescriberIdentifierN/A #N/A




XSD <xs:complexType name="markAsUndeliveredParam"> <xs:sequence> <xs:element name="rid" type="xs:string" minOccurs="0"/> </xs:sequence> </xs:complexType>

Sample <markAsUnDelivered xmlns="http://services.recipe.be"> <MarkAsUndeliveredParam xmlns=""> <rid>BEPPAAAAAAAA</rid> </MarkAsUndeliveredParam> </markAsUnDelivered>


XSD #N/A

Sample #N/A








#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

6.3.4.4 MARKASDELIVERED

Operation Name markAsDelivered


Description 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.




#N/A #N/A #N/A

Administrative Information 1 IdentifierType PrescriberIdentifierN/#N/A

2 IdentifierType PatientIdentifier#N/

3 IdentifierType ExecutorIdentifierN/#N/A #N/A






XSD <xs:complexType name="markAsDeliveredParam"> <xs:sequence> <xs:element name="rid" type="xs:string" minOccurs="0"/> </xs:sequence> </xs:complexType>

Sample <markAsDelivered xmlns="http://services.recipe.be"> <MarkAsdeliveredParam xmlns=""> <rid>BEPPAAAAAAAA</rid> </MarkAsdeliveredParam> </markAsDelivered>


XSD #N/A

Sample #N/A






#N/A

#N/A

#N/A

#N/A

#N/A

#N/A



6.3.4.5 MARKASARCHIVED

Operation Name markAsArchived


Description 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)



#N/A #N/A #N/A

Administrative Information 1 IdentifierType PrescriberIdentifierN/#/A


3 IdentifierType ExecutorIdentifierN/#/A #N/A




XSD <xs:complexType name="markAsArchivedParam"> <xs:sequence> <xs:element name="rid" type="xs:string" minOccurs="0"/> </xs:sequence> </xs:complexType>

Sample <markAsArchived xmlns="http://services.recipe.be"> <MarkAsArchivedParam xmlns=""> <rid>BEPPAAAAAAAA</rid> </MarkAsArchivedParam> </markAsArchived>


XSD #N/A



Sample #N/A






#N/A

#N/A

#N/A

#N/A

#N/A

#N/A

6.3.4.6 CREATEFEEDBACK

Operation Name createFeedback


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)



(Before Encryption process) 1 Long prescriberId INSS id of the recipient


3 byte[] feedbackText Xml message containing the feedback

Administrative Information 1 IdentifierType PrescriberIdentifier #N/A




3 IdentifierType ExecutorIdentifier




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="http://services.recipe.be"> <CreateFeedbackParam xmlns=""> <content>c3RyaW5n</content> <prescriberId>10</prescriberId> <rid>BEPPAAAAAAAA</rid> </CreateFeedbackParam> </createFeedback>


XSD #N/A

Sample #N/A



2 Request the Encryption Token (Signed Public Key) of recipient to ETK Depot (eHealth service)








#N/A

#N/A

#N/A

6.3.4.7 LISTNOTIFICATIONS

Operation Name listNotifications


Description 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)




#N/A #N/A #N/A

Administrative Information 1 IdentifierType ExecutorIdentifier #N/A


(After decryption Process) List<NotificaitionsItem> List of addressed Prescription


XSD <xs:complexType name="listNotification"> <xs:sequence> <xs:element name="ETK" type="xs:base64Binary" minOccurs="0"/> </xs:sequence> </xs:complexType>

Sample <listNotification xmlns="http://services.recipe.be"> <listNotificationParam xmlns=""> <ETK>aaaa</ETK> </ listNotificationParam > </listNotification>




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="http://services.recipe.be"> <listNotificationsItem xmlns=""> <prescriberId >123456789</prescriberId > <sentDate>2002-05-30T09:00:00</sentDate> <content>AADDSDFQ</content> </ listNotificationsItem> </ listNotifications>







#N/A

#N/A

#N/A

#N/A

#N/A

Application Analysis APPENDIX: Recip-e Client Package Content


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.

Application Analysis APPENDIX: Release notes


8 APPENDIX: RELEASE NOTES

8.1 SDK VERSION 1.0.0

In this release the following items were addressed:

The possibility to use only the personal certificate as prescriber.

Code packing structure has been changed to a module structure. o be.connector.common.CommonIntegrationModule

Session related functionalities o be.connector.executor.recipe.ExecutorIntegrationModule

Recip-e Executor related functionalities o be.connector.prescriber.recipe.PrescriberIntegrationModule

Recip-e Prescriber related functionalities

A new property “care.provider.type=PHARMACIST” is introduced for the executor module. This is a mandatory property and is part of the restructuring of the code.

Important: the old prescriber integration module class is deprecated and will be removed in future releases.



Implementation of the eHealth technical connector version 3.3.0 beta-1. This implementation manages the calls to the session service, ETK and KGSS. For more info about this technical connector visit: https://www.ehealth.fgov.be/nl/support/connectors

To read the eID we use the fedict eID library version 0.5.1

IKVM update to version ikvm-7.2.4630.5

A lot of properties has been changed, you can find more information in chapter 5.2.5 Properties also in the comments that are in the example .properties files delivered in the executor and prescriber conf folder.

j2pcsc.dll needs to be added in the working directory (the folder where you start the application .exe, .bat or …)

Important:

- We recommend to use version 1.1.0 of the business connector because we made some improvements in code.

- You cannot use the windows-com-dll in this version (this will be fixed in future release)



The problem with the eID in the windows-com-dll is fixed

Important:

- We recommend to use version 1.1.1 of the business connector because we made some improvements in code.


Application Analysis APPENDIX : Frequently asked Questions


9 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 Answer

How do we change the default prescription used in the mock version of the integration modules?

The prescription, notification and feedback used in the mock version are found in the \examples\resources folder. You can update these files.

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)

This is currently not foreseen. During the course of the pilot this will be evaluated.

Which doctor id should we use, the one in the Kmehr message, or the one in the header?

The INAMI/RIZIV number

Is it possible to store more than one prescription in the same Kmehr message?

No

Can we create our own prescriptions to use during testing?

Yes, using the sample prescriber application or, when using the mock version, by updating the example xmls.

Since there is no archiving currently foreseen, what has to happen with the MarkAsArchived function during the pilot? Should we always call it?

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.

Can e-health provide a service to get public keys of doctors?

Use the ETK depot service.

How do we implement during the time when the e-Health ETK service is not yet up?

The service is already 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?

e-Health will create a tool to automate this procedure. A sample certificate is provided in the conf folder of the module.

Please provide more information on the ’10 items’ limitation.

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

How use the mock functionality in Windev?

Declare the PrescriberIntegrationModuleMock class. This is valid for all programming languages. For Windev implementation specific questions please refer to your Windev documentation.

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?

No, each prescription has its own encryption key.

In the notification, do we have to encapsulate the full Kmehr message in notification xml message?

The field is optional

Can dll modules be used to do end to end encryption? (For other purpose than Recip-e communication).

Yes

Application Analysis APPENDIX : Frequently asked Questions


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 ?

The feedback is linked to the overall prescription. No link is foreseen with delivery items.

Should the software provider maintain a list of executors (pharmacists) with correct IDs or are they available on e-Health?

Currently neither Recip-e nor e-Health provides a pharmacist inventory. So at this time, implement it in the software itself.

Where do we need to pass the SAML token in the different functions of the integration module?

The SAML token is stored in memory by the module itself. You do not need to pass it as an input.

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?

If 1 of the items is delivered, the complete prescription is considered as delivered, and the MarkAsDelivered functionality should be called.

Documents

INTEGRATION SPE IFI ATION - GF-Homeminf.vub.ac.be/~marc/Recip-e_Integration_Specification_v2_1_2.pdf · This document mainly presents technical information regarding integration with