Open mHealth to FHIR - Local Development build (v0.0.0). See the Directory of published versions
Smart App Workflow
R24 Server Architecture
FHIR-enabled EHR system
- A Open mHealth to FHIR Server with FHIR server running SMART-on-FHIR protocols for authentication/authorization, etc.
- Patient’s step counter sensor (called ** StepSensor** in this use case) – specific product, may be the patient’s phone
- Data store for the Step-Counter output (e.g., cloud and/or phone (e.g., GoogleFit, HealthKit)) that either offers data directly in - Open mHealth format using an Open mHealth endpoint, or is supported by Shimmer or Granola
- OmH-on-FHIR Client a SMART on FHIR app – has roles for PCP, onboarding staff, and patient
Smart app Workflow
Retrieving OMH data in native OMH Schema format
| Step | Description |
|---|---|
| 1. | Smart app Launch from Provider EHR. See the Smart on FHIR Launch Specification |
| 2. | R24 server authenticates and authorizes app to get OMH data |
| 3. | Following successful launch, the Smart app request OMH step count data for patient Z as a standard FHIR search API on DocumentReference. It provides an opaque identifier as a search parameter that identifies patient Z and optionally a time range of interest. |
| 4. | The R24 server receives the request and either maps the opaque id to its user id list and creates the DocumentReference resource on the fly from a native format or searches its FHIR based datastore for DocumentReference matches. Note that the DocumentReference is a ‘wrapper’ and contains context and a link to a Binary resource that represents the actual OMH Step Count data. |
| 5. | The R24 server returns DocumentReference resources that match the search criteria |
| 6. | The smart app receives the DocumentReference resource(s) and processes them one by one extracting the Binary endpoint data. then makes a second request to fetch the Binary resources in the native OMH (json) format using the standard FHIR API for Binary data (Note that the data may also be requested as a base64 encoded string as well). |
| 8. | The R24 server receives the request for the OMH data in the native JSON format. |
| 9. | For successful matches, the R24 Server Return the native OMH JSON file |
| 10. | processes/displays the OMH data to the end user |
Example
Launch Smart on FHIR App (Steps 1 and 2).
| See the Smart on FHIR Launch Specification | for examples |
Fetch FHIR DocumentReference resources containing OMH step count data. (Steps 3-6)
Includes: Opaque patient identifier, date Range, OMH datapoint common name, OMH datapoint schema standard codes
| Details | URL |
|---|---|
| OMH Specification | http://www.openmhealth.org/schemas/omh_step-count |
| FHIR STU3 DocumentReference Resource | http://hl7.org/fhir/STU3/documentreference.html |
| FHIR STU3 Search API | http://hl7.org/fhir/STU3/search.html |
Request
GET /DocumentReference/?patient.identifier={identifier}
Content-type: application/json+fhir
Accept: application/json+fhir
...other headers...
Issues
- Assumed identifiers as ‘logical’ (opaque Identifiers) and not ‘literal’ reference to Patient resource (see http://hl7.org/fhir/STU3/references.html.
Response
HTTP/1.1 200 OK
Date: Tue, 22 May 2018 03:40:05 GMT
Content-Type: application/fhir+json; charset=utf-8
...other headers...
{
"resourceType": "Bundle",
"id": "d3334394-5e24-49d4-b8a2-d0fc004a69",
"meta": {
"lastUpdated": "2018-05-24T00:18:35Z"
},
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://test.fhir.org/r3/DocumentReference?_format=application/fhir+json&search-id=901a685f-a483-4e92-8a6e-fb3e14cbfc&&patient.identifier=some%2Duser&_sort=_id"
}
],
"entry": [
{
"fullUrl": "http://test.fhir.org/r3/DocumentReference/omh-stepcount-example",
"resource": {
"resourceType": "DocumentReference",
"id": "omh-stepcount-example",
"meta": {
"versionId": "4",
"lastUpdated": "2018-05-23T23:14:29Z"
},
"contained": [
{
"resourceType": "Patient",
"id": "p",
"identifier": [
{
"system": "https://omh.org/shimmer/patient_ids",
"value": "some-user"
}
]
}
],
"identifier": [
{
"system": "urn:ietf:rfc:3986",
"value": "urn:oid:1.3.6.1.4.1.21367.2005.3.7.1234"
}
],
"status": "current",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "55423-8",
"display": "Step Count"
}
]
},
"class": {
"text": "OMH schema data"
},
"subject": {
"reference": "#p"
},
"created": "2018-05-22T09:35:00+11:00",
"indexed": "2018-05-22T09:35:00+11:00",
"content": [
{
"attachment": {
"contentType": "application/json",
"url": "http://test.fhir.org/r3/Binary/omh-stepcount-example"
}
}
],
"context": {
"period": {
"start": "2018-05-23T08:00:00+11:00",
"end": "2018-05-23T08:01:00+11:00"
}
}
},
"search": {
"mode": "match"
}
}
]
}
Issues
- Need to assign classes and types codes to identify.
- need to assign system ( e.g OMH )
- Need to decide how much context to repeat here vs in OMH Schema data
- min date range and type of datatpoint
Fetch native OMH step count data. (Steps 7-10)
Includes: Binary id(s)
| Details | URL |
|---|---|
| OMH Specification | http://www.openmhealth.org/schemas/omh_step-count |
| FHIR STU3 Binary Resource | http://hl7.org/fhir/STU3/binary.html |
| FHIR STU3 REST API | http://hl7.org/fhir/STU3/html.html |
Request
GET /Binary/{id} or GET /Binary?_id={id}
Accept and Application-type headers absent!
...Other headers...
Response
HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
...Other Headers...
{
"header": {
"id": "243c773b-8936-407e-9c23-270d0ea49cc4",
"creation_date_time": "2015-09-10T12:43:39.138-06:00",
"acquisition_MedicationDispense": {
"source_name": "Jawbone UP API",
"modality": "sensed",
"source_updated_date_time": "2015-09-10T18:43:39Z"
},
"schema_id": {
"namespace": "omh",
"name": "step-count",
"version": "1.0"
},
"user_id": "306a1202-410d-11e8-842f-0ed5f89f718b"
},
"body": {
"effective_time_frame": {
"time_interval": {
"start_date_time": "2015-08-06T05:11:09-07:00",
"end_date_time": "2015-08-06T23:00:36-06:00"
}
},
"step_count": 7939
}
}
Issues:
- Fetching multiple files
- not specified - may want an operation to zip into folder see this Zulip Chat?
- …
Retrieving OMH data as FHIR Observations
| Step | Description |
|---|---|
| 1. | Smart app Launch from Provider EHR |
| 2. | R24 server authenticates and authorizes app to get OMH data |
| 3. | Following successful launch, the Smart app request OMH step count data for patient Z as a standard FHIR search API on *Observation*. It provides an opaque identifier as a search parameter that identifies patient Z and optionally a time range of interest. |
| 4. | The R24 server receives the request and either maps the opaque id to its user id list and maps the OMH step count schemas to Observation on the fly from a native format or searches its FHIR based datastore for matches. |
| 5. | R24 server returns Observation resources that match the search criteria |
| 6. | The smart app receives the Observation resource(s) and |
| 7. | processes/displays the OMH data to the end user |
Example
Launch Smart on FHIR App (Steps 1 and 2)
| See the Smart on FHIR Launch Specification | for examples |
Fetch FHIR Observation representing the OMH step count data. (Steps 3-6)
Includes: Opaque patient identifer, date range, OMH data type as code
| Details | URL |
|---|---|
| OMH Specification | http://www.openmhealth.org/schemas/omh_step-count |
| FHIR STU3 Observation Resource | http://hl7.org/fhir/STU3/documentreference.html |
| FHIR STU3 Search API | http://hl7.org/fhir/STU3/search.html |
Request
GET Observation?patient.identifier={identifier}&code=55423-8
Content-type: application/json+fhir
Accept: application/json+fhir
...other headers...
Issues
- Assumed identifiers as ‘logical’ (opaque Identifiers) and not ‘literal’ reference to Patient resource (see http://hl7.org/fhir/STU3/references.html.
- Using code to identify datapoint schema
- search by max and min and other parameters
- provenance?
Response
HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
...Other Headers...
{
"resourceType": "Bundle",
"id": "55f690f4-d5e5-4f26-8fa2-026be61019",
"meta": {
"lastUpdated": "2018-05-23T23:48:12Z"
},
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://test.fhir.org/r3/Observation?_format=application/fhir+json&search-id=7db95351-c995-4cbc-b990-1760a91987&&patient.identifier=some%2Duser&_sort=_id"
}
],
"entry": [
{
"fullUrl": "http://test.fhir.org/r3/Observation/stepcount-example",
"resource": {
"resourceType": "Observation",
"id": "stepcount-example",
"meta": {
"versionId": "5",
"lastUpdated": "2018-05-23T21:56:09Z"
},
"contained": [
{
"resourceType": "Patient",
"id": "p",
"identifier": [
{
"system": "https://omh.org/shimmer/patient_ids",
"value": "some-user"
}
]
}
],
"identifier": [
{
"system": "https://omh.org/shimmer/ids",
"value": "12341567"
}
],
"status": "unknown",
"category": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "68130003",
"display": "Physical activity (observable entity)"
}
]
}
],
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "55423-8",
"display": "Number of steps in unspecified time Pedometer"
}
],
"text": "Step count"
},
"subject": {
"reference": "#p"
},
"effectivePeriod": {
"start": "2018-04-17T00:00:00Z",
"end": "2018-04-24T00:00:00Z"
},
"issued": "2018-04-24T17:13:50Z",
"device": {
"display": "Jawbone UP API, modality =sensed, sourceCreationDateTime = 2018-04-17T17:13:50Z"
},
"component": [
{
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/observation-statistics",
"code": "maximum",
"display": "Maximum"
}
],
"text": "Maximum"
},
"valueQuantity": {
"value": 7939,
"unit": "steps/day",
"system": "http://unitsofmeasure.org",
"code": "{steps}/d"
}
}
]
},
"search": {
"mode": "match"
}
}
]
}
To view this API in action using the Postman Collection Runner import this Postman Collection.
