# Requesting - Magentus Practice Management FHIR Implementation Guide v1.2.60

* [**Table of Contents**](toc.md)
* **Requesting**

## 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](https://hl7.org/fhir/R4/workflow-management.html#optionf) in the [FHIR Workflow](https://hl7.org/fhir/R4/workflow.html#12.5) 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.
* `Task`s are also used to track the workflow associated with `CommunicationRequest`s. 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.

sequenceDiagram ; Placer->>eReq Server: Subscribe to `received`, `accepted`, etc. Group Tasks Filler->>eReq Server: Subscribe to `requested` Group Tasks ; Placer->>eReq Server: New order ; eReq Server->>Filler: New order notification ; Filler->>eReq Server: Search for new orders ; eReq Server->>Filler: New orders ; Filler->>eReq Server: Update Group and Individual Tasks to `received` ; eReq Server->>Placer: Order status update to `received` ; Filler->>eReq Server: Update Group and Individual Tasks to `accepted` ; eReq Server->>Placer: Order status update to `accepted` ; Filler->>eReq Server: Update Group and Individual Tasks to `in-progress` ; eReq Server->>Placer: Order status update to `in-progress` ; Filler->>eReq Server: Update Group and Individual Tasks to `completed` ; eReq Server->>Placer: Order status update ;

### 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](StructureDefinition-eorders-diagnosticrequest.md) should be regarded as a legacy profile and instead replaced by explicit [Pathology Request](StructureDefinition-eorders-pathologyrequest.md) and [Radiology Request](StructureDefinition-eorders-radiologyrequest.md) use as these are more specific to each of their domains of use.

| | | |
| :--- | :--- | :--- |
| [Diagnostic Service Request (legacy)](StructureDefinition-eorders-diagnosticrequest.md) | No | [ServiceRequest](http://hl7.org/fhir/R4/servicerequest.html) |
| [Pathology Request](StructureDefinition-eorders-pathologyrequest.md) | No | [ServiceRequest](http://hl7.org/fhir/R4/servicerequest.html) |
| [Radiology Request](StructureDefinition-eorders-radiologyrequest.md) | No | [ServiceRequest](http://hl7.org/fhir/R4/servicerequest.html) |
| [Diagnostic Request Base](StructureDefinition-eorders-diagnosticrequest-base.md) | Yes | [ServiceRequest](http://hl7.org/fhir/R4/servicerequest.html) |
|   |   |   |
| [Diagnostic Request Group Task](StructureDefinition-eorders-task-fulfillment-group.md) | No | [Task](http://hl7.org/fhir/R4/task.html) |
| [Diagnostic Request Task](StructureDefinition-eorders-diagnosticrequesttask.md) | No | [Task](http://hl7.org/fhir/R4/task.html) |
| [Diagnostic Request Task Base](StructureDefinition-eorders-task-fulfillment-base.md) | Yes | [Task](http://hl7.org/fhir/R4/task.html) |

##### CommunicationRequest and Task

| | |
| :--- | :--- |
| [Communication Request to Patient](StructureDefinition-eorders-communicationrequest-patient.md) | [CommunicationRequest](http://hl7.org/fhir/R4/communicationrequest.html) |
| [Communication Request to Provider](StructureDefinition-eorders-communicationrequest-provider.md) | [CommunicationRequest](http://hl7.org/fhir/R4/communicationrequest.html) |
| [Communication Request Task](StructureDefinition-eorders-task-communicationrequest.md) | [Task](http://hl7.org/fhir/R4/task.html) |

##### 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.

| | |
| :--- | :--- |
| [Parent Diagnostic Organization](StructureDefinition-eorders-organization-diagnostic-parent.md) | [Organization](http://hl7.org/fhir/R4/organization.html) |
| [Pathology Brand Organization](StructureDefinition-eorders-organization-pathology-laboratory.md) | [Organization](http://hl7.org/fhir/R4/organization.html) |
| [Imaging Brand Organization](StructureDefinition-eorders-organization-imaging-service.md) | [Organization](http://hl7.org/fhir/R4/organization.html) |

classDiagram Diagnostic Org <|-- Pathology Brand Diagnostic Org <|-- Imaging Brand Diagnostic Org: +code Diagnostic institution Pathology Brand: +code Clinical pathology service Pathology Brand: +partOf DiagnosticOrg Imaging Brand: +code Diagnostic Imaging service Imaging Brand: +partOf DiagnosticOrg

##### Other Profiles

| | |
| :--- | :--- |
| [Consent Withdrawl](StructureDefinition-eorders-consentwithdrawl.md) | [Consent](http://hl7.org/fhir/R4/consent.html) |
| [Request PractitionerRole](StructureDefinition-eorders-practitionerrole.md) | [PractitionerRole](http://hl7.org/fhir/R4/practitionerrole.html) |
| [Magentus HealthcareService](StructureDefinition-gs-healthcareservice.md) | [HealthcareService](http://hl7.org/fhir/R4/healthcareservice.html) |
| [Magentus Organization](StructureDefinition-gs-organization.md) | [Organization](http://hl7.org/fhir/R4/organization.html) |
| [Magentus Patient](StructureDefinition-gs-patient.md) | [Patient](http://hl7.org/fhir/R4/patient.html) |
| [Magentus Practitioner](StructureDefinition-gs-practitioner.md) | [Practitioner](http://hl7.org/fhir/R4/practitioner.html) |

##### Supporting Clinical Information

`ServiceRequest`s 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.

| | |
| :--- | :--- |
| [UV IPS Observation (Pregnancy: status)](https://www.hl7.org/fhir/uv/ips/StructureDefinition-Observation-pregnancy-status-uv-ips.html) | [Observation](http://hl7.org/fhir/R4/observation.html) |
| [Magentus Gestational Age](StructureDefinition-gs-gestationalage.md) | [Observation](http://hl7.org/fhir/R4/observation.html) |
| [Magentus Estimated Date of Delivery](StructureDefinition-gs-estimateddateofdelivery.md) | [Observation](http://hl7.org/fhir/R4/observation.html) |
| [Magentus Last Menstrual Period](StructureDefinition-gs-lastmenstrualperiod.md) | [Observation](http://hl7.org/fhir/R4/observation.html) |
| [HRT Flag](StructureDefinition-gs-hrt.md) | [Observation](http://hl7.org/fhir/R4/observation.html) |
| [Magentus Current Medication](StructureDefinition-eorders-medicationstatement.md) | [MedicationStatement](http://hl7.org/fhir/R4/medicationstatement.html) |
| [Magentus Allergy](StructureDefinition-eorders-allergyintolerance.md) | [AllergyIntolerance](http://hl7.org/fhir/R4/allergyintolerance.html) |

##### Contained

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

| | |
| :--- | :--- |
| [Request Coverage](StructureDefinition-eorders-coverage.md) | [Coverage](http://hl7.org/fhir/R4/coverage.html) |
| [Request Encounter](StructureDefinition-eorders-encounter.md) | [Encounter](http://hl7.org/fhir/R4/encounter.html) |
| [Request PractitionerRole Contact](StructureDefinition-eorders-practitionerrole-contact.md) | [PractitionerRole](http://hl7.org/fhir/R4/practitionerrole.html) |

#### 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 `ServiceRequest`s and `Task`s 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](ValueSet-eorders-placer-tag-valueset.md) and uses the code system `http://fhir.geniesolutions.io/CodeSystem/eorders-placer-tag-codesystem`.

The [EOrdersSubmitOrderBundle](StructureDefinition-eorders-submit-order-bundle.md) 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](#get-brands-operation)to discover available diagnostic service brand organizations (pathology laboratories and imaging services).
1. **Register Subscriptions**— Use the[Add Placer Subscription Operation](#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](#subscribing-to-requests)for details on subscription criteria and handling notifications.
1. **Submit Orders**— Use the[Submit Order Operation](#submit-order-operation)to submit a diagnostic order as a transaction Bundle conforming to the[EOrdersSubmitOrderBundle](StructureDefinition-eorders-submit-order-bundle.md)profile.
1. **Monitor Fulfillment**— Respond to subscription notifications by retrieving updated Tasks. See[Retrieving Subscription POST Notification Data](#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](OperationDefinition-EOrderGetBrandsOperation.md) for the full specification.

##### Parameters

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| in | serviceType | code | 0..1 | Filter by`pathology`or`imaging`. If omitted, both types are returned. |
| in | parentOrganization | Reference | 0..1 | Filter to brands belonging to a specific[Parent Diagnostic Organization](StructureDefinition-eorders-organization-diagnostic-parent.md). |
| out | brand | Organization | 0..* | A brand Organization resource ([Pathology Laboratory](StructureDefinition-eorders-organization-pathology-laboratory.md)or[Imaging Service](StructureDefinition-eorders-organization-imaging-service.md)). |

##### 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](StructureDefinition-eorders-submit-order-bundle.md) profile.

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

| | | |
| :--- | :--- | :--- |
| `Bundle`(type`transaction-response`) | Order is directed and successfully processed | All fulfillment Tasks had an`owner`and the transaction committed. |
| `OperationOutcome`(severity`error`or`fatal`) | Order failed validation or cannot be processed | Do not retry without correcting the reported issues. |
| `OperationOutcome`(severity`information`) | Order is undirected — no fulfillment Task has an`owner` | The order has been lodged for later routing. Not an error. |

See [Submit Order Operation Definition](OperationDefinition-EOrderSubmitOrderOperation.md) 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`.
1. **Patient presents**— the patient takes the request form (which carries the requisition barcode) to a filler of their choice.
1. **Claim**— the filler calls the[`$claim` operation](#claim-order-operation)with the requisition identifier (barcode) and their organisation reference. This assigns`Task.owner`to the claiming filler and returns a new group`Task`.
1. **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](StructureDefinition-eorders-submit-order-bundle.md) is a `transaction` Bundle that must contain the following entries at minimum:

| | | | |
| :--- | :--- | :--- | :--- |
| patient | [GSPatient](StructureDefinition-gs-patient.md) | 1..1 | The patient the order is for. |
| organization | [GSOrganization](StructureDefinition-gs-organization.md) | 1..* | Requesting organization and/or filler brand organizations. |
| practitioner | [GSPractitioner](StructureDefinition-gs-practitioner.md) | 1..1 | The requesting practitioner. |
| practitionerRole | [EOrdersPractitionerRole](StructureDefinition-eorders-practitionerrole.md) | 1..1 | The requesting practitioner's role. |
| serviceRequest | [EOrdersDiagnosticRequest](StructureDefinition-eorders-diagnosticrequest.md),[EOrdersPathologyRequest](StructureDefinition-eorders-pathologyrequest.md), or[EOrdersRadiologyRequest](StructureDefinition-eorders-radiologyrequest.md) | 1..* | One or more diagnostic service requests. |
| fulfillmentGroup | [EOrdersTaskFulfillmentGroup](StructureDefinition-eorders-task-fulfillment-group.md) | 1..1 | The group Task coordinating all individual fulfillment Tasks. |
| fulfillmentRequest | [EOrdersTaskFulfillmentRequest](StructureDefinition-eorders-diagnosticrequesttask.md) | 1..* | One fulfillment Task per ServiceRequest. |
| consent | [EOrdersConsentWithdrawl](StructureDefinition-eorders-consentwithdrawl.md) | 0..* | Optional consent withdrawal resources. |
| communicationRequestPatient | [EOrdersCommunicationRequestPatient](StructureDefinition-eorders-communicationrequest-patient.md) | 0..* | Optional patient communication preferences (e.g. do not send SMS). |
| communicationRequestProvider | [EOrdersCommunicationRequestProvider](StructureDefinition-eorders-communicationrequest-provider.md) | 0..* | Optional provider communication (e.g. urgent phone/fax). |
| taskCommunicationRequest | [EOrdersTaskCommunicationRequest](StructureDefinition-eorders-task-communicationrequest.md) | 0..* | Tasks tracking communication request fulfillment. |

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](#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:

| | |
| :--- | :--- |
| [FBC + LFT Request](Bundle-20afd601-ed83-476b-8121-ae976ea8cc44.md) | A pathology order containing FBC and LFT service requests with two fulfillment request Tasks. |
| [Diagnostic Request Example](Bundle-BundleERequestExample.md) | A diagnostic order with a pathology laboratory filler, consent withdrawal, and communication requests. |
| [Genie Generated Pathology Request](Bundle-cf387fc3-f224-491c-a3d3-317df15bb84b.md) | A complete pathology request as generated by the Genie clinical desktop application. |
| [Pathology Request Example](Bundle-BundlePathologyRequestExample.md) | A pathology request demonstrating supporting clinical information including pregnancy status, gestational age, and estimated date of delivery. |

##### Response Examples

The following examples illustrate each possible response from the operation:

| | |
| :--- | :--- |
| [Directed Order Success](Bundle-eorders-submit-response-success.md) | Transaction-response Bundle returned when all fulfillment Tasks have an owner and the order is successfully processed. |
| [Error Response](OperationOutcome-eorders-submit-response-error.md) | OperationOutcome returned when the submitted Bundle fails validation or cannot be processed. |
| [Undirected Order Response](OperationOutcome-eorders-submit-response-undirected.md) | Informational OperationOutcome returned when no fulfillment Task has an owner; the order has been lodged for later routing. |

#### 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](OperationDefinition-EOrderAddPlacerSubscriptionOperation.md) for the full specification.

##### Parameters

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| in | subscription | Subscription | 1..1 | The Subscription resource to register in each brand partition. See[Subscribing to Requests](#subscribing-to-requests)for subscription criteria format. |
| in | organization | Reference | 1..* | References to brand Organizations ([Pathology Laboratory](StructureDefinition-eorders-organization-pathology-laboratory.md)or[Imaging Service](StructureDefinition-eorders-organization-imaging-service.md)). May be literal or logical (identifier-based) references. |
| out | result | (part) | 1..* | One result per organization containing`organization`(Reference),`outcome`(Coding), and optionally`subscription`(Reference to the created Subscription). |

##### Result Codes

| | | |
| :--- | :--- | :--- |
| ok | OK | Subscription was successfully created in the partition. |
| organization-not-found | Organization Not Found | The referenced Organization could not be resolved. |
| partition-not-found | Partition Not Found | No SmileCDR partition is mapped to the resolved Organization. |
| subscription-invalid | Subscription Invalid | The Subscription resource failed validation. |
| subscription-exists | Subscription Exists | An equivalent Subscription already exists in the partition. |
| error | Error | An unexpected error occurred. |

##### 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](#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.

| | | |
| :--- | :--- | :--- |
| criteria | Search criteria to match resources of interest | Task?status=requested,cancelled&_tag=fulfillment-task-group&owner.partof.identifier=http://ns.electronichealth.net.au/id/hi/hpio/1.0|8003123456789123 |
| status | Fixed: requested | requested |
| channel.type | Fixed: rest-hook | rest-hook |
| channel.endpoint | Web service URL where webhook is posted | https://webhook.site/bbd78ee4-e267-4633-8acc-38a5e1dc54a0 |
| channel.header | Authorization header to be used in the subscription notification | Authorization: Bearer secret-token-abc-123 |

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](https://hl7.org/fhir/subscription.html#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.

| | | |
| :--- | :--- | :--- |
| _include | Task:patient | Patient |
| _include | Task:owner | Organization as the designated filler |
| _include | Task:requester | Clinician creating the request |
| _revinclude | Task:part-of | Group task for an individual`Task` |
| _revinclude:iterate | CommunicationRequest:about:Task | Communication with patient or requesting clinician |
| _include | Task:focus | `ServiceRequest`associated with`Task` |
| _revinclude:iterate | ServiceRequest:copiesTo | `PractitionerRole`s where reports should be sent |
| _include:iterate | PractitionerRole:practitioner | `Practitioner`associated with the requester |
| _include:iterate | PractitionerRole:organization | `Organization`associated with the requester |
| _revinclude:iterate | Consent:data:ServiceRequest | `Consent`s linked to the`ServiceRequest`s |

**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 `Task`s. 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](http://hl7.org/fhir/R4/task.html) resource, more specifically the [Task Status](https://hl7.org/fhir/R4/valueset-task-status.html) ValueSet. The sequencing of these statuses are prescribed by the [Task State Machine](https://hl7.org/fhir/R4/workflow-communications.html#12.6.2).

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](ValueSet-eorders-task-business-status.md) which may be extended.

| | | | | | | |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| ✓ | ✓ | requested | claimed-request | claimed request | Diagnostic request has been claimed | placer |
| ✓ | ✓ | accepted | booked | booked | Service has been booked | filler |
| ✓ | ✓ | accepted | scheduled | scheduled | Service has been scheduled | filler |
| ✓ | ✓ | cancelled | claimed-cancel | claimed cancel | Diagnostic request has been claimed by an alternative filler | placer |
| ✓ | ✓ | cancelled | user-cancelled-request | user cancelled request | Diagnostic request had been cancelled by the placer | placer |
| ✓ | ✓ | cancelled | cancel-handled | cancel handled | Cancellation has been handled by the filler | filler |
| ✓ | ✓ | rejected | invalid-request-data | invalid request data | Rejected fulfilment due to an issue with the request data | filler |
| ✓ | ✓ | rejected | inaccessible-request-data | inaccessible request data | Rejected fulfilment due to data being unavailable | filler |
| ✓ | ✓ | in-progress | preliminary | preliminary | Preliminary result completed | filler |
| ✓ | ✓ | completed | authorised | authorised | Authorised report created | filler |
| ✓ | ✓ | completed | addendum | addendum | Addendum created for reporting | filler |
| ✓ |   | in-progress | collected | collected | Specimen has been collected in lab collection centre | filler |
| ✓ |   | in-progress | in-lab | in-lab | Specimen is being processed in the pathology lab | filler |
|   | ✓ | accepted | checked-in | checked-in | Patient has checked in for service | filler |
|   | ✓ | in-progress | preparation | preparation | Patient has been prepared for the radiology service | filler |
|   | ✓ | in-progress | acquisition | acquisition | Image has been acquired at radiology service | filler |
|   | ✓ | in-progress | interpretation | interpretation | Image has been interpreted at radiology service | filler |

##### Task Output

We currently define two types of output:

* a `DiagnosticReport` reference to an [imaging report](StructureDefinition-gs-radiology-report.md) or a [pathology report](StructureDefinition-gs-pathology-report.md).
* a `BookingSlot` reference allowing for booking/appointment information to be shared back to the placer using [a profile](StructureDefinition-eorders-booking-slot.md) of the FHIR [slot](https://hl7.org/fhir/R4/slot.html). The `Slot` contains timing information and references a [Schedule](StructureDefinition-eorders-booking-schedule.md) which references a [HealthcareService](StructureDefinition-eorders-booking-healthcareservice.md) that ultimately references the [Location](StructureDefinition-eorders-booking-location.md) 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 `Task`s using [FHIR Patch (FHIRPath-based)](https://hl7.org/fhir/R4/fhirpatch.html) 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:

| | | |
| :--- | :--- | :--- |
| `type` | code | `add`— add a new element (must not already exist);`replace`— replace an existing element;`delete`— remove a field |
| `path` | string | For`add`: FHIRPath to the parent (e.g.`Task`). For`replace`/`delete`: FHIRPath to the element itself (e.g.`Task.status`). |
| `name` | string | Element name to add (used with`add`only; omitted for`replace`and`delete`) |
| `value` | varies | The new value (used with`add`and`replace`; omitted for`delete`) |

**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](#task-status-and-business-status) table for valid combinations.

See the FHIR transaction PATCH Bundle [example 1](Bundle-EOrdersStatusPatchBundle1.md) (set status to received, remove businessStatus and statusReason) and [example 2](Bundle-EOrdersStatusPatchBundle2.md) (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](OperationDefinition-EOrderClaimOperation.md) for the full specification.

##### Parameters

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| in | requisition | Identifier | 1..1 | The group identifier for the request, typically the barcode. |
| in | organization | Reference([GSOrganization](StructureDefinition-gs-organization.md)) | 1..1 | Reference to the brand Organization claiming the request. |
| out | groupTask | Reference([EOrdersTaskFulfillmentGroup](StructureDefinition-eorders-task-fulfillment-group.md)) | 0..1 | Reference to the group Task assigned to the claiming organization. Present when result is`ok`,`fulfillment-active`, or`already-fulfiller`. |
| out | result | Coding | 1..1 | The result of the claim attempt, bound to the claim result code system. |

##### Result Codes

| | | |
| :--- | :--- | :--- |
| ok | OK | Claim successful; a new fulfillment Task set has been created for the claiming organization. |
| fulfillment-active-elsewhere | Fulfillment is in-progress with another organization | The request is actively being fulfilled by a different organization. |
| fulfillment-active | Fulfillment is in-progress with the provided organization | The provided organization is already actively fulfilling the request. |
| already-fulfiller | Fulfillment is already claimed by the provided organization | The provided organization has already claimed but not yet started fulfillment. |
| fulfillment-cancelled | Fulfillment was cancelled | The fulfillment has been cancelled. |
| requisition-not-found | Requisition Not Found | No request matching the supplied identifier was found. |
| organization-not-found | Organisation Not Found | The referenced Organization could not be resolved. |
| claim-in-progress | Claim is already in progress | A concurrent claim attempt is already underway for this request. |

##### Error Recovery

| | | |
| :--- | :--- | :--- |
| `ok` | Claim succeeded | Proceed with fulfilment using the returned`groupTask`. |
| `fulfillment-active` | Your organisation is already fulfilling this order | No action needed — retrieve your existing group`Task`and continue. |
| `already-fulfiller` | Your organisation has already claimed but not started | No action needed — retrieve your existing group`Task`and continue. |
| `fulfillment-active-elsewhere` | Another organisation is actively fulfilling the order | The order cannot be claimed. Inform the patient and clinician as appropriate. |
| `fulfillment-cancelled` | The fulfilment was cancelled | The order is no longer active. No further action. |
| `requisition-not-found` | No matching order found | Verify the barcode/requisition identifier and retry. If persistent, contact the placer. |
| `organization-not-found` | The supplied Organisation reference cannot be resolved | Verify the Organisation is registered in the FHIR server and retry. |
| `claim-in-progress` | A concurrent claim attempt is underway | Wait briefly and retry — the server is processing another claim for the same order. |

##### 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](OperationDefinition-EOrderViewOperation.md) for the full specification.

##### Parameters

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| in | requisition | Identifier | 1..1 | The group identifier for the request, typically the barcode. |
| out | error | string | 0..1 | An error message if the request could not be viewed. Mutually exclusive with`bundle`and`providerHistory`. |
| out | bundle | Bundle | 0..1 | The order specification. Present on success. |
| out | providerHistory | (part) | 0..1 | Fulfilment history grouped by filler. Contains one`organizationTaskGroup`part per filler, each with an`organizationName`(string) and`groupTask`(Task). |

##### 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](Parameters-view-example-response.md) 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"
    }
  ]
}

```

