# Write a code workflow

At the end of this guide you have a **Code** workflow that finds everyone who declares a given expertise and sends each of them the same notice, with no model call anywhere. You will have rehearsed it against live data without changing anything, and set it to start by hand, on a schedule or on an event. Anyone who may create personal workflows can follow it; a shared workflow needs permission to create shared workflows.

## Before you begin

- Permission to create a personal workflow, or a shared workflow and a shared agent to run it.
- For a schedule, an agent with autonomous runs enabled.
- People in the workspace who declare expertise on their profile, so the example has someone to find.
- The [Code workflow API](/docs/code-workflow-api) open beside this guide, for the exact signatures.

## Create the workflow

1. Open **Workflows** and choose **New workflow**, then **New personal workflow** or **New shared workflow**.
2. Choose the **Agent**.
3. Under **Start from**, choose **Blank**, then pick **Code** instead of **Playbook**.
4. Optionally describe the automation under **What should it do? (Optional)**. **Fill with AI** then opens beside the editor with your description as its first message, and every change it proposes is checked before it lands in the editor.
5. Confirm the dialog. Volobox creates the workflow and opens the **Code** tab on a commented skeleton that already saves.

> **Tip: Start from the template instead**
>
> The body in this guide is the **Tell everyone with an expertise** template. Choose **Start from** > **Template** and pick it (Code templates carry a **Code** badge; typing "code" in the search box matches it). It arrives with its inputs and with `notify_user` already auto-approved.

### Or convert a playbook you already have

A playbook that does the same thing every time is a good candidate for Code. Converting keeps its triggers, access, inputs, runs and cost history.

1. Open the playbook workflow, open the **…** menu in the header and choose **Convert to code…**.
2. **Fill with AI** opens beside the empty editor with a convert message ready. Send it, or write the body yourself.
3. Read **What the assistant left open**: the steps it kept for the model and the questions it could not answer.
4. Choose **Convert to code** and confirm.

> **Warning: Converting is one way**
>
> A Code workflow can never become a playbook again; the old prose is kept for reading only. Conversion is refused while a run of the workflow is in progress.

## Add the inputs and grant the tools

1. Open the **Inputs** tab and add three required **Free text** inputs. Set each **Label** and technical **Name**:

   | Label | Name | Meaning |
   | --- | --- | --- |
   | **Expertise** | `expertise` | The expertise tag to look for, as people declare it |
   | **Title** | `notice_title` | The heading each person sees in their bell |
   | **Message** | `notice_body` | The markdown body each person reads, sent unchanged |

2. Open the **Skills** tab. Under **Auto-approved tools**, tick `notify_user` in the **Workflow actions** group, so a run does not stop for an approval card on every notice.

`find_people` and `notify_user` are baseline tools that every workflow has, so neither needs a skill.

## Write the body

On the **Code** tab, replace the skeleton with this body. Open **Reference** to see each tool's parameters and insert calls with the right shape.

```javascript
// Tells everyone who declares a given expertise the same thing, once.
// No model call anywhere: the message is what the person typed, so nothing needs writing.

await wf.reportProgress('Finding people', `Looking for ${inputs.expertise}.`);

const people = await tools.find_people({
  expertise: [inputs.expertise],
  availableOnly: true,
  maxResults: 50,
});

if (people.length === 0) {
  // Not a failure: nobody declaring that expertise is a real and useful answer.
  await wf.complete(`Nobody available declares ${inputs.expertise}.`);
}

await wf.reportProgress('Notifying', `${people.length} to tell.`);

const failed = [];
for (const person of people) {
  try {
    await tools.notify_user({
      userId: person.id,
      title: inputs.notice_title,
      body: inputs.notice_body,
    });
  } catch (error) {
    // One rejected write must not lose the rest of the list.
    log.warn('Could not notify', person.displayName, error);
    failed.push(person.displayName);
  }
}

if (failed.length > 0) {
  await wf.complete(
    `Told ${people.length - failed.length} of ${people.length}. Could not reach: ${failed.join(', ')}.`
  );
}

await wf.complete(`Told ${people.length} people who work on ${inputs.expertise}.`);
```

What the body does:

- `wf.reportProgress` names each phase on the run's **Journey**.
- `wf.complete` ends the run where it is called, so an empty result ends it quietly instead of failing.
- A failed tool call throws. The `try` / `catch` around each `notify_user` keeps one refused notice from losing the rest of the list.
- `notify_user` takes `body`, not `message`. A wrong argument name is an error before you save.

The chip in the toolbar shows the result of the check as you type; errors are listed in a strip under the editor. Choose **Save** (or press **Ctrl+S**, **Cmd+S** on a Mac). **Save** stays off while there is an error.

> **Tip: When the step needs judgment**
>
> Add one `ai.generate` call for the part that needs a model, with the data in `context` and a `schema` for the answer. Pass the whole list to one call rather than calling it inside the loop.

![The Weekly release readiness workflow on its Code tab, checked with no problems: a JavaScript body that names three phases, lists open tasks and pull requests, asks the model to assess readiness and creates the release notes task.](https://volobox.io/docs/images/code-workflow-editor.light.webp)

*The Code tab of a Code workflow: the body in the editor, Checked with no problems in the toolbar, and Reference, Test and Ask.*

## Rehearse it

A rehearsal reads for real and records every write instead of performing it, so you see exactly what a real run would do. Because a Code body takes a fixed path, that list is what a real run would do too.

1. On the **Code** tab's toolbar, open the **Test** menu and choose **Start rehearsal**.
2. Fill in **Expertise**, **Title** and **Message**, and start the run. If the page has unsaved changes, the start dialog offers **Save changes** first, because a run uses the last saved version.
3. On the run page, read the **Journey**: each `notify_user` call appears as a **Planned effect** with the arguments it would have passed. A banner says nothing was changed and counts the recorded writes.

Use **Start dry run** from the same menu to check that the reads work with no write tools at all, and **Start run** for a real run.

## Start it by hand, on a schedule or on an event

1. Open the **Triggers** tab and choose **Add trigger**.
2. Pick how the workflow starts:
   - **Manual run** lets Runners press **Start run**, or start it from the assistant's `/` menu.
   - **Scheduled run** starts it on a cadence: pick one under **When to run** (**Once at a specific time**, **Every N minutes or hours**, **Every day at a time**, **Weekly on selected days** or **Advanced (cron expression)**).
   - **Event** starts it when something happens: pick the event, narrow it with conditions, and use **Preview matches** to see how often it would have fired over the last week.
3. For a schedule or an event, expand **Workflow inputs** and save fixed values for the three inputs. Required values must be filled before the trigger saves.
4. Choose **Save**.

> **Note:** Schedule and event triggers pass the fixed values you saved, not the event's fields. Read the event itself from `wf.trigger` in the body; it is `null` for a schedule or a plain manual start.

## Check that it works

- The **Runs** tab lists the run with its status, duration and, for people who may see cost, its AI cost. The line under a Code run's status reads **Code · Version n**.
- The run's **Journey** shows **Finding people** and **Notifying**, one **Code ran** entry, and one entry per `notify_user` call.
- The run completes with its outcome, such as "Told 4 people who work on billing.", and each person has the notice in their bell.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| **Save** is off | The problem list holds an error. Click the chip in the toolbar to jump to the first one |
| A tool "is not granted" | Give the workflow the skill that provides it on **Skills**; the check reads the draft, so grant and call can be one save |
| The run waits on an approval card for every notice | Tick the tool under **Auto-approved tools**, then start a new run |
| The header shows **Won't run** | The saved body fails the check, for example after a skill was turned off. Its tooltip names the first error |
| The run failed on a line of your code | Choose **Open line n in the code** under the error on the run page |
| `wf.trigger` is `null` | The run came from a schedule or a plain manual start. Have the body call `wf.fail` with a clear reason when it needs an event |
| The run ended as **Code ran past its budget** | A per-run budget was reached. Do less per run, or split the work across scheduled runs |
| An edit did not change a waiting run | A run keeps the body it started with. Cancel it and start the workflow again |

## Next steps

- [Code workflow API](/docs/code-workflow-api)
- [Workflows](/docs/workflows)
- [Build an app](/docs/build-an-app)
- [Home and Inbox](/docs/home-and-inbox)
