How Groundwork handles editing conflicts

Everyone can edit at once. When two people change the same feature, their edits conflict, because Groundwork can keep only one version of it. Groundwork detects conflicting saves and merges the rest, feature by feature.

A check at every save instead of locks

Groundwork uses optimistic concurrency control. Nobody locks a layer or a feature while they edit, so everyone can work at the same time. Groundwork doesn’t try to prevent conflicting edits in advance. It checks for a conflict each time someone saves, then merges the changes or refuses the save.

On a cloud folder

An editable layer in a cloud folder is a GeoJSON file. Each save writes the whole file, so Groundwork has to make sure it never writes over a colleague’s save:

1. Every save is a conditional write. The folder accepts it only if the file is unchanged since Groundwork read it.
2. Groundwork records each feature the person changed: the copy they started from and the copy they have now.
3. Groundwork matches features by their GeoJSON id.
4. If a colleague saved first, the folder refuses the save. Groundwork merges the recorded changes into the newer revision.
5. Groundwork saves the merged file, again as a conditional write.
6. If another colleague saved in the meantime, the person can try again against the newest revision.

    sequenceDiagram
  participant You as Your Groundwork
  participant Folder as Dropbox folder
  participant Colleague as A colleague's Groundwork
  You->>Folder: Load revision 1
  Colleague->>Folder: Load revision 1
  Colleague->>Folder: Save, if the file is still at revision 1
  Folder-->>Colleague: Saved as revision 2
  You->>Folder: Save, if the file is still at revision 1
  Folder-->>You: Refused, because the file is at revision 2
  You->>Folder: Fetch revision 2
  Note over You: Merge your changes into revision 2, feature by feature
  alt No feature clashes
    You->>Folder: Save the merged file, if the file is still at revision 2
    Folder-->>You: Saved as revision 3
  else A feature clashes
    Note over You: Save none of your changes, and offer you revision 2 to edit again
  end
  

The merge is a three-way comparison. For each feature the person changed, Groundwork compares the copy they started from, their copy, and the copy now in the folder:

• The folder’s copy matches the one they started from. Nobody else changed that feature, so Groundwork applies their change, whether it adds, edits or deletes the feature.
• The folder’s copy already matches theirs. A colleague made the same change, so there is nothing to apply.
• The folder’s copy matches neither. A colleague changed the same feature differently. That is a conflict, described below.
• A new feature. Groundwork always adds it. If a colleague’s feature already uses its id, the new feature gets the next free id.

When a conflict occurs, Groundwork saves none of that person’s changes, and Groundwork keeps the folder’s copy. Groundwork offers the person the newer copy so they can make their edit again on it. Groundwork treats two other cases as conflicts too:

• Two people changed different attributes of the same feature. Groundwork compares whole features, not single attributes.
• A feature has no id, or shares its id with another, so Groundwork cannot tell which feature is which.

    flowchart TD
  A["A feature that the person changed"] --> N{"Is it a new feature?"}
  N -->|Yes| ADD["Add it, with the next free id if a colleague's feature uses its id"]
  N -->|No| ID{"Does it have an id that no other feature shares?"}
  ID -->|No| X["Conflict: save none of the person's changes, and keep the folder's copy"]
  ID -->|Yes| F{"How does the folder's copy compare?"}
  F -->|"Matches the copy they started from"| AP["Apply their change"]
  F -->|"Already matches theirs"| NO["Nothing to apply"]
  F -->|"Matches neither"| X
  

While a map is open, Groundwork listens for change notifications from the cloud folder and reloads any changed layer that you aren’t editing. Every save is a new revision in the folder’s version history, which records each change and lets you roll back.

On a WFS-T server

A WFS-T server keeps the data in its own store, and Groundwork changes one feature per transaction. Before each change, Groundwork checks that nobody else changed that feature:

1. Before an Update or Delete, Groundwork reads the feature from the server again with GetFeature.
2. Groundwork compares the feature with the copy it loaded.
3. If someone changed or deleted the feature since, Groundwork sends nothing, and the server keeps its copy.
4. An Update includes only the attributes that changed, and the geometry only if it moved.

    sequenceDiagram
  participant G as Groundwork
  participant S as WFS-T server
  G->>S: GetFeature, to read the feature again
  S-->>G: The feature as the server has it now
  alt Same as the copy that Groundwork loaded
    G->>S: Transaction with the Update or Delete
  else Changed or deleted since
    Note over G: Send nothing, and the server keeps its copy
  end
  

Each transaction changes one feature, so people editing different features never affect each other.

WFS-T also defines locking. LockFeature and GetFeatureWithLock reserve features so that nobody else can change them until the lock is released. Groundwork takes no locks. That leaves a short gap: a change saved between Groundwork’s check and its Transaction is not detected.

Limits

• Groundwork merges whole features. It does not merge attributes within a feature, or check how neighbouring features fit together, so two boundaries redrawn at once can overlap.
• Groundwork doesn’t merge when it can’t fetch the newer revision, or can’t tell whether the cloud folder kept the previous save. It refuses the save instead.
• Today, Groundwork saves to Dropbox folders. Saving to OneDrive is coming soon.
• Groundwork saves only to a folder that is shared privately with each editor, with edit access. It saves only from a link to a map whose Sharing is Sign in to edit.
• Each cloud-folder save writes the whole GeoJSON file. Put a layer on a WFS-T server if many people edit it all day, or if it’s too large to load at once. WFS-T servers are part of Teams.