CPAR <--> FHIR Mapping Details¶

Overview¶

The Central Patient Attachment Registry (CPAR) is a provincial initiative by Alberta Health Services (AHS) that supports structured reporting of patient-to-provider attachment. This enables longitudinal tracking of care relationships in primary care.

Polaris provides a FHIR-based representation of CPAR data across heterogeneous EMR platforms. This includes data extraction, canonical mapping to FHIR resources and extensions, and submission workflow tracking.

PolarisCoreRosterPanel (modelled as Group; CPAR Panel)¶

FHIR Profile: PolarisCoreRosterPanel.fsh
Example File: PolarisCoreRosterPanel-example.json
Identifier System Canonical URL:
https://fhir.apps.health/cpar/NamingSystem/cpar-panel-number

Roster Panel Modelling Approach¶

In this approach, the panel is modeled as a Group resource that captures:

The panel number in the identifier
Provider and facility information are captured via simple, repeating extensions on Group.
- These extensions use a valueReference whose identifier element is used to store the ID (and type) information; the reference field is left in place for potential future linking.
The automated submissions flag is also stored as an extension.
Marking a panel to be submitted during the next submission window is stored as an extension.

Patient details (demographics and identifiers) are stored in the Patient resource, and each panel member (with confirmation and last-visit dates) is referenced in Group.member.

All custom extension URLs use the base canonical URL https://fhir.apps.health/and are defined with hyphen-separated names.

Mapped Fields¶

S8_Panel_Number
- Group.identifier
  - system = https://fhir.apps.health/cpar/NamingSystem/cpar-panel-number
  - value = 10-digit numeric panel ID
Automated Submissions Flag
- Extension: https://fhir.apps.health/cpar/StructureDefinition/automated-submission-extension
- valueBoolean
Submit During Next Window Flag
- Extension: https://fhir.apps.health/cpar/StructureDefinition/submit-during-next-window-extension
- valueBoolean
Organization Reference
- Group.managingEntity.identifier
  - system = https://fhir.apps.health/NamingSystem/organization-identifier
  - value = Organization ID from AppState
Primary Provider (ID and Type)
- Extension: https://fhir.apps.health/cpar/StructureDefinition/primary-providers-extension
- valueReference.identifier:
  - system = https://fhir.infoway-inforoute.ca/NamingSystem/ca-ab-practitioner-id-ahcip
    - (this canonical is for PRACID provider type, please refer here for other canonical urls)
  - value = B1_Provider_Identifier
  - type = CodeableConcept.text = B2_Provider_Identifier_Type
  - reference = should be linked to the EMR-provided Practitioner resource
  - A repeating (1..*) extension that captures each provider’s identifier and type.
Facility (ID and Type)
- Extension: https://fhir.apps.health/cpar/StructureDefinition/panel-facilities-extension
- valueReference.identifier:
  - system = https://www.alberta.ca/fhir/NamingSystem/ca-ab-facility-id-billing
  - value = S10_Facility_ID
  - type = CodeableConcept.text = S13_Facility_ID_Type
  - reference = (optional, left for future linking to Location/Org. resource)
  - A repeating (0..*) extension that points (via a reference) to a Location resource while primarily using the identifier element.
Patient Reference (Panel Membership)
- Group.member.entity.reference = Patient resource reference
A11_Confirmation Date (Panel Membership)
- Group.member extension
  - URL: https://fhir.apps.health/cpar/StructureDefinition/panel-confirmation-date-extension
  - valueDate: Confirmatino date (YYYY-MM-DD)

Example¶

{
    "resourceType": "Group",
    "id": "panel-example",
    "type": "person",
    "actual": true,
    "identifier": [
        {
            "system": "https://fhir.apps.health/cpar/NamingSystem/cpar-panel-number",
            "value": "1234567890"
        }
    ],
    "managingEntity": {
        "identifier": {
            "system": "https://fhir.apps.health/NamingSystem/organization-identifier",
            "value": "org-001"
        }
    },
    "extension": [
        {
            "url": "https://fhir.apps.health/cpar/StructureDefinition/automated-submission-extension",
            "valueBoolean": true
        },
        {
            "url": "https://fhir.apps.health/cpar/StructureDefinition/primary-providers-extension ",
            "valueReference": {
                "identifier": {
                    "system": "https://fhir.infoway-inforoute.ca/NamingSystem/ca-ab-practitioner-id-ahcip",
                    "value": "prov001234567",
                    "type": {
                        "text": "PRACID"
                    }
                },
                "reference": "Practitioner/prac-001"
            }
        },
        {
            "url": "https://fhir.apps.health/cpar/StructureDefinition/primary-providers-extension",
            "valueReference": {
                "identifier": {
                    "system": "https://fhir.infoway-inforoute.ca/NamingSystem/ca-ab-practitioner-id-ahcip",
                    "value": "prov009876543",
                    "type": {
                        "text": "HSPID"
                    }
                }
            }
        },
        {
            "url": "https://fhir.apps.health/cpar/StructureDefinition/panel-facilities-extension ",
            "valueReference": {
                "identifier": {
                    "system": "https://www.alberta.ca/fhir/NamingSystem/ca-ab-facility-id-billing",
                    "value": "fac00012345",
                    "type": {
                        "text": "AHWFACID"
                    }
                }
            }
        }
    ],
    "member": [
        {
            "entity": {
                "reference": "Patient/pat-abc"
            },
            "extension": [
                {
                    "url": "https://fhir.apps.health/cpar/StructureDefinition/panel-confirmation-date-extension",
                    "valueDate": "2025-02-01"
                }
            ]
        },
        {
            "entity": {
                "reference": "Patient/pat-def"
            },
            "extension": [
                {
                    "url": "https://fhir.apps.health/cpar/StructureDefinition/panel-confirmation-date-extension",
                    "valueDate": "2025-02-05"
                }
            ]
        }
    ]
}

PolarisCorePatient¶

FHIR Profile: PolarisCorePatient.fsh
Example File: PolarisCorePatient-example.json
Identifier System Canonical URL:
https://fhir.apps.health/NamingSystem/-patient-identifier

Mapped Fields¶

A1_Client_Identifier
- Patient.identifier (two required):
  - Polaris-local patient ID (per EMR instance)
    - system: https://fhir.apps.health/NamingSystem/[product-instance]-patient-identifier
    - value: unique patient identifier from the EMR.
  - Provincial PHN/ULI using Infoway system URL
    - system: https://fhir.infoway-inforoute.ca/NamingSystem/ca-ab-patient-healthcare-id
    - value: Client Identifier (PHN/ULI)
- For the polaris identifier.value: Most EMRs have some concept of a unique identifier representing a patient. So either a primary key or a unique foreign key. Whatever is most natural.
A3_Client_ID_Type
- Patient.identifier.system
- Implicit from identifier.system (e.g., ULI = PHN)
A5_Client_Given_Name
- Patient.name.given
- Client's given name
A6_Client_Last_Name
- Patient.name.family
- Client's family name
A8_Client_Administrative_Gender
- Patient.gender
- Administrative gender for the client: we are only using the base FHIR gender for now (our only data source Juno doesn't support anything else anyway)
A9_Client_Date_Of_Birth
- Patient.birthDate
- Client's date of birth

Example¶

{
    "resourceType": "Patient",
    "id": "pat-abc",
    "identifier": [
        {
            "system": "https://fhir.apps.health/NamingSystem/org-001-patient-identifier",
            "value": "patient1234567890"
        },
        {
            "system": "https://fhir.infoway-inforoute.ca/NamingSystem/ca-ab-patient-healthcare-id",
            "value": "123456789"
        }
    ],
    "managingOrganization": {
        "identifier": {
            "system": "https://fhir.apps.health/NamingSystem/organization-identifier",
            "value": "org-001"
        },
        "display": "Example EMR"
    },
    "name": [
        {
            "family": "test",
            "given": ["test"]
        }
    ],
    "birthDate": "1965-01-01",
    "gender": "male"
}

PolarisCoreAppointment (Last Visit)¶

FHIR Profile: PolarisCoreAppointment.fsh
Example File: PolarisCoreAppointment-example.json
Identifier System Canonical URL:
https://fhir.apps.health/NamingSystem/-appointment-identifier

Mapped Fields¶

Appointment Status
- Appointment.status
- We will be filtering appointments by Appointment.status = fulfilled, denoting the actual visit
- NOTE - not all EMRs support a 'fulfilled' status. In those cases we will only have a 'booked', 'arrived' or 'checked in' status. For those consumers of FHIR data that are depending on this (including CPAR), a reasonable workaround is checking for fulfilled || ((booked || arrived || checked in) && before yesterday)
A12_Last Visit Date
- Appointment.start
Patient Participants
- Appointment.participant = [...]
  - actor.identifier.system = https://fhir.apps.health/NamingSystem/[instance-id]-patient-identifier
  - actor.identifier.value = EMR patient ID
  - status = accepted
  - Indicates the patient involved in the appointment
Provider Participants
- Appointment.participant = [...]
  - actor.identifier.system = https://fhir.apps.health/NamingSystem/[instance-id]-practitioner-identifier
  - actor.identifier.value = EMR provider ID
  - status = accepted

Example¶

{
    "resourceType": "Appointment",
    "identifier": [
        {
            "use": "official",
            "system": "https://fhir.apps.health/NamingSystem/SquirrelNet-Alpha-appointment-identifier",
            "value": "APPT-SQUIRREL-VISIT-AUTUMN-NUT-CHECKUP-009"
        }
    ],
    "status": "fulfilled",
    "start": "2024-10-27T08:15:11Z",
    "participant": [
        {
            "actor": {
                "identifier": {
                    "system": "https://fhir.apps.health/NamingSystem/SquirrelNet-Alpha-patient-identifier",
                    "value": "SQUIRREL-ID-SCRATCHY-11A"
                },
                "display": "Scratchy von Nuttingham III"
            },
            "status": "accepted"
        },
        {
            "actor": {
                "identifier": {
                    "system": "https://fhir.apps.health/NamingSystem/SquirrelNet-Alpha-practitioner-identifier",
                    "value": "DR-FLUFFYTAIL-OAKSPECIALIST"
                },
                "display": "Dr. Fluffytail, Chief Acorn Inspector"
            },
            "status": "accepted"
        }
    ]
}

PolarisCoreOrganization (Submitting Site / Tenant)¶

FHIR Profile: PolarisCoreOrganization.fsh
Example File: PolarisCoreOrganization-example.json
Identifier System Canonical URL:
https://fhir.apps.health/NamingSystem/organization-identifier

Mapped Fields¶

CPAR
- app state: cpar-enabled valueBoolean default false
- feature flag for CPAR
- Polaris - https://well-health.atlassian.net/issues/NEXT-501
S0_Submitting_Site_Identifier
- app state: submitting-site-identifier valueString default ""
- Note: CPAR does also require that a Polaris Organization is generated by the EMR. It needs standard unique Polaris ID with:
  - system: https://fhir.apps.health/NamingSystem/organization-identifier
  - value: A unique String value representing the EMR instance (sometimes referred to as a “clinic” – but that can get confusing when more than one clinic is served by a single EMR instance with multiple Locations)
Polaris - NEXT-407: Configure CPAR Site (UI and Save)
S3_Submitting_Site_Identifier_Type
- Hardcoded to AHWFACID
S1_Submitting_Site_Name
- app state: submitting-site-name valueString default ""
- The site/clinic name - maintained in CPAR app
- Polaris - NEXT-407: Configure CPAR Site (UI and Save)

Modeling Notes¶

The CPAR concept of a tenant (also called submitting site) is modeled using a Polaris Organization resource. One PolarisCoreOrganization instance must exist per EMR tenant, and this is usually the first resource created in the MedPlum store.

However, all metadata required for CPAR submission — including submitting identifier, identifier type, and site name — are maintained in AppState, rather than on the Organization resource itself.

This is by design: for example, Juno does not internally store the AHS-assigned billing identifier (AHSFACID). Since CPAR requires this identifier, it is configured separately and stored in AppState.

Example¶

{
    "resourceType": "Organization",
    "id": "org-site-001",
    "identifier": [
        {
            "system": "https://fhir.apps.health/NamingSystem/organization-identifier",
            "value": "org-001"
        }
    ],
    "name": "Sample Clinic"
}

PolarisDevice (Installed EMR Software)¶

FHIR Profile: PolarisDevice.fsh
Example File: PolarisDevice-example.json
Identifier System Canonical URL:
https://fhir.apps.health/NamingSystem/-device-identifier

Modeling Notes¶

FHIR Device resource can represent the EMR software. One of the requirements raised by the team is to have relationship between the submitting site (Organization) and its EMR system (Device) because the product version is site specific. Device will be created for the EMR and is linked to the Organization via the owner element.

It is not necessary to update the EMR Device version with the latest software version when the EMR tenant receives software updates.

However, there should be no problem if EMRs want to keep this value current. Healthquest sends the current software version each time.

Mapped Fields¶

S2_Submitting_EMR_Vendor_Name
- Device.manufacturer
S3_Submitting_EMR_Product_Name
- Device.deviceName.name (type = "model-name")
S4_Submitting_EMR_Product_Version
- Device.version.value
Device Type
- Device.type.text = "software"
Link to Organization
- Device.owner.reference = Organization/{org-id}

Device version does not need to be updated each submission. EMRs may optionally update it if they wish to keep software versioning current.

Example¶

{
    "resourceType": "Device",
    "id": "device-emr-001",
    "manufacturer": "VendorName",
    "deviceName": [
        {
            "name": "ProductName",
            "type": "model-name"
        }
    ],
    "type": {
        "text": "software"
    },
    "version": [
        {
            "value": "1.2.3"
        }
    ],
    "owner": {
        "reference": "Organization/org-site-001"
    }
}

PolarisCoreDocumentReference (CPAR Submission Metadata)¶

FHIR Profile: PolarisCoreDocumentReference.fsh
Example File: PolarisCoreDocumentReference-example.json
Identifier System Canonical URL:
https://fhir.apps.health/cpar/NamingSystem/cpar-submission-identifier

Submission Event¶

Recommended approach to store and XML submission file and its submission metadata in FHIR, while also linking back to the panel (i.e. the Group resource). In this design:

DocumentReference holds the submission metadata (submitting site, EMR vendor, schema version, etc.).
- DocumentReference.content.attachment references the Binary resource.
- DocumentReference.subject references the Group resource for the panel.
- Organization represents the submitting site (with site identifier, identifier type, and name).
- Device represents the EMR system (vendor name, product name, product version).
Binary holds the raw XML file (base64‑encoded).
Task (Workflow):
- Tracks the submission process. Task.for is used to reference the panel (Group) that is the subject of the submission. Task.focus is used to reference the DocumentReference (submission document).

(Detials below)

Mapped Fields¶

S9_Submission_Identifier
- DocumentReference.identifier.system = https://fhir.apps.health/cpar/NamingSystem/cpar-submission-identifier
- value = unique submission ID
S6_Upload_DateTime
- DocumentReference.date
S7_Submission_Schema_Version
- Extension: https://fhir.apps.health/cpar/StructureDefinition/submission-schema-version
- valueString = e.g., "v2.0"
S11_Number_Client_Attachments
- Extension: https://fhir.apps.health/cpar/StructureDefinition/number-client-attachments
- valueInteger
Panel Link
- DocumentReference.subject.reference = Group/{panel-id}
Author (EMR Software)
- DocumentReference.author.reference = Device/{id}
Raw XML Payload
- DocumentReference.content.attachment:
  - url = Binary/{binary-id}
  - contentType = application/xml

Example¶

{
    "resourceType": "DocumentReference",
    "id": "submission-001",
    "status": "current",
    "identifier": [
        {
            "system": "https://fhir.apps.health/cpar/NamingSystem/cpar-submission-identifier",
            "value": "cpar-sub-202503011045"
        }
    ],
    "date": "2025-03-01T10:45:00-07:00",
    "subject": {
        "reference": "Group/panel-123"
    },
    "author": [
        {
            "reference": "Device/device-emr-001"
        }
    ],
    "description": "CPAR Panel Submission",
    "extension": [
        {
            "url": "https://fhir.apps.health/cpar/StructureDefinition/submission-schema-version",
            "valueString": "v2.0"
        },
        {
            "url": "https://fhir.apps.health/cpar/StructureDefinition/number-client-attachments",
            "valueInteger": 25
        }
    ],
    "content": [
        {
            "attachment": {
                "contentType": "application/xml",
                "url": "Binary/binary-xml-001"
            }
        }
    ]
}

PolarisBinary¶

FHIR Resource: Binary

Mapped Fields¶

Raw XML File
- contentType = application/xml
- data = base64-encoded XML file

Example¶

{
    "resourceType": "Binary",
    "id": "binary-xml-001",
    "contentType": "application/xml",
    "data": "PD94bWwgdmVyc2lvbj0iMS4wIj8+CjxwYW5lbC1zdWJtaXNzaW9uPjwvcGFuZWwtc3VibWlzc2lvbj4="
}

PolarisTask (Submission Workflow)¶

FHIR Profile: Task

Mapped Fields¶

Task Status
- Task.status:
  - ready: Document created, awaiting submission
  - in-progress: Submission started
  - completed: Submission completed
  - failed: Submission failed
Task Intent
- Task.intent = "order"
Panel Reference
- Task.for.reference = Group/{panel-id}
Submission Reference
- Task.focus.reference = DocumentReference/{submission-id}
Authored On
- Task.authoredOn = Submission timestamp
Requester
- Task.requester.reference = Organization/{org-id}

Example¶

{
    "resourceType": "Task",
    "id": "task-001",
    "status": "in-progress",
    "intent": "order",
    "for": {
        "reference": "Group/panel-123"
    },
    "focus": {
        "reference": "DocumentReference/submission-001"
    },
    "authoredOn": "2025-03-01T10:40:00-07:00",
    "requester": {
        "reference": "Organization/org-site-001"
    }
}

Canonical Extensions and Naming Systems¶

Artifact	Canonical URL
Panel Number	https://fhir.apps.health/cpar/NamingSystem/cpar-panel-number
Submission Identifier	https://fhir.apps.health/cpar/NamingSystem/cpar-submission-identifier
Automated Submission Flag	https://fhir.apps.health/cpar/StructureDefinition/automated-submission-extension
Submit During Next Window	https://fhir.apps.health/cpar/StructureDefinition/submit-during-next-window-extension
Provider Extensions	https://fhir.apps.health/cpar/StructureDefinition/primary-providers-extension
Facility Extensions	https://fhir.apps.health/cpar/StructureDefinition/panel-facilities-extension
Confirmation Date Extension	https://fhir.apps.health/cpar/StructureDefinition/panel-confirmation-date-extension
Submission Schema Version	https://fhir.apps.health/cpar/StructureDefinition/submission-schema-version
Number of Client Attachments	https://fhir.apps.health/cpar/StructureDefinition/number-client-attachments

Implementation Notes¶

Identifier Strategy: All identifiers are logical and scoped per product-instance. Avoid using .id fields for resource linkage.
AppState Semantics: Know which settings apply to Device (software metadata) vs Organization (site identity).
No Masking Support: Unlike CII, CPAR does not support patient-level masking or address masking.
Submission Flow: Task tracks the workflow from draft to completed/failed state. Binary stores the base64-encoded submission document.
Sample Resources: See *-example.json in input/examples/ for examples of all resource instances referenced here.