Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Preview Merge


This is a call to the operation (with preview=true) that simply checks for potential errors and warnings, without committing any changes.

This may not be able to capture all possible causes of errors that could be encountered during the processing of the data patching.

The returned Patient resource is a preview only and has not been committed. Hence the version number and last_modified date would be different.

Initiate Merge

This stage processes the input parameters checking for errors/warnings and begins the changes to the patient resources.

If the system is able to complete the processing of all reference data to the target patient, then it may be complete and no task is required. Otherwise a task Task for tracking would be created and monitor the progress of the merge.

Data Processing

The rest operation may have returned, and processing is ongoing to patch any other resource that references the source patient to reference the target patient.

This may take a considerable period of time in some systems where the volume of records being updated is large.

Completed (or failed)All data processing is complete, and the Task is marked as completed (maybe with errors)


Merging Identifiers

If the result patient resource is provided in the parameters to the operation, then it is assumed that the caller has correctly included all the required identifiers desired to be in the target patient (though must include the identifiers specified in the input parameters).

If the result patient resource is not provided (only the identifier/reference to select it), then the values provided in the request parameters (source-patient.identifier and all source-patient-identifiers) will be copied into the target resource and marked as old.(Review if the marking of old still makes sense here for ALL provided identifiers that get copied across when the result patient isn't there)

The server may also migrate other identifiers (and properties) at its discretion, and choose to mark these as old or not.


Note: Some resources that have been updated as a result of the merge, such as AuditEvent, Provenance, may have been digitally signed, and this change would invalidate the signature. There may be other reasons impacting the updates that should be considered, further feedback on this specific use case is required.

Review Note: Are there other implications of these reference updates that should be identified relating to versions - (such as where a version specific reference was included)

Post Merge Expectations

Once the patient resources have been merged:


Answer: As this operation is not idempotent it is only defined for POST.------ up to here ------ 

Question: How should privacy related meta tags be handled?

Answer: When reconciling 2 patient resources to be merged, any security or privacy related tags should be included in the resulting target resource with the most sensitive values survivingremaining.

Question: Should a Task resource be included to track things that might take longer to process? Yes.

Question: Answer: Yes, the task resource can be used to track the asynchronous portions.

Question: Should we be explicit about how the identifiers from the source resource should be copied into the target resource (and if they should be marked with use=old), the ?

Answer: (As detailed in the merging identifiers section above - there are still questions on this to check if adequate detail) The system will not be expected to make these decisions in the operation, the caller of the operation will make those decisions, which are defined in the result-patient resource. For a case where this was an old MRN, we recommend that these also remain in the target resource so that if content comes in (such as a lab result) with the old MRN on it, then it can be attached to the appropriate.Question: What should happen if the 2 patient resources are already merged, an error code?.

Question: What should happen if the 2 patient resources are already merged, an error code?

Answer: This would return an error as noted.

Patient A merged into Patient B (success)

Then try to merge Patient B into Patient A?

using MRN identifiers - same resource is detected - return error "err: Same resource"

using the patient IDs - the source A has been deleted, but the B resource will have the link ID, and a provenance - return error "err: Target patient already merged"

using the patient IDs - the source A marked as merged into B and has links between each other, and and a provenance - return error "err: Target patient already merged"

Try to merge Patient A into Patient B again?

this will always return the error "err: Same resource"

Question: Should the merge operation update/correct/change all the resources that reference the patient to link to the resulting patient resource. E.g. Any Observations referencing Patient/01 will be changed to Patient/02

Answer: Yes, as noted above.

Question: Provenance/AuditEvent actions - any security issues here?

Answer: After some discussion, the Provenance is the preferred resource to track this content, as will likely remain with the clinical data retention, however the AuditEvents may be cleansed periodically. AuditEvents are not always available/exposed to all users.

Question: Will the spec also describe an $unmerge style operation, or will that be essentially a manual activity on the API using the Provenance/AuditEvents to determine context.

Answer: yes this will be documented, but not initially. This was not successful in v2.

------ up to here ------ 

Question: Should the updating process be able to be performed synchronously, or async? - Prefer to support Async given the potential duration the processing could take for some long term records


IssueDescriptionHttp Status
err: Same resourceThe Source and Target matching resulted in the same FHIR Patient resource, likely already merged.Bad Request
err: Missing Source ParametersThere are no source patient parameters, please include either a source-patient, source-patient-identifier parameter (or both)Bad Request
err: Missing Target ParametersThere are no target patient parameters, please include either a target-patient, target-patient-identifier parameter (or both)Bad Request
err: Target Patient Id mismatch

The target patient id does not match the patient id in the result-patient resource

(should we permit this to create a new resource?)

Bad Request
err: Source Patient not foundThe source patient was not found based on the provided parametersBad Request
err: Target Patient not foundThe target patient was not found based on the provided parametersBad Request
err: Target/Source not duplicates

Attempt to merge 2 records that are known to not be duplicates of each other.

(Previous manual marking of the resources was done, and will need to be removed before retrying)

422 Unprocessable Entity
err: Target patient already mergedThe Target patient resource was previously merged into another patient record, and is not a suitable target for merging.422 Unprocessable Entity
err: Target patient inactiveThe Target patient resource is marked as inactiveBad Request
info: Target Patient updatedAdditional notes on what happened to the target patient resource on update, such as if fields weren't updated as requested due to internal business rules etc422 Unprocessable Entity
info: Update summaryOther notes that are included reporting on what changed, such as how many resources were/may be effected
warn: Recommend reverse mergeThe source resource is much larger than the target resource (in terms of resources that reference it) and recommend that the merge occur in the other direction