Patient Assign Permanent MRN Operation

Draft

This is draft documentation for proposed functionality.

OPERATION: POST [base]/Patient/$assign-mrn

The Patient Assign Permanent MRN operation is used with the myAvatar CareRecord to assign a permanent medical record number (MRN) to a Call Intake Patient.

The operation is designed to follow the pattern of the Patient Merge operation.

Workflow

This extended operation is part of a larger workflow supporting the transition of myAvatar Call Intake Patients to standard Patients (with permanent MRNs).

Authorization

This operation will require the application obtain authorization to update a Patient using one of the following SMART clinical scopes.

• v1: [patient|user|system]/Patient.[write|*]
• v2: [patient|user|system]/Patient.[u] (future)

Parameters

Use	Name	Cardinality	Type	Documentation
IN	source-patient	1..1	Reference	The current temporary ID assigned to a Call Intake Patient.
IN	target-patient	0..1	Reference	The desired permanent ID to assign to a Call Intake Patient. If excluded a permanent ID will be auto-assigned.
OUT	result-patient	0..1	Reference	The resulting permanent ID assigned to a Call Intake Patient. If target-patient supplied these will match.
OUT	outcome	1..1	OperationOutcome	The outcome of the operation. On success this will provide a success statement or warnings related to the change. If the operation was unsuccessful, the OperationOutcome will include the reason for the failure.

Examples

Production

curl -X POST 'https://fhir.netsmartcloud.com/v4/Patient/$assign-mrn' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d @payload.json

Preview

curl -X POST 'https://fhirtest.netsmartcloud.com/v4/Patient/$assign-mrn' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d @payload.json

Payloads

Sample Assign Permanent MRN Payload

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "source-patient",
            "valueReference": {
              "reference": "Patient/1"
            }
        },
        // optional: a permanent MRN will be auto-assigned if not set
        {
            "name": "target-patient",
            "valueReference": {
              "reference": "Patient/2"
            }
        }
    ]
}

Sample Assign Permanent MRN Response Payloads

Assign Permanent MRN Success

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-patient",
      "valueReference": {
        "reference": "Patient/1"
      }
    },
    // if provided
    {
      "name": "target-patient",
      "valueReference": {
         "reference": "Patient/2"
      }
    },
    // outcome of request
    {
      "name": "result-patient",
      "valueReference": {
         "reference": "Patient/2"
      }
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "code": "informational",
            "details": {
              "text": "Success message"
            }
          }
        ]
      }
    }
  ]
}

Invalid Assign Permanent MRN Payload or Other Unprocessable Request

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "details": {
        "text": "Exception message"
      }
    }
  ]
}

Rejections or Other Assign Permanent MRN Processing Errors

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-patient",
      "valueReference": {
        "reference": "Patient/1"
      }
    },
    {
      "name": "target-patient",
      "valueReference": {
         "reference": "Patient/2"
      }
    },
    {
      "name": "preview",
      "valueBoolean": false
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "error",
            "code": "processing",
            "details": {
              "text": "status note"
            }
          }
        ]
      }
    }
  ]
}

Errors

Errors will be reported within an OperationOutcome and could include:

Issue	Description	HTTP Status
T.B.D.	The Source Patient was not found based on the provided parameters.	400 Bad Request
T.B.D.	The Source Patient has already been assigned a permanent MRN.	400 Bad Request
T.B.D.	The Target Patient ID was not accepted. E.g., unsupported value or syntax.	400 Bad Request

Integration Patterns

MRN Assignment Workflow

1. Create Call Intake Patient

   • Submit Basic resource for call intake
   • Receive temporary patient ID
   • Update demographics as needed

2. Prepare for Admission

   • Validate patient information
   • Determine if specific MRN needed
   • Prepare assignment parameters

3. Assign Permanent MRN

   • Submit assign-mrn operation
   • Handle response and new ID
   • Update system references

Best Practices

• Validate call intake patient exists before assignment
• Use auto-assignment unless specific MRN required
• Update all related resources with new patient ID
• Implement proper error handling for conflicts

Relationships to Other Resources

• Patient Resource - Patient data structure
• Basic Resource - Call intake representation
• Patient Merge Operation - Related patient operations
• OperationOutcome Resource - Operation results

Error Handling

For comprehensive error handling information, see Common Errors.

Support

For technical support with Patient Assign MRN operations:

• Contact: Netsmart Technologies, Inc.
• Documentation: Extended Operations
• CareRecord: myAvatar specific functionality