Aptli

Work Fulfillment

Work fulfillment covers the full lifecycle of field operations — from planning what needs to be done, to assigning crews, authorizing material pickups, capturing completed work, and verifying quality. The system separates planning (versioned, supports offline collaboration) from execution (real-time, immediate confirmation for workers).

Core Workflow

Jobs (Versioned) → Work Orders (Real-Time) → Reports (Real-Time) → Validations (Real-Time)
   Planning              Allocation              Execution            Quality Check
Tasks are now Jobs. The §193 work-model restructure renamed Task to Job everywhere — pages, admin rights, and URLs (/fulfillment/jobs). It also added a second registry, Activities, as the work-side sibling of resources. The sections below use the new names.

Jobs - Planning Phase (Versioned)

  • Admins design work areas offline
  • Define resource requirements and locations
  • Batch operations supported (redesign entire campaign)
  • Version/commit workflow with rollback capability

Work Orders - Allocation Phase (Real-Time)

  • Assign a job to a worker with a timeline, resource targets, and an activity line
  • Generate QR pickup codes for protected inventory (two-step authorize + complete)
  • Immediate confirmation (no waiting for version commits)
  • Standalone work orders supported for ad-hoc or emergency work

Reports - Execution Phase (Real-Time)

  • Workers document completed work
  • Auto-create inventory consumption transactions
  • Payment calculation based on actual work completed
  • Ad-hoc work supported (no formal job required)

Validations - Quality Check Phase (Real-Time, Shown on Reports)

  • QC staff verify report accuracy
  • Validations appear as traffic-light badges on the reports page (no standalone list page)
  • Click a badge to open the validation modal — view, edit, or create without leaving the report
  • Leave comments in a shared thread; set overall status (pass / fail / needs-revision / approved-with-notes)
  • Status controls payment release
  • Mobile supervisor queue at /m/validations is preserved

Key Concepts

Real-Time Execution:

  • Work orders, reports, validations operate in real-time (not versioned)
  • Workers need immediate confirmation: "Do I have this work?"
  • Payment chain requires committed data (can't wait for admin version commit)
  • Stock visibility must be current (next QR scan needs accurate balance)

Resources vs Activities (§193):

  • Resources = the materials/equipment the work consumes. Declared on the job as resource lines. Catalogue: Resources.
  • Activities = the work itself. Declared on the work order as its activity line. Catalogue: Activities.
  • Both are optional. A job needs no resources; a work order needs no registered activity. Use them where structured tracking, pickup authorization, or activity-based pay earns its keep.

Multi-Resource Jobs:

  • Single job can require multiple resources (reduces map clutter)
  • Example: Door installation = 1 door + 12 screws + 0.5L adhesive
  • Progress calculated as average across all resources

Resource Targets vs Reservations:

  • Work orders show Resource Targets = goals to accomplish
  • NOT hard reservations (inventory not locked)
  • Allows flexibility when priorities change
  • Actual allocation happens at QR pickup scan time

Ad-Hoc Work:

  • Reports don't require formal jobs
  • Linking a job in the report is optional
  • Supports unplanned maintenance, issue responses
  • Still creates consumption transactions and payment data

Progress Calculation

Job-Level Progress

Average completion across all resources in the job.

Example:

Job A (10m cable + 10m digging):
  Cable: 5m completed / 10m = 50%
  Digging: 0m completed / 10m = 0%
  Progress = (50% + 0%) / 2 = 25%

Work Order-Level Progress

Progress toward assigned resource targets (not full job volumes).

Example:

Work order linked to Job A:
  Resource Targets: 10m cable, 20m conduit
  Reported: 5m cable, 10m conduit
  Progress = (5/10 + 10/20) / 2 = 50%

Key Rule: Calculate against the work order's resource targets, not the full job volume.

Over-Delivery Handling

Cap contributions at 100% per job, validation verifies accuracy.

Example:

Work order (20m cable, 40m digging):
  Reported: 10m cable, 60m digging
  Progress = (10/20 + min(60,40)/40) / 2 = 75%

Immutability Considerations

Work Orders and Reports Stay:

  • When infrastructure demolished, assignments/reports remain
  • Provides work history (what was done, when, by whom)
  • Soft deletes supported (configurable retention in app settings)
  • View Deleted admin right to see soft-deleted records

Job Versions Compressed:

  • Job version history compressed, never deleted
  • Rollback to previous job definitions possible
  • Spatial conflict detection (overlapping geography)

Transaction Audit Trail:

  • Consumption transactions from reports immutable
  • Cannot erase material usage
  • Corrections add new adjustment transactions

Sections

  • Projects - Group related jobs; track campaign-level progress
  • Jobs - Define work areas with resource requirements
  • Work Orders - Allocate work to users with inventory authorization and an activity line
  • Reports - Document completed work and consumption
  • Validations - Quality control managed as badges on the reports page

Related catalogues:

  • Resources - The materials, equipment, and labour a job consumes
  • Activities - The types of work a work order performs