Editing offline in Hyz Desktop — check out, edit, sync

What a checkout is¶

Hyz Desktop edits a Hyz Layer by checking it out: the desktop downloads the layer's live rows, keeps a private baseline of what it received, and lets you edit the copy with every tool the desktop has, online or offline. Sync compares your copy with the baseline, sends the difference as one batch of edits, receives everyone else's changes since your version, and moves the baseline forward. Nothing leaves your machine until you sync, and nothing on the machine can lift a rule or a lock set on the portal.

A checkout belongs to you and expires after a set time (thirty days by default) or when the layer is restored from a snapshot; the desktop then asks you to check the layer out again.

Checking a layer out¶

1. Map → Add data → Browse data items…, signed in to the portal.
2. A layer whose item is editable shows Check out beside Add to project. The hint reads Check the Hyz Layer out for editing — sync your changes back later.
3. The layer arrives in the project with the origin hosted, its data item, its version and the capabilities the server granted. The baseline is stored under the project's hosted/ folder when you save.

A refusal is explained in place: editing is off for the layer, editing is not enabled on this instance, the layer is not ready, or the item is not visible to you.

Add to project still works for any layer you may view: that is a plain copy, edited locally and never sent back.

Editing the copy¶

A checked-out layer is edited like any other layer: the edit sessions, vertex tools, split and merge, transform, snapping, the attribute table, feature templates. What differs is that the server's answer to what may I do is enforced locally, and fails closed:

• if the layer's capabilities are missing or editing is off, the layer is read-only, and the Properties pane says so;
• create, edit, delete and geometry each follow the chip the server sent; a tool that needs a capability you do not have is greyed;
• fields outside the editable list are read-only cells, with Read-only: locked on the portal, or outside what you may edit on hover;
• locked features draw with a dashed contrast outline (ringed points) and refuse every edit; an edit session skips them; a delete reports how many were skipped.

The Field pane → Checked-out layers lists every checkout in the project with its pending counts (created, changed, deleted), its version, its last sync and a Sync button. The pending counts are computed from the difference to the baseline, so they are always right, even after a restart.

Syncing¶

Open the sync dialog from the Field pane, from the layer's Properties (Sync…) or from the command palette (Sync Hyz Layer). It shows the data item, your version and last sync; the capability chips; the pending counts; then, after a sync, Sent: applied of total · Received: changed, deleted.

A sync sends your edits in batches, each change carrying the revision it was based on and an identifier that makes a retry safe: sending the same change twice applies it once. The server answers per change, applies what it accepts, and returns everything that changed on the portal since your version. Accepted changes move the baseline; received changes land in your layer, except where you still hold an unsent change on the same feature.

Offline, Sync reports The portal is not reachable. Your edits are kept here; sync again when you are online. and changes nothing.

Conflicts¶

A change the portal refuses stays in the dialog under conflicts, one row per feature: the operation (New feature, Change, Delete), the feature, the reason in words, the field concerned, and your value beside the portal's. A Mine / Portal control on each row decides:

• Mine keeps your version and retries it against the portal's current revision on Apply choices. For a true conflict (changed on the server since you loaded it) that means your value replaces theirs; for a rule refusal (the feature is locked, outside the editing area, only its creator may change it) it will be refused again until the rule or the lock changes.
• Portal takes the portal's copy of the feature and drops your change.

A sync that leaves conflicts does not move your version forward, so the next pull delivers the portal's copies again and nothing is lost between two people. Every reason and its fix is listed in why an edit was refused.

When a checkout must be renewed¶

The dialog says	Why	What to do
Your copy is older than the portal's change log. Check the layer out again — your edits stay in this layer, copy them across.	the portal folds its edit log after the retention window (ninety days by default), or the layer was restored from a snapshot, which gives every feature a new identity	check the layer out again as a new layer; your old layer stays in the project with your edits, so you can copy what you need across
editing off badge in the Field pane	the owner switched editing off	you can keep the copy, but nothing syncs until it is on again
a permission refusal on every change	your role on the item changed	ask the owner; your edits stay on your machine

Check in as a copy¶

Check in as a copy in the sync dialog forgets the checkout: the baseline is deleted and the layer stays in the project as a plain copy with the origin portal. Unsynced edits are not sent. It is confirm-guarded. Use it when you want to keep working on data you no longer intend to push back.

What the desktop never does¶

• It never decides a capability: chips are rendered from the server's answer, and a missing answer means read-only.
• It never lifts a lock, widens an editing area or edits a read-only field, even offline.
• It never sends anything without Sync.
• It never edits a PMTiles archive: an archive is a published rendering for reading offline, and the editable thing is the Hyz Layer behind it.

Identity of a feature¶

The portal's feature identity travels in a hidden column of the layer, shown in the sync dialog's footer. Exports of a checked-out layer carry it as an ordinary attribute, which is how you can match rows between a checkout, a snapshot and the live layer.