Merge pull request #953 from NHSDigital/feat/gateway-action-model

Add gateway app with GatewayAction model and WorklistItemService

Author: carlosmartinez

.tool-versions

@@ -1,3 +1,4 @@
+gitleaks 8.18.4
 nodejs 24.11.0
 pre-commit 3.6.0
 python 3.14.0

manage_breast_screening/config/settings.py

@@ -85,6 +85,7 @@ def list_env(key):
     "manage_breast_screening.participants",
     "manage_breast_screening.mammograms",
     "manage_breast_screening.manual_images",
+    "manage_breast_screening.gateway",
     "rules.apps.AutodiscoverRulesConfig",
 ]
 

manage_breast_screening/gateway/__init__.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class GatewayConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "manage_breast_screening.gateway"

manage_breast_screening/gateway/apps.py

@@ -0,0 +1,39 @@
+# Generated by Django 6.0.1 on 2026-01-28 15:29
+
+import django.db.models.deletion
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('participants', '0057_alter_appointmentstatus_unique_together_and_more'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='GatewayAction',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('type', models.CharField(choices=[('worklist.create_item', 'Create Worklist Item')], max_length=50)),
+                ('payload', models.JSONField()),
+                ('status', models.CharField(choices=[('pending', 'Pending'), ('sent', 'Sent'), ('confirmed', 'Confirmed'), ('failed', 'Failed')], default='pending', max_length=20)),
+                ('accession_number', models.CharField(db_index=True, max_length=100, unique=True)),
+                ('sent_at', models.DateTimeField(blank=True, null=True)),
+                ('confirmed_at', models.DateTimeField(blank=True, null=True)),
+                ('retry_count', models.IntegerField(default=0)),
+                ('next_retry_at', models.DateTimeField(blank=True, null=True)),
+                ('last_error', models.TextField(blank=True)),
+                ('appointment', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='gateway_actions', to='participants.appointment')),
+            ],
+            options={
+                'ordering': ['-created_at'],
+                'indexes': [models.Index(fields=['status', 'next_retry_at'], name='gateway_gat_status_e73bd1_idx')],
+            },
+        ),
+    ]

manage_breast_screening/gateway/migrations/0001_create_gateway_action.py

@@ -0,0 +1 @@
+0001_create_gateway_action

manage_breast_screening/gateway/migrations/__init__.py

@@ -0,0 +1,51 @@
+"""Gateway action tracking models."""
+
+from django.db import models
+
+from manage_breast_screening.core.models import BaseModel
+
+
+class GatewayActionStatus(models.TextChoices):
+    PENDING = "pending", "Pending"
+    SENT = "sent", "Sent"
+    CONFIRMED = "confirmed", "Confirmed"
+    FAILED = "failed", "Failed"
+
+
+class GatewayActionType(models.TextChoices):
+    WORKLIST_CREATE = "worklist.create_item", "Create Worklist Item"
+
+
+class GatewayAction(BaseModel):
+    """Tracks actions sent to the screening gateway."""
+
+    appointment = models.ForeignKey(
+        "participants.Appointment",
+        on_delete=models.PROTECT,
+        related_name="gateway_actions",
+    )
+    type = models.CharField(max_length=50, choices=GatewayActionType.choices)
+    payload = models.JSONField()
+    status = models.CharField(
+        max_length=20,
+        choices=GatewayActionStatus.choices,
+        default=GatewayActionStatus.PENDING,
+    )
+
+    accession_number = models.CharField(max_length=100, unique=True, db_index=True)
+
+    sent_at = models.DateTimeField(null=True, blank=True)
+    confirmed_at = models.DateTimeField(null=True, blank=True)
+
+    retry_count = models.IntegerField(default=0)
+    next_retry_at = models.DateTimeField(null=True, blank=True)
+    last_error = models.TextField(blank=True)
+
+    class Meta:
+        ordering = ["-created_at"]
+        indexes = [
+            models.Index(fields=["status", "next_retry_at"]),
+        ]
+
+    def __str__(self):
+        return f"{self.type} - {self.accession_number} ({self.status})"

manage_breast_screening/gateway/migrations/max_migration.txt

@@ -0,0 +1,103 @@
+"""Gateway action services."""
+
+import logging
+import uuid
+from datetime import datetime, timezone
+
+from manage_breast_screening.participants.models import Appointment
+
+from .models import GatewayAction, GatewayActionStatus, GatewayActionType
+
+logger = logging.getLogger(__name__)
+
+
+class WorklistItemService:
+    """Service for creating worklist item actions for the gateway."""
+
+    def __init__(self, appointment: Appointment):
+        self.appointment = appointment
+        self.participant = appointment.participant
+
+    @classmethod
+    def create(cls, appointment: Appointment) -> GatewayAction:
+        """
+        Create a worklist item action for the given appointment.
+
+        Returns the GatewayAction with status PENDING.
+        The action will be picked up and sent by the relay sender service.
+        """
+        service = cls(appointment)
+        return service._create_action()
+
+    def _generate_accession_number(self) -> str:
+        """Generate unique accession number (max 16 chars per DICOM SH limit)."""
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d")
+        random_suffix = uuid.uuid4().hex[:4].upper()
+        return f"ACC{timestamp}{random_suffix}"
+
+    def _build_payload(self, action_id: uuid.UUID, accession_number: str) -> dict:
+        """Build the worklist create payload."""
+        participant = self.participant
+        appointment = self.appointment
+
+        # Format name: LAST^FIRST
+        participant_name = (
+            f"{participant.last_name.upper()}^{participant.first_name.upper()}"
+        )
+
+        scheduled_datetime = appointment.clinic_slot.starts_at
+        scheduled_date = scheduled_datetime.strftime("%Y%m%d")
+        scheduled_time = scheduled_datetime.strftime("%H%M%S")
+
+        return {
+            "schema_version": 1,
+            "action_id": str(action_id),
+            "action_type": GatewayActionType.WORKLIST_CREATE,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "source_system": "manage-breast-screening",
+            "source_reference": {
+                "appointment_id": str(appointment.pk),
+                "participant_id": participant.nhs_number,
+            },
+            "parameters": {
+                "worklist_item": {
+                    "accession_number": accession_number,
+                    "participant": {
+                        "nhs_number": participant.nhs_number,
+                        "name": participant_name,
+                        "birth_date": participant.date_of_birth.strftime("%Y%m%d"),
+                        "sex": participant.gender[0].upper()
+                        if participant.gender
+                        else "F",
+                    },
+                    "scheduled": {
+                        "date": scheduled_date,
+                        "time": scheduled_time,
+                    },
+                    "procedure": {
+                        "modality": "MG",
+                        "study_description": "Screening Mammography",
+                    },
+                }
+            },
+        }
+
+    def _create_action(self) -> GatewayAction:
+        """Create and persist the gateway action."""
+        action_id = uuid.uuid4()
+        accession_number = self._generate_accession_number()
+        payload = self._build_payload(action_id, accession_number)
+
+        action = GatewayAction.objects.create(
+            id=action_id,
+            appointment=self.appointment,
+            type=GatewayActionType.WORKLIST_CREATE,
+            accession_number=accession_number,
+            payload=payload,
+            status=GatewayActionStatus.PENDING,
+        )
+
+        logger.info(
+            f"Created gateway action {action_id} for appointment {self.appointment.pk}"
+        )
+        return action