Skip to main content

Extended Operations

Overview​

The General Purpose FHIR R4 API includes support for extended operations that provide functionality beyond the standard HL7 FHIR specification. These operations enable specialized workflows, data management tasks, and integration patterns specific to healthcare information systems.

Before implementing any operation, validate current capabilities by retrieving the CapabilityStatement:

GET {base-url}/metadata

Check the operation elements within resource definitions and server-level operations for supported functionality.

Operations Schema​

Extended operations follow FHIR operation patterns:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "{parameter-name}",
      "value[Type]": "{parameter-value}"
    }
  ]
}

Server-Level Operations​

Operations that apply to the entire FHIR server:

Process Message Operation​

Endpoint: POST {base-url}/$process-message

Purpose: Process FHIR messages for asynchronous communication

Documentation: Process Message Operation

Type-Level Operations​

Operations that apply to specific resource types:

Multi-Resource Operations​

Relay Operations​

Operations that route requests to external FHIR servers:

  • Create Relay - POST {base-url}/{ResourceType}/$create-relay
  • Read Relay - GET {base-url}/{ResourceType}/$read-relay
  • Search Relay - GET {base-url}/{ResourceType}/$search-relay
  • Update Relay - PUT {base-url}/{ResourceType}/$update-relay

Composition Operations​

Medicolegal Death Investigation (MDI)​

  • Search MDI - GET {base-url}/Composition/$search-mdi

    • Purpose: Retrieve medicolegal death investigation documents
    • Use case: Forensic and legal documentation workflows

  • Update MDI - POST {base-url}/Composition/$update-mdi

    • Purpose: Update active medicolegal death investigation cases
    • Use case: Case management and status updates

Patient Operations​

Identity Management​

CareRecord-Specific Operations​

  • Patient Assign MRN - POST {base-url}/Patient/{id}/$assign-mrn
    • Purpose: Assign permanent MRN to Call Intake patients
    • Supported: myAvatar CareRecord

Instance-Level Operations​

Operations that apply to specific resource instances:

Patient Instance Operations​

  • Patient Service History - GET {base-url}/Patient/{id}/$service-history
    • Purpose: Retrieve historical versions and service records
    • Status: Experimental

Examples​

Basic Operation Request​

# Production
curl -X POST 'https://fhir.netsmartcloud.com/v4/Patient/$match' \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/fhir+json" \
  -d @parameters.json

# Preview
curl -X POST 'https://fhirtest.netsmartcloud.com/v4/Patient/$match' \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/fhir+json" \
  -d @parameters.json

Integration Patterns​

Operation Discovery​

  1. Check CapabilityStatement

    • Verify operation availability
    • Review required parameters
    • Validate authorization requirements

  2. Parameter Validation

    • Use Parameters resource format
    • Include all required parameters
    • Follow parameter type specifications

  3. Response Processing

    • Handle operation-specific return types
    • Process OperationOutcome messages
    • Extract relevant data from results

Error Handling​

  • Validate parameters before submission
  • Handle operation-specific error codes
  • Implement appropriate retry logic
  • Monitor OperationOutcome details

Relationships to Other Resources​

  • CapabilityStatement - Operation discovery
  • Parameters Resource - Operation input/output format
  • OperationOutcome Resource - Error and status reporting
  • FHIR Messaging - Process Message operation

Error Handling​

For comprehensive error handling information, see Common Errors.

Support​

For technical support with extended operations:

  • Contact: Netsmart Technologies, Inc.
  • Documentation: Individual operation documentation pages
  • Validation: Use CapabilityStatement for current operation support