Point-of-Care Device Implementation Guide
1.0.0-draft - STU 1 Ballot3 International flag

Point-of-Care Device Implementation Guide, published by HL7 International / Devices. This guide is not an authorized publication; it is the continuous build for version 1.0.0-draft built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/uv-pocd/ and changes regularly. See the Directory of published versions

RESTful Transfer

Page standards status: Informative

Most FHIR implementations follow the RESTful approach for transferring resources between client and server. The FHIR server provides the RESTful API for managing resources. A medical device or gateway acts as a FHIR client, which reports device data using create and update interactions. Other clients (e.g., clinical applications) use read or search interactions to access stored data. There is also a subscription mechanism to get notifications when data becomes available.

For message-oriented architectures, see FHIR Messaging as an alternative approach.

Requirements for a FHIR server supporting this implementation guide are listed in the Server CapabilityStatement.

This section explains the transfer of device-sourced resources as listed on the Profiles page to a FHIR server using transaction bundles.

Bundles

A point-of-care medical device model consists of multiple resource instances, which have to be reported at least once during initialization. Even during runtime, a device may report multiple observations together. While it is possible using individual create and update interactions for each resource, this implementation guide recommends Bundle resources for transferring a set of resources in a single transaction. For example, an entire device containment tree or subtree is packed into a bundle of Device and DeviceMetric resources. Another bundle contains all Observation resources for an update cycle.

Transactions

A client submits a transaction bundle containing multiple request entries to create, update, or delete resources. The content is treated as a single entity, which is either accepted or rejected.

Each entry has a Bundle.entry.request element with HTTP method (e.g., POST or PUT) and relative URL, and a Bundle.entry.resource element for the resource content to be created or updated. When a resource is initially transferred, the client does not know the logical id that will be assigned by the server. To allow references between resources in the bundle, the client may assign a temporary identifier in the Bundle.entry.fullUrl element.

Example: Transaction bundle creating Device and DeviceMetric resources, where DeviceMetric refers to Device

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [ {
    "fullUrl": "urn:uuid:2fa92047-0cfa-47e5-b9f9-b3d93dd02366",
    "resource": {
      "resourceType": "Device",
      "identifier": [ {
        "system": "urn:oid:1.2.840.10004.1.1.1.0.0.1.0.0.1.2680",
        "value": "01-23-45-67-89-AB-CD-EF"
      } ],
      "status": "active",
      "type": {
        "coding": [ {
          "system": "urn:iso:std:iso:11073:10101",
          "code": "69965",
          "display": "MDC_DEV_MON_PHYSIO_MULTI_PARAM_MDS"
        } ],
        "text": "Patient Monitor"
      },
      // ...
    },
    "request": {
      "method": "POST",
      "url": "Device"
    }
  },
  // ...
  {
    "resource": {
      "resourceType": "DeviceMetric",
      "type": {
        "coding": [ {
          "system": "urn:iso:std:iso:11073:10101",
          "code": "150084",
          "display": "MDC_PRESS_BLD_VEN_CENT"
        } ],
        "text": "CVP"
      },
      "source": {
        "reference": "urn:uuid:2fa92047-0cfa-47e5-b9f9-b3d93dd02366"
      },
      // ...
    },
    "request": {
      "method": "POST",
      "url": "DeviceMetric"
    }
  } ]
}

If successful, the server returns a transaction-response bundle, which reports the result of each request. The bundle response entry returns also the server-assigned logical id and version for each resource. For subsequent transactions, the client can use literal references instead of temporary identifiers.

Example: Transaction response bundle returning logical identifiers

{
  "resourceType": "Bundle",
  "type": "transaction-response",
  // ...
  "entry": [ {
    "response": {
      "status": "201 Created",
      "location": "Device/1234/_history/1",
      // ...
    }
  },
  // ...
  {
    "response": {
      "status": "201 Created",
      "location": "DeviceMetric/2345/_history/1",
      // ...
    }
  } ]
}

Create

All Device and DeviceMetric resources that make the device model must exist on the server. When communication starts, the client may not know what's already on the server. To avoid duplicates, it can search for existing resources and create missing ones or start with conditional updates (see below).

For reporting a new measurement or changed setting, an Observation resource is created where at least the effective time (time stamp or period) differs from previously reported observations.

Create is an individual HTTP POST request or a transaction bundle entry as shown in the example.

Example: Create an Observation resource

{
  // ...
  "entry": [ {
    "resource": {
      "resourceType": "Observation",
      "status": "final",
      "code": {
        "coding": [ {
          "system": "urn:iso:std:iso:11073:10101",
          "code": "150087",
          "display": "MDC_PRESS_BLD_VEN_CENT_MEAN"
        } ],
        "text": "CVPm"
      },
      "subject": {
        "reference": "Patient/0123"
      },
      "effectiveDateTime": "2020-03-04T15:16:17+00:00",
      "valueQuantity": {
        "value": 5.5,
        "unit": "mmHg",
        "system": "http://unitsofmeasure.org",
        "code": "mm[Hg]"
      },
      "device": {
        "reference": "DeviceMetric/2345/_history/1"
      }
    },
    "request": {
      "method": "POST",
      "url": "Observation"
    }
  },
  // ...
  ]
}

Conditional Create

Resources generated by a medical device need references to resources that are most likely already present on the server, such as Patient or Location. The device or gateway may have only limited knowledge about it. Conditional create adds unique information as search criteria to the request. If a resource is found it remains unchanged, otherwise a new instance is created.

If no resource matches the search criteria, the server creates the new resource. If exactly one resource matches, nothing is created and the existing resource is used. If multiple resources match, the server rejects the request with 412 Precondition Failed (see conditional create). The search criteria should therefore be selective enough to match at most one resource.

Conditional Create is an HTTP POST request with If-None-Exist extension header.

For Location, use a stable identifier assigned by the hospital's location master, for example the ADT or bed management system that also populates HL7 v2 PV1-3 (Assigned Patient Location). Its system should scope the identifier to the facility or enterprise, and its value should combine the levels of the hierarchy needed for uniqueness, such as point of care, room and bed. Conditional create based on Location.name alone is not recommended. Bed labels such as "Bed 42" or room numbers such as "315" are typically repeated across units, buildings and facilities.

Example: Create Location resource for bed 42 in room 315 of surgical ICU C3 only if no Location with this bed identifier exists

{
  // ...
  "entry": [ {
    "fullUrl": "urn:uuid:0c52bec2-49bb-46ce-a2f7-a3cc16fc17a4",
    "resource": {
      "resourceType": "Location",
      "identifier": [ {
        "use": "official",
        "system": "http://hospital.example.org/fhir/sid/beds",
        "value": "C3-315-42"
      } ],
      "status": "active",
      "name": "Bed 42",
      "alias": [ "SICU C3, Room 315, Bed 42" ],
      "mode": "instance",
      "physicalType": {
        "coding": [ {
          "system": "http://terminology.hl7.org/CodeSystem/location-physical-type",
          "code": "bd"
        } ]
      },
      "partOf": {
        "identifier": {
          "system": "http://hospital.example.org/fhir/sid/rooms",
          "value": "C3-315"
        },
        "display": "SICU C3, Room 315"
      }
    },
    "request": {
      "method": "POST",
      "url": "Location",
      "ifNoneExist": "identifier=http://hospital.example.org/fhir/sid/beds|C3-315-42"
    }
  },
  // ...
  ]
}

See Location SomeLocation for the complete example resource.

Update

The client needs to update a resource on the server when content changes, but the object that the resource represents is still the same. For example, the operational status of a Device or calibration data of a DeviceMetric may change over time. An update adds a new version of the resource instance. Resource references can point to a specific version if needed.

In some cases an Observation resource may be updated too. Examples:

  • Observation.status changes from 'preliminary' to 'final' after manual validation
  • Observation.effectivePeriod has been created with start time only, and end time gets known

Update is an HTTP PUT request. URL includes the logical id.

Example: Update DeviceMetric resource when calibration is completed

{
  // ...
  "entry": [ {
    "fullUrl": "http://example.org/fhir/DeviceMetric/2345",
    "resource": {
      "resourceType": "DeviceMetric",
      "id": "2345",
      "type": {
        "coding": [ {
          "system": "urn:iso:std:iso:11073:10101",
          "code": "150084",
          "display": "MDC_PRESS_BLD_VEN_CENT"
        } ],
        "text": "CVP"
      },
      "source": {
        "reference": "Device/1234"
      },
      // ...
      "calibration": [ {
        "type": "offset",
        "state": "calibrated",
        "time": "2020-03-04T16:17:18+00:00"
      } ]
    },
    "request": {
      "method": "PUT",
      "url": "DeviceMetric/2345"
    }
  },
  // ...
  ]
}

Conditional Update

When submitting a Device or DeviceMetric resource for the first time, the client may not know if it is already available on the server or needs an update. Conditional update adds unique information as search criteria to the request URL. If a resource is found and its content differs, it's updated. If no resource is found a new instance is created.

If no resource matches the search criteria, the server creates the new resource. If exactly one resource matches, nothing is created and the existing resource is used. If multiple resources match, the server rejects the request with 412 Precondition Failed (see conditional create). The search criteria should therefore be selective enough to match at most one resource.

Conditional Update is an HTTP PUT request with search criteria instead of the logical id.

Example: Update Device resource with given EUI-64 identifier, or create it if it doesn't exist

{
  // ...
  "entry": [ {
    "fullUrl": "urn:uuid:915a7b26-f8df-4ec5-8fa9-4e623b1a12cc",
    "resource": {
      "resourceType": "Device",
      "identifier": [ {
        "system": "urn:oid:1.2.840.10004.1.1.1.0.0.1.0.0.1.2680",
        "value": "01-23-45-67-89-AB-CD-EF"
      } ],
      "status": "inactive",
      "statusReason": [ {
        "coding": [ {
          "system": "http://terminology.hl7.org/CodeSystem/device-status-reason",
          "code": "standby",
          "display": "Standby"
        } ]
      } ],
      "type": {
        "coding": [ {
          "system": "urn:iso:std:iso:11073:10101",
          "code": "69965",
          "display": "MDC_DEV_MON_PHYSIO_MULTI_PARAM_MDS"
        } ],
        "text": "Patient Monitor"
      },
      // ...
    },
    "request": {
      "method": "PUT",
      "url": "Device?identifier=urn:oid:1.2.840.10004.1.1.1.0.0.1.0.0.1.2680|01-23-45-67-89-AB-CD-EF"
    }
  },
  // ...
  ]
}

Delete

A resource should only be deleted if the object that it represents does no longer exist. In most cases, changing the operational status (Device.status or DeviceMetric.operationalStatus) is more appropriate.

Delete is an HTTP DELETE request without resource content.