PolarisCoreAppConsent Feature Overview

Introduction

The PolarisCoreAppConsent feature provides a standardized way to record and manage patient consent for third-party applications that integrate with healthcare data. This feature specifically addresses the scenario where patients sign up with apps that need access to their clinical information.

Use Case

The Problem

When patients want to use third-party healthcare applications (like AI scribes, wellness apps, or clinical decision support tools), healthcare providers need a standardized way to:

1. Record consent - Document that the patient has agreed to share their data
2. Track app details - Maintain information about which specific application has access
3. Manage consent lifecycle - Handle consent updates, withdrawals, and status changes
4. Maintain compliance - Keep records for legal and regulatory requirements
5. Enable interoperability - Use standardized FHIR structures for consent management

The Solution

PolarisCoreAppConsent uses two complementary FHIR profiles:

• PolarisCoreAppConsent - Records the patient's consent decision
• PolarisCoreAppDevice - Represents the third-party application

Profile Overview

PolarisCoreAppConsent Profile

The PolarisCoreAppConsent profile is based on the FHIR R4 Consent resource and follows a KISS (Keep It Simple, Stupid) approach, including only essential fields needed for app consent tracking.

Key Design Principles

1. Focused Use Case - Specifically designed for patient app signup consent
2. Required FHIR Compliance - Includes all mandatory R4 Consent fields
3. Fixed Values - Uses appropriate fixed values for the app consent context
4. Extensible - Can accommodate future enhancements while maintaining simplicity

Field Descriptions

Required Fields

Field	Value	Purpose	Why Required
identifier	Polaris naming pattern	Unique consent record ID	Track individual consent instances
status	active | draft | inactive | entered-in-error	Current consent state	FHIR R4 requirement, lifecycle management
scope	patient-privacy (fixed)	Type of consent	FHIR R4 requirement, indicates privacy consent
category	infa (fixed)	Consent category	FHIR R4 requirement, indicates information access
patient	Reference to PolarisCorePatient	Who gave consent	Identify the consenting patient
dateTime	ISO 8601 timestamp	When consent was given	Legal requirement, audit trail
policyRule	cric (fixed)	Consent policy framework	FHIR R4 requirement, either policy or policyRule must be present
provision.type	NOT USED in root provision	N/A - See R4 complexity below	FHIR R4 prohibits type in root provision
provision.actor	Reference to PolarisCoreAppDevice	Which app has access	Identify the specific application

Optional Fields

Field	Purpose	When to Use
sourceAttachment	Original signed consent document	When you have a PDF/image of the signed form

FHIR R4 Consent Complexity (Unfortunately Required)

FHIR R4 has a counterintuitive but official way to model consent decisions. We follow this for compliance, even though it's... not simple:

The Rules (From Official FHIR R4 Spec):

1. status='proposed' - Request more information from patient
2. status='active' + top-level provision with NO type - GRANT CONSENT
3. status='active' + top-level provision with NO type + nested provision with type='deny' - DENY CONSENT

Why This Complexity?

Per FHIR R4 specification: provision.type is "Not permitted in root rule, required in all nested rules". The logic is:

• Base assumption: The top-level provision grants access
• Exceptions: Nested provisions with type='deny' create specific denials
• Result: Complex but standards-compliant consent modeling

Status Meanings:

Status	Meaning	Provision Structure	User Summary
proposed	"We need more info before deciding"	Any provision structure	"Pending"
active	"Decision made - provision defines what"	See grant/deny patterns below	"Granted" or "Denied"
draft	Currently unused in our use case	TBD	"Pending"
inactive	"Previously active consent now withdrawn"	Any provision structure	"Invalid" or "Cancelled"
entered-in-error	"Consent record was created in error"	N/A - record is invalid	"Invalid" or "Cancelled"

Status to User Summary Translation

When displaying consent status to end users, use this translation logic:

For status = "active":

• Check provision structure:
• No nested provision with type="deny" → "Granted"
• Has nested provision with type="deny" → "Denied"

For status = "proposed" or status = "draft":

• → "Pending"

For status = "inactive" or status = "entered-in-error":

• → "Invalid" or "Cancelled" (consent decision is no longer valid/relevant)

PolarisCoreAppDevice Profile

The PolarisCoreAppDevice profile represents the third-party application and includes:

• identifier - App identifiers (including OAuth client_id)
• deviceName - Human-readable app name
• status - Whether the app registration is active
• manufacturer - App developer/company (optional)
• type - Software application type
• note - Brief description of the app

Complete Example

Here's a complete example showing how a patient consents to use an AI scribe application:

Step 1: Create the App Device

{
  "resourceType": "Device",
  "id": "smartdocs-ai-scribe",
  "meta": {
    "profile": ["https://fhir.apps.health/StructureDefinition/polaris-appdevice"]
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>SmartDocs AI Scribe</b></p><p>AI-powered clinical documentation assistant. Client ID: smartdocs-ai-scribe-prod</p></div>"
  },
  "identifier": [
    {
      "system": "https://fhir.apps.health/NamingSystem/polaris-appdevice-identifier",
      "value": "smartdocs-ai-scribe"
    },
    {
      "system": "https://oauth.example.com/client-registry",
      "value": "smartdocs-ai-scribe-prod",
      "use": "secondary"
    }
  ],
  "status": "active",
  "deviceName": [
    {
      "name": "SmartDocs AI Scribe",
      "type": "user-friendly-name"
    }
  ],
  "manufacturer": "ClinicalAI Solutions",
  "type": {
    "text": "AI Clinical Documentation App"
  },
  "note": [
    {
      "text": "AI application for automated clinical note generation and transcription that integrates with patient data."
    }
  ]
}

Step 2: Record the Patient Consent

{
  "resourceType": "Consent",
  "id": "polaris-core-app-consent-scribe-ai-example",
  "meta": {
    "profile": ["https://fhir.apps.health/StructureDefinition/polaris-core-app-consent"]
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>App Consent</b></p><p>Patient: <strong>Avery Linwood</strong> has <strong>CONSENTED</strong> to sign up with and share clinical data with <strong>SmartDocs AI Scribe</strong> application.</p><p>Date: April 8, 2025</p></div>"
  },
  "identifier": [
    {
      "system": "https://fhir.apps.health/NamingSystem/cedarbrook-clinic-app-consent-identifier",
      "value": "app-consent-scribe-ai-avery-20250408"
    }
  ],
  "status": "active",
  "scope": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/consentscope",
        "code": "patient-privacy",
        "display": "Privacy Consent"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/consentcategorycodes",
          "code": "infa",
          "display": "Information Access"
        }
      ]
    }
  ],
  "patient": {
    "identifier": {
      "system": "https://fhir.apps.health/NamingSystem/cedarbrook-clinic-patient-identifier",
      "value": "patient-avery-linwood"
    },
    "display": "Avery Linwood"
  },
  "dateTime": "2025-04-08T10:30:00-06:00",
  "policyRule": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/consentpolicycodes",
        "code": "cric",
        "display": "Common Rule Informed Consent"
      }
    ]
  },
  "sourceAttachment": {
    "contentType": "application/pdf",
    "title": "SmartDocs AI Scribe Consent Form - Signed",
    "creation": "2025-04-08T10:30:00-06:00",
    "size": 12345,
    "hash": "ZGEwNTQwYTM5YTMwMGM5ZjYzZGI4YzJjYTI2ZWFmYzE=",
    "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8L0ZvbnQgPDwvRjEgNCAwIFI+Pj4+Ci9Db250ZW50cyA1IDAgUgo+PgplbmRvYmoK"
  },
  "provision": {
    "actor": [
      {
        "role": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
              "code": "IRCP",
              "display": "information recipient"
            }
          ]
        },
        "reference": {
          "identifier": {
            "system": "https://fhir.apps.health/NamingSystem/polaris-appdevice-identifier",
            "value": "smartdocs-ai-scribe"
          },
          "display": "SmartDocs AI Scribe"
        }
      }
    ]
  }
}

Common Scenarios (Using Correct FHIR R4 Patterns)

Scenario 1: Request More Information

• Create PolarisCoreAppConsent with status = "proposed"
• Include provision with actor (the app requesting consent)
• Patient/provider can review and decide

Scenario 2: Patient Grants Consent

• Create PolarisCoreAppDevice resource for the application
• Create PolarisCoreAppConsent with:
• status = "active"
• Top-level provision with NO type (R4 prohibits type in root)
• provision.actor referencing the app
• Result: Consent granted (base assumption + no denials)

Scenario 3: Patient Denies Consent

• Create PolarisCoreAppDevice resource for the application
• Create PolarisCoreAppConsent with:
• status = "active"
• Top-level provision with NO type
• Nested provision with type = "deny"
• Both provisions reference the same app actor
• Result: Consent denied (base assumption overridden by denial)

Scenario 4: Patient Withdraws Previously Granted Consent

• Update existing PolarisCoreAppConsent
• Set status = "inactive"
• Update dateTime to withdrawal timestamp
• Keep original provision structure for audit trail

Scenario 5: Error Correction

• Set status = "entered-in-error"
• Create new corrected consent resource

Scenario 6: Draft Consent (Currently Unused)

• Not yet defined for our app consent use case
• Could potentially be used for staged consent workflows

R4-Compliant Examples

Example 1: Request More Information (status='proposed')

{
  "resourceType": "Consent",  
  "status": "proposed",
  "scope": { /* patient-privacy */ },
  "category": [{ /* infa */ }],
  "patient": { /* patient reference */ },
  "dateTime": "2025-04-08T10:30:00-06:00",
  "policyRule": { 
    "coding": [{ 
      "system": "http://terminology.hl7.org/CodeSystem/consentpolicycodes",
      "code": "cric",
      "display": "Common Rule Informed Consent"
    }]
  },
  "provision": {
    "actor": [{
      "role": { /* information recipient */ },
      "reference": { /* app device reference */ }
    }]
  }
}

Example 2: Grant Consent (R4 Pattern)

{
  "resourceType": "Consent",
  "status": "active", 
  "scope": { /* patient-privacy */ },
  "category": [{ /* infa */ }],
  "patient": { /* patient reference */ },
  "dateTime": "2025-04-08T10:30:00-06:00",
  "policyRule": { 
    "coding": [{ 
      "system": "http://terminology.hl7.org/CodeSystem/consentpolicycodes",
      "code": "cric",
      "display": "Common Rule Informed Consent"
    }]
  },
  "provision": {
    // NO type field - this is the R4 way to grant consent
    "actor": [{
      "role": { /* information recipient */ },
      "reference": { /* app device reference */ }
    }]
  }
}

Example 3: Deny Consent (R4 Pattern - Complex!)

{
  "resourceType": "Consent",
  "status": "active",
  "scope": { /* patient-privacy */ },
  "category": [{ /* infa */ }], 
  "patient": { /* patient reference */ },
  "dateTime": "2025-04-08T10:30:00-06:00",
  "policyRule": { 
    "coding": [{ 
      "system": "http://terminology.hl7.org/CodeSystem/consentpolicycodes",
      "code": "cric",
      "display": "Common Rule Informed Consent"
    }]
  },
  "provision": {
    // Top-level provision has NO type (base grant assumption)
    "actor": [{
      "role": { /* information recipient */ },
      "reference": { /* app device reference */ }
    }],
    // Nested provision with type="deny" overrides the base assumption
    "provision": [{
      "type": "deny",
      "actor": [{
        "role": { /* information recipient */ },
        "reference": { /* same app device reference */ }
      }]
    }]
  }
}

Note: The deny pattern is complex because FHIR R4 assumes the base provision grants access, then uses nested provisions to create exceptions. This is counterintuitive but standards-compliant.

Integration Patterns

With OAuth/OIDC

• Store OAuth client_id in PolarisCoreAppDevice.identifier
• Link consent decisions to OAuth authorization flows

With EMR Systems

• Use consent status to control data access APIs
• Integrate with existing EMR consent workflows

With Audit Systems

• Track all consent lifecycle events
• Maintain compliance audit trails

Best Practices

1. Always create the Device first - The app must exist before consent can reference it
2. Use meaningful identifiers - Include clinic/system identifiers in naming systems
3. Maintain source documents - Use sourceAttachment when available for legal compliance
4. Update, don't delete - Use status changes rather than deletion for consent lifecycle
5. Include narrative text - Provide human-readable summaries for clinical staff

Validation Notes

• Both profiles include Polaris identifier invariants for validation
• Standard FHIR R4 validation applies to all fields
• Fixed values for scope and category ensure consistency across implementations
• Must Support (MS) flags indicate which fields should be supported by implementations

Related Resources

• PolarisCoreAppConsent Profile
• PolarisCoreAppDevice Profile
• FHIR R4 Consent Resource
• FHIR R4 Device Resource