Working with workbooks

A workbook is the data-collection design an experiment runs. Its ordered cells can contain instructions, questions, protocols, device commands, analysis macros, branches, markdown notes, and generated outputs.

Workbooks also have a description. Use it to state the purpose, intended device or sample, and field method so people can distinguish similarly named designs.

Attach a workbook

You can choose a workbook in the Details step when creating an experiment. For an existing experiment, open its Design tab:

1. select or search for the workbook;
2. attach it to the experiment;
3. confirm the pinned version shown beside its name;
4. test the full flow on the mobile app.

Attaching a workbook publishes its current cells as a numbered version and pins the experiment to that immutable snapshot. The pinned snapshot includes the referenced protocol and macro code, so later edits do not silently change what the experiment is collecting.

Open workbooks (opens in a new tab)

Use connected-device context

Branch cells include a pinned Connected device source. It exposes the connected device's family, id, name, zero-based index, and firmwareVersion. A device-based branch can send each connected device to its own protocol or command cell; unmatched devices sit out that measurement round.

Macros receive earlier workbook values through a read-only ctx namespace. Each completed upstream question, protocol, command, or macro is available under its canonical workbook name, for example ctx.soil_moisture. Multi-device outputs are scoped to the device whose macro is running, and ctx.$device contains that device's runtime identity. In the web workbook runner, a macro can run from earlier ctx values such as answers even when no protocol measurement precedes it.

See Writing macros for verified Python and JavaScript examples using json, ctx, and ctx.$device.

Edit and publish changes

The workbook owner edits the live draft. Workbooks autosave, and publishing creates a newer version. If a protocol or macro belongs to someone else, fork it before editing so the workbook points to your copy.

You can also fork a whole workbook: open it and select Fork to create your own editable copy of all its cells, then attach that copy to your experiment and adjust it. This is the recommended way to start from a baseline workbook someone else published.

An experiment continues to use its pinned version until an admin changes it. A newer version produces an update indicator. Before upgrading, open the review:

• compare added, removed, and changed cells;
• review protocol and macro code changes;
• resolve missing references or mixed sensor families;
• run a representative field test.

The version history can also repin an older or newer published version. Treat that as a methods change and record why it was made.

For protocol choice and safe adaptation, see Protocols: choosing & adjusting.