Skip to content

Commit 9f44616

Browse files
adrianoaru-nhsadrianoaru-nhs
committed
Updating and creating markdown docs
1 parent 30f3d56 commit 9f44616

File tree

3 files changed

+130
-2
lines changed

3 files changed

+130
-2
lines changed

‎docs/utility-guides/CallAndRecallUtils.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Utility Guide: Call and Recall
2+
3+
The **Call and Recall utility** provides helper methods for executing Call and Recall stored procedures in BCSS.<br>
4+
These utilities interact directly with the **OracleDB** backend to run failsafe checks and initiate FOBT screening invitations.
5+
6+
## Table of Contents
7+
8+
- [Utility Guide: Call and Recall](#utility-guide-call-and-recall)
9+
- [Table of Contents](#table-of-contents)
10+
- [Summary of Utility Methods](#summary-of-utility-methods)
11+
- [Main Methods](#main-methods)
12+
- [`run_failsafe`](#run_failsafe)
13+
- [`invite_subject_for_fobt_screening`](#invite_subject_for_fobt_screening)
14+
- [Supporting Classes](#supporting-classes)
15+
- [Example Usage](#example-usage)
16+
17+
---
18+
19+
## Summary of Utility Methods
20+
21+
| Method | Purpose | Key Arguments | Expected Behaviour |
22+
|----------------------------------------|-------------------------------------------------------------------------|--------------------------------------|--------------------|
23+
| `run_failsafe` | Runs the **failsafe trawl** for a given subject. | `nhs_no` (`str`) | Executes stored procedure `pkg_fobt_call.p_failsafe_trawl` and checks success. |
24+
| `invite_subject_for_fobt_screening` | Transitions a subject into an **invited state** for FOBT screening. | `nhs_no` (`str`), `user_role` (`UserRoleType`) | Executes database transition (ID `58`) to create an FOBT episode. |
25+
26+
---
27+
28+
## Main Methods
29+
30+
### `run_failsafe`
31+
32+
Runs the failsafe trawl stored procedure for a subject identified by their NHS number.
33+
34+
**Arguments:**
35+
36+
- `nhs_no` (`str`): The NHS number of the subject.
37+
38+
**How it works:**
39+
40+
1. Looks up the subject ID for the provided NHS number.
41+
2. Connects to the OracleDB with a 30-second call timeout.
42+
3. Executes `pkg_fobt_call.p_failsafe_trawl`.
43+
4. Asserts that the stored procedure reports success.
44+
5. Cleans up database connections and cursors.
45+
6. Logs success/failure.
46+
47+
**Raises:**
48+
49+
- `AssertionError` if the stored procedure does not report success.
50+
- Database connection errors if OracleDB cannot be accessed.
51+
52+
---
53+
54+
### `invite_subject_for_fobt_screening`
55+
56+
Transitions the subject into an **invited state** for FOBT screening.
57+
58+
**Arguments:**
59+
60+
- `nhs_no` (`str`): The NHS number of the subject.
61+
- `user_role` (`UserRoleType`): The role of the user initiating the transition.
62+
63+
**How it works:**
64+
65+
1. Resolves the subject ID for the given NHS number.
66+
2. Fetches the **PIO user ID** for the given `user_role` from the `UserRepository`.
67+
3. Creates a `DatabaseTransitionParameters` object with:
68+
- `transition_id = 58` (invite to FOBT screening),
69+
- `subject_id` for the subject,
70+
- `user_id` of the PIO,
71+
- `rollback_on_failure = 'Y'`.
72+
4. Executes the transition using `GeneralRepository`.
73+
5. Logs success/failure.
74+
75+
**Raises:**
76+
77+
- `oracledb.DatabaseError` if the stored procedure execution fails.
78+
79+
---
80+
81+
## Supporting Classes
82+
83+
These classes are required by the utility:
84+
85+
- `OracleDB` — Provides database connection and helper functions (e.g. resolve subject ID from NHS number).
86+
- `GeneralRepository` — Executes transitions in the database.
87+
- `DatabaseTransitionParameters` — Holds configuration for a transition (IDs, rollback policy).
88+
- `UserRoleType` — Enum-like class describing different user roles.
89+
- `UserRepository` — Maps user roles to PIO IDs.
90+
91+
---
92+
93+
## Example Usage
94+
95+
```python
96+
from utils.call_and_recall_utils import CallAndRecallUtils
97+
from classes.user_role_type import UserRoleType
98+
99+
# Log in with a user and populate the user_role variable
100+
user_role = UserTools.user_login(
101+
page, "Hub Manager State Registered at BCS01", return_role_type=True
102+
)
103+
104+
# Create the utility
105+
call_and_recall = CallAndRecallUtils()
106+
107+
# Example 1: Run failsafe for a subject
108+
call_and_recall.run_failsafe("9434765919")
109+
110+
# Example 2: Invite a subject to FOBT screening
111+
call_and_recall.invite_subject_for_fobt_screening(
112+
nhs_no="9434765919",
113+
user_role=user_role,
114+
)
115+
```

‎docs/utility-guides/FitKit.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ from utils.fit_kit import FitKitGeneration
4040
### Required Arguments
4141

4242
- `create_fit_id_df`: Requires `tk_type_id` (int), `hub_id` (int), and `no_of_kits_to_retrieve` (int).
43+
- `get_fit_kit_for_subject`: Requireds `nhs_no` (str), `logged` (boolean), `read` (boolean).
4344

4445
### Key Methods
4546

@@ -53,6 +54,14 @@ from utils.fit_kit import FitKitGeneration
5354
3. **`convert_kit_id_to_fit_device_id(kit_id: str) -> str`**
5455
- Converts a kit ID into a FIT Device ID by appending an expiry date and a fixed suffix.
5556

57+
4. **`get_fit_kit_for_subject_sql(self, nhs_no: str, logged: bool, read: bool) -> str:`**
58+
- Retrieves the FIT kit information for a specific subject based on their NHS number.
59+
- **Arguments:**
60+
- **nhs_no (str):** The subject's NHS number
61+
- **logged (bool):** Whether to look for logged kits.
62+
- **read (bool):** Whether to look for read kits.
63+
- **Returns:** A string containing the fit device id of the subject matching the provided criteria.
64+
5665
> **Tip:**
5766
> To obtain a pandas DataFrame containing a list of FIT Kits to use, you only need to call the `create_fit_id_df` method. This method internally calls the other two methods to generate the correct check digits and expiration tags.
5867
@@ -92,6 +101,7 @@ from utils.fit_kit import FitKitLogged
92101

93102
- `process_kit_data`: Requires `smokescreen_properties` (dict)
94103
- `split_fit_kits`: Requires `kit_id_df` (pd.DataFrame), `smokescreen_properties` (dict)
104+
- `read_latest_logged_kit`: Requires `user` (UserRoleType), `kit_type` (int), `kit` (str), `kit_result` (str)
95105

96106
### Key Methods
97107

@@ -103,6 +113,9 @@ from utils.fit_kit import FitKitLogged
103113
- Splits the DataFrame into two: one for normal kits and one for abnormal kits, based on the numbers specified in `smokescreen_properties`.
104114
- **Returns:** A tuple containing two DataFrames: `(normal_fit_kit_df, abnormal_fit_kit_df)`.
105115

116+
3. **`read_latest_logged_kit(user: UserRoleType, kit_type: int, kit: str, kit_result: str) -> None`**
117+
- Reads the subject's latest logged FIT kit and updates its status/result.
118+
106119
> **How it works:**
107120
>
108121
> - The number of normal and abnormal kits is determined by the `c3_eng_number_of_normal_fit_kits` and `c3_eng_number_of_abnormal_fit_kits` keys in the `smokescreen_properties` dictionary.

‎utils/call_and_recall_utils.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ def invite_subject_for_fobt_screening(
6969
Raises:
7070
oracledb.DatabaseError: If there is an error in the execution of the stored procedure
7171
"""
72-
logging.info(f"START: invite_subject_for_fobt_screening for NHS No: {nhs_no}")
72+
logging.debug(f"START: invite_subject_for_fobt_screening for NHS No: {nhs_no}")
7373

7474
try:
7575
# Prepare parameters for the stored procedure
@@ -88,4 +88,4 @@ def invite_subject_for_fobt_screening(
8888
raise oracledb.DatabaseError(
8989
f"Error in invite_subject_for_fobt_screening for NHS No {nhs_no}: {e}"
9090
)
91-
logging.info(f"END: invite_subject_for_fobt_screening for NHS No: {nhs_no}")
91+
logging.debug(f"END: invite_subject_for_fobt_screening for NHS No: {nhs_no}")

0 commit comments

Comments
 (0)