For Telemonitoring Providers

Authorization

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

{
  "access_token":"eyJhbGciOiJIU...",
  "token_type":"bearer",
  "expires_in":3600
}

EHR’s can be kept up to date with the data you provide as a Telemonitoring 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 Telemonitoring 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).

Carepath HL7

During a status update call it’s possible as a Telemonitoring 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 Telemonitoring 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

Status : Requested

The Prescription Request is triggered when a HCP clicks on the ‘prescribe’-button. Each Telemonitoring session will initially be created in the status “Requested”.

Status : Accepted

The first thing you need to inform the Telemonitoring HUB of is if you accepted the Telemonitoring Prescription Request. Doing so is done through a PUT request to the Telemonitoring HUB. Changing the status of a Telemonitoring Session to “Accepted” is only possible in case the current status of the session is “requested”.

PUT : https://api.telemonitoring-prescription.com/prescription
HEADERS : { Authorization : access_token }
BODY : 
{
  telemonitoringId: 'xxx',
  status : 'accepted',
  providerContext : '<extra provider context>',
  carepath : {id : 'hl7-be/...', version : 'x'}
}

Note that you can add a providerContext. This can be used if the Telemonitoring Provider wants to add extra context to the HUB, which could be relevant for the EHR.

Status : In-Progress

The status ‘in-progress’ can be sent by the Telemonitoring Provider to inform the EHR the Telemonitoring Session is ongoing and measurements or data relevant to the Telemonitoring Session is or can become available. Changing the status of a Telemonitoring Session to “In-Progress” is only possible in case the current status of the session is “Accepted”.

PUT : https://api.telemonitoring-prescription.com/prescription
HEADERS : { Authorization : access_token }
BODY : 
{
  telemonitoringId: 'xxx',
  status : 'in-progress',
  providerContext : '<extra provider context>',
  carepath : {id : 'hl7-be/...', version : 'x'}
  attachments : [...]
}

Note that in the status 'in-progress', attachments can be defined. We cover attachments in a separate section.

Status : Cancelled

“Cancelled” is a status if the HCP decided to cancel a Telemonitoring Session. This is done by the cancel action. Changing the status of a Telemonitoring Session to “Cancelled” is only possible in case the current status of the session is “Requested” or “Accepted”.
Note, that for most Telemonitoring Sessions a cancel can only happen if there was no data measured and only if the Telemonitoring Provider supports the ‘cancel’ action.

PUT : https://api.telemonitoring-prescription.com/prescription
HEADERS : { Authorization : access_token }
BODY : 
{
  telemonitoringId: 'xxx',
  status : 'cancelled', 
  carepath : {id : 'hl7-be/...', version : 'x'}
}

Status : Completed

When the Telemonitoring Session has ended a status update to “Completed” needs to happen. The EHR is in that way informed that no further data will become available on that specific telemonitoring ID. Changing the status of a Telemonitoring Session to “Completed” is only possible in case the current status of the session is “Accepted” or “In-Progress”.

PUT : https://api.telemonitoring-prescription.com/prescription
HEADERS : { Authorization : access_token }
BODY : 
{
  telemonitoringId: 'xxx',
  status : 'completed'
  providerContext : '<extra provider context>',
  carepath : {id : 'hl7-be/...', version : 'x'}
  attachments : [...]
}

Attachments

The Telemonitoring HUB can receive 3 types of data and make those available to the EHR.

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",
  "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 Telemonitoring 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",
  "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 Telemonitoring 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",
  "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 Telemonitoring 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 Telemonitoring 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
• 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 Telemonitoring Provider.
• Every attachment should be made available. If it is out of the array in the webhook, the EHR can mark it as deleted.

If supported by the Telemonitoring 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 Telemonitoring 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 Telemonitoring 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.