feat: implement effect for exporting ccdas (#1477)

Author: nmpsilva

canvas_generated/messages/effects_pb2.py

@@ -335,6 +335,7 @@ class EffectType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
     CREATE_PATIENT_FACILITY_ADDRESS: _ClassVar[EffectType]
     UPDATE_PATIENT_FACILITY_ADDRESS: _ClassVar[EffectType]
     DELETE_PATIENT_FACILITY_ADDRESS: _ClassVar[EffectType]
+    CREATE_CCDA: _ClassVar[EffectType]
     HOMEPAGE_CONFIGURATION: _ClassVar[EffectType]
 UNKNOWN_EFFECT: EffectType
 LOG: EffectType
@@ -664,6 +665,7 @@ UPDATE_EXTERNAL_EVENT: EffectType
 CREATE_PATIENT_FACILITY_ADDRESS: EffectType
 UPDATE_PATIENT_FACILITY_ADDRESS: EffectType
 DELETE_PATIENT_FACILITY_ADDRESS: EffectType
+CREATE_CCDA: EffectType
 HOMEPAGE_CONFIGURATION: EffectType
 
 class Effect(_message.Message):

canvas_generated/messages/effects_pb2.pyi

@@ -0,0 +1,3 @@
+from .ccda_export import CreateCCDA, DocumentType
+
+__all__ = __exports__ = ("CreateCCDA", "DocumentType")

canvas_sdk/effects/ccda/__init__.py

@@ -0,0 +1,75 @@
+import xml.etree.ElementTree as ET
+from enum import StrEnum
+from typing import Any
+
+from pydantic import Field
+from pydantic_core import InitErrorDetails
+
+from canvas_generated.messages.effects_pb2 import EffectType
+from canvas_sdk.effects.base import _BaseEffect
+from canvas_sdk.v1.data import Patient
+from logger import log
+
+
+class DocumentType(StrEnum):
+    """Valid CCDA document types."""
+
+    CCD = "CCD"
+    REFERRAL = "Referral"
+
+
+class CreateCCDA(_BaseEffect):
+    """
+    An Effect that will create a CCDA document for a patient with the provided XML content.
+
+    Attributes:
+        patient_id: The patient's key (required)
+        content: The CCDA XML content as a string (required)
+        document_type: Type of CCDA document (default: DocumentType.CCD)
+    """
+
+    class Meta:
+        effect_type = EffectType.CREATE_CCDA
+
+    patient_id: str = Field(min_length=1)
+    content: str = Field(min_length=1)
+    document_type: DocumentType = Field(default=DocumentType.CCD, strict=False)
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """The CreateCCDA's values."""
+        return {
+            "patient_id": self.patient_id,
+            "content": self.content,
+            "document_type": self.document_type.value,
+        }
+
+    def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
+        errors = super()._get_error_details(method)
+
+        log.info(f"Creating CCDA document for patient {self.patient_id}")
+        if not Patient.objects.filter(id=self.patient_id).exists():
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    f"Patient with ID {self.patient_id} does not exist.",
+                    self.patient_id,
+                )
+            )
+
+        # Validate XML content
+        try:
+            ET.fromstring(self.content)
+        except ET.ParseError as e:
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    f"Invalid XML content: {e}",
+                    self.content[:100] if len(self.content) > 100 else self.content,
+                )
+            )
+
+        return errors
+
+
+__exports__ = ("CreateCCDA", "DocumentType")

canvas_sdk/effects/ccda/ccda_export.py

@@ -0,0 +1,197 @@
+import json
+from collections.abc import Generator
+from unittest.mock import MagicMock, patch
+
+import pytest
+from pydantic import ValidationError
+
+from canvas_generated.messages.effects_pb2 import EffectType
+from canvas_sdk.effects.ccda import CreateCCDA, DocumentType
+
+SAMPLE_XML_CONTENT = """<?xml version="1.0" encoding="UTF-8"?>
+<ClinicalDocument xmlns="urn:hl7-org:v3">
+    <typeId root="2.16.840.1.113883.1.3" extension="POCD_HD000040"/>
+</ClinicalDocument>"""
+
+INVALID_XML_CONTENT = """<ClinicalDocument>
+    <unclosed_tag>
+</ClinicalDocument>"""
+
+
+@pytest.fixture
+def mock_patient_exists() -> Generator[MagicMock]:
+    """Mock Patient.objects to return that the patient exists."""
+    with patch("canvas_sdk.effects.ccda.ccda_export.Patient.objects") as mock_patient:
+        mock_patient.filter.return_value.exists.return_value = True
+        yield mock_patient
+
+
+def test_values_with_all_fields() -> None:
+    """Test that values property returns all fields correctly."""
+    effect = CreateCCDA(
+        patient_id="patient-key-123",
+        content=SAMPLE_XML_CONTENT,
+        document_type=DocumentType.CCD,
+    )
+
+    assert effect.values == {
+        "patient_id": "patient-key-123",
+        "content": SAMPLE_XML_CONTENT,
+        "document_type": "CCD",
+    }
+
+
+def test_values_with_minimal_fields() -> None:
+    """Test that values property returns correctly with required fields and default document_type."""
+    effect = CreateCCDA(
+        patient_id="patient-key-123",
+        content=SAMPLE_XML_CONTENT,
+    )
+
+    assert effect.values == {
+        "patient_id": "patient-key-123",
+        "content": SAMPLE_XML_CONTENT,
+        "document_type": "CCD",
+    }
+
+
+def test_values_with_referral_document_type() -> None:
+    """Test that values property works with Referral document type."""
+    effect = CreateCCDA(
+        patient_id="patient-key-123",
+        content=SAMPLE_XML_CONTENT,
+        document_type=DocumentType.REFERRAL,
+    )
+
+    assert effect.values["document_type"] == "Referral"
+
+
+def test_document_type_accepts_string_value() -> None:
+    """Test that document_type accepts plain strings via strict=False."""
+    effect = CreateCCDA(
+        patient_id="patient-key-123",
+        content=SAMPLE_XML_CONTENT,
+        document_type="Referral",  # type: ignore[arg-type]
+    )
+
+    assert effect.document_type == DocumentType.REFERRAL
+    assert effect.values["document_type"] == "Referral"
+
+
+def test_effect_payload_structure() -> None:
+    """Test that effect_payload has correct structure."""
+    effect = CreateCCDA(
+        patient_id="patient-key-123",
+        content=SAMPLE_XML_CONTENT,
+        document_type=DocumentType.CCD,
+    )
+
+    payload = effect.effect_payload
+    assert "data" in payload
+    assert payload["data"]["patient_id"] == "patient-key-123"
+    assert payload["data"]["content"] == SAMPLE_XML_CONTENT
+    assert payload["data"]["document_type"] == "CCD"
+
+
+def test_construction_raises_error_without_patient_id() -> None:
+    """Test that construction raises validation error when patient_id is missing."""
+    with pytest.raises(ValidationError) as exc_info:
+        CreateCCDA(content=SAMPLE_XML_CONTENT)  # type: ignore[call-arg]
+
+    assert "patient_id" in str(exc_info.value)
+
+
+def test_construction_raises_error_with_empty_patient_id() -> None:
+    """Test that construction raises validation error when patient_id is empty."""
+    with pytest.raises(ValidationError) as exc_info:
+        CreateCCDA(patient_id="", content=SAMPLE_XML_CONTENT)
+
+    assert "patient_id" in str(exc_info.value)
+
+
+def test_construction_raises_error_without_content() -> None:
+    """Test that construction raises validation error when content is missing."""
+    with pytest.raises(ValidationError) as exc_info:
+        CreateCCDA(patient_id="patient-key-123")  # type: ignore[call-arg]
+
+    assert "content" in str(exc_info.value)
+
+
+def test_construction_raises_error_with_empty_content() -> None:
+    """Test that construction raises validation error when content is empty."""
+    with pytest.raises(ValidationError) as exc_info:
+        CreateCCDA(patient_id="patient-key-123", content="")
+
+    assert "content" in str(exc_info.value)
+
+
+def test_default_document_type_is_ccd() -> None:
+    """Test that document_type defaults to CCD."""
+    effect = CreateCCDA(patient_id="patient-key-123", content=SAMPLE_XML_CONTENT)
+    assert effect.document_type == DocumentType.CCD
+
+
+def test_effect_payload_serialization() -> None:
+    """Test that effect_payload contains correctly serialized data."""
+    effect = CreateCCDA(
+        patient_id="test-patient-key",
+        content=SAMPLE_XML_CONTENT,
+        document_type=DocumentType.REFERRAL,
+    )
+
+    payload = effect.effect_payload
+    assert payload["data"]["patient_id"] == "test-patient-key"
+    assert payload["data"]["content"] == SAMPLE_XML_CONTENT
+    assert payload["data"]["document_type"] == "Referral"
+
+
+def test_document_type_enum_values() -> None:
+    """Test DocumentType enum has expected values."""
+    assert DocumentType.CCD.value == "CCD"
+    assert DocumentType.REFERRAL.value == "Referral"
+
+
+def test_apply_succeeds_with_valid_data(mock_patient_exists: MagicMock) -> None:
+    """Test that apply returns an Effect with correct type and payload."""
+    effect = CreateCCDA(
+        patient_id="patient-key-123",
+        content=SAMPLE_XML_CONTENT,
+        document_type=DocumentType.CCD,
+    )
+
+    applied = effect.apply()
+
+    assert applied.type == EffectType.CREATE_CCDA
+    payload = json.loads(applied.payload)
+    assert payload["data"]["patient_id"] == "patient-key-123"
+    assert payload["data"]["content"] == SAMPLE_XML_CONTENT
+    assert payload["data"]["document_type"] == "CCD"
+
+
+def test_apply_raises_error_for_nonexistent_patient() -> None:
+    """Test that apply raises validation error when patient does not exist."""
+    with patch("canvas_sdk.effects.ccda.ccda_export.Patient.objects") as mock_patient:
+        mock_patient.filter.return_value.exists.return_value = False
+
+        effect = CreateCCDA(
+            patient_id="nonexistent-patient",
+            content=SAMPLE_XML_CONTENT,
+        )
+
+        with pytest.raises(ValidationError) as exc_info:
+            effect.apply()
+
+        assert "does not exist" in str(exc_info.value)
+
+
+def test_apply_raises_error_for_invalid_xml(mock_patient_exists: MagicMock) -> None:
+    """Test that apply raises validation error when content is invalid XML."""
+    effect = CreateCCDA(
+        patient_id="patient-key-123",
+        content=INVALID_XML_CONTENT,
+    )
+
+    with pytest.raises(ValidationError) as exc_info:
+        effect.apply()
+
+    assert "Invalid XML content" in str(exc_info.value)

canvas_sdk/tests/effects/ccda/__init__.py

@@ -455,6 +455,14 @@
     "Event",
     "EventRecurrence"
   ],
+  "canvas_sdk.effects.ccda": [
+    "CreateCCDA",
+    "DocumentType"
+  ],
+  "canvas_sdk.effects.ccda.ccda_export": [
+    "CreateCCDA",
+    "DocumentType"
+  ],
   "canvas_sdk.effects.claim": [
     "BannerAlertIntent",
     "ClaimBillingProvider",

canvas_sdk/tests/effects/ccda/test_ccda_export.py

@@ -422,6 +422,8 @@ enum EffectType {
   UPDATE_PATIENT_FACILITY_ADDRESS = 8201;
   DELETE_PATIENT_FACILITY_ADDRESS = 8202;
 
+  CREATE_CCDA = 8300;
+
   HOMEPAGE_CONFIGURATION = 9000;
 }