The _action field

Every object you import as YAML or JSON carries an (optional) _action field. It tells Cavaliba what to do with that object: create it, update it, delete it, etc. When _action is missing, Cavaliba assumes create.

So far in this tutorial, every snippet you pasted in the Import UI tool used the implicit create action. Let’s now use orga_it, the IT staff list on your Site schema, to also see append and unappend in action - the two actions used to add or remove values from a multi-valued field without retyping the whole list.

Append values

The demo data ships the ANCON site (Ancon Surgical Day Clinic) with 2 IT staff members in orga_it.

Open the ANCON site detail page and check the Organization section: you should see 2 names in IT staff.

Let’s add 4 more, borrowed from another site’s IT team:

- classname: site
  keyname: ANCON
  _action: append
  orga_it:
    - charlotte47
    - bolanderhella
    - ipedraza
    - jnogueira

Paste this in the Import UI tool, check, and import.

Check: the ANCON site now has 6 names in IT staff - the 2 original ones plus the 4 you just appended. Nothing else on the object was touched: append only ever adds to the field(s) you list, it never replaces the whole object.

Remove values

Now let’s remove two of the names you just added, with unappend:

- classname: site
  keyname: ANCON
  _action: unappend
  orga_it:
    - charlotte47
    - bolanderhella

Check: orga_it is back down to 4 names.

append and unappend only make sense on fields that accept more than one value (like orga_it, cardinal_max: 0 in the Site schema). On a single-valued field, both behave exactly like update.

Other actions, in short

You already used create throughout this tutorial. Here is one minimal example for each of the other actions, using a scratch TEST01 site so you don’t disturb your demo data:

init - create only if missing; does nothing if the object already exists (safe to re-run):

- classname: site
  keyname: TEST01
  _action: init
  displayname: Scratch site

update - change an existing object; fails if it doesn’t exist:

- classname: site
  keyname: TEST01
  _action: update
  displayname: Scratch site (renamed)

disable / enable - hide an object from regular users without deleting it:

- classname: site
  keyname: TEST01
  _action: disable

- classname: site
  keyname: TEST01
  _action: enable

delete - remove the object for good:

- classname: site
  keyname: TEST01
  _action: delete

noop - do nothing; useful to safely re-import an export file without risking any change, or to check field values against what a file contains before really applying it. Every YAML/JSON export already comes with _action: noop on each row for this reason.

- classname: site
  keyname: ANCON
  _action: noop