How Workspace Ordering Works

Helpdocs Admin Updated by Helpdocs Admin

Groups and tickets within a workspace are both ordered — groups have a position relative to other groups in the workspace, and tickets have a position relative to other tickets within their group. This article explains the model behind that ordering, and why the API is built around anchors rather than simple index numbers.

Why not just use an index or order number?

A common approach to ordering is to give each item a numeric position (1, 2, 3, ...) or an index in an array. The problem shows up as soon as you need to insert or move something between two existing items: there's no number available between 1 and 2, so you'd need to renumber every item that comes after the insertion point just to make room.

That's fine for small lists, but it becomes a real cost at scale — a single reorder can turn into an update that touches many other groups or tickets just to keep everyone's position number consistent, even though only one item conceptually moved. This gets worse under concurrent usage: two people reordering different items at the same time might both need to renumber overlapping ranges, creating a real risk of conflicting or lost updates.

Anchor-based positioning

Instead of asking you for a fixed position number, the API asks you for a relative position: where you want the item to end up, relative to its neighbors. You express this using:

  • operator — the type of move: move-top, move-bottom, or move-between.
  • anchorBeforeEntityId / anchorAfterEntityId — for move-between, the ID(s) of the neighboring item(s) you want to land next to.

When you specify an anchor, the server locates it and works out a new position value that fits appropriately in that spot — without needing to touch or renumber any other item in the group or workspace. Under the hood, this is done using a technique commonly known as fractional indexing, where position values can always have new values inserted between them without reshuffling existing ones. You don't need to understand the technique itself to use the API — it's mentioned here only so the general shape of the behavior makes sense.

This calculation is scoped to whichever level you're reordering:

  • Groups are positioned relative to other groups in the same workspace.
  • Tickets are positioned relative to other tickets in the same group — not across the whole workspace.

Anchor resolution and fallback

Anchors are resolved by ID at the time of the request. If an anchor can't be found — for example, it was deleted, or moved somewhere else in the meantime — the operation doesn't fail outright. Instead, it falls back to placing the item at the bottom, so the request still completes successfully rather than erroring out over a stale reference.

Concurrency

This model is specifically built to hold up under concurrent use — for example, multiple people or automations reordering groups or tickets in the same workspace at the same time. Because a move only ever affects the item being moved (not the position of every other item), concurrent moves don't conflict with or overwrite each other's changes.

In practice, a move request will only fail if one of the following is true:

  • The ticket, group, or workspace being referenced doesn't exist.
  • The caller doesn't have permission to modify the workspace.

Otherwise, the operation is designed to always succeed — even if the exact anchor you asked for is no longer available, thanks to the bottom-fallback behavior described above.

How did we do?

Creating and Reordering Workspace Groups

Contact