Your own steps

When you will do the same thing more than once, and no ready-made step does it, write your own. A step you write sits in the step picker beside the built-in ones and behaves the same way: fields, an output, an error output, logs.

What a step is made of

A step is two things:

• A manifest (manifest.json) that declares it: which fields the canvas draws, which account it acts as, and what it hands downstream.
• An execute function that does the work. It receives what arrived from the previous step as input, the step's fields as config, and a context with storage, state and the accounts it acts as.

{
  "description": "Remember an email address, and say whether it is new",
  "auth": { "type": "none" },
  "properties": {
    "email": { "label": "Email", "type": "text", "required": true }
  },
  "outputs": ["success", "error"]
}

import type { PluginModule } from "@visualautomate/plugin-sdk"
 
const plugin: PluginModule = {
  async execute(input, config, context) {
    const seen = (await context.state.get("seen")) ?? []
    if (seen.includes(config.email)) {
      return { output: "success", data: { new: false } }
    }
    await context.state.set("seen", [...seen, config.email])
    return { output: "success", data: { new: true } }
  },
}
 
export default plugin

output names the port the run leaves by, success or error, and data is what the next steps read. You never see a credential and never name a host: a step asks context.connections for the account it was configured with, and the token is attached on the way out.

Where it runs

Your step runs in an isolated sandbox created for the run and destroyed afterwards, separate from every other customer's runs. It can keep state between runs and read and write files through its context.

Keep it, or publish it

A step you write is yours: it shows up under My Plugins in the dashboard and in your own step picker. When it is ready for other people, publish it so they can install it. Published steps are reviewed, and what runs is exactly the version that was approved; a later change is a new version that is reviewed in turn.

For a few lines: the Code step

Not everything deserves a step of its own. The built-in Code step runs a few lines of JavaScript at one point in a workflow, with the step's input as input:

// Keep only the orders over 100, and add a total.
const orders = input.orders.filter((order) => order.amount > 100)
return { orders, total: orders.reduce((sum, order) => sum + order.amount, 0) }