Action

Documentation

Data

Action

_action is a per-object field used in import data (YAML, JSON, CSV) to tell Cavaliba what to do with that object: create it, update it, delete it, etc. It is used the same way whether you import through the Web UI, the API, the local CLI, or cavctl.

If _action is omitted, it defaults to create.

Available values

`_action`	Effect	Requires existing instance?
`create`	Create the instance if missing, else update it	No
`init`	Create the instance only if missing; silent no-op if it already exists	No
`update`	Update an existing instance; fails if not found	Yes
`append`	Add value(s) to multivalued field(s), keeping existing ones (dedup)	Yes
`unappend`	Remove value(s) from multivalued field(s)	Yes
`enable`	Set `is_enabled: true`	Yes
`disable`	Set `is_enabled: false`	Yes
`delete`	Delete the instance	Yes
`noop`	Do nothing (useful for safe dry inspection of an export/import file)	-

create

- classname: laptop
  _action: create
  keyname: pc0001
  displayname: Evan's laptop

init

- classname: laptop
  _action: init
  keyname: pc0001
  displayname: Evan's laptop

update

- classname: laptop
  _action: update
  keyname: pc0001
  displayname: Evan's laptop (renamed)

append

Added in version 4.5.0. Only meaningful for multivalued fields (fields that accept more than one value); on a single-valued field it behaves exactly like update.

- classname: laptop
  _action: append
  keyname: pc0001
  tags: [warranty-2027]

If pc0001.tags was already [refurbished], it becomes [refurbished, warranty-2027]. Re-running the same import is a no-op (no duplicate entries).

unappend

Added in version 4.5.0. Removes the given value(s) from a multivalued field; a value not currently present is silently ignored. On a single-valued field it behaves exactly like update.

- classname: laptop
  _action: unappend
  keyname: pc0001
  tags: [refurbished]

enable / disable

- classname: laptop
  _action: disable
  keyname: pc0001

delete

- classname: laptop
  _action: delete
  keyname: pc0001

noop

- classname: laptop
  _action: noop
  keyname: pc0001

Every YAML/JSON export includes _action: noop on each row for exactly this reason: it can be re-imported as a safe roundtrip check, then edited to create/update/… to actually apply changes. CSV exports don’t get an _action column.

Edge cases

Field constraints (min/max number of values) are not enforced during import, only in the Web UI create/edit forms. An append that pushes a field past its allowed number of values is silently accepted.
CSV multi-value cells use a ^ separator (e.g. tags: a^b^c), split into a list of values before _action is applied - this is independent from _action itself and works the same for every action.
Fields absent from the payload are always left untouched, regardless of _action - only listed fields are considered.

Scope: not available for Schema, Permission, Home definitions

The full list above applies to regular Schema instances (your data objects). Three special object kinds have their own, narrower set of actions, with no append/unappend:

Schema definitions (classname: _schema) -> create/init/update/ enable/disable/delete/noop (see the Schema reference page)
Permission definitions (classname: _permission) -> init/create/ update/delete
Dashboard/Home definitions (classname: _home) -> create/update/ enable/disable/delete

append/unappend only make sense for data field values, so they don’t apply to these three.

Where to set it

This is a quick reminder - see the API, CLI, and cavctl reference pages for full details.

YAML/JSON/CSV file: a _action key/column on each row.
API (/api/load/, /api/rawfile/): ?action=... query param overrides every object’s own _action for that request.
CLI (cavaliba load): --force_action ... flag, same override behavior.
cavctl (cavctl load, cavctl rawfile): --action ... flag.

Enumerate Search & Filters