PHR FHIR Envelope

All data that you want to transfer, should be in a FHIR Bundle, forming the base PHR Envelope. A Bundle is a means of packaging multiple information of multiple types - either as disparate Collection or as Document. The entire bundle is referred as data "content".

• You can send over multiple such contents/bundles through the data transfer api. Please see the reference API documentation for details.
• Note the content (bundle) itself must be encrypted. Please refer to the API documentation of how data should be sent over HTTPS. For encryption of the "content" or "bundle", you should refer to the API and Diffie-Hellman key exchange documentation.
• The relevant sections only focuses on the packaging information in FHIR resources' format.

The basic Bundle

{
    "resourceType": "Bundle",
    "id": "fe13172d-107f-4004-8d01-ebcc9c2485cb",
    "type": "collection",
    "entry": [
        {
            "fullUrl": "urn:uuid:8789a6c5-c139-4a06-bc4d-7c6ec822fe36",
            "resource": {
                "resourceType": "Media",
                "id": "8789a6c5-c139-4a06-bc4d-7c6ec822fe36",
                ....
            }
        },
        {
            "fullUrl": "urn:uuid:12d593df-dece-4a74-8bd9-b89ee769e316",
            "resource": {
                "resourceType": "Observation",
                "id": "12d593df-dece-4a74-8bd9-b89ee769e316",
                ....
            }
        }, 
        .... 
    ]
}

The above is the basic structure of a FHIR Bundle.

• resourceType* - must be Bundle
• id* - must be unique for each bundle that you want to send. For traceability purpose, its recommended that you provide id (and not just for this element) that you must be able to resolve within your system.
• type* - must be "collection" or "document". Collection is meant for assembling disparate resources together,while document is meant for contextual grouping of information. We will explain Bundle type "document" in detail later.
• entry* - is an array of FHIR resources. As of now, the reference HIU service supports 5 top level resources like "Media", "Observation", "Condition", "MedicationRequest" & "DiagnosticReport".
  • notice each entry's fullUrl, prefixed with urn:uuid, followed by the <uuid>. This is also the "id" of resource. In FHIR specification, it need not be so, but ref stack expects so.

 

So let's say a Lab wants to send over an image or pdf, assuming the requester can interpret the information. for example, a doctor looking at ECG or Blood test result. The lab can provide the result, but does not means of mapping and sending standardised/encoded data - yet. Here, we can use a Media resource to minimally describe and send over data.

Media Resource

A media resource, can contain any attachment - usually inline (preferred). The attachments can be any file - PDF, WORD, JPEG, PNG, MPEG etc. For complete details on FHIR Media Resource, please refer to the the FHIR documentation website.

Towards the above example, we would probably send over a response like

{
    "resourceType": "Media",
    "id": "8789a6c5-c139-4a06-bc4d-7c6ec822fe36",
    "status": "completed",
    "createdDateTime": "2020-04-15T08:30:00+05:30",
    "note": [ 
        {
            "text": "BILATERAL DIGITAL MAMMOGRAPHY and 3D TOMOSYNTHESIS"
        },
        { 
            "text":"No particular impression"
        }
    ],
    "content": {
        "contentType": "application/pdf",
        "data":"<base 64 encoded content of the file>"
        "title": "BILATERAL DIGITAL MAMMOGRAPHY and 3D TOMOSYNTHESIS"
    }
}

The above is an example of a Media resource with minimal information. Most of it should be self-explanatory, but it is trying to send over a Digital Mammography report as PDF.

• resourceType* - must be specified - in this case Media
• id* - unique Id of the Media resource within the bundle context. Please note the relevance to the entry fullUrl as explained above
• status* - complete. Usually. For other status values - check FHIR Media documentation.
• createdDateTime* - time in UTC format. Note, if the Media resource is sent independently, then you must specify the createdDateTime.
• note* - textual notes about the media that you are sending.
• content* - is an attachment, meaning the file you are sending over.
  • contentType - Mime type of the content. It upto the HIU viewer what mimetype they can render/display. But try to stick to the following - application/pdf, image/jpeg, image/png, application/msword, application/rtf, audio/mpeg, application/dicom
  • title - optional but useful to express what the attachment is for
  • data - base 64 encoded content of file. For example, if I would want to base64 encode a file from command line I would probably do something like below

For example: in Java:

    String input = "your-content-as-fhir-bundle";
    String content = Base64.getEncoder().encodeToString(input.getBytes());

Or from shell:

openssl base64 -in <infile> -out <outfile>

Putting it altogether

Now if I were to put the "Media Resource" in the bundle's entry section, I would have something like below.

{
  "resourceType": "Bundle",
  "id": "fe13172d-107f-4004-8d01-ebcc9c2485cb",
  "type": "collection",
  "entry": [
    {
      "fullUrl": "urn:uuid:8789a6c5-c139-4a06-bc4d-7c6ec822fe36",
      {
        "resourceType": "Media",
        "id": "8789a6c5-c139-4a06-bc4d-7c6ec822fe36",
        "status": "completed",
        "createdDateTime": "2020-06-05T08:30:00+05:30",
        "note": [
          {
            "text": "BILATERAL DIGITAL MAMMOGRAPHY and 3D TOMOSYNTHESIS"
          },
          {
            "text": "No particular impression"
          }
        ],
        "content": {
          "contentType": "application/pdf",
          "data": "<do not forget to put base 64 encoded content of the file>",
          "title": "BILATERAL DIGITAL MAMMOGRAPHY and 3D TOMOSYNTHESIS"
        }
      }
    }
  ]
}

And thats it, you have your first PHR FHIR bundle ready to be encrypted and sent!

TIPS

• You are never going to handcode the JSON above! You would use a FHIR client library. There are many in many different programming language in the FHIR references for developers/implementers.
• During development, its usually a good idea to validate the resource. For this, you may use one of the validators listed in the reference library/resources section. For example, the following example validates the entire file content (json)

java -jar org.hl7.fhir.validator.jar AttachedMediaAsReport.json -version 4.0