<Feature> Retrieve Lost AID (with Face Capture & Match Verification)

[Varaniya201]

Purpose

As a registration_support_user, I should be able to search for an AID based on the resident details provided in order to identify the lost AID and share it with the respective resident. Before the AID is shared, the resident's identity must be confirmed through a live face capture and a face match against the biometric enrolled for that AID, so that the acknowledgement is only resent to a verified resident.

As part of this story, a new role named registration_support_user must be introduced in the system. Only users assigned this role are able to see and access the Retrieve Lost AID option in the admin portal.

Note: registration_support_user will be termed as User hereafter.

Pre-Requisites

• The registration_support_user role must be created and available in the system's identity/access management (IAM) configuration.
• A user must be assigned the registration_support_user role in the admin portal.
• User should have logged into the admin portal.
• Only users with the registration_support_user role should be able to view and access the Retrieve Lost AID feature in the admin portal.
• A working SBI (Secure Biometric Interface) compliant face capture device should be available and connected for the verification step.

Role & Access Control

• A new role registration_support_user is introduced as part of this feature.
• The role must be defined in the IAM/authorization configuration (e.g. realm roles in Keycloak) and made assignable to users through the admin portal's user/role management.
• The Retrieve Lost AID menu/sub-menu option is displayed in the admin portal only to users who hold the registration_support_user role; for all other users the option is hidden.
• Menu visibility is driven by the logged-in user's role(s) — the option must not appear for users without this role.
• The Retrieve Lost AID APIs/endpoints must also be authorized for the registration_support_user role at the backend, so that the functionality cannot be invoked by users lacking the role even if the UI control were bypassed.
• A user who does not hold the registration_support_user role attempting to access the feature directly should receive an appropriate authorization error (e.g. 403 Forbidden) handled via the standard error page.

Acceptance Criteria

Basic Flow

0. The Retrieve Lost AID option is visible in the admin portal sub-menu only because the logged-in User holds the registration_support_user role. (A user without this role does not see the option.)
1. User navigates to Retrieve Lost AID by clicking on the option present in the sub menu.
2. Once navigated, user should be able to view the below fields to search:
   • Registration From date & To date – Mandatory field (date field)
   • Full Name – text box which allows only alphabetical input.
   • Email – text box which allows alphabetic letters & special characters.
   • Phone Number – text box which allows only numerical input.
   • Location – the support user should be able to select region, province, city, zone or postal code and search (should be based on the ID Schema).
   • Centre Name
   • Type (Update, New)
   • Enquiry mode – (In person, Phone)
3. The User should select the date and must fill one or more inputs, then click on Search.
4. A list of resident details is displayed with details such as AID, Full Name, Centre Name, Registration Date, Status and an Action column with a View button placed on it.

Identity Verification via Face Capture & Match (new)

5. When the User clicks on the View button, a Resident Details pop-up is displayed with Name, AID, profile picture, enrolled date and status for the User to review.
6. To proceed, the User initiates Capture Face. The resident's live face is captured using the SBI-compliant biometric capture device.
7. The system performs a 1:1 face match of the captured live face against the face biometric enrolled for that AID.
8. On a successful match (match score greater than or equal to the configurable threshold):
   • A success indicator is displayed to the User.
   • The Resend Acknowledgement action (and the Print actions, where applicable) is enabled.
9. On an unsuccessful match (score below threshold):
   • A clear "Face did not match" message is displayed.
   • The User may recapture and retry up to the configurable number of attempts.
   • The Resend Acknowledgement and Print actions remain disabled until a successful match is achieved.
10. Once the face is matched and identity is verified, the User clicks on Resend Acknowledgement to send the acknowledgement with the AID through the registered email id and phone number.
11. The User should also be able to print the acknowledgement and share it with the resident.
12. If the status of the application process has already reached the printing stage and processing is completed, the User should be able to print the ID card and issue it to the resident.
13. Once the card is printed and issued, the status should be updated accordingly for the specific AID/UIN.
14. This feature should support multi-language. The alignment of the data on the screen should follow the same as the current flow: for the Arabic language, the screen should display text and alignment from right to left (RTL). This applies to the face capture/verification pop-up as well.

Alternate Flow – Records not available

• If the records are not available, an error message should be displayed:
  • Heading: 'Results not found.'
  • Message: 'Sorry! No Records Found'
  • Button: Ok — when the User clicks on the Ok button, the popup should be closed and the User should be navigated back to the search page.

Alternate Flow – Face match unsuccessful (new)

• When the captured face does not match the enrolled biometric:
  • A message "Face did not match. Please try again." is displayed.
  • The User can retry up to the configured number of attempts.
  • After all attempts are exhausted, the Resend Acknowledgement and Print actions stay disabled, and the User is returned to the resident list / search page. The attempt is recorded for audit.

Business Rules

• The Retrieve Lost AID option and its functionality are accessible only to users with the registration_support_user role; the option is hidden for all other users and the backend APIs are authorized for this role.
• Except for Registration From and To date, all other fields should not be mandatory.
• When the User searches for records, in addition to Registration From and To date, at least any one parameter needs to be provided by the User to continue the search. If not, an error should be displayed. Search criteria should follow an AND query.
• The total number of records displayed once the User clicks on Search should be restricted to 10. This should be configurable.
• The number of searches allowed per day per logged-in User should be restricted to 30. This value should be configurable.
• If the number of results for the search is more than the restricted number of records to display (i.e. 10), an alert should be displayed: "Please refine your search criteria and search again as the number of records fetched are more than configured."
• Resend Acknowledgement, Print Acknowledgement and Print ID Card actions are gated behind a successful 1:1 face match — they remain disabled until the captured face matches the enrolled biometric for the selected AID.
• The face match threshold (minimum acceptable match score) should be configurable.
• The number of face capture/match retry attempts per record should be configurable (e.g. 3).
• Every face capture and match attempt (success or failure) should be logged for audit, including the User, AID, timestamp and outcome (the captured image should not be persisted beyond what policy permits).
• If no face biometric is enrolled for the selected AID, the system should handle this per the configurable fallback policy (e.g. block the resend with an appropriate message, or allow a policy-controlled manual override), and the action should not silently succeed.

Data Fields

Retrieve Lost AID – Landing / Search Page

Field Name	Data Type	Field Type	Mandatory	Field Validations	Error Messages
Registration From Date	Date	Date Picker	Mandatory	—	Please Select Registration From Date
Registration To Date	Date	Date Picker	Mandatory	Future dates disabled; user cannot select a future date	Please Select Registration To Date
Email	Text	Text input	Non-Mandatory	Validate that the entered email is valid	Please enter a valid email
Phone	Number	Text input	Non-Mandatory	Only numerical values allowed	Please enter a valid phone number
Full Name	Text	Text input	Non-Mandatory	Allow alphanumerical values	—
Zone	Text	Dropdown	Non-Mandatory	Zones mapped to the user are listed; displayed based on ID schema	—
Province	Text	Dropdown	Non-Mandatory	Provinces mapped to the selected Zone are listed; displayed based on ID schema	—
Region	Text	Dropdown	Non-Mandatory	Regions mapped to the selected Province are listed; displayed based on ID schema	—
City	Text	Dropdown	Non-Mandatory	Cities mapped to the selected Region are listed; displayed based on ID schema	—
Postal Code	Text	Dropdown	Non-Mandatory	Postal codes mapped to the selected City and assigned to the current user; displayed based on ID schema	—
Centre Name	Text	Dropdown	Non-Mandatory	Centre Names mapped to the current user and selected city; displayed based on ID schema	—
Type	Text	Value: New / Update	Non-Mandatory	—	—

AID List (results table)

Column	Data Type	Notes
AID	Text	Alphanumeric value allowed
Full Name	Text	Alphanumeric value allowed
Centre Name	Text	Alphanumeric value allowed
Registration Date	Date	—
Action	Link	View button → resident details page

Resident Details (pop-up)

Field	Data Type	Notes
Application ID	Text	Non-editable, display only
Resident Full Name	Text	Non-editable, display only
Registered Date	Date	Non-editable, display only
Status	Text	Non-editable, display only
Profile Picture	Image	Non-editable, display only

Face Capture & Match (new – within Resident Details verification)

Field	Data Type	Field Type	Mandatory	Notes / Validations	Error Messages
Capture Face	Biometric (face image)	Capture control	Mandatory before resend/print	Live capture via SBI-compliant device; quality check on capture	Device not detected / Capture failed, please try again
Match Score	Number	Internal/display	System-generated	Compared against configurable threshold	—
Match Status	Text	Display	System-generated	Values: Matched / Not Matched	Face did not match. Please try again.

Exceptions

• As per the basic flow and data definition.
• Generic error pages — designed as per UX.
• Common error page to handle the below HTTP response status codes:
  • 5XX → 500, 502, 503, 504
  • 4XX → 400, 403, 404, 405, 415
• Should have a standard image as per the image embedded in UX indicating "Something went wrong". Only the error message should vary based on the error code.
• For all error messages, the main error message as per the error code can appear in bold, followed by the statement "Our experts are working hard to make things working again. Please try again later."
• All error messages should be retained for 10 seconds (configurable) and should disappear either at the end of 10 seconds or when the User clicks on the 'OK' button.

Face Capture & Match exceptions (new)

• Biometric device not connected / not detected — display an appropriate message prompting the User to connect the device and retry.
• Capture timeout or poor-quality capture — prompt the User to recapture.
• Face match service unavailable (5XX) — handle via the standard "Something went wrong" error page.
• No face biometric enrolled for the AID — display the appropriate message and handle per the configurable fallback policy (resend/print not enabled by default).

Reference UX

• Retrieve Lost RID (existing flow) for layout, alignment and error-handling patterns.