SMARTWebEHR 1.4.2

SMARTWebEHR

SMARTWebEHR is a .NETStandard 2.0 library that handles SMART WEB messaging as an Electronic Health Record (EHR). See https://build.fhir.org/ig/HL7/smart-web-messaging/smart-web-messaging.html

Features

• Handles SMART WEB messaging
• Compatible with .NETStandard 2.0

Messages from app to EHR

Currently the following messages are supported:

• status.handshake
• scratchpad.create
• scratchpad.update
• scratchpad.read
• scratchpad.write
• form.submitted

Messages from EHR to app

• form.requestSubmit

If a resource is changed (create/update) a ResourceChanged event is fired with the resource included.

Installation

To install SMARTWebEHR, you can use the NuGet Package Manager:

dotnet add package SMARTWebEHR

Usage

Here is a simple example of how to use the SMARTWebEHR library:

SmartMessageHandler messageHandler = new SmartMessageHandler();
// subscribe to resource changed event
EventHandler<ResourceChangedEventArgs> eventHandler = (sender, e) =>
{
    // Handle the resource change event
    Console.WriteLine("Resource changed:");
    Console.WriteLine(e.Resource.ToString());
    if (e.Resource.TypeName == "QuestionnaireResponse")
    {
        QuestionnaireResponse QR = e.Resource as QuestionnaireResponse;
        // Do something with the QuestionnaireResponse
    }
};
messageHandler.ResourceChanged += eventHandler;
// Create scratchpad.create message to create a QuestionnaireResponse in the scratchpad
string jsonString = """
    {
     "messageId": "123",
     "messagingHandle": "bws8YCbyBtCYi5mWVgUDRqX8xcjiudCo",
     "messageType": "scratchpad.create",
     "payload": {
       "resource": {
         "resourceType": "QuestionnaireResponse",
         "questionnaire": "http://hl7.org/fhir/Questionnaire/gcs",
         "status": "in-progress",
         "subject": {"reference": "Patient/123"},
         "encounter": {"reference": "Encounter/123"}
       }
     }
    }
 """;
// Handle the message
var result = messageHandler.HandleMessage(jsonString);

Example Messages

status.handshake

Request

{
  "messageId": "1234",
  "messagingHandle": "bws8YCbyBtCYi5mWVgUDRqX8xcjiudCo",
  "messageType": "status.handshake",
  "payload": {  }
}

Response (success)

{
  "messageId": "eb678ea5-79a6-444b-90a7-a1a2a8c275be",
  "responseToMessageId": "1234",
  "additionalResponsesExpected": false,
  "payload": {
    "$type": "base",
  }
}

scratchpad.create

Request

{
  "messageId": "123",
  "messagingHandle": "bws8YCbyBtCYi5mWVgUDRqX8xcjiudCo",
  "messageType": "scratchpad.create",
  "payload": {
    "resource": {
      "resourceType": "QuestionnaireResponse",
      "questionnaire": "http://hl7.org/fhir/Questionnaire/gcs",
      "status": "in-progress",
      "subject": {"reference": "Patient/123"},
      "encounter": {"reference": "Encounter/123"}
    }
  }
}

Response (success)

{
  "messageId": "eb678ea5-79a6-444b-90a7-a1a2a8c275be",
  "responseToMessageId": "123",
  "additionalResponsesExpected": false,
  "payload": {
    "$type": "scratchpadCreate",
    "status": "201 Created",
    "location": "QuestionnaireResponse/2034822185"
  }
}

scratchpad.update

Request

{
  "messageId": "1234",
  "messagingHandle": "bws8YCbyBtCYi5mWVgUDRqX8xcjiudCo",
  "messageType": "scratchpad.update",
  "payload": {
    "resource": {
      "id": "1593463928",
      "resourceType": "QuestionnaireResponse",
      "questionnaire": "http://hl7.org/fhir/Questionnaire/gcs",
      "status": "completed",
      "subject": {"reference": "Patient/123"},
      "encounter": {"reference": "Encounter/123"}
    }
  }
}

Response (success)

{
  "messageId": "eb678ea5-79a6-444b-90a7-a1a2a8c275be",
  "responseToMessageId": "1234",
  "additionalResponsesExpected": false,
  "payload": {
    "$type": "scratchpadUpdate",
    "status": "200 OK",
  }
}

scratchpad.read

Request

{
  "messageId": "1234",
  "messagingHandle": "bws8YCbyBtCYi5mWVgUDRqX8xcjiudCo",
  "messageType": "scratchpad.read",
  "payload": {}
}

Response (success)

{
    "messageId":"3c3febbe-08e6-41b6-9f80-d89c3cee52bd",
    "responseToMessageId":"1234",
    "additionalResponsesExpected":false,
    "payload":{
        "$type":"scratchpadRead",
        "scratchpad":[
            {
                "resourceType":"QuestionnaireResponse",
                "id":"1593463928",
                "questionnaire":"http://hl7.org/fhir/Questionnaire/gcs",
                "status":"completed",
                "subject":{
                    "reference":"Patient/123"
                },
                "encounter":{
                    "reference":"Encounter/123"
                }
            }
        ]
    }
}

Request

{
    "messageId": "1234",
    "messagingHandle": "bws8YCbyBtCYi5mWVgUDRqX8xcjiudCo",
    "messageType": "scratchpad.read",
    "payload": {
        "location": "QuestionnaireResponse/1593463928"
    }
}

Response (success)

{
    "messageId":"3c3febbe-08e6-41b6-9f80-d89c3cee52bd",
    "responseToMessageId":"1234",
    "additionalResponsesExpected":false,
    "payload":{
        "$type":"scratchpadRead",
        "resource": {
            "resourceType":"QuestionnaireResponse",
            "id":"1593463928",
            "questionnaire":"http://hl7.org/fhir/Questionnaire/gcs",
            "status":"completed",
            "subject":{
                "reference":"Patient/123"
            },
            "encounter":{
                "reference":"Encounter/123"
            }
        }
    }
}

scratchpad.delete

Request

{
    "messageId": "1234",
    "messagingHandle": "bws8YCbyBtCYi5mWVgUDRqX8xcjiud4o",
    "messageType": "scratchpad.delete",
    "payload": {
        "location": "QuestionnaireResponse/1593463928"
    }
}

Response (success)

{
  "messageId": "eb678ea5-79a6-444b-90a7-a1a2a8c2754e",
  "responseToMessageId": "1234",
  "additionalResponsesExpected": false,
  "payload": {
    "$type": "scratchpadDelete",
    "status": "200 OK",
  }
}

Errors

The error responses are not part of the specifications so might change in the future.

JsonException response

{
    "messageId":"c305686f-54eb-416e-8f8c-3203416d1e73",
    "responseToMessageId":"123",
    "additionalResponsesExpected":false,
    "payload":{
        "$type":"error",
        "errorMessage":"',' is an invalid start of a property name. Expected a '\"'. Path: $ | LineNumber: 1 | BytePositionInLine: 23.",
        "errorType":"JsonException"
    }
}

ValidationException response

{
  "messageId": "eb678ea5-79a6-444b-90a7-a1a2a8c2754e",
  "responseToMessageId": "1234",
  "additionalResponsesExpected": false,
  "payload": {
    "$type": "error",
    "errorMessage": "MessagingHandle is mandatory.",
    "errorType":"ValidationException"
  }
}

UnknownMessageTypeException response

{
    "messageId":"24ff4fab-145d-418f-b131-e67ca4373aab",
    "responseToMessageId":"123",
    "additionalResponsesExpected":false,
    "payload":{
        "$type":"error",
        "errorMessage":"Unknown messageType: ??",
        "errorType":"UnknownMessageTypeException"
    }
}

Authors

• Thibault Mahieu - thibault.mahieu@tiro.health