actions

Details #

An action is a step. Once the extension is installed it shows in the add-step picker under the extension's name, and its type is <extension id>.<action id>. You declare it under adds.actions in switchboard.json and implement it with action(id, handler). The handler gets the step's params and a ctx, and returns the step's output.

{
  "adds": {
    "actions": [{
      "id": "count", "title": "Count Words", "dryRunSafe": true,
      "params": { "type": "object", "properties": { "text": { "type": "string", "title": "Text" } }, "required": ["text"] },
      "output": { "type": "object", "properties": { "words": { "type": "integer" } } }
    }]
  }
}

import { defineExtension, action } from '@switchboard/sdk';

export default defineExtension({
  actions: [
    action('count', (p: { text: string }) => ({ words: p.text.trim().split(/\s+/).length })),
  ],
});

dryRunSafe is required. Set it to true only when running the action cannot change anything outside Switchboard. Dry runs and the debugger then run it for real. Otherwise they simulate it.

The declaration and the code must match. An extension that declares an action it does not implement, or implements one it does not declare, is refused when it loads.

Gotchas #

• A call that takes more than 5 seconds without answering is killed and the extension restarts.

• Throw an Error to fail the step. The run shows your message.

• Anything the action does outside the sandbox (network, files, clipboard, keyboard) needs a permission in the manifest. Without it the call fails with permission denied.

• switchboard ext dev <folder> loads an extension into the running engine and hot-reloads it on every save.

How the Inspector draws your params #

The Inspector turns params into controls from the schema alone; it never runs your code to do so. Per property:

• Label and help: title (default: the key, spaced out) and description.

• Control: enum is a menu; boolean a switch; number and integer a number field; array of strings a list, of an enum a set of checkboxes; object or anything else the JSON editor. A string is a text field, multiline with "format": "multiline" or "textarea", a URL with "uri" or "url", a file or folder with "path", "file" or "directory", and masked with "secret": true.

• Text with variables: string fields take {{ }} templates, with completion, tokens and an Example result, except secret ones, which are never evaluated or previewed.

• Order: required properties first, then A to Z.

• Defaults: default is shown as the field's hint. A property that is absent is not written until it is set.

• into: a string property named into is drawn as Save result as, the name of the variable that receives the output.

• Unknown keys: values saved in a step that the schema does not describe are listed under Additional settings and always kept.

A schema the Inspector cannot read (a property that is not an object, enum of non-text) is reported, and the step falls back to its JSON so nothing is lost. The built-in steps use richer x-editor annotations (role, group, order, help, example, accepts, visibleWhen, picker, sensitive) from Switchboard's own schema; extension schemas do not read them yet, so use the standard keys above. If the extension is removed, its steps keep every value and the Inspector says to install it again.

Full example #

The sample below has two steps: a pure one (dryRunSafe) that counts words, and one with a side effect that keeps a value in the extension's own store. You can download it from the Full example section and edit it into your own.

See also #

• conditions

• functions