Actions

An action is a button a project declares: Sync now, Reimport one type, Send the weekly report. It runs one of the project's workflows, a script in the project folder, or a prompt into a named session or a fresh one, with the inputs it asks for, and it can ask before it runs. The buttons sit in a row above the project page's tabs and in the master view's Actions panel; the line under them says how the last run went.

What it is for

Some work you want on demand rather than on a schedule: pull the orders now, reimport one type of record, write the report this afternoon. Without an action that means opening the Workflows tab and pressing Run on the right one, or typing the same prompt into a session again. An action puts it one click away, with the few things that change each time asked for in a small form, and keeps every launch on the project's record of runs.

How to use it

Launch one

Press the button. An action that asks for inputs opens a form first: each input is text, a number or a choice, starts from its default, and Run waits until the needed ones are filled. An action that asks before it runs shows its question after that; Back sends nothing. The button holds while its run goes on, and the line under the row follows the newest run: under way, then done with what it did, or failed with why.

Make, edit and remove them

The pencil at the end of the row opens the project's actions, each with Edit and Remove, and New action. A project with none yet has an Action button at the end of its tab row instead. The form takes a name, a short description for the button's tooltip, what it runs (a workflow of the project, a script, or a prompt with the session it goes into, empty for a fresh one), the inputs it asks for and whether it asks before it runs.

An input reaches what runs as {{key}}: in a prompt and in a workflow step's text as you typed it, in a command (a script action's, or a workflow's script step) in single quotes for the shell, so a value is never read as shell syntax. The form says when the text names a {{key}} no input fills.

Write the file instead

The actions live in the project's .cterm/actions.json, beside .cterm/workflows/, so they are committed with the project, and a session may write the file as well as the form:

{ "actions": [
  { "id": "reimport", "name": "Reimport one type", "run": { "kind": "workflow", "workflow": "import" },
    "inputs": [ { "key": "type", "kind": "choice", "options": ["products", "orders"], "required": true },
                { "key": "days", "kind": "number", "label": "Days back", "default": "7" } ] },
  { "name": "Clear the cache", "run": { "kind": "script", "command": "bin/cache clear" }, "confirm": "Clear it now?" },
  { "name": "Weekly report", "run": { "kind": "prompt", "text": "Write this week's report", "session": "reports" } }
] }

The id is made from the name when it is left out. The file is read one action at a time: one that does not read is left out with a red line under the buttons naming it, and the others still show. A change to the file reaches the open pages within a couple of seconds.

From the master view

The Actions panel holds the same buttons, every project's or one project's (the panel's project setting); a project's name opens its page.

Who may launch them

The project's owner and its members launch its actions and change them. One that runs a script (a script action, or a workflow with a script step) runs only for an admin among them, the rule of a workflow's script step. Anyone else who sees the project, an admin watching it among them, sees the buttons off, and the button's tooltip says why.

How it works

Every launch is a run of the workflow runner: a workflow action runs its file with the inputs filled in, and a script or a prompt action runs as a workflow of one step, so Stop and Resume, the session a prompt goes into, the ten minutes a script has and the file it writes what it did to are a workflow's. The run goes on the project's record of runs as an action's, with who launched it, the values it was given and its summary; a prompt's run that no script summed up says the first line of the session's answer. Only one run of an action goes at a time. The daemon checks the inputs and who may launch it again, and refuses an action that asks before it runs until the page says it was confirmed.

Scenarios

Reimport one type of record

A shop's import runs every night from a routine. When the supplier fixes their order feed at noon, Reimport one type… asks for the type and how many days back, runs the import workflow with them, and the line says how many records came in. The same run sits on the record with the values used, for whoever asks later why the orders moved.

A report on demand

Weekly report sends the same prompt into the project's reports session each time it is pressed, so the report grows in one conversation; the line under the buttons carries the first line of the answer.

Related

• Workflows: what a workflow action runs, and how a script says what it did.
• The project page: where the buttons sit.
• The master view: the Actions panel.