Aptli

Validations

Validations are the quality control step after a report is submitted. Validations live alongside the report they apply to — shown as a traffic-light badge on the reports list and a status-grouped badge row in the expanded report view. There is no separate validations navigation page.

A supervisor or QC inspector opens a report, clicks a validation badge to view or create a validation in an overlay modal, verifies measurements and installation quality, records issues as free-form comments in a shared thread, and sets the overall status. The status determines whether payment is released or the worker needs to correct their work.

Where Validations Live

Reports list: Every report row shows an aggregate validation badge (grey/red/yellow/green) in its own column. The badge displays the most-severe status with a count — for example, FAILED · 3 if there are three failed validations on that report. Hovering the badge reveals a per-status breakdown like failed: 1, passed: 2.

Expanded report: Opening a report in the list shows a validation badge row grouped by status. Clicking any badge opens the ValidationEditModal — a full-featured overlay for viewing, editing, or creating a validation without leaving the report.

Mobile: The mobile supervisor queue at /m/validations lists validations assigned to you. Mobile validators work through the queue from a dedicated list.

Print view: The standalone /fulfillment/validations/:id page is a print-only view. The modal has a Print button in its header that opens the print page in a new tab. Deep-links from old bookmarks still resolve.

Opening a Validation

From the reports list:

  1. Find the report you want to validate
  2. Click the validation badge in the report row (or expand the row to see badges grouped by status)
  3. The ValidationEditModal opens over the page
  4. View the existing validation, or click Create validation if none exists
  5. Review the work, leave comments, set status, and save

Access gates:

  • Viewing validations requires no special right
  • Creating requires the validationsCreate admin right
  • Editing requires the validationsUpdate admin right

Unified Submit (Report + Validation Together)

When you have both the report and a validation open, the Submit button saves everything together — report edits and validation edits are committed in one step. You do not save validations separately from the report.

Validation Structure

Core Fields:

  • Report — Reference to the validated report (set automatically when you open from the report)
  • Validator — User who performed the QC check
  • Status — pass, fail, needs-revision, approved-with-notes
  • Validation Date — When QC was performed
  • Comments — Threaded discussion between validator and worker (see below)
  • Attachments — Photos and documents supporting the QC decision

Discussion Comments

Validators and workers communicate through a shared comment thread on the validation record. There are no structured issue types or severity levels — comments are free-form text, and the validator sets the overall status independently.

How it works:

  • The validator leaves comments describing issues found, measurements taken, or context for the status decision
  • The worker can reply in the same thread (editable until payment is released)
  • Both parties see the full history of the conversation

Example comment flow:

Validator: "Cable measured 42 m on site vs. 45 m reported. Junction box at pole 3 is not properly weather-sealed. Setting to needs-revision."

Worker: "Confirmed — cable run had to detour around an obstacle. Will reseal the junction box on Friday."

Validator: "Reseal confirmed on revisit. Updating to pass."

Comments preserve the full context of the QC process for audit purposes — who said what, and when.

Validation Status

pass — Work meets quality standards

  • Measurements accurate
  • Installation per specifications
  • Materials properly documented

fail — Work does not meet standards

  • Critical quality issues or significant discrepancies
  • Requires rework before payment

needs-revision — Minor issues, corrections needed

  • Small measurement differences or incomplete documentation
  • Worker addresses issues and requests re-validation

approved-with-notes — Acceptable with caveats

  • Work meets minimum standards
  • Issues noted in comments for tracking
  • Full payment released

Creating Validations

Access Required: validationsCreate admin right

Workflow:

  1. Navigate to Fulfillment → Reports
  2. Open (or expand) the report you want to validate
  3. Click a validation badge to open the ValidationEditModal, or click Create validation if none exists
  4. Review the work completed against physical site observations, photos, or data
  5. Leave comments describing any issues, measurements, or observations
  6. Upload photos or documents supporting your QC decision
  7. Set the overall status (pass / fail / needs-revision / approved-with-notes)
  8. Click Submit to save the report and validation edits together

Mobile validator workflow (/m/validations):

  • GPS context to confirm which site you're at
  • Camera integration for attaching quality photos
  • Auto-save to device while you work; queued for the server and submitted when back online

Validation Workflow

Typical Process:

  1. Report Submitted — Worker completes and submits a report
  2. Badge Visible — Reports list shows a grey "none" badge for reports without validations
  3. Validator Opens Report — Clicks the badge, opens the modal
  4. Site Visit — Validator visits the location (or reviews photos and data remotely)
  5. Measurements — Physical verification of work
  6. Photos — Document quality (good or bad)
  7. Comments — Record any discrepancies, observations, or instructions in the comment thread
  8. Status — Set pass / fail / needs-revision / approved-with-notes
  9. Submit — Saves report and validation atomically
  10. Follow-Up — If needs-revision, worker addresses issues and replies in comments
  11. Re-Validation — Re-open the badge, add a comment to the existing validation or create a new one
  12. Final Approval — Report approved, payment released

Filtering Reports by Validation Status

The reports list accepts a validation status filter:

  • all — every report (default)
  • none — reports without any validation (needs QC attention)
  • any — reports with at least one validation
  • failed — reports with at least one failed validation
  • revision — reports with at least one needs-revision validation
  • passed — reports where all validations pass

Custom filters:

  • Validator (who performed QC)
  • Date range

Payment Integration

Validations control payment release:

Payment Hold:

  • Reports with fail status → payment held
  • Reports with needs-revision → partial payment (configurable)

Payment Release:

  • pass or approved-with-notes → full payment released
  • needs-revision → partial payment, re-validation required before full release
  • fail → no payment, rework required

Financial Protection:

  • Prevents payment for substandard work
  • Incentivises quality
  • Comment thread serves as the audit trail for payment decisions

Best Practices

Timely Validation:

  • Use the reports list's none filter to find reports awaiting QC
  • Validate within 24–48 hours of report submission
  • Fresh evidence (materials still visible, worker still remembers) and faster payment to workers

Specific Comments:

  • Describe exactly what you measured and where (e.g., "42 m confirmed from pole 4 to the junction box at building 12, vs. 45 m reported")
  • Reference work completed items by name if you need to flag a specific line
  • Attach photos — they provide indisputable evidence

Constructive Feedback:

  • Frame issues as training opportunities
  • Explain why the issue matters (safety, standards, cost)
  • Offer concrete suggestions for correction

Consistent Standards:

  • Apply the same criteria to all workers
  • Document your quality standards so workers know what to expect
  • Calibrate across validators regularly to ensure consistency

Use the Print View for Hard Copies:

  • Open the ValidationEditModal on an existing validation
  • Click the Print button in the modal header
  • The print page opens in a new tab, ready for paper or PDF export

Validation Immutability

Soft Deletes: Validations can be marked deleted but stay in the database:

  • Preserves QC history
  • Maintains payment audit trail
  • viewDeleted admin right to see deleted validations

Edit Restrictions: After payment is released:

  • Validations become read-only (modal is view-only)
  • Corrections require a new validation with additional comments
  • Preserves financial integrity
  • Full comment history is always retained