🔗 Source article (Salesforce): Click here
The ADR-XML format is intended for advanced message sending purposes. This convention will be used by both Hector as the Unified Messaging module. It is used both as a file or as an element in web service communication. The main purpose of this format is to enhance the communication between eHealthBoxes and to extend some of the functionalities/shortcomings of the existing adr format (=adrV1, the txt-file containing the riziv/inami of the receiver).
The ADR format is an XML based interface which enables a lot more functionalities in the communication over the eHealthBox channel. More information on eHealthBox can be found on the following website: http://www.ehealth.fgov.be.
In general an adrxml file is a reprensentation of one message containg a body and optionally attachments. To empower EMD's/DMI's for automatic integration of ADRXML, the format is enriched with a patient identifier and metadata.
The Adrxml folders
In case the adrxml is used as a file, you can define Outgoing or Incoming folder for ADR-XML-files.
UM:
Outgoing: Out-folder defined in the settings page (Settings-File Interface-Outgoing folder); typically c:\unifiedmessaging\out
Incoming: activate via Settings-Dispatch
Hector:
Outgoing: default location c:/hector/to_send (configurable via config/emd integration)
Incoming: default location c:/hector/received (configurable via config/emd integration)
XSD Definition
[ IMAGE: Graphical representation of the XSD ]
The XSD consists of a main element: ADR which has the following attributes:
Field name
|
Description
|
ClientMessageID
|
This unique ID can be freely chosen by the sending party. This message ID uniquely identifies the message.
|
PrevClientMessageID
|
Message ID of the previous message.
|
Sender
|
The address of the person or organization the message is sent from.
|
Addressee
|
The address of the person or organization the message is sent to.
|
Subject
|
The subject of the message, if there is no subject supplied a default value is used by Hector when the message is sent
|
Body
|
The body will contain the content of the message. The body references to a file on the file system of the format specified in the MimeType.
|
Patient
|
The patient the message is about.
|
Attachment
|
All attachments added to the message. All attachments reference to a file on the file system of the format specified in the MimeType.
|
MetaData
|
A key-value pair which hold additional information concerning the message.
|
Link
|
Deprecated - An additional link to the message that a receiver can click and be forwarded to existing references (for example PACS or lab result viewers)
|
Every ADR can also have a ClientMessageID. This unique ID can be freely chosen by the sending party. This message ID is intended for tracking purposes (eg. Request the status of the message to the UM module over webservices, etc.).
Sender
The sender is an optional field and defines the sender of the message. This can be a person or organization.
If Hector or UM contain multiple ehealth certificates, it is necessary to specify a sender when sending a message. If not, Hector or UM will choose the first certificate as sending identity. This information is important if the receiver wants to reply to the 'real' sender. When the sender field is present it has to match with the configuration in Hector or UM. For example if the sender contains an ehboxid or applicationID that is not configured in Hector with its ehealth certificate, then the message will be refused and moved to error.
When the sender is not present, Hector will send the message using the certificate of the default sender (this is a configurable property in Hector/UM)
The sender elements are the same as the addressee elements. For more explanation, see the next paragraphs.
Addressee
[ IMAGE: image.png ]
Field name | Description |
Quality
|
Required: Defines the ehealthbox quality of the receiver. The overview of possible values is listed in the quality table.
|
Identifier
|
Required: Defines the ehealthbox identifier of the receiver. Cfr quality – type list table
|
Name
|
The name of the organization. This value will only be shown in Hector, if the identifier was not a known Hector contact. When a known contact is available in Hector it will use the name of the existing (Hector) contact.
|
EhboxIdType
|
The type of the ehoxid. If not defined, Hector will try to derive it. The overview of possible values is listed in the quality table.
|
Firstname
|
The firstname of the individual caregiver. This value will only be shown in Hector, if the identifier was not a known hector contact. When a known contact is available in Hector it will use the first name of the existing (Hector) contact.
|
Lastname
|
The lastname of the individual caregiver. This value will only be shown in Hector, if the identifier was not a known hector contact. When a known contact is available in Hector it will use the last name of the existing (Hector) contact.
|
ApplicationID
|
The applicationID of the addressee. This is only possible when the receiver is some organization (hospital, labo, …)
|
Subaddressee
|
The person or group inside the receivers' organization for whom the message is intended to
|
LocationId
|
(Deprecated) Useful when the receiver has multiple clients and only wants to receive certain messages in one location. This location is defined by the locationID and is published on the Yellow Pages.
|
LocationAlias
|
(Deprecated) A description of the locationID. For instance "De praktijk in Destelbergen"
|
An Addressee can be a person or an organization. List of all supported qualities.
SubAddressee
When sending to an organization, a subAddressee can be filled in. A subAddresssee can for example be a doctor inside a hospital or a department inside a hospital.
The possible subAddressees are (* indicates that the subquality currently is not yet supported):
DEPARTMENT
|
DOCTOR
|
NURSE
|
PHYSIOTHERAPIST
|
DENTIST
|
Field name
|
Description
|
SubqualityType
|
Describes the quality of the subaddressee. Cfr Subquality table.
|
Name
|
Describes the name of the department (not used for individual caregivers). In hospital only kmehr IDs of the following list and starting with 'dept' are allowed: https://www.ehealth.fgov.be/standards/kmehr/en/tables/healthcare-party-type
|
Firstname
|
The first name of the individual caregiver
|
Lastname
|
The last name of the individual caregiver
|
Identifier
|
Contains the identifier (NIHII, INSZ,…) of the individual caregiver
|
The subAddressee information is given as extra information to the Addressee. The message is still send to the eHealthBox of the Addressee.
Example: When sending to a doctor inside a hospital, the message is sent to the eHealthBox of the Hospital. The Hospital is able to react to the subAddressee information and can choose to treat the message differently.
Body
The body entry will contain the content of the message and is an optional field. When no body is specified, HealthConnect will set a default body-content to send the message.
When a body entry is supplied you must provide the content of the file as a Base64 encoded string. Please note that only text files will be used for the body (TXT, HTML, RTF or other). The content of this file will be used for the body of the eHealthBox message.
[ IMAGE: image.png ]
Field name | Description |
FileReference
|
a filesystem-reference to the file to include
|
Content
|
Base64 encoding of the content of the original file
|
Name
|
(Optional) The name of the body. This will be used to give a filename at the receiver side. Although it is optional in the xsd, it should always be filled in.
|
MimeType
|
(Optional) The mime type of the body. If text/plain is used, the body will displayed differently in the ehealthbox webapp. When the mimetype is not supplied "application/x" will be used
|
Encoding
|
(Optional) Only useful for mime types text/plain. Defines the text encoding that is used. The receiver will see this value. Can be useful for the receiving EMD. The supported encodings are defined in this list: http://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html
|
Subject
This is the subject of the eHealthBox messages. The subject is optional.
Attachments
An attachment is identical to the body structure. It is allowed to have multiple attachments.
IMPORTANT: You can add as many attachments as you want given that the total size of the attachments does not exceed 10MB (MegaBytes).
[ IMAGE: image.png ]
Field name
|
Description
|
All fields
|
Cfr Body table
|
FunctionalType
|
This element is necessary for the receiving EMR to know what type of file is added. Without it is not possible to perform routing to EMR
|
The FunctionalType is used for defining the purpose of the attachment. It will be used for routing the attachments to the correct location for importing by the EMR. For example: ALA-LAB, DMA-REP.
MetaData
The metadata are optional key-value pairs. These pairs should be used to either provide more information about the message before downloading it from the eHealthBox or provide more information about the message in order to correctly dispatch the file to the receiving system.
It is important not to include any patient specific data in the metadata pairs as these fields will not be encrypted before sending to eHealthBox. Eg. The name of the patient should not be added as metadata, but in the dedicated patient field.
The metadata can hold any key-value pair, but there are some predefined meta-data key-value pairs identified:
Key
|
Value
|
Description
|
important
|
Boolean
|
Indicating high or low priority (used to be isImportant)
|
FlashMessages
|
Boolean
|
Deprecated
|
encrypted
|
Boolean
|
Indicating the fact that this message is encrypted or not when sent through eHealthBox.
Default is true
|
askPublicationReceipt
|
Boolean
|
Indicating the fact that a publication receipt must be asked when sending the message. The receipt will be received as message.
Default is false
|
askReceivedReceipt
|
Boolean
|
Indicating the fact that a received receipt must be asked when sending the message. The receipt will be received as message.
Default is false
|
askReadReceipt
|
Boolean
|
Indicating the fact that a read receipt must be asked when sending the message. The receipt will be received as message.
Default is false
|
createMetaDataAttachment
|
Boolean
|
Deprecated
|
CreateHCMetaDataKeys
|
Boolean
|
Creates HC specific metadata in the ehealthbox message
Default value is true.
|
CodageEncryptionApplicationID
|
String
|
The application ID of the eHealth certificate used to encrypt the message
|
LocationIdentifierNumber
|
Integer
|
(Deprecated) Unique number to identify the location where the message should be downloaded
|
Patient
As every eHealthBox message is intended for one specific patient, it is advised to add patient identification details:
INSS number
LastName
FirstName
Important:
only use firstname and lastname for none-medical data. On ehealthbox-level firstname and lastname will NOT be encrypted.
The patient field in the ADR is optional but strongly advised to be used when sending eHealthBox messages.
Links
Deprecated.
Use of the ADR XML file
You can also use the adr format in the SendMessageRequest for the Hector webservices. This is the recommended way to communicate with Hector, as it does not rely on having a shared file interface between any third party software and Hector.
For more information regarding the Hector Webservices, please consult the Hector Webservices documentation.
An elaborate example:
[ IMAGE: image.png ]
When a new message is received in Hector or Unified Message Module, the complete message can be made available to the EMR. The adr xml file will provide all necessary information as it was received, including metadata, to the EMR.
Mapping from old ADR format
The easiest old adr file which contained only a NIHII number and was intended to send a file with name test.txt, now looks like this:
[ IMAGE: image.png ]
The file is not placed in the body. It is added as an attachment. The body is intended for a human readable file (text, html, …) and should contain a message, a summary or a description for the receiver.
[ IMAGE: image.png ]
XSD and WSDL Definition
Use the latest installation of Hector or UM to find the adr.xsd.
Product
|
link
|
Hector
|
http://localhost:8081/services/UMService/1_0?wsdl
|
Unified Messaging
|
http://servername:serverport/unified-messaging/services/UnifiedMessagingService/1_0?wsdl
|
Unified Messaging next release
|
unified-messaging/services/UnifiedMessagingService/1_0?xsd=xsd/ADR.xsd
|