Skip to end of metadata
Go to start of metadata

Document revision history







Andries Demont

Transfer from site

5.528/08/2015Andries DemontAdded ldap configuration info
5.5 Andries DemontUpdated status info of received status
6.36/6/2017Andries DemontAdding recip-e and mexi channels

Table of contents


The unified messaging module allows your organization to manage communications using multiple channels. Currently it supports five channels:

  1. eHealthbox: Addressed and medical communication with careactors (send and receive)
  2. eBox: Addressed and non-medical communication with belgian residents. (only send)
  3. Zorgmail: Addressed and medical communication with careactors in the Netherlands. (send and receive)
  4. Recip-e: Non-addressed medical communication (up to now only used for medical prescriptions)
  5. meXi: addressed medical communication via the meXi backend

The UM is a connector, containing file and web service interfaces. All trafic going through the UM connector is queryable via an easy web application. On top of the UM connector, it is possible to use the mybox application. This application is suitable for caregivers in the organisation to follow-up their own messages. The web application of UM is more suitable for troubleshooting support.

UM user authentication

During installation of the UM the customer can choose how users should login into the UM. There are 5 modes:

  • No authentication: everyone with access to the server can see the web application
  • Basic authentication: one admin account and password are available to login
  • LDAP authentication: authenticates via an ldap connection to the active directory of your organisation
  • Combination of Basic authentication and LDAP authentication
  • Ehealth authentication: authentication is done based on the ehealth IDP and will look up the role of the user on CSAM and


Configuration screen in settings page:

No authentication

There is no login page available. Users surfing to the web applciation will see immediately the home screen.

Basic authentication

In the settings page of UM, one adminstrator user is created together with its password. All users opening the web application will be asked to give in that login and password. The checkbox "enable basic authentication" must be active.

LDAP authentication

In the settings page of UM it is possible to configure the ldap connection.

LDAP parameters

Ldap connection stringThis path will be added to the "Username" value in order to make the connection to ldap
(Don' put annything after the / This part can be placed in the User and Group search base)

ldap://myorg.local:389/ (if you can login but get an error try port 3268 or 3269 for LDAPS
this causes LDAP referrals to work correctly) 

User search baseThe base that will be used to look for the usersdc=myorg,dc=local
User search filter

The element that will be searched for within the returned users.

Note: If the user is defined as a mycaregiver, the found value should match the "user name" (listed in the mycaregiver page)
the Value of in this case sAMAAccountName must match the "user name" (listed in the mycaregiver page) 

Group search baseThe base that will be used to look for groupsOU=GROUPS,OU=myOrgSecured,DC=myorg,DC=LOCAL
Group search filterThe filter that will be applied to query the groups


*with [x_] an empty value or prefered prefix

Group role attribute cn
UsernameThe username that may query the ldap (using the "ldap connection string" as prefix)
(in the form of username@domainnam)
Gebruiker te zoekenThis is a test field, look up a certain user in order to test your ldap settings
in the form of the User search filter (in this example the value of sAMAAccountName)

Update 2 parameters via the database in the table 'properties'

  • update properties set propertyValue = 'false' where propertyKey = 'EID_AUTHENTICATION'

  • update properties set propertyValue = 'http://<servername>:<port>/unified-messaging/login?login_error=1' where propertyKey = 'AUTHENTICATION_FAILURE_URL' (replace <servername> with the name of the server and replace <port> with the portnumber tomcat runs on


The following groups (or values containing the specified names) are necessary in the ldap.

Type of userLDAP group 

All users defined in ldap as a user must be defined as myCaregiver.


All users defined in ldap as an administrator don't need to be defined as a myCaregiver.

web service userUM_WSWeb services users can use the secure endpoint of the UM:  http://servername:serverport/unified-messaging/services/secure/UnifiedMessagingService/1_0 (deprecated)

Remark:  UM_USER or A_UM_USER are both valid group names

LDAP and Basic authentication combined

This combination is deprecated. It was necessary in UM release older than 5.5. Earlier releases could not define multiple administrators

However it is advisable the basic authentication is setup during LDAP configuration, it can be used as fallback login in case LDAP is not working.

Ehealth authentication

This integration requires extra software components and an ehealth dossier. In order to have this configuration it is best to call the healthconnect support desk.


The home page shows the following data.

  1. On the top it shows the time to go before the module will load the new messages in the out foldr.
  2. In the middle it shows box statistics.
  3. On the bottom it shows a chart of the status of all messages that were sent in the defined period.
  4. On the right bottom it is possible to calculate the statistics of average time of arrival for a message to all doctor individually or consult the routing history of the file interface.

Routing file history

Routing history of file interface shows an overview of daily, except Sundays, statistics of the messages sent via Unified Messaging (To Outbox) compared to fallback traffic.

Message overviews

Message Folders

The Unified Messaging module allows to keep an overview of all messages at all time, regardless if they are already sent, about to be sent or already received.
Inbox: Contains all the messages sent to your organization
Sent: Contains all the messages that were sent from your organization

  • The folder takes into account all messages, those who came in via the batch and those who were created manually in the browser

Outbox: Contains all messages that are about to be sent.

  • The folder takes into account all messages, those who came in via the batch and those who were created manually in the browser.
  • How long will messages typically reside in this folder?

Trash: Contains messages that used to be located in one of the other folders.

Message status

A message can have one of the following statusses. This page describes the possible message statusses.

Export to fallback folder

 Dedicated message functionality

Select one or more messages to export out of the UM. This is usefull when ehbox is unavailable during a given period. It will only export messages that can be encoded to valid adr and content files (e.g. no messages sent to a company) .
Hint: Select all messages in the outbox with the status "Failure" and press the export to fall back icon.
Only available in out and sent box!


In some cases it might be useful to resend a message. For instance when a doctor lost his EMD data by a system crash and wants to build up his EMD database again.
Hint: Filter the messages for one specific doctor. Select them all and press resend.
Only available in out and sent box!

Message filtering

Basic search functionality

Each message screen contains on top of the message the basic search functionality.

It is possible to fill in multiple words. The search will find all messages containing each of the words in one of the following dedicated fields. The search is not case-sensitive.

  • To
  • From
  • Subject
  • Patient INSS

Example search value: "Ilma test"
This search could result in a message sent to hospital "Wilmar" containing "test" in its subject.

Advanced search functionality

The advanced search functionality allows you to build more specific filters using a timeframe in which to look. The search is not case-sensitive and will only return messages that match all criteria.

Create a message

In this screen you can create an entire new message. The To field uses autocompletion to find a contact in the contact book. If no autocompletion is suggested make sure the contact is already in the contact book.


It is possible to add one or multiple attachments to a message. Fill in the type when the message needs to be integrated in a Doctors' EMD. Use the same name as the functional types used for the file interface (cfr dispatch file or subfolders of the out folder). The total attachment size is limited.

User management

In the UM users can have different roles and forward actions. The mycaregivers and mydepartmens screens allow these configurations. Apart from user management, these pages will also automaticcally publish to which doctors or departments are addressable in your ogranisation.

User Roles

is administratorread, delete and send all messages. Can configure the module
manage all messagesread all messages
can read all messages of the departmentread all messages of the department of the user
can send messagesallows the user to reply, forward or create new messages

Forward Message to actions

EmailForwards a notification for each new message to the configured email address. Make sure the email settings are complete (editbale in settings page) and the email system is secured
File System

Export the message to the file system. It will use the predefined export configuration:

  • raw attachment export
  • raw attachment export and envelope file (the enveloper file can contain the nihii number of the individual caregiver)
  • adrxml export
Departmentforward the message to the department, so the collegues can read it as well
personal ehealthbox

forward message to the personal ehealthbox of the receiver.

Make sure the mycaregiver has an active ehealth certificate. If not, the forward messages will fail.

Bulk import

Doctors and departments can be also published by file upload.Use the CSV file with layout explained below.


  • For mycaregivers only 11 characters nihii is accepted. 
  • Email address may only be a valid email addresses or just blank.
  • For fields 'email routing enabled', 'file system routing enabled' and 'department routing enabled' only 1 (yes) or 0 (no) is accepted.

The possible examples:


  • For departmentcodes only official codes are accepted.(cfr KMEHR documentation)Field for email addres may be left blank.
  • For fields 'email routing enabled' and 'file system routing enabled' only 1 (yes) or 0 (no) is accepted.
  • The possible examples: deptanatomopathology, , 0, 1,deptkinesitherapy,,1,0

Important: error on one line inside of upload file will lead to rejection of the whole file.


Incoming messages
Configure the routing rules for incoming messages in this screen.


The functional type of the incoming messages to which this rule will apply.


This will be the extension of the file when it is placed on the file system.


This is the folder to which the files will be copied. Warning: Make sure this folder is readable and writable!

Use the import functionality to import the rules from a dispatch file all at once.
  • This function only works if the path to the dispatch file exists on the server.

Outgoing messages
Outgoing routing rules have four components:

  1. Functional type
  2. Extension of attachment to .adr file
  3. Outbox subfolder
  4. Fallback folder

The functional type should be assigned to messages whose attachment has the same extension type as that listed in the rule and which are found in the outbox subfolder given. If the receiver can read ADR-XML files, this functional type is included in the message. If not, the message is moved to the fallback folder. In this case, it is left up to the fallback folder to decide the functional type.
It is not necessary to specify all routing rules by hand. An implicit routing rule moves messages not covered by an explicit routing rule. This rule looks at the relative position of a message with regard to the outbox root and gives the message that same relative position with regard to the fallback folder. For instance, a file in a subfolder "sub" of the outbox folder is moved to a subfolder "sub" of the fallback folder.


Ehbox settings

  • Name: The name of the organisation that will be used in the communication with eHealth. This is not the sender name that the doctors will see when they receive a message of your organistation.
  • Type: Defines the eHealth Type that will be used for the communication. The following types are available:
    • Hospital
    • Labo
    • Company
  • Certificate: Contains the path (on the server) of the eHealth certificate. Do not change the name of the key, the module uses the original etee-requestor names.
  • Password: The password that belongs to the key.
  • RRN: The national registry number of the UM Module responsible in your organisation.

File Interface settings

  • Polling interval: Defines how much time is in between two file polling actions.
  • Out Folder: Defines the root folder that will be used to send messages.
  • In Folder: The root folder that will contain the messages that came in the inbox (This functionality is on the roadmap and not implemented yet)
  • Error Folder: The root folder that contains all messages that could not be picked up by the sending process (no addressee, to big contents, .adr withtout attachment file, empty attachment file...)
  • File Types: If an extension is added in this field, content with the given extension will be visible in the message preview screens.
  • Fall back Folder: The root folder that will be used for the export message functionality and for none-hectorians.
  • Auto create contacts: Only enable this functionality if you want save contacts via the file interface. Take in account that this only applies to .adr files that contain both nihii and name. When only nihii is defined, the contact will not be saved.

SMTP Settings

The settings are optional parameters to configure mail functionality. Currenlty it is only possible to send mails via smtp connection that is based on ssl and needs authentication with username and password.

  • Host: The servername of the smtp server
  • Port: The port of the smtp server
  • Username: the username to login with
  • Password: the password to login with
  • From: the mail address to send from

Receiving messages for doctors in your hospital

In order to be able to receive messages for a doctor in my hospital the following steps should be followed:

Your hospital:

  1. Check your incoming routing rules in the mydispatch screen (This is mostly already configured by HealthConnect)
  2. Create and Publish a MyDoctor via the MyDoctor screen
  3. Fill in all necessary values and make sure the file system checkbox is enabled

The sender:

  1. The sender should use the xxxxxxxx.yyyyyyyy adrv1 format or ADR V2 to address the mydoctor in your hospital. Therefore he should use 2 NIHII numbers: the one of your hospital and the one of the doctor.

C2M integration

  1. In the mydispatch screen: received
  2. enable the checkbox create .env file
  3. Fill in a custom path where the env files need to be placed

When a message is received by the UM the attachment will be copied to the defined folder and an .env file is generated in a folder (possibly the same). The env file will contain the nihii of the doctor and will be used by C2M to link the message to the doctors dossier.

  • No labels