Feature/bcss 21859 sspi utils fix (#147)

<!-- markdownlint-disable-next-line first-line-heading -->
## Description

<!-- Describe your changes in detail. -->
Updating the methods used to populate a subject class object from an NHS
number by altering the subject selection query builder to be able to add
columns and joins.
Then updating the mapping of the result which is stored in a pandas
dataframe to the subject class object.
Updated documentation accordingly.

## Context

<!-- Why is this change required? What problem does it solve? -->
This was required as when doing SSPI updates some information such as
the subject's GP practice would be overwritten and set to None / Null.
This change has resolved that issue.

## Type of changes

<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply. -->

- [x] Refactoring (non-breaking change)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would change existing
functionality)
- [x] Bug fix (non-breaking change which fixes an issue)

## Checklist

<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [x] I am familiar with the [contributing
guidelines](https://github.com/nhs-england-tools/playwright-python-blueprint/blob/main/CONTRIBUTING.md)
- [x] I have followed the code style of the project
- [x] I have added tests to cover my changes (where appropriate)
- [x] I have updated the documentation accordingly
- [x] This PR is a result of pair or mob programming

---

## Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others
privacy, we kindly ask you to NOT including [PII (Personal Identifiable
Information) / PID (Personal Identifiable
Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public)
or any other sensitive data in this PR (Pull Request) and the codebase
changes. We will remove any PR that do contain any sensitive
information. We really appreciate your cooperation in this matter.

- [x] I confirm that neither PII/PID nor sensitive data are included in
this PR and the codebase changes.

Author: adrianoaru-nhs

classes/subject/gender_type.py

@@ -88,3 +88,18 @@ def by_redefined_value(cls, redefined_value: int) -> Optional["GenderType"]:
         return next(
             (item for item in cls if item.redefined_value == redefined_value), None
         )
+
+    @classmethod
+    def by_allowed_value(cls, allowed_value: str) -> Optional["GenderType"]:
+        """
+        Returns the GenderType enum member matching the given allowed value.
+
+        Args:
+            allowed_value (str): The allowed value to search for.
+
+        Returns:
+            Optional[GenderType]: The matching enum member, or None if not found.
+        """
+        return next(
+            (item for item in cls if item.allowed_value == allowed_value), None
+        )

classes/subject/subject.py

@@ -1302,6 +1302,16 @@ def from_dataframe_row(row: pd.Series) -> "Subject":
             ),
             "date_of_birth": DateTimeUtils.parse_date(row.get("date_of_birth")),
             "date_of_death": DateTimeUtils.parse_date(row.get("date_of_death")),
+            "title": row.get("person_title"),
+            "other_names": row.get("person_other_given_names"),
+            "address_line1": row.get("address_line_1"),
+            "address_line2": row.get("address_line_2"),
+            "address_line3": row.get("address_line_3"),
+            "address_line4": row.get("address_line_4"),
+            "address_line5": row.get("address_line_5"),
+            "postcode": row.get("postcode"),
+            "gp_practice_code": row.get("gp_practice_code"),
+            "gender": GenderType.by_allowed_value(str(row.get("person_gender"))),
         }
 
         return Subject(**field_map)
@@ -1318,13 +1328,17 @@ def populate_subject_object_from_nhs_no(self, nhs_no: str) -> "Subject":
             SubjectSelectionQueryBuilder,
         )
 
-        nhs_no_criteria = {"nhs number": nhs_no}
+        criteria = {
+            "nhs number": nhs_no,
+            "add column to select statement": " c.person_title, c.person_other_given_names, CASE c.person_gender WHEN 130 THEN 'M' WHEN 131 THEN 'F' WHEN 132 THEN 'I' WHEN 160 THEN 'U' END, adds.address_line_1, adds.address_line_2, adds.address_line_3, adds.address_line_4, adds.address_line_5, adds.postcode, (SELECT hub.org_code FROM org hub WHERE org_id = c.gp_practice_id) AS gp_practice_code ",
+            "add join to from statement": " INNER JOIN sd_address_t adds ON adds.contact_id = c.contact_id ",
+        }
         subject = Subject()
         user = User()
         builder = SubjectSelectionQueryBuilder()
 
         query, bind_vars = builder.build_subject_selection_query(
-            criteria=nhs_no_criteria,
+            criteria=criteria,
             user=user,
             subject=subject,
             subjects_to_retrieve=1,

classes/subject_selection_query_builder/subject_selection_criteria_key.py

@@ -24,6 +24,7 @@ class SubjectSelectionCriteriaKey(Enum):
     """
 
     ADD_COLUMN_TO_SELECT_STATEMENT = ("add column to select statement", False, False)
+    ADD_JOIN_TO_FROM_STATEMENT = ("add join to from statement", False, False)
     APPOINTMENT_DATE = ("appointment date", False, True)
     APPOINTMENT_STATUS = ("appointment status", True, True)
     APPOINTMENT_TYPE = ("appointment type", False, True)

docs/utility-guides/SubjectSelectionQueryBuilder.md

@@ -64,8 +64,8 @@ This approach ensures injection-safe execution (defending against SQL injection
 
 ```python
 criteria = {
-    "nhs_number": "1234567890",
-    "screening_status": "invited"
+    "nhs number": "1234567890",
+    "screening status": "invited"
 }
 
 user = User(user_id=42, organisation=None)     # Optional; used for 'unchanged' logic
@@ -122,9 +122,9 @@ Example:
 
 ```python
 {
-  "subject_has_event_status": "ES01",
-  "subject_age": "> 60",
-  "date_of_death": "null"
+  "subject has event status": "ES01",
+  "subject age": "> 60",
+  "date of death": "null"
 }
 ```
 
@@ -134,12 +134,12 @@ Each of those triggers a different clause in the generated SQL.
 
 This gives the builder context about who’s requesting the query, including their organisation and permissions.
 
-Some criteria (like "USER_HUB" or "USER_ORGANISATION") don’t refer to a fixed hub code, but instead dynamically map to the hub or screening centre of the user running the search. That’s where this comes into play.
+Some criteria (like "USER HUB" or "USER ORGANISATION") don’t refer to a fixed hub code, but instead dynamically map to the hub or screening centre of the user running the search. That’s where this comes into play.
 
 Example:
 
 ```python
-"SUBJECT_HUB_CODE": "USER_HUB"
+"SUBJECT HUB CODE": "USER HUB"
 ```
 
 This means “filter by the hub assigned to this user’s organisation,” not a fixed hub like ABC.

subject_criteria_builder/criteria.json

@@ -4891,5 +4891,10 @@
     "key": "ADD_COLUMN_TO_SELECT_STATEMENT",
     "value_source": "",
     "notes": "Enter the name of the column to add to the select statement, also specify the prefix. E.g. ss.screening_subject_id."
+  },
+  {
+    "key": "ADD_JOIN_TO_FROM_STATEMENT",
+    "value_source": "",
+    "notes": "Enter the join you wish to add to the query. E.g. 'INNER JOIN sd_address_t adds ON adds.contact_id = c.contact_id'"
   }
 ]

utils/oracle/subject_selection_query_builder.py

@@ -716,6 +716,8 @@ def _dispatch_criteria_key(self, user: "User", subject: "Subject") -> None:
             # ------------------------------------------------------------------------
             case SubjectSelectionCriteriaKey.ADD_COLUMN_TO_SELECT_STATEMENT:
                 self._add_extra_column_to_select_statement()
+            case SubjectSelectionCriteriaKey.ADD_JOIN_TO_FROM_STATEMENT:
+                self._add_extra_join_to_from_statement()
             # ------------------------------------------------------------------------
             # 🛑 Fallback: Unmatched Criteria Key
             # ------------------------------------------------------------------------
@@ -792,6 +794,12 @@ def _add_extra_column_to_select_statement(self) -> None:
         """
         self.sql_select.append(f", {self.criteria_value}")
 
+    def _add_extra_join_to_from_statement(self) -> None:
+        """
+        Adds extra joins to the FROM statement.
+        """
+        self.sql_from.append(f" {self.criteria_value} ")
+
     def _add_criteria_nhs_number(self) -> None:
         """
         Adds a check for the subject's NHS number