Magentus Practice Management FHIR Implementation Guide - Local Development build (v1.2.60) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Requesting

The Magentus Requesting Service supports pathology and radiology diagnostic requesting with an intent to eventually support the round tripping of requests and reports. The profiles in this section attempt to leverage common foundations for both flavours of requests while allowing for relevant domain specific specialisations.

Some features to note:

• Requesting depends on a ServiceRequest/Task pattern that is defined as Option F in the FHIR Workflow description. This uses a Task to track the fulfillment of a ServiceRequest, primarily through the status and businessStatus attributes.
• In addition to a Task for each ServiceRequest, we also allocate a Group Task that provides a resource coordinating a set of individual Task's for each ServiceRequest (each individual test or service where multiple may constitute a single order). In addition to the explicit Group Task, they are also implicitly bound together through their common groupIdentifier attribute. The reason for an explicit Group Task resource is to aid searching and discovery of complete orders rather than needing to discover each part of the order in isolation.
• Tasks are also used to track the workflow associated with CommunicationRequests. These are used to track fulfilment of communication with a patient about their diagnostic service or with a clinician for urgent results. In future, this will also be used to carry the existing copyTo information for copying results to other clinicians.

The FHIR Resources used by the Magentus Requesting Service are shown in the diagram below.

Typical sequence of interactions involving Placers and Fillers.

Requesting Service

Requesting Profiles

The FHIR Resources generated by the Magentus Requesting Service are listed below.

ServiceRequest and Task

It should be noted that Diagnostic Service Request should be regarded as a legacy profile and instead replaced by explicit Pathology Request and Radiology Request use as these are more specific to each of their domains of use.

CommunicationRequest and Task

Organizations

Fulfilment Tasks are linked to an owner organization to indicate a preferred or assigned filler. From a placer's perspective these are diagnostic service brands. From a filler's perspective, brands belong to an organizational entity. We represent these using a child brand Organization linked to a parent Organization. This is important for fillers discovering new requests as they can discover across all brands by searching for brands that have a known parent without needing to search for requests for each individual brand Organization.

Other Profiles

Supporting Clinical Information

ServiceRequests can include a set of supporting information that provides relevant clinical background for the patient. They are linked from ServiceRequest.supportingInfo which is a list of resource references. All supporting information resources should include a narrative representation, e.g. Observation.text, so that the resource can be processed into text-based clinical notes if the structured information in the resource cannot be processed. Since a diagnostic order can include multiple requests, common supportingInfo should be referenced from each ServiceRequest. This means that referenced resource should be a full resource in the order transaction and not contained within the ServiceRequest.

Contained

Additional resources are contained within the Requesting resources above, the FHIR profiles for these resources are listed below.

Workflow

The eRequesting workflow describes the interactions between a placer and a filler (or alternate filler) via the eRequesting FHIR Service.

Test/Service Data Consistency

While our use of individual ServiceRequests and Tasks could allow for unique attributes such as Status, Note, etc., we currently require that all child ServiceRequest and Task share common values, including that within the Group Task.

Placer Family Tag

All ServiceRequest and Task resources carry an optional meta.tag slice called placer-family that identifies the placer system that generated the order (e.g. genie, gentu, acmepms). The tag is bound to the EOrdersPlacerTagValueSet and uses the code system http://fhir.geniesolutions.io/CodeSystem/eorders-placer-tag-codesystem.

The EOrdersSubmitOrderBundle profile enforces a consistent-placer-tag invariant that requires all Task and ServiceRequest entries within a submit-order transaction Bundle to carry the same placer-family tag value. This ensures that the placer identity is consistent across the entire order.

Placer Integration

Placer Integration Overview

A placer system interacts with the Requesting Service through a series of operations that follow a natural workflow:

1. Discover Brands — Use the Get Brands Operation to discover available diagnostic service brand organizations (pathology laboratories and imaging services).
2. Register Subscriptions — Use the Add Placer Subscription Operation to register a Subscription across one or more brand partitions so that the placer receives notifications when order statuses change. See also Subscribing to Requests for details on subscription criteria and handling notifications.
3. Submit Orders — Use the Submit Order Operation to submit a diagnostic order as a transaction Bundle conforming to the EOrdersSubmitOrderBundle profile.
4. Monitor Fulfillment — Respond to subscription notifications by retrieving updated Tasks. See Retrieving Subscription POST Notification Data for search patterns including _include and _revinclude parameters.

Get Brands Operation

The Get Brands operation allows a placer to discover available diagnostic service brand Organizations (Pathology Laboratories and Imaging Services). This is typically the first step in the placer workflow — the placer retrieves the list of brands to present to the requesting clinician.

See Get Brands Operation Definition for the full specification.

Parameters

Example — Retrieve all pathology brands

POST [base]/Organization/$get_brands

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "serviceType",
      "valueCode": "pathology"
    }
  ]
}

Example — Retrieve all brands (no filter)

POST [base]/Organization/$get_brands

{
  "resourceType": "Parameters",
  "parameter": []
}

Submit Order Operation

The Submit Order operation is used to submit a diagnostic order (pathology or radiology) as a transaction Bundle. The Bundle must conform to the EOrdersSubmitOrderBundle profile.

The HTTP response body is always a single resource. Check resourceType to determine the outcome:

See Submit Order Operation Definition for the full specification.

Undirected Order Lifecycle

When no fulfillment Task carries a Task.owner, the order is undirected — it has been lodged in the registry but not assigned to a specific filler. The $submit_order operation returns an informational OperationOutcome to confirm this.

The lifecycle of an undirected order after submission:

1. Lodged — the order Bundle is stored and the fulfillment Task(s) sit in requested status with no owner.
2. Patient presents — the patient takes the request form (which carries the requisition barcode) to a filler of their choice.
3. Claim — the filler calls the $claim operation with the requisition identifier (barcode) and their organisation reference. This assigns Task.owner to the claiming filler and returns a new group Task.
4. Fulfilment — once claimed, the workflow proceeds identically to a directed order.

Note that fillers cannot search for or subscribe to undirected orders — filler discovery is based solely on Task.owner. An undirected order becomes visible to a filler only after they claim it using a requisition identifier provided by the patient.

The placer discovers that an undirected order has been claimed by subscribing to status changes on the group Task (e.g. Task?status=received,accepted) — the same subscription pattern used for directed orders. No special handling is required on the placer side.

Order Bundle Profile

The EOrdersSubmitOrderBundle is a transaction Bundle that must contain the following entries at minimum:

All entries must include fullUrl and request.method = PUT.

All ServiceRequest and Task entries should carry a placer-family meta tag identifying the placer system. The Bundle enforces a consistent-placer-tag invariant requiring all Task and ServiceRequest entries to use the same tag value — see Placer Family Tag for details.

Example — Submit an order

POST [base]/$submit_order

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "order",
      "resource": {
        "resourceType": "Bundle",
        "meta": {
          "profile": [
            "http://fhir.geniesolutions.io/StructureDefinition/eorders-submit-order-bundle"
          ]
        },
        "type": "transaction",
        "timestamp": "2024-01-15T10:30:00+11:00",
        "entry": [
          ...
        ]
      }
    }
  ]
}

Bundle Examples

The following example Bundles conform to the EOrdersSubmitOrderBundle profile and can be used as reference when constructing orders:

Response Examples

The following examples illustrate each possible response from the operation:

Add Placer Subscription Operation

The Add Placer Subscription operation registers a Subscription resource across one or more SmileCDR partitions mapped from brand Organization references. This allows a placer system to register for notifications across multiple diagnostic service brands in a single call rather than manually creating subscriptions in each brand's partition.

Each Organization reference (literal or logical) is resolved to the corresponding SmileCDR partition. The provided Subscription is then submitted to each partition. The operation returns a result per organization indicating success or failure.

See Add Placer Subscription Operation Definition for the full specification.

Parameters

Result Codes

Example — Register a subscription across two pathology brands

POST [base]/Subscription/$add_placer_subscription

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "subscription",
      "resource": {
        "resourceType": "Subscription",
        "criteria": "Task?status=requested,cancelled&_tag=fulfillment-task-group&owner.partof.identifier=http://ns.electronichealth.net.au/id/hi/hpio/1.0|8003123456789123",
        "status": "requested",
        "reason": "Task requested and cancelled subscription",
        "channel": {
          "type": "rest-hook",
          "endpoint": "https://webhook.site/bbd78ee4-e267-4633-8acc-38a5e1dc54a0",
          "header": ["Authorization: Bearer <access-token>"]
        }
      }
    },
    {
      "name": "organization",
      "valueReference": {
        "reference": "Organization/dda4a656-f60e-11ed-baf1-d2cbed391bcf",
        "display": "Magentus Pathology Lab Brand A"
      }
    },
    {
      "name": "organization",
      "valueReference": {
        "reference": "Organization/another-lab-brand-id",
        "display": "Magentus Pathology Lab Brand B"
      }
    }
  ]
}

Example Response

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "part": [
        {
          "name": "organization",
          "valueReference": {
            "reference": "Organization/dda4a656-f60e-11ed-baf1-d2cbed391bcf"
          }
        },
        {
          "name": "outcome",
          "valueCoding": {
            "system": "http://fhir.geniesolutions.io/CodeSystem/eorder-add-placer-subscription-result-codesystem",
            "code": "ok",
            "display": "OK"
          }
        },
        {
          "name": "subscription",
          "valueReference": {
            "reference": "Subscription/sub-12345"
          }
        }
      ]
    },
    {
      "name": "result",
      "part": [
        {
          "name": "organization",
          "valueReference": {
            "reference": "Organization/another-lab-brand-id"
          }
        },
        {
          "name": "outcome",
          "valueCoding": {
            "system": "http://fhir.geniesolutions.io/CodeSystem/eorder-add-placer-subscription-result-codesystem",
            "code": "ok",
            "display": "OK"
          }
        },
        {
          "name": "subscription",
          "valueReference": {
            "reference": "Subscription/sub-12346"
          }
        }
      ]
    }
  ]
}

Tip: The Subscription criteria and channel format used in this operation is identical to the format described in Subscribing to Requests. The key difference is that this operation handles distributing the Subscription across brand partitions automatically.

Filler Integration

Subscribing to Requests

In order to receive subscription notifications from the FHIR Server when resources of interest are created or updated, a subscription is registered. A subscription request includes the following properties.

In this case we are interested in Task resources that are

• in a requested or cancelled status,
• are associated with a Task group, not an individual Task fulfillment, and
• are directed to a child brand of the Organization with HPI-O of 8003123456789123.

It is also possible to subscribe to each individual child brand rather than via the parent but this is more cumbersome and requires updating everytime a new brand is added.

Example The following example creates a new Subscription for the Task resource with criteria as described above.

POST [base]/Subscription

{
  "resourceType": "Subscription",
  "criteria": "Task?status=requested,cancelled&_tag=fulfillment-task-group&owner.partof.identifier=http://ns.electronichealth.net.au/id/hi/hpio/1.0|8003123456789123",
  "status": "requested",
  "reason": "Task requested and cancelled subscription",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://webhook.site/bbd78ee4-e267-4633-8acc-38a5e1dc54a0",
    "header": ["Authorization: Bearer secret-token-abc-123"]
  }
}

The Subscription endpoint can also be used to Search, Read, Update and Delete as per the standard FHIR REST API pattern.

Subscription POST Notification

A subscription notification is received as a POST request on the endpoint specified in the subscription registration request. The POST request has an empty body.

Example

POST https://webhook.site/bbd78ee4-e267-4633-8acc-38a5e1dc54a0
Authorization: Bearer <access-token>

Responding to a Subscription Notification

The subscription notification shall respond as quickly as possible with a success status of 200 OK or 202 Accepted, and an empty body. The latter is normally returned when the request is accepted for processing but processing will commence after the response has been returned, which is the preferred approach for subscription notifications.

Any error response may result in a subsequent retry by the FHIR Server to submit the Subscription Notification until the number of retries is exceeded, at which time the FHIR Server will stop the subscription. See Managing Subscriptions and Errors for more details.

Retrieving Subscription POST Notification Data

When a subscription notification is received, perform a Search request with the corresponding criteria along with a _lastUpdated parameter with the timestamp when the last search request was performed with the gt prefix (see https://hl7.org/fhir/r4/search.html#prefix).

Example

GET [base]/Task?status=requested,cancelled & \
owner.identifier=http://ns.electronichealth.net.au/id/hi/hpio/1.0|8003123456789123 & \
_lastUpdated=gt2022-12-13T12:30:00Z

Include Referenced Resources

In order to retrieve the entire Orders, use the following _include and _revinclude parameters.

Example

GET [base]/Task?status=requested,cancelled & \
owner.identifier=http://ns.electronichealth.net.au/id/hi/hpio/1.0|8003123456789123 & \
_lastUpdated=gt2022-12-13T12:30:00Z &\
_include=Task:patient & _include=Task:owner & _include=Task:requester & _revinclude=Task:part-of & \
_revinclude:iterate=CommunicationRequest:about:Task & \
_include=Task:focus & _revinclude:iterate=ServiceRequest:copiesTo & \
_include:iterate=PractitionerRole:practitioner & _include:iterate=PractitionerRole:organization & \
_revinclude:iterate=Consent:data:ServiceRequest

Updating Tasks based on Fulfilment

Fillers have two opportunities to update fulfilment Tasks. The first is with a combination of status (where values are fixed), businessStatus, and statusReason. The second is through adding outputs from fulfilment to Task.output. These two fulfilment updates are described below.

Status and businessStatus Combinations

Task statuses are fixed and defined within the FHIR R4 Task resource, more specifically the Task Status ValueSet. The sequencing of these statuses are prescribed by the Task State Machine.

In addition to status, Task supports a businessStatus attribute which further refines status. This is a CodeableConcept which may or may not be coded. We have defined a set of useful codes which may be extended.

Task Output

We currently define two types of output:

• a DiagnosticReport reference to an imaging report or a pathology report.
• a BookingSlot reference allowing for booking/appointment information to be shared back to the placer using a profile of the FHIR slot. The Slot contains timing information and references a Schedule which references a HealthcareService that ultimately references the Location information containing name and address. Most slot information is optional. This may be especially useful for imaging appointments and should be aligned with a booked businessStatus.

Updating Task Status with PATCH

Rather than replacing a whole Task resource with PUT, fillers should update the group and individual Tasks using FHIR Patch (FHIRPath-based) via a transaction Bundle. This minimises the chance of overwriting concurrent updates from other parties.

Each entry in the transaction Bundle has request.method = PATCH and carries a Parameters resource as its payload. The Parameters resource contains one or more parameter entries named operation, each with the following parts:

Example — mark Tasks as received, remove businessStatus and statusReason

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        { "name": "type",  "valueCode": "replace" },
        { "name": "path",  "valueString": "Task.status" },
        { "name": "value", "valueCode": "received" }
      ]
    },
    {
      "name": "operation",
      "part": [
        { "name": "type", "valueCode": "delete" },
        { "name": "path", "valueString": "Task.businessStatus" }
      ]
    },
    {
      "name": "operation",
      "part": [
        { "name": "type", "valueCode": "delete" },
        { "name": "path", "valueString": "Task.statusReason" }
      ]
    }
  ]
}

​This Parameters resource is then included as the resource in each entry of the transaction Bundle, with request.method = PATCH and request.url set to a conditional reference such as Task?_id=[task-id]. Every patch must explicitly handle all three fields — status, businessStatus, and statusReason — either setting them to the correct value or deleting them. See the Task Status and Business Status table for valid combinations.

See the FHIR transaction PATCH Bundle example 1 (set status to received, remove businessStatus and statusReason) and example 2 (set status to accepted and businessStatus to booked, remove statusReason).

Claim Order Operation

The claim operation is used to create a new fulfilment Task for an alternate filler. Implementation of the operation cancels the original fulfilment Task, if it exists, but leaves the ServiceRequest unchanged. The original filler can determine that the order is being alternatively filled but not who is the alternative filler and similarly the alternate filler cannot determine who was originally designated to fulfill the order, if one was specified.

See Diagnostic Service Claim Operation for the full specification.

Parameters

Result Codes

Error Recovery

Example — Claim a request

POST [base]/Task/$claim

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "requisition",
      "valueIdentifier": {
        "system": "http://ns.electronichealth.net.au/id/hpio-scoped/order/1.0/8003628672586276",
        "value": "GTU00000-TWRYT3"
      }
    },
    {
      "name": "organization",
      "valueReference": {
        "reference": "Organization/18751557-2550-411a-a874-9e7631505a00",
        "display": "Magentus Practice Lab"
      }
    }
  ]
}

Note that the Organization reference should reference a known filler organization within the FHIR server.

Patient Integration

View Order Operation

The view operation is focussed on providing a patient portal with access to a diagnostic request based on a barcode. If the barcode is found and it is accessible then information is returned about the request as well as any fulfilment information by service providers. If the request has had multiple fulfilment pathways (e.g. request is directed to one provider but claimed by another provider based on patient choice) then the group Task for each filler is included. See Diagnostic Service View Operation for the full specification.

Parameters

Example — View a request

POST [base]/Task/$view_request

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "requisition",
      "valueIdentifier": {
        "system": "http://ns.electronichealth.net.au/id/hpio-scoped/order/1.0/8003629850181971",
        "value": "GTU00000-V79K2K"
      }
    }
  ]
}

If the operation is successful, a result such as Diagnostic Service View Operation Result will be returned.

If an error occurs finding the request based on the barcode, the following will be returned

Example

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "error",
      "valueString": "Internal server error: Requisition Not Found"
    }
  ]
}