Subscriptions

Subscriptions may be used to automatically trigger actions on certain conditions. Subscriptions may be created using the “Default Subscriptions” page of the developer portal or using the FHIR API.

A subscription consists of a trigger (when is an action triggered) and the action (what is done).

The following triggers are supported:

  • Daily : The action is triggered once a day
  • Each 30 minutes : The action is triggered every 30 minutes
  • Resource change : The action is triggered when a FHIR resource is created or updated. Provide the type of FHIR resource in the second column.
  • Consent change : The action is triggered whenever a Consent visible to the application is created or updated.
  • Once : The action is triggered once when the application is first used.

The following actions are supported:

  • Call NodeJS script
  • Call REST-hook
  • Send eMail
  • Send SMS
  • Forward to other application

Creating subscriptions via the portal

As developer log into the portal. Go to the overview page of the application and click on “Change Default Subscriptions”.

Creating subscriptions via the API

Subscriptions may be created or queried using the FHIR API. As prerequisite the access filter of the application must contain “Subscription”.

Here is an example subscription as returned by the API:

{
    "resourceType": "Subscription",
    "id": "62b1946c07d8ed57a26e3f42",
    "status": "active",
    "criteria": "MessageHeader?event=http://midata.coop/event/test",
    "channel": {
       "type": "message",
       "endpoint": "node://myScript.js"
    }
}

Please note that for security reasons it is not possible to create subscriptions that forward to another application via the FHIR API. This can only be done using the developer portal. However it is possible to query these subscriptions. The have a channel.endpoint with protocoll “app://”.

FHIR Messages

The MIDATA platform may be used to send FHIR messages from one application to another.

FHIR messages need to be sent via POST to the endpoint /fhir/$process-message

Here is a minimal example message:

{
    "resourceType": "Bundle",
    "type": "message",    
    "entry": [
        {
            "fullUrl": "Bundle-MessageHeader",
            "resource": {
                "resourceType": "MessageHeader",                
                "eventUri": "http://midata.coop/event/test",
                "focus": [
                    { "reference": "resource1" }
                ]
            }
        },
        {
            "fullUrl": "resource1",
            "resource": {
               ...
            }
        }
    ]
}

Synchronous or asynchronous?

The message is send synchronous per default. That means that if the target of the message returns an answer that answer will be passed back to the caller. The platform will wait for a maximum time of 60 seconds for the target to return an answer.

If you do not want to wait for an answer you can send the message asynchronous by adding async=true to the URL:

POST /fhir/$process-message?async=true

Sending a message to the backend script of the same application

You can send a message from an application to a script belonging to the same application on the MIDATA server:

  • Include an “eventUri” or “eventCoding” into the FHIR message.
  • In the developer portal on the default subscriptions page add a subscription with trigger “FHIR message” and provide the eventUri or eventCoding.code of the message into the second column. Choose “Call node.js script” as action and enter the name of the script.

Sending a message to an external service type application

You can send a message from an application to a script of an external service that the user is using:

  • Include an “eventUri” or “eventCoding” into the FHIR message.
  • Include “destination” with a “endpoint” URL. Use “service://appname” as URL and replace appname with the internal name of the target service.
  • In the developer portal on the default subscription page of the source application add a line with trigger “FHIR message” and provide the eventUri or eventCoding.code of the message into the second column. Choose “Forward to other application” as action and enter the internal name of the target service into the last column.
  • On the default subscription page of the target service add a line with the trigger “FHIR message”. Also provide the eventUri or eventCoding.code but append a “:” and the source application internal name to the uri.

Sending a message to another application and user

You can send a message from an application to a script of an application that is used by a different user:

  • Include an “eventUri” or “eventCoding” into the FHIR message.
  • Include “destination” with an “endpoint” URL. For a list of supported uri schemes see below
  • In the developer portal on the default subscription page of the source application add a line with trigger “FHIR message” and provide the eventUri or eventCoding.code of the message into the second column. Choose “Forward to other application” as action and enter the internal name of the target service into the last column.
  • On the default subscription page of the target application add a line with the trigger “FHIR message”. Also provide the eventUri or eventCoding.code but append a “:” and the source application internal name to the uri.

These uri schemes are supported as destination:

  • Patient/id : Use a patient reference providing the id of the target account holder
  • Practitioner/id : Use a practitioner reference providing the id the target practitioner
  • patient://email@domain.com : Reference a patient by providing its registration email address
  • practitioner://email@domain.com : Reference a practitioner by providing its registration email address

Message sender extension

The platform automatically adds a FHIR extension with the sender user to each MessageHeader resource:

{    
    "resourceType": "MessageHeader", 
    ...               
    "extension" : [
        {
            "url" : "http://midata.coop/extensions/sender-user",
            "valueReference" : {
                "reference" : "Patient/1234567890"
            }
        }
    ],
    ...   
}

If such an extension is already present in the MessageHeader it will be replaced.

SMS / EMail sending

Using subscriptions and/or FHIR messages it is possible to send users an email or SMS message. The message content must be predefined in the developer portal on the corresponding page of the application definition. See Configure application emails. For sending email/SMS with FHIR messages use “Process FHIR message with event [code]” as trigger and enter the eventUri as code.

Using parameters

It is possible to use additional variables in the message text.(example “<myparameter>”) When you sent the FHIR message to MIDATA to trigger the message sending send a Parameters resource with the message. Include a parameter for each variable that is used in the messaqe text. Provide a valueString for each parameter with the text content you want to include into the message.

SMS / EMail message recipient

For security reasons emails or SMS cannot be sent to arbitrary people. Instead there are three options:

  • application user Per default the message is sent to the user using the source application.
  • fixed receiver Messages may be sent to a static predefined address. (An administrator)
  • user of other application Messages may be sent to a user of another application.

In order to send to the application user just send the FHIR message without destination and leave the last column on the subscription definition page in the portal empty. To use a fixed receiver include the target email or the target phone number into the URI parameter column (the rightmost column) on the subscription definition page.

Sending email or SMS using subscriptions and FHIR messages

It is possible to send emails or SMS messages to users using FHIR messages.

  • Send a FHIR message with an “eventUri” or “eventCoding” and optionally a Parameters resource.
  • In the developer portal on the default subscription page of the source application add a line with trigger “FHIR message” and provide the eventUri or eventCoding.code of the message into the second column. Choose “Forward to other application” as action and enter the internal name of the target service into the last column.
  • On the default subscription page of the target application add a line with the trigger “FHIR message”. Also provide the eventUri or eventCoding.code but append a “:” and the source application internal name to the uri. Select Send email or send SMS as action.
  • On the message definition page of the target application define a message with trigger FHIR message and the same event code as before. Provide the message text in multiple languages.

Example message with uri “http://example.com/event/example”, receiver “patient://test@example.com” and a variable named “examplevariable” with value “1234567890”:

{
  "resourceType" : "Bundle",
  "entry" : [
    {
      "resource" : {
         "resourceType" : "MessageHeader",
         "eventUri" : "http://example.com/event/example",
         "destination": {
           "endpoint" : "patient://test@example.com"
         },
         "focus" : [
           { "reference" : "Parameters/1" }
         ]
      }
    },
    {
      "fullUrl" : "Parameters/1",
      "resource" : {
         "resourceType" : "Parameters",
         "id" : "1",
         "parameter" : [
           { 
              "name" : "examplevariable",
              "valueString" : "1234567890"
           }
         ]
      }
    }
  ]
}