Add Bloom v0 order specimen references

Author: iamh2o

bloom_lims/api/v1/external_specimens.py

@@ -127,6 +127,7 @@ async def find_external_specimens_by_reference(
     trf_euid: str | None = Query(None),
     patient_id: str | None = Query(None),
     order_euid: str | None = Query(None),
+    order_test_euid: str | None = Query(None),
     shipment_euid: str | None = Query(None),
     kit_barcode: str | None = Query(None),
     atlas_tenant_id: str | None = Query(None),
@@ -138,6 +139,7 @@ async def find_external_specimens_by_reference(
         trf_euid=trf_euid,
         patient_id=patient_id,
         order_euid=order_euid,
+        order_test_euid=order_test_euid,
         shipment_euid=shipment_euid,
         kit_barcode=kit_barcode,
         atlas_tenant_id=atlas_tenant_id,

bloom_lims/domain/beta_lab_refs.py

@@ -330,9 +330,28 @@ def _replace_container_entity_references(
         atlas_context: dict[str, Any],
     ) -> None:
         atlas_tenant_id = str(atlas_context.get("atlas_tenant_id") or "").strip()
+        atlas_order_euid = str(
+            atlas_context.get("atlas_order_euid") or atlas_context.get("order_euid") or ""
+        ).strip()
+        atlas_order_test_euid = str(
+            atlas_context.get("atlas_order_test_euid")
+            or atlas_context.get("order_test_euid")
+            or ""
+        ).strip()
         atlas_trf_euid = str(atlas_context.get("atlas_trf_euid") or "").strip()
         atlas_test_euid = str(atlas_context.get("atlas_test_euid") or "").strip()
         atlas_test_euids: list[str] = []
+        atlas_order_test_euids: list[str] = []
+        seen_order_tests: set[str] = set()
+        if atlas_order_test_euid:
+            seen_order_tests.add(atlas_order_test_euid)
+            atlas_order_test_euids.append(atlas_order_test_euid)
+        for value in list(atlas_context.get("atlas_order_test_euids") or []):
+            clean_value = str(value or "").strip()
+            if not clean_value or clean_value in seen_order_tests:
+                continue
+            seen_order_tests.add(clean_value)
+            atlas_order_test_euids.append(clean_value)
         seen_tests: set[str] = set()
         if atlas_test_euid:
             seen_tests.add(atlas_test_euid)
@@ -345,6 +364,14 @@ def _replace_container_entity_references(
             atlas_test_euids.append(clean_value)
         fulfillment_items = list(atlas_context.get("fulfillment_items") or [])
         for fulfillment_item in fulfillment_items:
+            candidate_order_test = str(
+                fulfillment_item.get("atlas_order_test_euid")
+                or fulfillment_item.get("order_test_euid")
+                or ""
+            ).strip()
+            if candidate_order_test and candidate_order_test not in seen_order_tests:
+                seen_order_tests.add(candidate_order_test)
+                atlas_order_test_euids.append(candidate_order_test)
             candidate = str(fulfillment_item.get("atlas_test_euid") or "").strip()
             if not candidate or candidate in seen_tests:
                 continue
@@ -359,6 +386,54 @@ def _replace_container_entity_references(
             (self.ORGANIZATION_SITE_REFERENCE_TYPE, "atlas_organization_site_euid"),
         )
         created_payloads: list[dict[str, Any]] = []
+        self._delete_reference_type(instance, reference_type="order_test_euid")
+        self._delete_reference_type(instance, reference_type="order_euid")
+        if atlas_tenant_id and atlas_order_euid:
+            properties = {
+                "provider": "atlas",
+                "reference_type": "order_euid",
+                "reference_value": atlas_order_euid,
+                "foreign_reference": atlas_order_euid,
+                "atlas_tenant_id": atlas_tenant_id,
+                "order_euid": atlas_order_euid,
+                "atlas_order_euid": atlas_order_euid,
+                "validation": {},
+            }
+            created_payloads.append(properties)
+            ref_obj = self.bobj.create_instance_by_code(
+                self.EXTERNAL_REFERENCE_TEMPLATE_CODE,
+                {"json_addl": {"properties": properties}},
+            )
+            self.bobj.create_generic_instance_lineage_by_euids(
+                instance.euid,
+                ref_obj.euid,
+                relationship_type=self.EXTERNAL_REFERENCE_RELATIONSHIP,
+            )
+        if atlas_tenant_id:
+            for reference_value in atlas_order_test_euids:
+                properties = {
+                    "provider": "atlas",
+                    "reference_type": "order_test_euid",
+                    "reference_value": reference_value,
+                    "foreign_reference": reference_value,
+                    "atlas_tenant_id": atlas_tenant_id,
+                    "order_test_euid": reference_value,
+                    "atlas_order_test_euid": reference_value,
+                    "validation": {},
+                }
+                if atlas_order_euid:
+                    properties["order_euid"] = atlas_order_euid
+                    properties["atlas_order_euid"] = atlas_order_euid
+                created_payloads.append(properties)
+                ref_obj = self.bobj.create_instance_by_code(
+                    self.EXTERNAL_REFERENCE_TEMPLATE_CODE,
+                    {"json_addl": {"properties": properties}},
+                )
+                self.bobj.create_generic_instance_lineage_by_euids(
+                    instance.euid,
+                    ref_obj.euid,
+                    relationship_type=self.EXTERNAL_REFERENCE_RELATIONSHIP,
+                )
         self._delete_reference_type(instance, reference_type=self.TEST_REFERENCE_TYPE)
         if atlas_tenant_id:
             for reference_value in atlas_test_euids:

bloom_lims/domain/external_specimens.py

@@ -34,6 +34,7 @@ class ExternalSpecimenService:
         "trf_euid",
         "patient_id",
         "order_euid",
+        "order_test_euid",
         "shipment_euid",
         "kit_barcode",
         "atlas_tenant_id",
@@ -53,6 +54,10 @@ class ExternalSpecimenService:
             "reference_types": ("order_euid",),
             "value_field": "reference_value",
         },
+        "order_test_euid": {
+            "reference_types": ("order_test_euid",),
+            "value_field": "reference_value",
+        },
         "shipment_euid": {
             "reference_types": ("shipment_euid",),
             "value_field": "reference_value",
@@ -77,6 +82,7 @@ class ExternalSpecimenService:
     _REFERENCE_RESPONSE_NORMALIZATION: dict[str, tuple[str, str]] = {
         "atlas_trf": ("atlas_trf_euid", "atlas_trf_euid"),
         "atlas_test": ("atlas_test_euid", "atlas_test_euid"),
+        "order_test_euid": ("order_test_euid", "reference_value"),
         "atlas_patient": ("atlas_patient_euid", "atlas_patient_euid"),
         "atlas_testkit": ("atlas_testkit_euid", "atlas_testkit_euid"),
         "atlas_shipment": ("atlas_shipment_euid", "atlas_shipment_euid"),
@@ -351,6 +357,7 @@ def _validate_atlas_refs(
             "trf_euid": refs.trf_euid,
             "patient_id": refs.patient_id,
             "order_euid": refs.order_euid,
+            "order_test_euid": refs.order_test_euid,
             "shipment_euid": refs.shipment_euid,
             "kit_barcode": refs.kit_barcode,
             "atlas_tenant_id": refs.atlas_tenant_id,

bloom_lims/schemas/external_specimens.py

@@ -11,6 +11,7 @@ class AtlasReferences(BaseModel):
     trf_euid: str | None = None
     patient_id: str | None = None
     order_euid: str | None = None
+    order_test_euid: str | None = None
     shipment_euid: str | None = None
     kit_barcode: str | None = None
     atlas_tenant_id: str | None = None
@@ -33,6 +34,7 @@ def validate_references(self) -> "ExternalSpecimenCreateRequest":
         if not any(
             [
                 refs.order_euid,
+                refs.order_test_euid,
                 refs.patient_id,
                 refs.shipment_euid,
                 refs.kit_barcode,

tests/test_api_auth_rbac.py

@@ -121,6 +121,43 @@ def _unexpected_atlas_service():
     assert service._atlas is None
 
 
+def test_external_specimen_lookup_uses_order_test_reference_filter(monkeypatch):
+    def _unexpected_atlas_service():
+        raise AssertionError(
+            "AtlasService should not be constructed for lookup-only queries"
+        )
+
+    monkeypatch.setattr(
+        "bloom_lims.domain.external_specimens.AtlasService",
+        _unexpected_atlas_service,
+    )
+
+    calls: list[tuple[str, str]] = []
+
+    def _find_parent_uids_for_reference(*, reference_type: str, reference_value: str):
+        calls.append((reference_type, reference_value))
+        if reference_type == "order_euid":
+            return {123}
+        if reference_type == "order_test_euid":
+            return set()
+        raise AssertionError(f"unexpected reference filter: {reference_type}")
+
+    service = object.__new__(ExternalSpecimenService)
+    service._atlas = None
+    service.bdb = SimpleNamespace()
+    service.bobj = SimpleNamespace()
+    service._find_parent_uids_for_reference = _find_parent_uids_for_reference
+
+    result = ExternalSpecimenService.find_by_references(
+        service,
+        AtlasReferences(order_euid="ORDER-1", order_test_euid="ORDERTEST-1"),
+    )
+
+    assert result == []
+    assert calls == [("order_euid", "ORDER-1"), ("order_test_euid", "ORDERTEST-1")]
+    assert service._atlas is None
+
+
 def test_user_tokens_endpoints_create_list_usage_revoke(client):
     token_id = _create_token(client)
 

tests/test_queue_flow.py

@@ -67,8 +67,13 @@ def _assert_no_uuid_keys(payload):
 
 
 def _atlas_context_payload() -> dict[str, object]:
+    order_euid = _opaque("order")
+    primary_order_test_euid = _opaque("order-test-primary")
     return {
         "atlas_tenant_id": _opaque("tenant"),
+        "atlas_order_euid": order_euid,
+        "atlas_order_test_euid": primary_order_test_euid,
+        "atlas_order_test_euids": [primary_order_test_euid, _opaque("order-test-secondary")],
         "atlas_trf_euid": _opaque("trf"),
         "atlas_test_euid": _opaque("test-primary"),
         "atlas_test_euids": [_opaque("test-secondary")],
@@ -746,3 +751,26 @@ def test_external_specimen_lookup_finds_queue_ready_material_by_container_refs()
             and item["container_euid"] == material["container_euid"]
             for item in payload["items"]
         )
+
+
+def test_external_specimen_lookup_finds_queue_ready_material_by_order_refs():
+    app.dependency_overrides[require_external_token_auth] = _external_rw_user
+
+    with TestClient(app) as client:
+        material, atlas_context = _create_material_and_queue(client)
+        lookup = client.get(
+            "/api/v1/external/specimens/by-reference",
+            params={
+                "atlas_tenant_id": atlas_context["atlas_tenant_id"],
+                "order_euid": atlas_context["atlas_order_euid"],
+                "order_test_euid": atlas_context["atlas_order_test_euid"],
+            },
+        )
+        assert lookup.status_code == 200, lookup.text
+        payload = lookup.json()
+        assert payload["total"] >= 1
+        assert any(
+            item["specimen_euid"] == material["specimen_euid"]
+            and item["container_euid"] == material["container_euid"]
+            for item in payload["items"]
+        )