Documentation Get help

Write a code action

Use code when the rule is exact and should run the same way every time. Code reads and changes your objects, can use your connected apps, and can stop to ask a person. It uses no AI, so it has no AI spend, only compute.

You need Manage actions. Ask your Flowstate admin.

Where it runs

Code is TypeScript. Each run gets its own isolated sandbox with no internet, no files and nothing inside Flowstate’s network. The only module is flowstate. Nothing can be installed.

The editor

  1. Add an action and choose Code under Run by.
  2. Choose the type under When first. The editor’s types come from it.
  3. Set the Access the code needs. The editor only offers what the action is allowed to do, so set access before you write.
  4. Write the code in action.ts on the Build tab.

The editor knows your ontology. Each type and property is typed, and the meanings and examples you wrote show as help when you hover or autocomplete. What your code can call lists every function available to this action.

The top of the editor shows No problems or Problems with a count. An action can’t be saved until its code compiles: Why it doesn’t compile lists each problem by line and column.

What your code is given

Every action exports one function, made with defineAction. It’s given:

NameWhat it is
objectThe object that started the run, with its properties. A deleted object has only its id and title.
eventWhat happened to it: 'created', 'changed' or 'deleted'. Empty when the action is tried.
objectsOne entry for each type the action can read, by the type’s key, such as objects.people
appsThe operations of connected apps the action is allowed, such as apps.hubspot.create_note
askQuestions for a person: choice, confirm, number, text and person
ratesYour organization’s exchange rates: rates.monthly('EUR', 'GBP')
logAdds a line to the run’s steps. At most 200 lines of 2,000 characters are kept.

For each type, depending on its access:

  • find({ search, where, limit }) searches by title and by properties that must be equal. It returns 20 objects unless limit says otherwise, and at most 100.
  • get(id) reads one object, or null.
  • update(object, changes) changes the properties the action may change.
  • link(object, link, to) links two objects through one of your links.
  • linked(object, link) reads the objects linked to one object through a link, whichever way the link goes. It returns at most 100. Objects of a type the action can’t read are left out, and an object with nothing linked gives an empty list.

linked is offered for a link when the action can read both of its types. The editor offers each link it can follow, with the link’s name and the type at the other end, such as the “pays for” link from Deals to Work.

update and link only work on the object that started the run, objects linked to it, and objects the run created.

A property’s key is shown under its name on the type’s Properties tab, such as bench_status.

Money

Money is held exactly, in whole pence or cents, so code can’t do arithmetic on it directly. Import money from flowstate and use its functions: money(500, 'EUR') makes an amount, and money.plus, money.minus, money.times, money.round, money.convert, money.compare and money.format work with it. Two currencies are never added together by mistake: converting needs a rate, such as one from rates.monthly.

Asking a person

Each ask function pauses the run until someone answers on the Runs tab, then the run carries on with the answer. A paused run uses no compute while it waits. See Answer a question.

A worked example

In our people example, People has an added property Bench status, a choice of on_client or benched. This action runs when a person changes. When their bench status is empty, it asks whether they’re on client work and records the answer.

When: People, changed. Access: Read on People, and Change properties with Bench status ticked.

import { defineAction } from 'flowstate';

// When someone's bench status is empty, ask whether they're on client work,
// then record the answer.
export default defineAction(async ({ object, objects, ask, log }) => {
  if (object.bench_status !== null) return;

  const onClient = await ask.confirm({
    title: `Is ${object.title} on client work now?`,
    yes: 'On client work',
    no: 'Free for new work',
  });

  const status = onClient ? 'on_client' : 'benched';
  await objects.people.update(object, { bench_status: status });
  log(`Bench status for ${object.title}: ${status}`);
});

If you typed 'available' instead of 'benched', the editor would mark the line, because Bench status has no such value. The same check stops code changing a property its access doesn’t allow.

Try it on one object. The try shows Would ask a person and stops there, because nothing is changed in a try.

If something’s not right

“The code imports something other than flowstate”. Only flowstate is available. Write what you need in the action itself.

A run fails with “The code stopped with an error”. Open the run. The last steps and your log lines show where it stopped.

A run fails with “The code changed since the run started”. The action was changed while this run was waiting for an answer, so it couldn’t carry on. Change a code action when none of its runs Need you.

A run fails with “Reached its memory limit” or “Reached its time limit”. Raise Memory or Stop after on the Limits tab, or have each run do less.