Aptli

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.

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 work location
  • Order - Parent work order grouping related tasks
  • Resources - Array of required materials/labor (multi-resource support)

Resource Requirements: Each resource entry includes:

  • resource - Resource definition reference
  • volume - Quantity/amount required
  • uom - Unit of measure

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

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

Benefits:

  • Reduced map clutter
  • Grouped related materials (door + screws + adhesive = one task)
  • Progress tracked across all resources

Tasks Are Versioned

Unlike assignments/reports, tasks use 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 version (draft mode)
  2. Add/edit tasks in 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 overlapping geography

Task Geometry Types

Point Tasks

Single location work (equipment installation, inspection).

Example: Install junction box

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

Line Tasks

Linear work (cable runs, pipeline installation).

Example: Run 500m of fiber optic cable

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

Polygon Tasks

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

Example: Door-to-door outreach in neighborhood

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

Proximity Filtering

Find tasks near specific locations:

Use Case: Worker at warehouse wants tasks nearby

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

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

Task Usage in Work Orders

Tasks appear in assignments as available work options:

Flexible Allocation:

  • Work order might have 10 tasks available
  • Resource targets require completing 1-2 of those tasks
  • Worker chooses which tasks to complete (flexibility)
  • Over-allocation by 10x common (more options than targets)

Example:

Work order to John:
  Resource Targets: 50m cable, 20 junction boxes
  Available Tasks: [Task1, Task2, Task3, ... Task30]
  
John completes:
  Task 5: 30m cable, 12 junction boxes
  Task 12: 20m cable, 8 junction boxes
  Total: Met cable target, met junction box target

Worker had 30 task options to meet targets - high flexibility.

Task Progress Tracking

Calculation: Progress = Average completion across all resources

Example:

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

Visual Indicators:

  • Progress bar: Green ≥100%, Yellow ≥50%, Red <50%
  • Geometry indicator: Green check if valid point/line/polygon
  • Used in: Shows which assignments/reports reference this task

Creating Tasks

Access Required: tasksCreate admin right

Workflow:

  1. Navigate to Fulfillment → Tasks
  2. Create new version (or edit existing draft)
  3. Click "Add Task" in version
  4. Fill basic info (name, description)
  5. Select order (parent grouping)
  6. Click map to set geometry
  7. Add resources (can add multiple)
  8. Save task in draft
  9. Commit version when planning complete

Best Practices:

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

Bulk Task Generation

Create many similar tasks efficiently:

Scenario: Install 100 junction boxes at different buildings

Method 1: Import from GeoJSON

  1. Create GeoJSON with 100 points
  2. Each feature has properties: name, description, resources
  3. Import → creates 100 tasks in one version

Method 2: Generate from Map Selection

  1. Select 100 existing building features on map
  2. Click "Generate Tasks"
  3. Choose task template (resource requirements)
  4. Creates task at each building location

Method 3: Copy Existing Task

  1. Select task with correct resource configuration
  2. Click "Duplicate Task"
  3. Edit geometry to new location
  4. Repeat for similar installations

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] — a comma-separated list of task IDs in the URL
  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, so you get one task per printed page

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.
  • No new server work is involved — the batch view reads the existing /api/tasks/get?_id=csv endpoint and renders each task using the same RecordDetail* components as the individual task page, so the printed content matches what you'd get printing tasks one-by-one.

Task Validation

Before version commit, system validates:

Spatial Conflicts:

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

Resource Availability:

  • Warning if required resources 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 draft version
  2. Commit - Version committed, tasks become official
  3. Work Order - Tasks added to worker assignments (availableTasks array)
  4. Execution - Worker completes some of the available tasks
  5. Reporting - Worker links the completed task in their field report
  6. Progress - Task progress updated based on completed work
  7. Completion - When all resources at 100%, task marked complete

Task Reuse: Tasks can appear in multiple assignments:

  • Same task assigned to multiple workers (split work)
  • Task partially completed by one worker, finished by another
  • Progress aggregated across all reports

Viewing Task Details

Task Detail Page Shows:

  • Basic information and geometry
  • Resource requirements list
  • Progress bar and percentage
  • Used in: Work orders and reports referencing this task
  • Version history (which versions modified this task)
  • Spatial relation to nearby tasks

Map View:

  • Color-coded by progress (red = not started, yellow = partial, green = complete)
  • Geometry type indicators (icon for point, line style, polygon fill)
  • Clickable for quick detail popup
  • Filterable by order, progress, proximity