Skip to content

PractitionerRole Profile

Canonical../StructureDefinition/nexus-emr-core-practitionerrole
Statusdraft · 1.26.0
BasePractitionerRole (constraint)
SourceFSH · JSON

Represents a practitioner's role at an organization/location -- the tenant-scoped access/role binding (the "actor"). Links a Practitioner to an Organization and Location(s) and carries the clinical role code(s). A practitioner may have one or more PractitionerRoles, including more than one active at the same organization. This is NOT the EMR user: the user's stable identity is the Practitioner (which carries the user-account identifier). Use PractitionerRole to differentiate providers by role (e.g. list only doctors, route a task to a nurse), not to represent the login.

FSH

The authored source of truth: resources/StructureDefinition-nexus-emr-core-practitionerrole.fsh (edit on GitHub). One FSH file may define several related artifacts.

// NexusEmrCorePractitionerRole.fsh - V1.1 - 2025-03-17
// Defines the minimal Nexus EMR PractitionerRole profile based on FHIR R4.
// Focuses on linking Practitioners to Organizations and Locations via identifiers.

Alias: $NexusEmrCorePractitionerRole = ../StructureDefinition/nexus-emr-core-practitionerrole
Alias: $NexusClinicalRoles = ../ValueSet/nexus-clinical-roles


// --- Profile Definition ---

Profile:        NexusEmrCorePractitionerRole
Parent:         PractitionerRole
Id:             nexus-emr-core-practitionerrole
Title:          "PractitionerRole Profile"
Description:    """
Represents a practitioner's role at an organization/location -- the tenant-scoped access/role binding
(the "actor"). Links a Practitioner to an Organization and Location(s) and carries the clinical
role code(s). A practitioner may have one or more PractitionerRoles, including more than one active at
the same organization. This is NOT the EMR user: the user's stable identity is the Practitioner (which
carries the user-account identifier). Use PractitionerRole to differentiate providers by role
(e.g. list only doctors, route a task to a nurse), not to represent the login.
"""
// THE effective date for this profile (see the EffectiveDate / NoEffectiveDate
// RuleSets): one date concept per resource, declared here rather than guessed.
* insert NoEffectiveDate

// SMART on FHIR exposure -- READ-ONLY. An app may read and search this resource but not
// create, update or delete it: this is reference/directory data, maintained by the EMR
// rather than by third-party apps, and a delete here is data loss rather than workflow.
* insert SmartExposedReadOnly(practitionerrole)

* ^url = $NexusEmrCorePractitionerRole // Canonical URL from alias
* ^status = #draft

* meta.source 0..1 MS
* meta.source ^short = "Identifies EMR instance & pipeline version the resource came from"
* meta.source ^definition = "A URI that identifies the EMR pipeline and version from which this resource originated.  This tells you which EMR instance (recommend using the instance identifier), and the version of the pipeline code/transformations."

* text 0..1 MS // Narrative element with human-readable summary
* text ^short = "Narrative"
* text ^definition = "A human-readable narrative summary of the NexusEmrCorePractitionerRole resource for human interpretation."

// identifier: optional (0..*), MS. Identifies the role/assignment record, not the EMR user.
* identifier 0..* MS
* identifier.system 1..1
* identifier.value 1..1
* identifier ^short = "identifiers including Nexus EMR ID and any source role/assignment id"
* identifier ^definition = """
Identifiers for this practitioner role (the role/assignment record -- NOT the EMR user account,
which is identified on the Practitioner).
"""
* identifier ^comment = "Multiple identifiers may exist including role/assignment IDs and system-specific identifiers. The EMR user-account id lives on Practitioner, not here. A source system's own identifier SHOULD be carried alongside this one, flagged `use = secondary`. See [Carrying the raw code](../guide/patterns/raw-codes.md)."


// active + period: needed because a practitioner may hold more than one role, including
// more than one active at the same organization. Consumers use these to tell live role
// bindings from ended ones, and to retire a role without deleting history.
* active 0..1 MS
* active ^short = "Whether this role assignment is currently in active use"
* active ^definition = "Whether this PractitionerRole (role/assignment binding) is currently in active use. When absent, assume active."
* period 0..1 MS
* period ^short = "Period during which the practitioner is authorized to act in this role"
* period ^definition = "The period during which the person is authorized to act in this role at this organization/location."

// practitioner: Reference to the practitioner (1..1 MS).
* practitioner 1..1 MS
* practitioner ^short = "Reference to the practitioner"
* practitioner ^definition = "Reference to the Practitioner resource representing the person in this role."
* practitioner ^comment = "Must reference a valid NexusEmrCorePractitioner resource."

// organization: Reference to the organization (0..1 MS). 
* organization 0..1 MS
* organization ^short = "Organization where the role is performed"
* organization ^definition = "The organization where the practitioner performs this role."
* organization ^comment = "Should reference a valid NexusEmrCoreOrganization resource when known."

// Code: clinical role(s) this practitioner performs in this binding.
// This is the "Clinical Roles" dropdown (doctor / nurse / MOA / echo-tech / ...): it binds
// PractitionerRole.code, it is NOT a separate resource. Extensible binding to the Nexus
// clinical-roles ValueSet -- the R4 practitioner-role value set is only an example (flooded with
// specialist codes; teacher/researcher in the top defaults), so Nexus defines its own.
* code 0..* MS
* code from $NexusClinicalRoles (extensible)
* code ^short = "Clinical role(s) (doctor, nurse, MOA, ...) -- binds the Clinical Roles dropdown"
* code ^definition = """
The clinical role(s) this practitioner performs in this binding (e.g., doctor, nurse, MOA,
receptionist, echo tech). Used throughout the EMR to differentiate providers (list only doctors,
route a task to a nurse, workflow routing echo-tech -> doctor -> nuclear-doctor). Distinct from
access permissions, which are managed in the auth layer (Auth0), not here.

RECOMMENDED: the Nexus clinical-roles ValueSet (extensible -- add local roles as needed)
OPTIONAL: additional standard terminology (SNOMED CT) or raw EMR codes for source preservation

Where this code was mapped from a source system's own vocabulary, carry the raw coding alongside the mapped one, flagged `userSelected = true`. See [Carrying the raw code](../guide/patterns/raw-codes.md).
"""


// Specialty: Specific specialty of the practitioner
* specialty 0..* MS
* specialty ^short = "Practitioner specialty with raw code support"
* insert SourceCoding(specialty)
* specialty ^definition = """
Specific specialty of the practitioner (e.g., cardiology, orthopedics, family medicine).

RECOMMENDED: SNOMED CT or other standard terminology when available
OPTIONAL: Raw EMR codes for source system preservation
"""


// location: Reference to the location(s) where services are provided
* location 0..*
* location ^short = "Location(s) where the practitioner provides care"
* location ^definition = "The location(s) at which this practitioner provides care in this role."
* location ^comment = "Can reference multiple NexusEmrCoreLocation resources for practitioners working at multiple sites."


// -----------------------------------------------------------------------------
// Nexus Clinical Roles -- the curated "Clinical Roles" dropdown bound to code.
// A curated Nexus DEFAULT set (product/design-owned), extensible so instances add their own.
// NOTE: this is NOT the same vocabulary either existing implementation emits today --
//   - oscar-next-fhir emits regulatory college codes (CPSO/OCP/CMO/CNORN...) under a
//     per-client raw-code system, not these role slugs;
//   - the WellServices frontend currently uses the HL7 R4 example system
//     (terminology.hl7.org/CodeSystem/practitioner-role: doctor/nurse/pharmacist/researcher/
//     teacher/ict).
// Adopting this system therefore requires a coordinated migration of the write + search paths
// (system|code searches keyed on the old system return nothing against the new one). The
// extensible binding keeps existing codings legal in the meantime. Membership below is a
// starting default, subject to product/design curation; NOT exhaustive.
// -----------------------------------------------------------------------------
CodeSystem: NexusClinicalRolesCS
Id: nexus-clinical-roles
Title: "Clinical Roles CodeSystem"
Description: "Curated Nexus default clinical roles a practitioner performs at an organization (bound extensibly to PractitionerRole.code), for EMR workflow/filtering. A product/design-owned default, distinct from OSCAR's regulatory provider_type codes and the HL7 R4 example role set; adopting it requires coordinated write/search migration."
* ^status = #draft
* ^experimental = false
* ^caseSensitive = true
* ^content = #complete
* ^url = "../CodeSystem/nexus-clinical-roles"
* #doctor "Doctor / Physician"
* #specialist "Specialist Physician"
* #resident "Resident"
* #nurse "Nurse"
* #nurse-practitioner "Nurse Practitioner"
* #echo-tech "Echocardiography Technician"
* #xray-tech "X-Ray Technician"
* #nuclear-doctor "Nuclear Medicine Physician"
* #radiologist "Radiologist"
* #pharmacist "Pharmacist"
* #moa "Medical Office Assistant (MOA)"
* #receptionist "Receptionist"
* #biller "Biller"
* #documentator "Documentator / Scribe"
* #allied-health "Allied Health Professional"
* #admin "Administrative Staff"

ValueSet: NexusClinicalRoles
Id: nexus-clinical-roles
Title: "Clinical Roles"
Description: "Curated clinical roles bound (extensible) to PractitionerRole.code. Extensible: instances may add local roles not in this default set."
* ^status = #draft
* ^experimental = false
* ^url = "../ValueSet/nexus-clinical-roles"
* include codes from system ../CodeSystem/nexus-clinical-roles