For Transmural Care Data Providers

Authorization

All API calls towards the Telemonitoring HUB require an Authorization Header. The Transmural Care Data Provider will have to request a valid access_token based on the provided client and secret.

The API documentation for the Authorization call for Transmural Care Data Providers can be found here.

EHR’s can be kept up to date with the data you provide as a Transmural Care Data Provider. This is done by informing the Telemonitoring HUB with the needed information.
Keep in mind that informing the Telemonitoring HUB is only possible with the Telemonitoring ID. This ID is received during the request through Context Integration.

A Telemonitoring Session always has a status. The diagram below shows the possible statuses and the possible. transitions between those statuses. As Transmural Care Data Provider you are the owner of the status of each session. An HCP can request a status change though the Supported Actions (see later section).

To update the status, the Transmural Care Data Provider has to do a HTTPS PUT call towards the Telemonitoring HUB.

The OpenAPI documentation can be found here.

An overview of the different statuses:

Carepath HL7

During a status update call it’s possible as a Transmural Care Data Provider to inform the EHR about the carepath for which the Telemonitoring Prescription has been created via the carepath property. This carepath property can be passed along with any status update towards the Telemonitoring HUB and will be persisted with the corresponding telemonitoringId. This means that as a Transmural Care Data Provider you only have to pass the carepath once or you can also decide to pass it towards the Telemonitoring HUB with each update. The carepath is added by the provider when there is a link to a validated HL7 carepath. This link refers to to the HL7 implementation Guide.

Example carepath for Heartfailure can be found here (Telemonitoring Hub Identifier): https://build.fhir.org/ig/hl7-be/patient-monitoring/branches/main/heartfailure.html

Attachments

Type 1 : PDF

The PDF gives an overview of the Telemonitoring Session in a human readable format. This can be shared with the health hubs. Every PDF has a unique ID, which makes it possible for the EHR to know if an update to the same file occured. If you share multiple languages, you should add the contentLanguage attribute.

The Telemonitoring HUB does not import or read data in any way. The data remains on the side of the Telemonitoring Provider and it is up to the EHR to download the data. That means the HUB will only share metadata on the PDF.

Example of a PDF document :

{
  "id":"pdf",
  "name": "Telemonitoring Report",
  "etag":"f2fd2ddd34eebc9d039f5e693b95a61c",
  "contentMD5":"f2fd2ddd34eebc9d039f5e693b95a61c",
  "contentLength":255917,
  "contentType":"application/pdf",
  "lastModified":"2024-09-30T07:44:17.335Z",
  "contentLanguage":"nl",
  "uri":"https://xxx/pdf?token=0ba1b31c",
  "headers": { 
     "X-Custom-Header": "HeaderValue" 
  }
}

It’s highly recommended as a Transmural Care Data Provider to add MD5 hash and content Length to guarantee there is no data loss or corruption during download of the file by the EHR.

Type 2 : FHIR

Next to PDF, all carepath data that is sent through the Telemonitoring HUB requires a structured FHIR format as well so parsing, visualisation and re-use can be guaranteed. The FHIR format and definition is going through a fixed process, which you can see in the flow chart below.

Example of the FHIR structure

{
  "id": "summary",
  "name": "Patient Observation"
  "contentType": "application/fhir+json",
  "contentMD5": "YWIzZGVmNA==",
  "contentLength": 120,
  "lastModified": "2023-09-02T12:30:00.000-05:00",
  "etag": "\"12345abc\"",
  "uri": "https://example.com/resource1",
  "headers": { 
    "X-Custom-Header": "HeaderValue" 
  }
}

Type 3 : Dashboard

The final Type is required when visualisation is needed and done by the Transmural Care Data Provider. This can be the case by specialized dashboard requirements (for example a neurologists dashboard to monitor and view multi modal signals). In this case a URI is shared that can be included and i-Framed by the EHR.

{
  "id": "customId2",
  "name": "Patient dashboard
  "contentType": "x-tm-dashboard",
  "uri": "https://example.com/dashboard",
  "headers": { 
     "X-Dashboard-Header": "DashboardValue" 
  }
}

Securing your data

As the Telemonitoring HUB acts as a gateway for metadata, but doesn’t store data the EHR needs to get data from the Transmural Care Data Provider in way that it is safe for the Telemonitoring Provider to not expose this data. There are several ways of doing this and as a Transmural Care Data Provider you are free to choose your way of working. Hereby some ways we’ve seen that might work for you.

Obscuring the URI :
This makes the URI impossible to guess, which guarantees that only the EHR can actually read this information.

Adding a prescriber specific token to the URI :
Adding a Token enables you to know what prescriber you’ve sent the data to and validate the correctness of the token. This gives you more control and information versus obscuring the URI.

Limiting in time (signed URI or temporary token) :
This makes the availability of the URI temporary and limits the security risk drastically.

Limiting in requests :
This guarantees a read only-once and so reduces the security risk.

Adding extra headers in the metadata of the HUB :
This URI requires extra authentication that needs to be added by the EHR before downloading. This functionality is currently not supported by the Telemonitoring Portal (so downloading of files with extra authentication will not work with the Telemonitoring Portal)

As an extra security measure some EHR’s will also use white-listing on DNS level and so will require the DNS where you store data on upfront. This will be requested by the Telemonitoring HUB during activation

Attachment Limitations

• There is currently a soft limit of 10 attachments (per API call, not per session)
• There can be multiple FHIR, PDF and Dashboard URI’s available for a Telemonitoring Prescription.
• Every FHIR, PDF and Dashboard are identified by a unique ID defined by the Transmural Care Data Provider.
• Every attachment should be made available. If it is out of the array in the webhook, the EHR can mark it as deleted.

As a Transmural Care Data Provider you might also want to allow the patients to directly communicate with your service. Being it via a mobile app or via your website. One way to do so is authenticate the patient via it’s SSIN, but that means that you’ll need to receive and safely store the SSIN of each patient if you really want to be secure and use Authentication tools like ItsMe.

With the Patient Authentication Token, TMP supports an alternative flow in which a unique token is genFor Transmural Care Data Providerserated which is linked with the launched Telemonitoring Session. When the Patient Authentication Token is enabled for the Transmural Care Data Provider and the Hospital has enabled it too, the unique Patient Authentication Token is send towards the EHR system together with the “Accepted” status update from the Transmural Care Data Provider. This token can be given to the patient by the HCP at that moment (see Patient Authentication Link for more information on how). Since the HCP is with the patient, the patient authentication is secure and only the patient knows the token. Later the patient can use this token to authenticate with the Transmural Care Data Provider.

The Transmural Care Data Provider can verify the received token with the Transmural Platform, the OpenAPI specifications of the verify call can be found here.

Patient Authentication Link

Together with the Patient Authentication Token, TMP can also configure a Patient Authentication URL which is a unique link towards the Transmural Care Data Provider including (if necessary) the telemonitoringId and token. This deep link can help patients to easily authenticate themselves with the Transmural Care Data Provider. For example by creating a deep link towards the mobile app of the Provider. With the unique Patient Authentication Token and TelemonitoringId in that link, the Provider can immediately authenticate and identify the patient from that deep link.

The TMP Portal will display a QR code with that Patient Authentication Link, this QR code can be shown or given to the patient for further authentication. Any EHR system can implement a similar solution.

If supported by the Transmural Care Data Provider and the EHR, an HCP can trigger actions towards the Telemonitoring Provider. Current supported actions by the Telemonitoring Prescription Portal are stop and cancel.

When the HCP triggers such an action, the Telemonitoring Prescription Portal will trigger the Transmural Care Data Provider via the given Action URI:

POST : Action URI webhook
HEADERS : { headers as defined by the Provider }
BODY : 
{
  telemonitoringId: 'xxx',
  prescriber: {
     id: '...'
  },
  action: 'stop' or 'cancel'
}

It is up to the Transmural Care Data Provider to adjust the status of the Telemonitoring Session according to your business rules and update the Telemonitoring HUB of the status change as described in the section on Status Updates.