Magentus Practice Management FHIR Implementation Guide
1.2.60 - ci-build Australia flag

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

OperationDefinition: Diagnostic Request Claim Operation

Official URL: http://fhir.geniesolutions.io/OperationDefinition/EOrderClaimOperation Version: 1.2.60
Active as of 2026-04-03 Computable Name: EOrderClaimOperation

This operation is used to claim a request based on a scanned barcode and returns a group Task reference. An Organization reference is also supplied so that a particular brand of service may be required for the transfer of the request.

The transferred request will result in the creation of a new set of Tasks, including a group Task and child Tasks, each of which will be placed in a requested status. To distinguish a request that has been claimed, the businessStatus of the Tasks will be set to claimed-request and a tag will be set to the same claimed-request value. The reason for the tag is that the businessStatus will change over time but the tag is persistent between resource versions.

The original Task will be placed in a cancelled status and the businessStatus will be set to claimed-cancel. To prevent re-discovering Cancelled tasks, the original filler should set the businessStatus to cancel-handled and when searching for new requested or cancelled tasks, explicitly exclude those that have already been handled via the businessStatus.

The operation will return a Coding value that indicates the result of the claim attempt. If the claim is successful, the group Task reference will be returned. If the claim is unsuccessful, an error code will be returned.

URL: [base]/Task/$claim

Parameters

UseNameScopeCardinalityTypeBindingDocumentation
INrequisition1..1Identifier

The group identifier for the request, typically the barcode.

INorganization1..1Reference (Genie Organization)

Reference to the branded organization claiming the request.

OUTgroupTask0..1Reference (EOrders Task Fulfillment Request Group)

Returns a reference to the group Task assigned to the requesting organisation or nothing if an error occurred.

OUTresult1..1CodingRequest Claim Result Type ValueSet (Required)

The result of the attempting request claim.

Notes:

  • The server MUST enforce authentication and authorisation before processing this operation. Callers that are not authenticated or not authorised to claim requests MUST receive a 401 Unauthorized or 403 Forbidden response respectively.
  • The groupTask output is returned for result codes ok, fulfillment-active, and already-fulfiller.
  • The result Coding indicates the outcome of the claim attempt.

Parameters

Direction Name Type Card. Description
in requisition Identifier 1..1 The group identifier for the request, typically the barcode.
in organization Reference(GSOrganization) 1..1 Reference to the brand Organization claiming the request.
out groupTask Reference(EOrdersTaskFulfillmentGroup) 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

Code Display Description
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.

Example Response

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "groupTask",
      "valueReference": {
        "reference": "Task/b1c3d456-e789-4abc-def0-123456789abc"
      }
    },
    {
      "name": "result",
      "valueCoding": {
        "system": "http://fhir.geniesolutions.io/CodeSystem/eorder-claim-result-type-codesystem",
        "code": "ok",
        "display": "OK"
      }
    }
  ]
}