Overview

The Founda Healthcare Gateway supports exchanging clinical documents as described in the IHE (Integrating the Healthcare Enterprise) Mobile Access to Health Documents (MHD) Profile.

The MHD Profile defines one pair of actors and a transaction to submit or push new “document entries” from the mobile device to a receiving system. Another set of actors and transactions is used to query a list of “document entries” having specific metadata, and to retrieve a document. To support this profile we have integrated the following 4 ITI-transactions inside our platform:

  • ITI-65: Provide Document Bundle (Upload a document)
  • ITI-66: Find Document List (Find submissionsets/folders of document (sets))
  • ITI-67: Find Document References (Find document metadata)
  • ITI-68: Retrieve Document (Download a document)

alt text

The Founda Healthcare Gateway supports MHD to MHD and MHD to XDS/XCA transactions. MHD to MHD transactions will query for data in backbones that use the FHIR specification, while MHD to XDS/XCA queries the data stored in Cross-Enterprise Document Sharing (XDS) or Cross Community Access (XCA) backends.

Upload documents

Uploading documents on the Founda Healthcare Gateway is based on the Provide Document Bundle [ITI-65] transaction, which allows healthcare applications to send documents to a (target) Provider Organization.

Request

Send a POST request to endpoint https://api.founda.com/1/health/organizations/{organizationId}/fhir/4/. All document types are supported by creating a FHIR Binary resource and including the base64 encoded data in the data field. The whole payload should be a FHIR4 Bundle resource with type transaction.

An example submissionset Bundle payload with minimal metadata:

{
  "resourceType" : "Bundle",
  "id" : "ex-minimalProvideDocumentBundleSimple",
  "meta" : {
    "profile" : [
      "https://profiles.ihe.net/ITI/MHD/StructureDefinition/IHE.MHD.Minimal.ProvideBundle"
    ],
    "security" : [
      {
        "system" : "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code" : "HTEST"
      }
    ]
  },
  "type" : "transaction",
  "timestamp" : "2004-10-25T23:50:50-05:00",
  "entry" : [
    {
      "fullUrl" : "urn:uuid:aaaaaaaa-bbbb-cccc-dddd-e00111100001",
      "resource" : {
        "resourceType" : "List",
        "id" : "aaaaaaaa-bbbb-cccc-dddd-e00111100001",
        "meta" : {
          "profile" : [
            "https://profiles.ihe.net/ITI/MHD/StructureDefinition/IHE.MHD.Minimal.SubmissionSet"
          ],
          "security" : [
            {
              "system" : "http://terminology.hl7.org/CodeSystem/v3-ActReason",
              "code" : "HTEST"
            }
          ]
        },
        "text" : {
          "status" : "extensions",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\">SubmissionSet with Patient</div>"
        },
        "contained" : [
          {
            "resourceType" : "Practitioner",
            "id" : "founda-practitioner2",
            "telecom" : [
              {
                "system" : "email",
                "value" : "testingMHD@founda.com"
              }
            ]
          }
        ],
        "extension" : [
          {
            "url" : "https://profiles.ihe.net/ITI/MHD/StructureDefinition/ihe-sourceId",
            "valueIdentifier" : {
              "value" : "urn:oid:1.2.3.4"
            }
          },
          {
            "url" : "https://profiles.ihe.net/ITI/MHD/StructureDefinition/ihe-intendedRecipient",
            "valueReference" : {
              "reference" : "#in-practitioner2"
            }
          }
        ],
        "identifier" : [
          {
            "use" : "official",
            "system" : "urn:ietf:rfc:3986",
            "value" : "urn:oid:1.2.129.6.58.92.88337.1"
          },
          {
            "use" : "usual",
            "system" : "http://example.org/documents",
            "value" : "23425234-23470-1"
          }
        ],
        "status" : "current",
        "mode" : "working",
        "code" : {
          "coding" : [
            {
              "system" : "https://profiles.ihe.net/ITI/MHD/CodeSystem/MHDlistTypes",
              "code" : "submissionset"
            }
          ]
        },
        "subject" : {
          "reference" : "urn:uuid:aaaaaaaa-bbbb-cccc-dddd-e00111100004"
        },
        "date" : "2004-10-25T23:50:50-05:00",
        "entry" : [
          {
            "item" : {
              "reference" : "urn:uuid:aaaaaaaa-bbbb-cccc-dddd-e00111100002"
            }
          }
        ]
      },
      "request" : {
        "method" : "POST",
        "url" : "List"
      }
    },
    {
      "fullUrl" : "urn:uuid:aaaaaaaa-bbbb-cccc-dddd-e00111100002",
      "resource" : {
        "resourceType" : "DocumentReference",
        "id" : "aaaaaaaa-bbbb-cccc-dddd-e00111100002",
        "meta" : {
          "profile" : [
            "https://profiles.ihe.net/ITI/MHD/StructureDefinition/IHE.MHD.Minimal.DocumentReference"
          ],
          "security" : [
            {
              "system" : "http://terminology.hl7.org/CodeSystem/v3-ActReason",
              "code" : "HTEST"
            }
          ]
        },
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\">Resource \"aaaaaaaa-bbbb-cccc-dddd-e00111100002\" </p><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-IHE.MHD.Minimal.DocumentReference.html\">MHD DocumentReference Minimal</a></p><p style=\"margin-bottom: 0px\">Security Labels: <span title=\"{http://terminology.hl7.org/CodeSystem/v3-ActReason http://terminology.hl7.org/CodeSystem/v3-ActReason}\">http://terminology.hl7.org/CodeSystem/v3-ActReason</span></p></div><p><b>masterIdentifier</b>: id: urn:oid:1.2.840.113556.1.8000.2554.53432.348.12973.17740.34205.4355.50220.62012</p><p><b>identifier</b>: id: urn:uuid:7d5bb8ac-68ee-4926-85e7-b8aac8e1f09d</p><p><b>status</b>: current</p><p><b>subject</b>: <a href=\"#Patient_aaaaaaaa-bbbb-cccc-dddd-e00111100004\">See above (urn:uuid:aaaaaaaa-bbbb-cccc-dddd-e00111100004)</a></p><blockquote><p><b>content</b></p><p><b>format</b>: ITI XDS-SD TEXT (Details: http://ihe.net/fhir/ihe.formatcode.fhir/CodeSystem/formatcode code urn:ihe:iti:xds-sd:text:2008 = 'ITI XDS-SD TEXT', stated as 'null')</p></blockquote></div>"
        },
        "masterIdentifier" : {
          "system" : "urn:ietf:rfc:3986",
          "value" : "urn:oid:1.2.840.113556.1.8000.2554.53432.348.12973.17740.34205.4355.50220.62012"
        },
        "identifier" : [
          {
            "system" : "urn:ietf:rfc:3986",
            "value" : "urn:uuid:7d5bb8ac-68ee-4926-85e7-b8aac8e1f09d"
          }
        ],
        "status" : "current",
        "subject" : {
          "reference" : "urn:uuid:aaaaaaaa-bbbb-cccc-dddd-e00111100004"
        },
        "content" : [
          {
            "attachment" : {
              "contentType" : "text/plain",
              "url" : "urn:uuid:aaaaaaaa-bbbb-cccc-dddd-e00111100003",
              "size" : 11,
              "hash" : "MGE0ZDU1YThkNzc4ZTUwMjJmYWI3MDE5NzdjNWQ4NDBiYmM0ODZkMA=="
            },
            "format" : {
              "system" : "http://ihe.net/fhir/ihe.formatcode.fhir/CodeSystem/formatcode",
              "code" : "urn:ihe:iti:xds-sd:text:2008"
            }
          }
        ]
      },
      "request" : {
        "method" : "POST",
        "url" : "DocumentReference"
      }
    },
    {
      "fullUrl" : "urn:uuid:aaaaaaaa-bbbb-cccc-dddd-e00111100003",
      "resource" : {
        "resourceType" : "Binary",
        "id" : "aaaaaaaa-bbbb-cccc-dddd-e00111100003",
        "meta" : {
          "security" : [
            {
              "system" : "http://terminology.hl7.org/CodeSystem/v3-ActReason",
              "code" : "HTEST"
            }
          ]
        },
        "contentType" : "text/plain",
        "data" : "SGVsbG8gV29ybGQ="
      },
      "request" : {
        "method" : "POST",
        "url" : "Binary"
      }
    },
    {
      "fullUrl" : "urn:uuid:aaaaaaaa-bbbb-cccc-dddd-e00111100004",
      "resource" : {
        "resourceType" : "Patient",
        "id" : "aaaaaaaa-bbbb-cccc-dddd-e00111100004",
        "meta" : {
          "security" : [
            {
              "system" : "http://terminology.hl7.org/CodeSystem/v3-ActReason",
              "code" : "HTEST"
            }
          ]
        },
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\">Resource \"aaaaaaaa-bbbb-cccc-dddd-e00111100004\" </p><p style=\"margin-bottom: 0px\">Security Labels: <span title=\"{http://terminology.hl7.org/CodeSystem/v3-ActReason http://terminology.hl7.org/CodeSystem/v3-ActReason}\">http://terminology.hl7.org/CodeSystem/v3-ActReason</span></p></div><p><b>name</b>: Dee Schmidt </p></div>"
        },
        "name" : [
          {
            "family" : "Schmidt",
            "given" : [
              "Dee"
            ]
          }
        ]
      },
      "request" : {
        "method" : "POST",
        "url" : "Patient"
      }
    }
  ]
}

Response

The response payload is a FHIR4 Bundle resource of type transaction-response.

Payload

Each entry of the response Bundle contains an OperationOutcome resource indicating the result of processing each Bundle entry provided with the request.

Bundle.entry.response.status will be 201 to indicate the Resource has been created.

Status code: 200

Find submissionsets or folders

This endpoint is used to locate and return metadata for previously stored document submission sets or folders. The endpoint is located on our FHIR4 List endpoint. The Founda platform supports this part of the functionality as pointed out in ITI-66 transaction.

Request

Send a GET request to endpoint https://api.founda.com/1/health/organizations/{organizationId}/fhir/4/List.

The following query parameters are supported.

Property Type Required Format Allowed values
patient string x [1]
patient.identifier string x [1] token
code string x token submissionset, folder
status string x token current, superseded
date string date
designationType string token
identifier string token
source.given string
source.family string
sourceId string token

[1] Either patient or patient.identifier should be provided

Response

If the request is processed successfully, whether or not any FHIR List Resources are found, the HTTP status code shall be 200. The response message is a FHIR Bundle Resource with type searchset, containing zero or more List Resources.

Status code: 200

Payload: FHIR Bundle

{
    "link": [
        {
            "relation": "self",
            "url": "https://api.founda.com/1/health/organizations/<Healthcare_Organisation>/fhir/4/List?patient=466050&status=current"
        }
    ],
    "entry": [
        {
            "resource": {
                "subject": {
                    "reference": "Patient/466050"
                },
                "encounter": {
                    "reference": "Encounter/466101"
                },
                "meta": {
                    "tag": [
                        {
                            "code": "HTEST",
                            "display": "test health data",
                            "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason"
                        }
                    ],
                    "source": "#E9pZKf4ownVxJ3BA",
                    "versionId": "1"
                },
                "identifier": [
                    {
                        "system": "urn:uuid:a9fcea7c-fcdf-4d17-a5e0-f26dda030b59",
                        "value": "23974652"
                    }
                ],
                "entry": [
                    {
                        "flag": {
                            "text": "Deleted due to error"
                        },
                        "deleted": true
                    },
                    {
                        "flag": {
                            "text": "Added"
                        }
                    }
                ],
                "resourceType": "List",
                "status": "current",
                "mode": "changes",
                "id": "466102"
            },
            "search": {
                "mode": "match"
            },
            "fullUrl": "https://api.founda.com/1/health/organizations/<Healthcare_Organisation>/fhir/4/List/466102"
        }
    ],
    "type": "searchset",
    "total": 1,
    "resourceType": "Bundle"
}

Status code 404: Payload:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "diagnostics": "Resource could not be found"
    }
  ]
}

Find document metadata

As stated in ITI transaction 67, this operation will get all metadata related to zero or more documents. The response contains a Bundle of FHIR4 DocumentReferences. A FHIR4 DocumentReference resource is used to index a document, clinical note, and other binary objects to make them available to a healthcare system.

Request

Send a GET request to endpoint https://api.founda.com/1/health/organizations/{organizationId}/fhir/4/DocumentReference.

The following query parameters are supported.

Property Type Required Format Allowed values Note
patient string x [1]
patient.identifier string x [1] token
status string x token current, superseded
author.given string
author.family string
category string token
creation string dateTime Specifies a search against the creation time of the attachment
event string token
facility string token
format string token
identifier string token
period string date
security-label string token
setting string token
type string token

[1] Either patient or patient.identifier should be provided

Response

If the request is processed successfully the HTTP status code shall be 200. The response message is a FHIR4 Bundle Resource with type searchset, containing zero or more DocumentReference Resources.

The location to the downloadable content can be found in DocumentReference.content.attachment.url. This url is encrypted and only works for a certain Provider Organization.

Status code: 200

Example payload:

{
    "link": [
        {
            "relation": "self",
            "url": "https://api.founda.com/1/health/organizations/<Healthcare_Organisation>/fhir/4/DocumentReference"
        }
    ],
    "entry": [
        {
            "resource": {
                "masterIdentifier": {
                    "system": "urn:ietf:rfc:3986",
                    "value": "urn:oid:1.3.6.1.4.1.21367.2005.3.7"
                },
                "type": {
                    "coding": [
                        {
                            "code": "34108-1",
                            "display": "Outpatient Note",
                            "system": "http://loinc.org"
                        }
                    ]
                },
                "subject": {
                    "reference": "Patient/285871"
                },
                "authenticator": {
                    "reference": "Organization/285780"
                },
                "custodian": {
                    "reference": "Organization/285780"
                },
                "context": {},
                "meta": {
                    "tag": [
                        {
                            "code": "HTEST",
                            "display": "test health data",
                            "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason"
                        }
                    ],
                    "source": "#B7fc7bpVGs69hlfC",
                    "versionId": "1"
                },
                "identifier": [
                    {
                        "system": "urn:ietf:rfc:3986",
                        "value": "urn:oid:1.3.6.1.4.1.21367.2005.3.7.1234"
                    }
                ],
                "category": [
                    {
                        "coding": [
                            {
                                "code": "History and Physical",
                                "display": "History and Physical",
                                "system": "http://ihe.net/xds/connectathon/classCodes"
                            }
                        ]
                    }
                ],
                "author": [
                    {
                        "reference": "Practitioner/285892"
                    },
                    {
                        "reference": "#a2"
                    }
                ],
                "securityLabel": [
                    {
                        "coding": [
                            {
                                "code": "V",
                                "display": "very restricted",
                                "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality"
                            }
                        ]
                    }
                ],
                "content": [
                    {
                        "attachment": {
                            "contentType": "application/hl7-v3+xml",
                            "hash": "2jmj7l5rSw0yVb/vlWAYkK/YBwk=",
                            "language": "en-US",
                            "size": 3654,
                            "title": "Physical",
                            "url": "https://api.test.founda.com/1/health/organizations/<Healthcare_Organisation>/mhd/documents/mjxJoWA87f0mJl%2B1ztHqa2z%2BC2eiN4i5ADBjM7csSvY%3D%2Cy01PyeBz0sArK%2BIj0%2F9Uhg%3D%3D%2Ce4cf2f79cf855d44ea3412557fca0eb9b26f3181530f6fc77cb312af6e1aa49f520e70f2bc1daf8f693674fbb2676b6c187723851825ae0d2aa729e86f929e6f49553b08d50c5dfaba897d7aabebe749edc5d81ebe8d179b37967248ccc5ba998c29874709c2b91bc4624326565b7200bd4bc9368d21873afb1daefc37a1197c2ede063e52c31d1d706701d4163b254c6683acb15af19d47c75f5cee34cb397e03d6756f568702115fa1ff217c048841f0c2ece3f9db1311daed01d3b7db87aa10bca95cfb978ed29b94b20672b14331e602ad4fa7fa2ed890b195a21d9a2a98bcafa6c0aabab6e7dff95f0823f9f9e8b26aef2207c3b592f5c707b15f0d192eb2d4c4807449123d0472bc6e530b748a6e197e3cea1c637576ba883cad89fd71572d3665815a099ca4770cc18ca1"
                        },
                        "format": {
                            "code": "urn:ihe:pcc:handp:2008",
                            "display": "History and Physical Specification",
                            "system": "urn:oid:1.3.6.1.4.1.19376.1.2.3"
                        }
                    }
                ],
                "resourceType": "DocumentReference",
                "status": "current",
                "docStatus": "preliminary",
                "date": "2005-12-24T09:43:41+11:00",
                "description": "Physical",
                "id": "285919"
            },
            "search": {
                "mode": "match"
            },
            "fullUrl": "https://api.founda.com/1/health/organizations/<Healthcare_Organisation>/fhir/4/DocumentReference/285919"
        }
    ],
    "type": "searchset",
    "total": 1,
    "resourceType": "Bundle"
}

Download document

In order to download from a Document trough the Founda Healthcare Gateway, a url is needed from ‘Retrieve document metadata’ transaction. This endpoint will stream the document to the Application.

Request

Send a GET request to endpoint https://api.founda.com/1/health/organizations/{organizationId}/mhd/documents/{encrypted_metadata}. The encrypted_metadata part of the url is generated by Founda and contains metadata for downloading the document.

Response

Status code: 200

Payload: Document stream