Skip to main content

Preview Mode

Adding ?previewOnly=true stops the request after the projection phase. Nothing is written. The response is the projection itself — the flat, aliased list of commands the server would have executed.

POST ~/api/asset?previewOnly=true

What You Get Back​

The response is not the usual envelope. It is a JSON array of aliased commands.

Request
{
  "AssetType": "Story",
  "Scope": "Scope:0",
  "Name": "Story Time",
  "Children": [{ "AssetType": "Test", "Name": "Test Time" }]
}
Response
[
  {
    "@ffa2169f-bd6b-44d2-9cca-05c37a725dfd$auto-aliased": {
      "AssetType": "Story",
      "Scope": "Scope:0",
      "Name": "Story Time"
    }
  },
  {
    "@31e11be0-525c-4ee1-9002-4e6ee4453641$auto-aliased": {
      "AssetType": "Test",
      "Name": "Test Time",
      "#ContextOid": "@ffa2169f-bd6b-44d2-9cca-05c37a725dfd$auto-aliased"
    }
  }
]

The Projection Round-Trips​

The projection is itself a valid request body. Posting it back to api/asset without ?previewOnly=true produces the same result as posting your original payload would have.

This works because the projected content is already user-aliased from the server's point of view, so the second request forwards each command through to processing essentially unchanged.

That makes preview mode a review gate for risky bulk edits:

  1. Post the request with ?previewOnly=true.
  2. Read the projection and confirm it targets what you expect.
  3. Delete or edit any commands you do not want.
  4. Post the edited array back to api/asset.
This is the answer to unbounded query-scoped updates

A command like { "from": "Story", "update": { "Status": "Done" } } matches every Story you can see. Previewing it expands the query into one explicit per-asset command, so you can count them, inspect them, and trim the list before committing. See Updating assets.

Preview is what lets you confirm the blast radius before it commits: the expanded list is either the size you expected or it is thousands of rows, and you see which before anything is written. The same applies to a mass execute of Close or Delete — and unlike updates, those cannot carry a ChangeComment, so previewing is the guard rail you have before the fact.

What the Projection Reveals​

Preview is the only way to observe several behaviors directly:

BehaviorWhat you see
Auto-aliasingGUID aliases, with $auto-aliased on create commands
Hierarchy flatteningNested creates become siblings linked by #ContextOid
Update normalisationEvery attribute update becomes { "add": [...], "remove": [] }
Query expansionA where-scoped update becomes one command per matched asset, each with a literal oid
DeferralUser-aliased commands stay unflattened and unexpanded
Find and replacefind / replace is preserved rather than resolved to add / remove

Caveats​

Preview mode is not covered by tests

The previewOnly parameter, the response shape and the resubmit round trip described on this page are not asserted by any executable test. Treat the exact projection formats as illustrative, and verify behaviour against your instance before relying on preview ahead of a destructive change.

Preview evaluates queries in order to expand them, so a preview of a query-scoped update still costs a read against the database. It is not free, just non-destructive.