# Diagnostic Request Claim Operation - Magentus Practice Management FHIR Implementation Guide v1.2.60

* [**Table of Contents**](toc.md)
* [**Artifacts Summary**](artifacts.md)
* **Diagnostic Request Claim Operation**

## 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 `Task`s, including a group `Task` and child `Task`s, each of which will be placed in a `requested` status. To distinguish a request that has been claimed, the `businessStatus` of the `Task`s 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. 

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

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| 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

| | | |
| :--- | :--- | :--- |
| 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"
      }
    }
  ]
}

```



## Resource Content

```json
{
  "resourceType" : "OperationDefinition",
  "id" : "EOrderClaimOperation",
  "url" : "http://fhir.geniesolutions.io/OperationDefinition/EOrderClaimOperation",
  "version" : "1.2.60",
  "name" : "EOrderClaimOperation",
  "title" : "Diagnostic Request Claim Operation",
  "status" : "active",
  "kind" : "operation",
  "date" : "2026-04-03",
  "publisher" : "Magentus Practice Management",
  "contact" : [{
    "name" : "Magentus Practice Management",
    "telecom" : [{
      "system" : "url",
      "value" : "https://www.magentus.com/practice-management"
    },
    {
      "system" : "email",
      "value" : "andy.bond@magentus.com"
    }]
  },
  {
    "name" : "Magentus Practice Management",
    "telecom" : [{
      "system" : "url",
      "value" : "https://www.magentus.com/practice-management",
      "use" : "work"
    }]
  }],
  "description" : "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.\n\nThe transferred request will result in the creation of a new set of `Task`s, including a group `Task` and child `Task`s, each of which will be placed in a `requested` status.  To distinguish a request that has been claimed, the `businessStatus` of the `Task`s 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.  \n\nThe 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`.\n\nThe 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.",
  "jurisdiction" : [{
    "coding" : [{
      "system" : "urn:iso:std:iso:3166",
      "code" : "AU"
    }]
  }],
  "code" : "claim",
  "resource" : ["Task"],
  "system" : false,
  "type" : true,
  "instance" : false,
  "parameter" : [{
    "name" : "requisition",
    "use" : "in",
    "min" : 1,
    "max" : "1",
    "documentation" : "The group identifier for the request, typically the barcode.",
    "type" : "Identifier"
  },
  {
    "name" : "organization",
    "use" : "in",
    "min" : 1,
    "max" : "1",
    "documentation" : "Reference to the branded organization claiming the request.",
    "type" : "Reference",
    "targetProfile" : ["http://fhir.geniesolutions.io/StructureDefinition/gs-organization"]
  },
  {
    "name" : "groupTask",
    "use" : "out",
    "min" : 0,
    "max" : "1",
    "documentation" : "Returns a reference to the group `Task` assigned to the requesting organisation or nothing if an error occurred.",
    "type" : "Reference",
    "targetProfile" : ["http://fhir.geniesolutions.io/StructureDefinition/eorders-task-fulfillment-group"]
  },
  {
    "name" : "result",
    "use" : "out",
    "min" : 1,
    "max" : "1",
    "documentation" : "The result of the attempting request claim.",
    "type" : "Coding",
    "binding" : {
      "strength" : "required",
      "valueSet" : "http://fhir.geniesolutions.io/ValueSet/eorder-claim-result-type-valueset"
    }
  }]
}

```
