Automation and apps

Guide

Write a code workflow

Create a Code workflow (or convert a playbook), write a body that finds people and notifies them, rehearse it, then schedule or trigger it.

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 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:

    LabelNameMeaning
    ExpertiseexpertiseThe expertise tag to look for, as people declare it
    Titlenotice_titleThe heading each person sees in their bell
    Messagenotice_bodyThe 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 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

SymptomFix
Save is offThe 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 noticeTick the tool under Auto-approved tools, then start a new run
The header shows Won't runThe 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 codeChoose Open line n in the code under the error on the run page
wf.trigger is nullThe 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 budgetA per-run budget was reached. Do less per run, or split the work across scheduled runs
An edit did not change a waiting runA run keeps the body it started with. Cancel it and start the workflow again

Next steps