Aptli

Version Management

Aptli's version management system lets you edit maps and schematics on your device — at your desk, in subway tunnels, on remote sites, or anywhere with no connectivity — and submit your changes when you're ready. The system auto-saves your in-progress work to the device as you go, detects conflicts when two users have edited the same area, preserves permanent version history for every commit, and gives admins a review queue before field edits go live. This page covers how to use the version controls, the device-storage model, and how to resolve conflicts.

Mental Model — The Three-Sided Coin

The version manager has three faces, all working with the same on-device store:

  • Auto save to device — when your in-progress work is written to your device's storage. Cadence-only; doesn't talk to the server.
  • Work from device — what the app reads from when you open a list page (the device's local copy vs. live from the server). Read-side switch.
  • Version Manager window — the view of what's currently on your device (drafts, pending changes, commits) and the controls to act on them (Submit, Resync, etc.).

Together they let you keep editing through patchy connections, while keeping the team-side commit/review workflow intact for when you're ready to push.

Version Controls Interface

Version controls appear in two places depending on context:

On the map — the toolbar at the top of the map surface. On desktop they sit in the first row of icons next to the mode selector and data‑transfer button; on mobile they form the first line of the bottom navigation bar.

On list pages (Tasks, Work Orders, Reports, Projects, Inventory, etc.) — the action strip is in the upper-right of the filter row at the top of the page. The same Add, Undo, Redo, Resync, and Submit buttons appear there alongside any bulk-action controls. On mobile, list pages render the action strip at the top of the page inside the page header.

Primary Controls:

  • Undo - Revert the last change in current session
  • Redo - Reapply a change that was undone
  • Resync - Reset the in-memory state and replay every recorded change. Used to push pending diffs into the live records, or to recover after a corrupted session
  • Submit - Push all uncommitted changes to the server

Pending-changes glow: When there are diffs that haven't been applied to your in-memory records yet (typical after coming back from work-from-device mode, or after an undo), the Redo and Resync buttons pulse with a subtle green ring. This is your cue to apply or replay them — the app does not auto-walk through your pending diffs by design, so nothing changes silently behind your back.

Uncommitted Changes Badge:

  • Orange badge on SelectedFeatures button shows count of uncommitted changes
  • Updates reactively as you create/edit/delete features
  • Helps track pending work before Submit

How Versioning Works

(Server imports: background jobs such as automated data feeds create and commit their own versions. End users do not need to load these manually – imported features simply appear in the map once the job finishes.)

The Version/Commit Flow

1. Draft Created       → Change exists on your device
   ↓                     Feature has _uncommitted flag
   
2. Edit on device      → Modify properties, geometry, relationships
   ↓                     Auto-save persists to device storage as you go
   
3. Submit              → Push changes to server
   ↓                     Server creates version record
   
4. Conflict Check      → Server detects spatial/ID conflicts
   ↓                     Option to view others' drafts
   
5. Merge or Rollback   → Accept changes or undo
   ↓
   
6. Version Compressed  → Historical state preserved forever
                         Change becomes permanent record

Three Change Tracking Systems

Aptli uses different patterns based on workflow needs:

1. Versioned Models (Map Features, Layers, Schematics):

  • Changes stored on your device until Submit
  • _uncommitted flag tracks draft state
  • Conflicts detected via spatial analysis
  • Permanent version history (never deleted)

2. Real-Time Models (Assignments, Reports, Transactions):

  • Changes saved immediately to the server
  • No on-device drafting (execution requires confirmation)
  • No version history (operational data)

3. Tasks (Hybrid):

  • Versioned for planning phase (edit on device, push when ready)
  • Real-time for execution (assignments bypass versions)
  • See Work Fulfillment Guide for details

Auto Save to Device

Auto save is the cadence knob — it controls when the app writes your in-progress diffs from memory to your device's storage. It never talks to the server; the on-disk copy is purely there so a refresh, a crash, or a closed tab doesn't lose your work.

Three save triggers:

  • Idle debounce (~5s) — every change resets a short timer; the save fires 5s after your last edit. Bursts (drawing 100 features in a row, typing into a properties form) collapse into a single write.
  • Heartbeat (~60s) — a periodic check flushes whatever's pending if the dirty flag is set. Catches "user is editing continuously without ever pausing 5s" so you never lose more than ~60s of work.
  • Hard fences — closing the browser tab, hiding it (Cmd+Tab away), or navigating to a different page always flushes the pending state. These ignore the toggle below by design — data preservation is non-negotiable.

Toggle: "Auto save to device" / "Manual save to device" (Version Manager menu)

  • Auto save on (default) — idle debounce + heartbeat + hard fences all run. You don't think about it.
  • Manual save off — only the hard fences fire. In-progress edits live in memory; nothing hits the device's storage until you trigger an explicit save (Submit, an explicit "Save" action) or one of the hard-fence events kicks in. Useful when you want to keep many speculative edits without persisting them between idle periods.

In both modes, hard fences ALWAYS flush — closing the tab will not lose unsaved work in either mode.

Work from Device

Work from device is the read-source switch — it controls what the app reads from when you open a list page or the map. It's independent of auto save.

Toggle: "Work from device" / "Work from server" (Version Manager menu, or version-status pill in the page header)

  • Work from server (default) — list pages and the map fetch live from the server. Latest data, but you need a connection.
  • Work from device — list pages and the map serve from your device's local copy (the baseline: a snapshot of records the app prefetched or you previously loaded). No server calls for read. Writes still queue locally as drafts; they push to the server the next time you toggle back to server-mode and Submit.

When you toggle on, the app prefetches data for the most-used endpoints (work orders, tasks, reports, sites, stock items, plus map points/lines/polygons) into the baseline. The map "snapshots" whatever features are currently loaded. Use this before going to a no-signal site so the local copy is fresh.

When you toggle back to "Work from server" with pending un-pushed changes, the app surfaces a "you have unsynced changes" toast — your cue to Submit or apply them via Resync.

The pulsing-green Redo/Resync glow described above stays visible whenever there are diffs not yet applied to the live records, so the visual cue is always there even if you missed the toast.

Per-User Device Isolation

The version manager scopes all on-device storage by user. If two people log into Aptli on the same device:

  • Each user only sees their own drafts in the local Version Manager list.
  • A draft saved by one user can't accidentally overwrite the other's working version.
  • Staged file uploads, the offline write queue, and the "currently checked-out" pointer are all per-user.

Server-side, drafts are still gated by the standard owners/permissions system — sharing a draft requires explicit add-as-owner via the Admin → Versions surface. The local isolation is layered on top: each user's device-side store is invisible to other users on the same device.

Practical implication: if you log in as someone else "to check something" on a shared field tablet, you won't see your own pending drafts in that session. Log back in as yourself to pick them up where you left off.

Using Version Controls

Submit - Push Changes to Server

When to Submit:

  • End of work session (push progress to server)
  • Before switching projects (persist changes server-side)
  • After major edits (create a checkpoint)
  • Before flipping to Work from device (so the baseline reflects your latest server-side state)

What Gets Submitted:

  • All features with _uncommitted flag
  • Layer modifications
  • Schematic diagram changes
  • Property updates, geometry edits, new features
  • Any files attached to those records (photos, documents)

Note: server‑side import jobs (e.g. nightly GeoJSON imports) also create versions automatically; these appear on the Admin → Versions page and their features become visible to users as soon as the job completes, just like normal commits.

Workflow:

1. Make changes (draw, edit, import features)
2. Monitor uncommitted badge count
3. Click Submit when ready
4. Check for conflicts (if any)
5. Resolve conflicts or accept submission

Request Commit & Admin Review

For non‑administrators the Submit button initially acts as a request for review rather than an immediate publish. When you choose Request Commit the version is flagged submittedForReview and saved to the server; it does not become visible to other users until an admin approves it. Administrators open the new Admin → Versions page (see the Administration guide) to see a queue of pending versions; they can either commit the version (making it live) or delete it. This workflow ensures that field edits are checked before being applied to the shared dataset.

File Attachments

Any files you attach to a record (photos, documents, etc.) are staged locally as part of your current version. They are uploaded automatically when the version is submitted and included in the commit process; if you undo or discard changes the staged files are removed. See the Development documentation for technical details on file staging.

Result:

  • Changes visible to all users
  • Version record created on server
  • _uncommitted flag removed
  • Badge count resets to 0

Undo - Revert Last Change

What It Does:

  • Steps backward through change history
  • Works on uncommitted local changes
  • Maintains redo stack (can redo after undo)

Limitations:

  • Only affects current session changes
  • Cannot undo submitted/committed changes (use Resync instead)
  • History cleared on page reload

Use Cases:

  • "Oops, deleted wrong feature"
  • "Need to try different approach"
  • "Accidentally moved feature"

Redo - Reapply Undone Change

What It Does:

  • Steps forward through change history
  • Only available after Undo
  • Cleared when new change made

Workflow:

1. Undo removes change
2. Redo restores it
3. Continue undoing/redoing as needed
4. Make new change → clears redo stack

Conflict Resolution

When two users edit the same feature/version concurrently, a conflict warning appears at the top of the map.

Click View conflict details to open a comparison view where you can accept or reject individual changes. The history panel highlights which versions contributed each modification.

Offline Write Queue

Whether you're explicitly in Work from device mode or you simply lost connectivity mid-edit, write operations that can't reach the server are queued locally per-user. The queue persists across reloads. When the connection returns (or you toggle back to Work from server), the queue flushes automatically; failures stay in the queue for a manual retry from the Version Manager. The queue only applies to write paths — reads are governed by the Work from device toggle described above.

(network indicator screenshots: offline and online)

Resync - Reload from Server

When to Use:

  • Discard all uncommitted changes
  • Reload latest from server (others' work)
  • "Undo everything" nuclear option
  • Resolve corrupted local state

⚠️ Warning:

  • All uncommitted changes lost
  • Cannot be undone
  • Confirms before proceeding

Safe Alternative:

  • Submit first to preserve work
  • Then Resync to get latest

Parallel Workflows: Direct vs Staging

Aptli supports two workflows for feature manipulation:

Direct Manipulation (Simple Edits)

Best For:

  • Moving single features
  • Quick property updates
  • Deleting features
  • Simple geometry adjustments

How It Works:

1. Select feature on map or in table
2. Edit directly (drag, properties form)
3. Change tracked automatically
4. Submit when ready

Advantages:

  • Fast, no intermediate steps
  • Familiar pattern (edit in place)
  • Minimal UI overhead

Draw Staging (Complex Operations)

Best For:

  • Importing external data (GeoJSON, ESRI files)
  • Complex geometry editing (reshape polygons)
  • Batch operations (create many features)
  • Reviewing before committing

How It Works:

1. Load features to Draw (imports, Load to Draw button)
2. Edit in Draw mode (reshape, split, merge)
3. Select target layer
4. Commit to features (tracked as uncommitted)
5. Submit when ready

Advantages:

  • Staging area for review
  • Advanced geometry tools
  • Separate imports from real features
  • Undo at Draw level (before commit)

Color Coding:

  • Blue - Your selected features loaded to Draw
  • Orange - Conflicts from other users (read-only)
  • Default - Imports and manually drawn features

Conflict Resolution

How Conflicts Occur

Spatial Conflicts:

  • Two users add features in same location
  • Overlapping infrastructure placement
  • Competing network designs

ID Conflicts:

  • Same feature edited by multiple users
  • Different property changes
  • Geometry modifications

Viewing Conflicts

Team Conflicts (Layer Manager → Overlays)

The primary way to see what other people are working on in your area is Layer Manager → Overlays → Team Conflicts. Click the refresh button to query the server for other users' draft versions (uploaded but not yet committed) that overlap your current viewport. Conflicting features render as orange on the map; pick a contributor's email from the dropdown to filter the view.

What it queries: server-side, all uncommitted versions in your viewport's bounding box. Committed versions are excluded by design — those are already in your map data, not "in progress."

What it tells you: someone else is mid-edit on features you're about to touch. Coordinate before committing to avoid stepping on each other.

The viewport is captured at the time you click refresh. Pan or zoom the map and an "Outdated" indicator appears next to the section header — click refresh again to re-query for the new view.

Load Conflicts Button (DrawToolbar) — legacy path

The DrawToolbar's Load Conflicts button is the older, draw-centric version of the same query. It pulls the same uncommitted-versions data and renders results as orange features inside the Draw layer (read-only — you can't commit someone else's draft). Useful when you're already in a draw flow; the Layer Manager → Overlays surface is the cleaner entry point for general "what's everyone else doing here?" checks.

Workflow (Draw-toolbar variant):

1. Click "Load Conflicts" in DrawToolbar
2. Orange features appear (others' drafts)
3. Review spatial overlap
4. Adjust your features if needed
5. Submit your changes (conflicts flagged)

Resolving Conflicts

Option 1: Coordinate with Team

  • See who's editing (conflict shows user email)
  • Discuss via chat/phone
  • Decide who submits first

Option 2: Sequential Submission

  • One user submits
  • Other user resyncs
  • Second user adjusts and submits

Option 3: Manual Merge

  • Load conflicts to see both versions
  • Create merged feature manually
  • Both users resync and accept merge

Uncommitted Change Tracking

Features you have created, edited, or imported — but not yet submitted — are tracked as uncommitted. An orange badge on the Selected Features button shows the count of uncommitted changes in your current session.

The badge updates in real time:

  • Increases when you commit features from the Draw staging area
  • Resets to zero when you Submit
  • Resets to zero when you Resync (discarding all uncommitted changes)

Use the badge count as your reminder to Submit regularly. A high count means a lot of work could be lost if your browser closes before you submit.

Best Practices

When to Submit

Recommended Times:

  • End of each work session
  • After completing logical unit of work
  • Before switching between projects
  • When badge count feels "too high"
  • Before going offline (preserves as checkpoint)

Avoid:

  • Submitting incomplete work (confuses team)
  • Never submitting (risk of data loss)
  • Submitting constantly (creates version noise)

Working from Device Strategy

1. Prep Before You Lose Connectivity:

1. Submit any pending changes (push to server)
2. Toggle "Work from device" ON (prefetches the baseline)
3. Edit on the device — auto save persists as you go
4. When you regain connectivity, toggle OFF
5. Submit your queued changes

2. Check for Conflicts:

1. Use Team Conflicts (Layer Manager → Overlays) before major edits
2. Coordinate with visible users
3. Submit non-overlapping work first

3. Regular Checkpoints:

1. Submit every 30-60 minutes when online
2. Creates recovery points server-side
3. Shares progress with the team

4. On a Shared Device:

1. Each user's drafts are isolated locally — your work is yours
2. Log out cleanly to avoid leaving auto-save firing under a stale session
3. Log back in to pick up your own pending drafts

Version History Review

Check Who Changed What:

  • Version records show user, timestamp, operation
  • Compressed versions still reconstructible
  • Audit trail for compliance

Rollback Process:

1. Identify problem version
2. Resync to before problem commit
3. Redo changes correctly
4. Submit new version

Load to Draw Feature

Purpose

Enables complex geometry manipulation beyond simple drag-and-drop:

  • Reshape polygon boundaries
  • Split lines into segments
  • Merge adjacent areas
  • Advanced geometry operations

How to Use

From SelectedFeatures Table:

1. Select rows in table (checkbox)
2. Click "Load to Draw" button (pencil icon)
3. Features appear in Draw (blue)
4. Edit using Draw tools
5. Select target layer
6. Click commit button
7. Features get _uncommitted flag
8. Submit when ready

Styling:

  • User selections: Blue (#3b82f6)
  • Conflicts: Orange (#f97316, read-only)
  • Imports: Default Draw colors

Advanced Operations

Reshape Polygons:

  1. Load polygon to Draw
  2. Click vertices to move
  3. Add/remove points
  4. Commit back to features

Split Features:

  1. Load line/polygon to Draw
  2. Use Draw tools to create split
  3. Commit as separate features

Merge Areas:

  1. Load multiple polygons to Draw
  2. Delete boundaries between them
  3. Create single merged polygon
  4. Commit result

Troubleshooting

"Changes Not Saving"

Check:

  • Uncommitted badge count increasing?
  • Submit button active?
  • Browser console for errors?

Solution:

  • Verify network connectivity
  • Check browser storage not full
  • Submit to persist changes

"Lost My Changes After Reload"

Cause:

  • Hard fences (close tab, hide tab, navigate away) flush pending diffs to device storage unless the session ended mid-flush.
  • Resync cleared in-progress diffs by replaying from the baseline.
  • Device storage was cleared (browser data wiped, "clear all drafts" used).
  • Logged in as a different user — drafts are scoped per-user, so they appear empty under a different account.

Prevention:

  • Submit before closing the browser to push to the server (the source of truth).
  • Trust auto save for in-session work — it survives reloads, but server-side history only persists what you Submit.
  • On a shared device, log out cleanly, and log back in as yourself.

"Conflict Won't Resolve"

Steps:

  1. Load Conflicts to see other version
  2. Contact other user
  3. One user Resyncs
  4. Modify and Submit again
  5. Second user Resyncs and continues

"Undo/Redo Not Working"

Limitations:

  • Only in-session changes
  • Cleared on page reload
  • Cannot undo submitted changes

Workaround:

  • Resync to before problem commit
  • Redo changes correctly
  • Submit new version

Related Guides