Configure application emails

Your application may send emails to the account holder.

The platform may automatically send an email on predefined events like first use of your app. You can send email or sms messages using a FHIR message.

The texts for email messages may be predefined on the developer portal. You should at least define the text for the platforms default language.

For multi language applications you may predefined email texts in multiple languages.

You may also configure an SMTP server to be used for sending application specific emails.

List of events that may trigger an application specific email

Registration of new user - This message will be send when a new user registers an account on MIDATA using your apps OAuth2 login page.
Registration of a new user by someone else - This message will be send if a new user account is created using an API call from your application. (Using a POST request to the /fhir/Patient endpoint)
First use of app - This message will be send if a user uses your application for the first time
First use of app (if no registration email sent) - Same as “First use of app” but the message will only be sent if no “Registration of new user” message is send at the same time.
One-time password sent - Message will be sent when a user that has no password yet is trying to log in. This mail contains a one time password that can be used to log in. OAuth portal needs to be called with pwl=true parameter to enable this feature. See links to the portal.
Login Notification (if enabled by user) - This message will be send everytime the user logs into your app. A message is only sent if the user enabled this feature in his security settings.

Proposed consent (Grantor, Invitation) - This message is send if a new proposed consent is created where a person who is not a midata account holder (yet) is asked to share data. The message is send to the person who is asked to join MIDATA.
Proposed consent (Grantor, Account Holder) - This message is send if a new proposed consent is created where a person who is already a midata account holder is asked to share data. The message is send to the person who shall agree to the data sharing. (The owner of the consent)
Proposed consent (Grantee, Invitation) - This message is send if a new proposed consent is created where a person who is not a midata account holder (yet) is asked to share data. The message is send to the person who requested the consent.
Proposed consent (Grantee, Account Holder) - This message is send if a new proposed consent is created where a person who is already a midata account holder is asked to share data. The message is send to the person who requested the consent.
Consent confirmation (Grantor) - This message is send if a consent gets confirmed by the person who is asked to share data. The message is send to the person who confirms the consent.
Consent confirmation (Grantee) - This message is send if a consent gets confirmed by the person who is asked to share data. The message is send to the person who requested the consent.
Consent rejection (Grantor) - This message is send if a consent gets rejected by the person who is asked to share data. The message is send to the person who rejected the consent.
Consent rejection (Grantee) - This message is send if a consent gets rejected by the person who is asked to share data. The message is send to the person who requested the consent.

Messages triggered by change of data

Change of resource [code] - A message of this type will be send if a resource of a certain type is created or changed in the users data. In addition to the message definition a subscription with action “Send email” or “Send SMS” and condition “Resource change” needs to be setup.

Messages triggered by the application

Process FHIR message with event [code] - A message of this type is send if the server receives a FHIR message with the specified code. In addition to the message definition a subscription with action “Send email” or “Send SMS” and condition “FHIR message” needs to be setup.

Using the developer portal to define messages

In order to provider your own message texts on the application detail page is a button „edit messages“.

This will open the message editor where you can define application specific messages in multiple languages.

eMail Message List

Initially there will be no message defined. You can view and change existing messages by clicking on the “view” button.

Click on the “Add” button to add a new message.

eMail for application

Event (trigger)

Select a trigger from the list. (See above).

Code

For the message triggers “Change of resource” or “Process FHIR message with event code” you also need to enter a code.

For all the consent related messages you can either leave the code field empty or restrict to a specific type of consent.

Useful values for code for consent related messages are:

CIRCLE - Only consents where one account holder asks another account holder to share data
HEALTHCARE - Only consents where a healthcare provider asks an account holder to share data
STUDYPARTICIPATION - Only consents where an account holders shares data with an research project

Language

Select the language of your message. After you have filled out the title and text you can change the language and provide the title and text also for the new language. Repeat until you have added all desired languages.

Message Title

The title for your email. This will be ignored if you use the message as SMS.

Message Text

The text of your email. The messages may contains variables like the user name. The available variable names are listed on the editor page and vary for the different types of messages.

Click “Submit” to save the message definition.

Configure SMTP server

Go to the „edit messages“ page of your application. Click on „configure SMTP server“ and provide the following information for the SMTP server:

host - The hostname of the SMTP server
port - The port to be used. The default port is 587.
ssl - Does the SMTP server require SSL encryption?
tls - Does the SMTP server require startTLS?
user - The username for authentication. Not needed for some SMTP servers.
password - The password for authentication. Not needed for some SMTP servers. Even if set, the password will not be returned to the MIDATA portal.
from - The sender including name and email. Use this format: “Firstname Lastnamesupport@example.com”