Azure Fhir Developer

Required Fields by Resource

Coding Systems

LOINC (Logical Observation Identifiers Names and Codes)

System URL: http://loinc.org

Use for: Laboratory observations, vital signs, clinical documents

Example:

{
  "coding": [{
    "system": "http://loinc.org",
    "code": "8867-4",
    "display": "Heart rate"
  }]
}

SNOMED CT (Systematized Nomenclature of Medicine)

System URL: http://snomed.info/sct

Use for: Clinical findings, procedures, body structures, organisms

Example:

{
  "coding": [{
    "system": "http://snomed.info/sct",
    "code": "73211009",
    "display": "Diabetes mellitus"
  }]
}

RxNorm (Normalized Drug Names)

System URL: http://www.nlm.nih.gov/research/umls/rxnorm

Use for: Medications, drug ingredients, brand names

ICD-10-CM (International Classification of Diseases)

System URL: http://hl7.org/fhir/sid/icd-10-cm

Use for: Diagnoses (billing/administrative)

Azure Authentication Patterns

SMART on FHIR (Patient-Facing Apps)

// Configure MSAL for SMART on FHIR
const msalConfig = {
  auth: {
    clientId: process.env.CLIENT_ID,
    authority: `https://login.microsoftonline.com/${process.env.TENANT_ID}`,
    redirectUri: process.env.REDIRECT_URI
  }
};

// Request FHIR scopes
const loginRequest = {
  scopes: [
    `${process.env.FHIR_URL}/.default`,
    'openid',
    'profile',
    'launch/patient'
  ]
};

Managed Identity (Backend Services)

import { DefaultAzureCredential } from '@azure/identity';

const credential = new DefaultAzureCredential();
const token = await credential.getToken(
  `${process.env.FHIR_URL}/.default`
);

const response = await fetch(`${process.env.FHIR_URL}/Patient`, {
  headers: {
    'Authorization': `Bearer ${token.token}`,
    'Content-Type': 'application/fhir+json'
  }
});

Service Principal

# Get token via Azure CLI
az account get-access-token \
  --resource https://{workspace}-{fhir-service}.fhir.azurehealthcareapis.com \
  --query accessToken -o tsv

Pydantic v2 Patterns

Patient Model

from pydantic import BaseModel, Field
from typing import Optional, List
from datetime import date

class HumanName(BaseModel):
    use: Optional[str] = None
    family: Optional[str] = None
    given: Optional[List[str]] = None

class Identifier(BaseModel):
    system: Optional[str] = None
    value: Optional[str] = None

class Patient(BaseModel):
    resourceType: str = Field(default="Patient", frozen=True)
    id: Optional[str] = None
    identifier: Optional[List[Identifier]] = None
    active: Optional[bool] = True
    name: Optional[List[HumanName]] = None
    gender: Optional[str] = None
    birthDate: Optional[date] = None

    model_config = {
        "populate_by_name": True,
        "json_schema_extra": {
            "example": {
                "resourceType": "Patient",
                "identifier": [{"system": "http://example.org", "value": "12345"}],
                "name": [{"family": "Smith", "given": ["John"]}],
                "gender": "male",
                "birthDate": "1970-01-01"
            }
        }
    }

Observation Model

class Coding(BaseModel):
    system: Optional[str] = None
    code: Optional[str] = None
    display: Optional[str] = None

class CodeableConcept(BaseModel):
    coding: Optional[List[Coding]] = None
    text: Optional[str] = None

class Quantity(BaseModel):
    value: Optional[float] = None
    unit: Optional[str] = None
    system: Optional[str] = Field(default="http://unitsofmeasure.org")
    code: Optional[str] = None

class Reference(BaseModel):
    reference: Optional[str] = None
    display: Optional[str] = None

class Observation(BaseModel):
    resourceType: str = Field(default="Observation", frozen=True)
    id: Optional[str] = None
    status: str  # required
    code: CodeableConcept  # required
    subject: Reference  # required
    effectiveDateTime: Optional[str] = None
    valueQuantity: Optional[Quantity] = None
    valueCodeableConcept: Optional[CodeableConcept] = None

Validation Patterns

Profile Validation

POST https://{fhir-server}.azurehealthcareapis.com/Patient/$validate
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "resource",
    "resource": {
      "resourceType": "Patient",
      "name": [{"family": "Smith"}]
    }
  }]
}

Bundle Validation

POST https://{fhir-server}.azurehealthcareapis.com
Content-Type: application/fhir+json

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:patient-1",
      "resource": {
        "resourceType": "Patient",
        "name": [{"family": "Smith"}]
      },
      "request": {
        "method": "POST",
        "url": "Patient"
      }
    }
  ]
}

Search Parameters

Common Search Modifiers

Date Search Prefixes

Common Search Patterns

# Search patients by name and birthdate
GET /Patient?name=Smith&birthdate=1970-01-01

# Search observations by patient and code
GET /Observation?patient=Patient/123&code=http://loinc.org|8867-4

# Include related resources
GET /Patient?_id=123&_include=Patient:organization

# Reverse include
GET /Patient?_id=123&_revinclude=Observation:patient

# Paginated search
GET /Patient?_count=50&_offset=100

Bulk Data Operations

System Export

GET https://{fhir-server}.azurehealthcareapis.com/$export
Accept: application/fhir+json
Prefer: respond-async

# Response: 202 Accepted
# Content-Location: https://{fhir-server}/_operations/export/{job-id}

Export Status Check

GET https://{fhir-server}/_operations/export/{job-id}

# When complete (200 OK):
{
  "transactionTime": "2024-01-15T12:00:00Z",
  "request": "https://{fhir-server}/$export",
  "output": [
    {
      "type": "Patient",
      "url": "https://storage.blob.core.windows.net/export/Patient.ndjson"
    }
  ]
}

Azure-Specific Features

Private Link Configuration

az network private-endpoint create \
  --name pe-fhir \
  --resource-group myRG \
  --vnet-name myVNet \
  --subnet default \
  --private-connection-resource-id $(az healthcareapis workspace show \
    --name myWorkspace --resource-group myRG --query id -o tsv) \
  --group-id fhir \
  --connection-name fhir-connection

Diagnostic Logging

az monitor diagnostic-settings create \
  --name fhir-diagnostics \
  --resource $(az healthcareapis workspace fhir-service show \
    --name myFhir --workspace-name myWorkspace --resource-group myRG \
    --query id -o tsv) \
  --logs '[{"category": "AuditLogs", "enabled": true}]' \
  --workspace $(az monitor log-analytics workspace show \
    --name myLAWorkspace --resource-group myRG --query id -o tsv)

References

For detailed documentation, see:

• references/fhir-r4-resources.md - Complete resource reference
• references/azure-fhir-api.md - Azure API specifics
• references/smart-auth.md - SMART on FHIR authentication
• references/pagination.md - Pagination patterns
• references/bundles.md - Transaction and batch bundles