In-Phone Validation

How In-Phone Validation Works

Form: NG-HTS 001 Client Intake | Version: v1.6 | Country: Nigeria

This page documents the automated real-time validation rules applied by the ScanForm mobile app at the moment a field worker photographs this form. If any check fails, the app immediately alerts the worker and prompts them to correct the paper form and retake the photo — before the data is submitted to the server. No human verifier is involved in this process.

flowchart LR
  A["📷 Photo taken\nby field worker"]
  B["🤖 OCR runs\non device"]
  C{"✅ All checks\npass?"}
  D["📤 Data submitted\nto server"]
  E["⚠️ Alert shown\nto worker"]
  F["📝 Worker corrects\npaper form"]

  A --> B --> C
  C -- Yes --> D
  C -- No --> E --> F --> A

Why validate on the phone?

Catching errors at the point of data capture — while the client and clinician are still present — is far cheaper than discovering them during data quality audits weeks later. In-phone validation closes the feedback loop instantly and prevents systematically missing or multi-selected fields from entering the database.

Key Concepts

Table 1

Concept	Meaning
In-Phone Validation — Concept Glossary
Record eligibility	A patient row is only validated if a minimum number of its key fields contain data. Fully blank rows (unregistered slots) are silently skipped to avoid false alerts.
boxals_threshold_for_eligibility	The minimum number of filled boxes in a field before that field counts as ‘active’ for eligibility purposes. Example: a date field with threshold 2 is only considered active if at least 2 of its 8 boxes are filled.
check__boxes__enough_filled	Required field check — fires if the field has zero filled boxes. Used for digit/letter box fields that must not be left blank.
check__checkboxes__enough_answers	Minimum-one bubble check — fires if no bubble is crossed in the group. Used for mandatory single-select questions.
check__checkboxes__not_too_many_answers	Maximum-one bubble check — fires if more than one bubble is crossed in the group. Used for all single-select questions to prevent accidental multi-selection.
Exactly-one pair	When both enough_answers and not_too_many_answers are applied to the same field, the combined effect is: exactly one bubble must be selected — no more, no less.
At-most-one (solo)	When only not_too_many_answers is applied, the field is optional but cannot have more than one bubble selected.
Discard criteria	If the discard bubble is marked on the form, all validation checks for that record are suppressed — the row is intentionally void.
PageNumberBlock(0)	Alert message references the left-hand page (Page 1) of the two-page photopack.
PageNumberBlock(1)	Alert message references the right-hand page (Page 2) of the two-page photopack.

Record Eligibility

Before any field-level check is evaluated, the app determines whether a given record (patient row) contains enough data to warrant validation. This prevents alerts on genuinely empty form slots.

Eligibility rule for this form:

A record is considered active when at least one key question field is filled (checked_groups_threshold = 1, with checked_groups = None meaning any registered field counts).
If the Discard both pages bubble (discardPage2) is marked, the record is unconditionally skipped — no checks run.
The minimum tries before a record can be skipped is 3 — the app will attempt to process the record at least three times before allowing it to be bypassed.

Validated Fields

Page 1 — Validated Fields

Table 2

Variable	Field Label	Check Type	Alert shown to worker
dateVisit	Date of Visit	🔴 Required	"Date of Visit" is required
referredFrom	Referred From	✅ Exactly one	"Referred From" requires exactly one option
testingSetting	Setting	✅ Exactly one	"Setting" requires exactly one option
modality	Modality	🔴 Required	"Modality" is required
sex	Sex	⚠️ At most one	"Sex" requires no more than one option
firstTimeVisit	First Time Visit	⚠️ At most one	"First Time Visit" requires no more than one option
maritalStatus	Marital Status	⚠️ At most one	"Marital Status" requires no more than one option
employmentStatusId	Employment Status	⚠️ At most one	"Employment Status" requires no more than one option
educationId	Education Level	⚠️ At most one	"Education Level" requires no more than one option
typeConsueling	Type of Session	⚠️ At most one	"Type of Session" requires no more than one option
previouslyTested	Previously tested within the last 3 months	⚠️ At most one	"Previously tested within the last 3 months" requires no more than one option
indexClient	Index Testing: Is client identified from an index client?	⚠️ At most one	"Index Testing: Is client identified from an index client?" requires no more than one option
relationWithIndexClient	If yes — relation with index client	⚠️ At most one	"If yes — relation with index client" requires no more than one option
pregnant	Client is Pregnant	⚠️ At most one	"Client is Pregnant" requires no more than one option
breastFeedingUnder6	Client breastfeeding < 6 months	⚠️ At most one	"Client breastfeeding < 6 months" requires no more than one option
breastFeedingOver6	Client breastfeeding > 6 months	⚠️ At most one	"Client breastfeeding > 6 months" requires no more than one option
previousTestedHIVNegative	Previously tested HIV negative	✅ Exactly one	"Previously tested HIV negative" requires exactly one option
timeLastHIVNegativeTestResult	Time of last HIV Negative test Results	⚠️ At most one	"Time of last HIV Negative test Results" requires no more than one option
clientInformHivTransRoutes	Client informed about HIV transmission routes	⚠️ At most one	"Client informed about HIV transmission routes" requires no more than one option
clientInformRiskkHivTrans	Client informed about risk factors for HIV transmission	⚠️ At most one	"Client informed about risk factors for HIV transmission" requires no more than one option
clientInformPreventingsHivTrans	Client informed on preventing HIV transmission methods	⚠️ At most one	"Client informed on preventing HIV transmission methods" requires no more than one option
clientInformPossibleTestResult	Client informed about possible test results	⚠️ At most one	"Client informed about possible test results" requires no more than one option
informConsentHivTest	Informed consent for HIV testing given	⚠️ At most one	"Informed consent for HIV testing given" requires no more than one option
everHadSexualIntercourse	Ever had sexual intercourse	✅ Exactly one	"Ever had sexual intercourse" requires exactly one option
moreThanOneSexPartnerLastThreeMonths	More than 1 sex partner	✅ Exactly one	"More than 1 sex partner" requires exactly one option
unprotectedVaginalSex	Unprotected Vaginal Sex	✅ Exactly one	"Unprotected Vaginal Sex" requires exactly one option
uprotectedAnalSex	Unprotected Anal Sex	✅ Exactly one	"Unprotected Anal Sex" requires exactly one option
bloodtransInlastThreeMonths	Blood transfusion in last 3 months	✅ Exactly one	"Blood transfusion in last 3 months" requires exactly one option
sexUnderInfluence	Sex under the influence of drugs and alcohol	✅ Exactly one	"Sex under the influence of drugs and alcohol" requires exactly one option
stiLastThreeMonths	History of STI	✅ Exactly one	"History of STI" requires exactly one option
uprotectedSexWithRegularPartnerLastThreeMonths	Unprotected sex with regular partner in last 3 months	✅ Exactly one	"Unprotected sex with regular partner in last 3 months" requires exactly one option
uprotectedSexWithCasualLastThreeMonths	Unprotected sex with casual partner in last 3 months	✅ Exactly one	"Unprotected sex with casual partner in last 3 months" requires exactly one option

Page 2 — Validated Fields

Table 3

Fields Not Validated In-Phone

The fields listed below exist on the form and are OCR-processed, but are not subject to in-phone automated validation. They appear as commented-out lines in the validation configuration. This is a deliberate design choice — either the field is considered optional, its validation is handled downstream in the data pipeline, or adding an in-phone check was judged likely to produce excessive false alerts in field conditions.

Table 4

Variable(s)	Field Label	Why not validated in-phone
Fields Present on Form but Not Validated In-Phone
photoTaken1 / photoTaken2	Photo taken (both pages)	Administrative flag — not a data quality concern
referredFromOther	Referred From — specify	Optional free-text; validated conditionally downstream
testingSettingOther	Setting — specify	Optional free-text; validated conditionally downstream
firstName / otherName / surname	Client names	Free-text letter boxes; completeness not enforced in-phone
age	Age (years)	Digit box; range checks handled in pipeline
numWives / numChildren	No. of wives / No. of children <5 years	Optional numeric fields
clientCode	Client Code	Pre-printed; format check handled in pipeline
recency	Recency Number	Optional identifier field
phoneNumber	Client Telephone Number	Optional contact detail
nearestLandmark / state / line / lga	Address fields	Free-text; completeness not enforced in-phone
indexClientCodeNew / indexClientCodeOld	Index Client Code (ScanForm / Legacy)	Conditional; only one should be filled; handled downstream
knowledgeAssessment	Knowledge Assessment Score	Derived sum; consistency check handled in pipeline
riskAssessment	Personal HIV Risk Assessment Score	Derived sum; consistency check handled in pipeline
tbScreening / stiScreening	TB / STI screening scores	Derived sums; consistency check handled in pipeline
sexPartnerRiskAssessment	Sex Partner Risk Assessment Score	Derived sum; consistency check handled in pipeline
condomProvidedToClientCount	How many condoms provided	Optional count; range check handled in pipeline
lubricantProvidedToClientCount	How many lubricants provided	Optional count; range check handled in pipeline
cd4FlowCytometry	CD4 Flow Cytometry (cells/m3)	Conditional (HIV+ only); range check handled in pipeline
date (completion)	Date signed by provider	Completion date; validated downstream

Summary

Figure 1: Distribution of in-phone check types across validated fields

Table 5

Metric	Value
In-Phone Validation Summary — HTS 001 Client Intake
Total fields on form (OCR-banded)	92
Fields with in-phone validation	73
Fields NOT validated in-phone	19
"Required" checks (must not be blank)	3
"Exactly one" checks (mandatory single-select)	13
"At most one" checks (optional single-select)	57
Page 1 validated fields	32
Page 2 validated fields	41
Discard criteria fields	1 (discardPage2)
Minimum attempts before record can be skipped	3

Important limitation

In-phone validation uses a lightweight on-device OCR that determines only whether a box contains a mark or not — it does not read the actual character written. This means checks can confirm that a bubble was selected, but cannot verify which bubble was selected. Full character-level OCR and value range checks are applied after submission during server-side processing.