Workflow Steps

Plugins can register custom workflow triggers and steps via the workflow client. These appear alongside the built-in ones in the workflow editor.

Getting the client

const workflowClient = ctx.getWorkflowClient();

Call registerStep on it for each trigger or step you want to add.

Registering a trigger

A trigger watches for a condition and fires the workflow when it occurs.

await workflowClient.registerStep({
	id: "my-trigger",
	type: "trigger",
	getOptions() {
		return [{ id: "interval", type: "integer" }];
	},
	create(ctx) {
		const interval = ctx.getOption("interval", "integer") ?? 60;
		const timer = setInterval(() => ctx.activate(false), interval * 1000);
		// return a cleanup function
		return () => clearInterval(timer);
	},
});

create(ctx) - WorkflowTriggerContext

Method Purpose
activate(allowRerun) Fire the workflow. allowRerun controls whether a second instance starts if one is already running.
getCreateReason() "startup", "trigger-add", or "options-update" - why this trigger instance was created
getOption(id, type, ...args) Read a configured option value
getWorkflowUuid() / getStepUuid() IDs of the workflow and this step
getLogger() Logger prefixed with the workflow name

create must return a cleanup function. It is called when the trigger is removed or its options change.

Registering a step

A step is an action that runs as part of a workflow after a trigger fires.

await workflowClient.registerStep({
	id: "my-step",
	type: "step",
	getOptions() {
		return [
			{ id: "target", type: "string" },
			{ id: "dry-run", type: "boolean" },
		];
	},
	async run(ctx) {
		const target = ctx.getOption("target", "string");
		const dryRun = ctx.getOption("dry-run", "boolean") ?? false;
		ctx.updateProgress(0);
		await doSomething(target, dryRun);
		ctx.updateProgress(1);
	},
});

run(ctx) - WorkflowStepContext

Method Purpose
updateProgress(percent) Report progress (0–1) to the UI
getOption(id, type, ...args) Read a configured option value
getWorkflowUuid() / getStepUuid() IDs of the workflow and this step
getLogger() Logger prefixed with the workflow name

If run throws, the workflow stops and marks the run as failed.

Option types

Type getOption return
"string" string | null
"boolean" boolean | null
"integer" number | null
"decimal" number | null
"enum" string | null (pass allowed values as third arg)

For enum options, declare the items in getOptions():

{
    id: "mode",
    type: "enum",
    enum: [
        { id: "fast", name: "Fast" },
        { id: "thorough", name: "Thorough" },
    ],
}

And read with:

ctx.getOption("mode", "enum", ["fast", "thorough"]);