Version Management

Aptli's version management system lets you edit maps and schematics offline — in subway tunnels, remote sites, or areas with poor connectivity — and submit your changes when you're ready. The system 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 and resolve conflicts.

Version Controls Interface

Version controls appear in the map toolbar itself – on desktop they sit in the first row of icons next to the mode selector and data‑transfer button, while on mobile they form the first line of the bottom navigation bar. The accompanying image shows the desktop layout; if you look at the map toolbar you’ll also notice the Data Transfer button beside the controls (used for import/export).

Version Toolbar

Primary Controls:

Undo - Revert the last change in current session
Redo - Reapply a change that was undone
Resync - Reload data from server, discard uncommitted local changes
Submit - Push all uncommitted changes to server

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 in browser storage
   ↓                     Feature has _uncommitted flag
   
2. Edit Offline        → Modify properties, geometry, relationships
   ↓                     All changes tracked locally
   
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 in browser storage 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 server
No offline drafting (execution requires confirmation)
No version history (operational data)

3. Tasks (Hybrid):

Versioned for planning phase (offline design)
Real-time for execution (assignments bypass versions)
See Work Fulfillment Guide for details

Using Version Controls

Submit - Push Changes to Server

When to Submit:

End of work session (save progress)
Before switching projects (persist changes)
After major edits (create checkpoint)
Before going completely offline (sync latest)

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

Data Transfer Export Tab

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 Queue Viewer

When working offline, changes are queued locally; the Offline Queue Viewer shows pending operations, sync status and allows manual retry.

(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

Load Conflicts Button (DrawToolbar):

Fetches other users' uncommitted changes
Displays as orange features in Draw
Read-only - cannot commit others' drafts
Helps coordinate before submission

Workflow:

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)

Offline Editing Strategy

1. Sync Before Going Offline:

1. Resync to get latest
2. Make offline changes
3. Submit when back online

2. Check for Conflicts:

1. Load Conflicts before major edits
2. Coordinate with visible users
3. Submit non-overlapping work first

3. Regular Checkpoints:

1. Submit every 30-60 minutes
2. Creates recovery points
3. Shares progress with team

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: