Tasks

Tasks represent individual units of planned field work, each with a map location, resource requirements (materials, equipment, labour), and progress tracking. A task might be installing a junction box at a specific building, running 500 m of cable along a route, or conducting an inspection in a defined area. Tasks are versioned, so teams can plan offline, batch-create work, and roll back changes before committing to the shared dataset.

Where Tasks Fit in the Hierarchy

Project  (campaign grouping)
  └── Task  ← you are here
        └── Work Order  (assignment of this task to a worker or team)
              └── Report  (worker's record of what was actually done)

A task is the core planning record. It carries the geometry (where), the resource requirements (what), and the progress data. Work orders assign it to people. Reports fill in what was actually done, rolling progress back up to the task.

Task Structure

Tasks page showing planned work with progress tracking and multi-resource requirements

Basic Fields:

• Name — Descriptive task name
• Description — Detailed work instructions
• Geometry — Point, line, or polygon showing the work location
• Resources — Array of required materials and labour (multi-resource support)

Resource Requirements: Each resource entry includes:

• resource — Resource definition reference
• volume — Quantity required
• uom — Unit of measure
• assignedTo — Person responsible for picking up this specific resource line (optional — see Per-Resource Assignment)

Example:

Task: "Install network junction box at Building 42"
Geometry: Point (lat: 40.7128, lng: -74.0060)
Resources: [
  { resource: "Junction Box",    volume: 1,  uom: "units" },
  { resource: "Cat6 Cable",      volume: 15, uom: "meters" },
  { resource: "Mounting Screws", volume: 8,  uom: "units" },
  { resource: "Electrician",     volume: 2,  uom: "hours" }
]

Multi-Resource Tasks

Prior system: one resource per task

• Problem: complex work creates excessive map markers
• Example: 100 installations × 4 resources = 400 map points

Current system: multiple resources per task

• Single map marker represents the complete work package
• Same example: 100 map points (one per installation)
• Cleaner map, easier spatial planning

Per-Resource Assignment

Each resource line on a task can be assigned to a specific person. This lets planners designate who is responsible for picking up each material or completing each labour component — at the line level, not just at the work-order level.

How assignment works:

• In the task detail, each resource row has an Assigned To column
• The column appears automatically when any row in the task carries an assignment; it stays hidden when no assignments are set
• Assigning someone to a resource line does not reserve inventory — it records who is expected to pick up and deliver that item
• Actual pickup state (who picked up, how much, when) is tracked through the transaction ledger, not on the task itself

Why track at the resource level?

A single task can have many resource lines (materials, equipment, labour), and those lines may be spread across multiple work orders and crews. Per-resource assignment fills the gap: a planner can say "Alice fetches the 50 m of conduit for this task, Bob handles the junction boxes." Each person gets a scoped view of exactly what they need to collect — no ambiguity about who is responsible for which item.

Filtering by your resource assignments:

The Work Orders page has a My Resource Assignments filter that shows work orders whose linked task has a resource line assigned to you. Workers can use this to go straight to their specific material pickups without scanning the whole task list.

Send Assignments notification:

Once resource assignments are set, the Send Assignments action on the tasks page dispatches notifications to all assignees. Each person receives a single combined message covering their work orders (name, due date, link) plus one QR code per assigned resource line. The QR code is the pickup authorization — the worker scans it at the warehouse to collect their specific item. Pickup is recorded as a transaction automatically on scan.

The Send Assignments action is available both as a per-row action on individual tasks and as a bulk operation when multiple tasks are selected in the table.

Tasks Are Versioned

Unlike work orders and reports, tasks use the version/commit workflow:

Why Versioned:

• Admins design work areas offline (subway tunnels, remote sites)
• Spatial conflict detection needed (overlapping geography)
• Batch operations common (redesign entire campaign)
• Rollback valuable (undo entire planning change)

Workflow:

1. Create a version (draft mode)
2. Add/edit tasks in the draft
3. Spatial validation (check for overlaps)
4. Commit version → tasks become "official"
5. Workers see committed tasks in assignments

Offline Collaboration: Multiple admins can create separate versions:

• Admin A: Plan north region tasks
• Admin B: Plan south region tasks
• Both work offline, commit later
• Conflict resolution if geographies overlap

Task Geometry Types

Point Tasks

Single location work (equipment installation, inspection).

Geometry: { type: "Point", coordinates: [lng, lat] }

Line Tasks

Linear work (cable runs, pipeline installation).

Geometry: { type: "LineString", coordinates: [[lng1,lat1], [lng2,lat2], ...] }

Polygon Tasks

Area-based work (coverage zones, service areas).

Geometry: { type: "Polygon", coordinates: [[[lng1,lat1], ...]] }

Proximity Filtering

Find tasks near specific locations:

1. Open the Tasks page
2. Click Filter Nearby
3. Drag the map marker to a location
4. Set distance (e.g., 5 km)
5. Table shows only tasks within that radius

Row Action: click "Filter Nearby" on a task row → auto-sets proximity to that task's location.

Task Usage in Work Orders

Each work order links to one task — the specific task the worker is being assigned to execute. Work orders cannot span multiple tasks; if work crosses task boundaries, create a work order per task or use ad-hoc standalone work orders.

A task can be referenced by multiple work orders — useful when splitting a large task across several crews or when work is phased over multiple days.

Example:

Task: "Run cable on floor 3" 
  Resources: 200m cable, 4 hours labour

Work Order A (Morning crew):
  Task: "Run cable on floor 3"
  Resource Targets: 100m cable, 2 hours labour

Work Order B (Afternoon crew):
  Task: "Run cable on floor 3"
  Resource Targets: 100m cable, 2 hours labour

Both work orders reference the same task; reports from both roll into the task's progress calculation.

Task Progress Tracking

Calculation: Progress = Average completion across all resource lines

Example:

Task with 3 resources:
  - Cat6 Cable: 10m required, 5m completed = 50%
  - Screws: 8 required, 8 completed = 100%
  - Labour: 2 hours required, 0 hours reported = 0%
  
Overall progress = (50% + 100% + 0%) / 3 = 50%

Visual Indicators:

• Progress bar: Green ≥ 100%, Yellow ≥ 50%, Red < 50%

Creating Tasks

Access Required: tasksCreate admin right

Workflow:

1. Navigate to Fulfillment → Tasks
2. Create a new version (or edit an existing draft)
3. Click Add Task
4. Fill basic info (name, description)
5. Click the map to set geometry
6. Add resource lines (can add multiple)
7. Set per-resource assignments if needed
8. Save the task in draft
9. Commit the version when planning is complete

Best Practices:

• Group related materials in a single task (reduces map clutter)
• Use consistent naming (e.g., "Install — Junction Box — Building 42")
• Set realistic resource volumes (informs inventory planning)
• Include labour resources (helps staffing calculations)

Bulk Task Generation

Method 1: Import from GeoJSON

1. Create a GeoJSON file with one feature per task
2. Each feature carries properties: name, description, resources
3. Import → creates all tasks in one version

Method 2: Generate from Map Selection

1. Select existing features on the map
2. Click Generate Tasks
3. Choose a resource configuration
4. One task created at each selected location

Method 3: Duplicate a Task

1. Select a task with the correct resource configuration
2. Click Duplicate
3. Edit the geometry to the new location

Batch Print Tasks

A project may contain dozens or hundreds of tasks. Rather than printing each one from its detail page, use the project-level Print all tasks action:

1. Open the parent project's detail page (/fulfillment/projects/:id)
2. Click Print all tasks in the header
3. The batch print view opens at /fulfillment/tasks/batch/[ids]
4. Screen shows 10 tasks per page (paginated, CSS-driven — all records are in the DOM so printing emits everything)
5. Print the page — each task is separated by a hard page break

Notes:

• Safety cap: the batch view is limited to 200 tasks per print run. If the project exceeds this, a banner warns you and tasks beyond 200 are truncated — split the print into smaller batches if needed.
• Each task renders with the same layout as its individual task page.

Task Validation

Before a version is committed, the system validates:

Spatial Conflicts:

• Overlapping polygons (two tasks covering the same area)
• Point tasks too close together (configurable threshold)
• Line tasks crossing restricted zones

Resource Availability:

• Warning if required resources are not in inventory
• Doesn't block commit (tasks may be future-dated)
• Helps procurement planning

Geometry Validity:

• Points must have valid coordinates
• Lines must have at least 2 points
• Polygons must close (first point = last point)

Task Work Order Lifecycle

Typical Flow:

1. Planning — Admin creates tasks in a draft version
2. Commit — Version committed, tasks become official
3. Work Order — A work order is created, linking to this task and assigning it to a worker
4. Execution — Worker executes the task, possibly over multiple work orders
5. Reporting — Worker submits a report referencing this task
6. Progress — Task progress updates based on all reports referencing it
7. Completion — When all resources reach 100%, the task is effectively complete
8. Graduation — If the completing work order has a Graduates To layer set, the task's geometry is placed or moved on the map (see Task Graduation below)

Task Reuse: Tasks can be referenced by multiple work orders:

• Split large tasks across multiple crews
• Partial completion by one worker, finished by another
• Progress aggregated across all reports

Task Graduation

Task graduation is how completed field work becomes part of the shared GIS dataset. When a work order that links to a task is completed, it can automatically place or advance the task's geometry on the map.

Setting Up Graduation

In the work order create or edit form, set the Graduates To field to the target layer. When that work order is marked completed, the graduation hook fires:

• No existing map feature → a new feature is created in the target layer, using the task's geometry and properties. A sourceTaskId link is stamped on the feature for traceability.
• Existing map feature → the feature is moved to the target layer. The feature retains the same ID — nothing is duplicated.

The task itself is never deleted or archived. It remains as the permanent planning and work record.

Multi-Stage Graduation

A task can graduate through multiple layers as successive work orders complete. Example for a fibre network installation:

Each completion just re-points which layer shows the task's geometry — no re-linking of the task itself is needed.

Graduation Log

The task detail view → Location tab shows a Graduation Log: a timestamped timeline of every layer move, including which work order triggered each transition. Use this to audit the lifecycle of a field installation.

Viewing Task Details

Task Detail Page Shows:

• Basic information and geometry
• Resource requirements list with per-resource assignment
• Progress bar and percentage
• Work orders referencing this task
• Reports that have recorded work against this task
• Graduation log (Location tab)