[Uganda project - Technoforte team] PRN Validation Before Printing Certificate – Architectural Limitation & Proposal

[Abhay-Dev-Gautam]

Summary

We are implementing a PRN (Payment Reference Number) flow for late birth registrations, where a PRN is generated during declaration and must be validated before allowing certificate printing.

While a temporary workaround stores the PRN in a form field, this approach has proven unreliable and insufficient for enforcing validation during the PRINT_CERTIFICATE action. This discussion outlines the limitation encountered and proposes a core-level solution.

---

Background / Context

• PRN (Payment Reference Number) is generated server-side via an external provider API during DECLARE.
• Currently, PRN is temporarily stored in a declaration field (e.g. child.prnNumber)
• Requirement:
  • User must enter PRN before printing
  • Printing should be blocked if PRN is invalid or missing

Conceptually, PRN behaves very similarly to trackingId:

• System-generated
• Immutable
• Must be accessible during PRINT_CERTIFICATE
• Should not rely on form fields

---

Current Implementation (Workaround)

• PRN is generated during DECLARE
• Stored in a declaration field for:
  • Email notification
  • UI visibility

This works functionally, but introduces architectural issues (explained below).

---

Problem Observed

During implementation, we found that PRN validation cannot be reliably enforced in the PRINT_CERTIFICATE flow due to framework constraints.

---

1. PRINT_CERTIFICATE has no reliable access to user-entered form data

• pendingAction.declaration is empty for PRINT actions
• Aggregated declaration does not include current PRINT form inputs
• Backend handlers cannot reliably read PRN entered during print

---

2. Form-level validators cannot access event metadata

• Custom validators do not have access to event.trackingId or other event-level fields
• This makes it impossible to compare a user-entered PRN with a trusted server-side value

---

3. UI-only validation is not enforceable

• requireCompletionToContinue and validators only affect navigation
• They do not prevent the PRINT action from being executed server-side

---

4. Storing PRN as form data is unreliable

• Form fields may be hidden or skipped
• PRN is not conceptually form data
• It is a system-generated identifier similar to trackingId or registrationNumber

---

Key Insight

PRN is event metadata, not form data

Because of this:

• PRN should not live in declaration fields
• PRN should be persisted at the event level
• Validation must happen server-side before allowing PRINT_CERTIFICATE

---

Proposed Solution (Core-Level)

---

1. Persist PRN at the Event Level

• Store PRN in PostgreSQL alongside trackingId
• Make it accessible via event metadata (similar to event.trackingId)

---

2. Introduce a Server-Side Print Guard

• Block PRINT_CERTIFICATE unless:
  • PRN exists on the event
  • Entered PRN matches stored PRN
• This guard should live in core / country-config API, not UI forms

---

3. Keep UI Validation as a Convenience Only

• UI can still prompt user to enter PRN
• Enforcement must happen server-side

---

Why Tracking ID Was Not a Viable Substitute

As part of exploration, we attempted to validate using trackingId as a stand-in for PRN. While this proved that event-level data is accessible, it does not solve the real problem.

• trackingId is not user-entered
• It has no security or payment significance
• Validating it does not reflect PRN’s business requirement

This confirmed that the issue is architectural, not implementation-specific.

---

Questions for Core Team

1. Is persisting PRN as event-level metadata the recommended approach?
2. Is there an existing pattern for blocking PRINT_CERTIFICATE server-side based on custom validation?
3. Would a core-supported hook/guard for PRINT actions be acceptable for this use case?
4. If not, what is the recommended way to enforce mandatory validation before printing?

---

Environment

• OpenCRVS V1.9.6
• Event type: Birth Registration
• Action: PRINT_CERTIFICATE
• Country: Uganda
• Late registration PRN integration

[prinzab]

@Abhay-Dev-Gautam We have just finished a meeting with Aman and Prabakaran, with @jpye-finch as well to discuss this issue. Aman is going to be providing a list of the use cases that is going to be supported with regards to the PRN. Once he does this, we'll internally review and come back to you with an approach.

CC: @euanmillar

[euanmillar]

@Abhay-Dev-Gautam your architectural decision making in how to implement this is in contradiction with OpenCRVS design and you need to re-think your approach. We are not going to introduce the ability to customise metadata with random ids at this time I'm afraid.

You say "Should not rely on form fields" - can you explain why? Using HTTP components in a form can request generation of a field via an API and it can be immutable, as the API can potentially store it for validation in a custom DB and it can pre-populate a disabled field. See some docs on this here re "API integration within an event form": If it is impossible to change by the user, and exists in a custom DB you could validate it there.

Please can you block PRINT_CERTIFICATE on the client side via navigation or print form configuration using validation logic. Why is blocking server-side a necessity? What are you mitigating against? See below comments for other ideas to achieve what you might need ...

[euanmillar]

You can also use HTTP components within your print form to validate using an external API. Build whatever you want in any middleware you like to do what you need (explained below). A LINK_BUTTON component can also redirect to a payment gateway.

[euanmillar]

If you investigate the workings of our mosip-api middleware you can see it utilises an SQLite DB. Why dont you build a similar middleware and store what you need there during DECLARE. Then you can validate it from the client during print collection.

The PRINT_CERTIFICATE action on the server side serves a notification and tracking purpose. OpenCRVS is designed to generate a PDF for printing on the client side. Connectivity concerns have driven this decision. Some countries make use of entirely offline certificate printing capabilities.