Unlink operation

The $unlink operation reverses a previous $link. Supply a reverse transaction Bundle, usually deleting the profiled Linkage. MDMbox validates the original link Task, adds audit records, sets its status to unlinked, and commits all changes atomically.

Use $unlink when a link cluster was created by mistake or when a client needs to remove records from an MDMbox-managed Linkage.

How it works

1. Find the original link Task and build a reverse transaction Bundle.
2. Send the Task reference and reverse plan to $unlink.
3. MDMbox adds audit records, marks the original Task unlinked, and commits or rolls back the transaction as a whole.

Request

POST https://<mdmbox-host>/api/fhir/$unlink
Content-Type: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "task", "valueReference": { "reference": "Task/link-task-123" } },
    { "name": "preview", "valueBoolean": false },
    {
      "name": "plan",
      "resource": {
        "resourceType": "Bundle",
        "type": "transaction",
        "entry": [
          {
            "request": {
              "method": "DELETE",
              "url": "Linkage/linkage-456",
              "ifMatch": "W/\"3\""
            }
          }
        ]
      }
    }
  ]
}

Parameters

Plan Bundle

The plan is a standard FHIR transaction Bundle. It usually contains a DELETE entry for the Linkage, because the MDM Linkage profile represents active clusters and MDMbox preserves history through the FHIR history API.

Allowed plan methods are PUT, POST, and DELETE. The plan must not contain duplicate PUT or DELETE URLs.

Use ifMatch for optimistic locking. If the Linkage or another resource changed after the client built the reverse plan, the transaction rolls back and $unlink returns 422 Unprocessable Entity with an OperationOutcome code such as conflict.

Preview mode

Set preview to true to validate the request and inspect the assembled transaction without writing anything:

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "task", "valueReference": { "reference": "Task/link-task-123" } },
    { "name": "preview", "valueBoolean": true },
    {
      "name": "plan",
      "resource": {
        "resourceType": "Bundle",
        "type": "transaction",
        "entry": [
          { "request": { "method": "DELETE", "url": "Linkage/linkage-456" } }
        ]
      }
    }
  ]
}

Preview response:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [{ "severity": "information", "code": "informational" }]
      }
    },
    {
      "name": "bundle",
      "resource": {
        "resourceType": "Bundle",
        "type": "transaction",
        "entry": ["... assembled entries including audit resources ..."]
      }
    }
  ]
}

Response

On success, the response is a Parameters resource containing:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [{ "severity": "information", "code": "informational" }]
      }
    },
    {
      "name": "input-parameters",
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          {
            "name": "task",
            "valueReference": { "reference": "Task/link-task-123" }
          },
          { "name": "preview", "valueBoolean": false }
        ]
      }
    },
    {
      "name": "task",
      "resource": {
        "resourceType": "Task",
        "id": "generated-unlink-task-id",
        "status": "completed",
        "intent": "order",
        "code": { "coding": [{ "code": "unlink" }] },
        "businessStatus": { "coding": [{ "code": "completed" }] },
        "basedOn": [{ "reference": "Task/link-task-123" }]
      }
    }
  ]
}

The input-parameters echo omits the potentially large plan parameter.

Audit trail

Every executed unlink creates or updates these resources in the same transaction:

Unlink Task

• code - unlink
• businessStatus - completed
• basedOn - the original link Task
• input[] - copied from the original link Task when present

Original link Task

• businessStatus changes from linked to unlinked
• updated with ifMatch using the Task version read during validation

Provenance

• activity - unlink from http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle
• target - every reverse-plan target plus the unlink Task
• entity[] - versioned references to pre-unlink revisions when available
• agent - Device/mdmbox

AuditEvent records the initiating user or client when available, outcome, service, correlation, and references to the original link Task, new unlink Task, Provenance, and domain resources. If this event cannot be written, the reversal rolls back. See Audit for failure and preview behavior.

After the reverse plan removes their existing cluster membership, the records can be linked again. The original link Task remains in the audit history with businessStatus=unlinked.

Validation

MDMbox validates the unlink request before execution:

Structural validation (400 Bad Request):

• Request body must be a FHIR Parameters resource
• task is required
• plan must be a transaction Bundle with at least one entry
• Plan methods must be PUT, POST, or DELETE
• No duplicate PUT or DELETE URLs in the plan

State validation (422 Unprocessable Entity):

• The referenced Task must exist
• The Task must be a link Task (code=link)
• The link Task must still be active (businessStatus=linked)

FHIR transaction validation (422 or 500):

• If any transaction entry fails validation or optimistic locking, the whole transaction rolls back
• Client-side transaction failures return 422 with an OperationOutcome
• Server-side transaction failures return 500

See also