Workflows

Workflows are multi-step automation chains that execute a sequence of actions across one or more servers. They let you build complex operational procedures — deploy pipelines, health-check routines, maintenance scripts — and run them with a single tap or trigger them externally from Tasker, iOS Shortcuts, or a deep link.

Workflows are a Pro feature.

Workflow Structure

A workflow consists of:

• Name — a descriptive label (e.g., “Deploy Production”, “Nightly Health Check”).
• Description — optional notes about what the workflow does.
• Steps — an ordered list of actions to execute sequentially.
• Notification Settings — whether to send local notifications on success, failure, or both.
• Schedule Expression — an optional cron-like expression for future scheduling support.
• Enabled/Disabled — toggle a workflow on or off without deleting it.

Workflows are serialized as JSON and stored in SharedPreferences. Each workflow gets a UUID on creation.

Step Types

Every step in a workflow has a type, an optional connection target, a timeout, and a failure action. The four step types are:

Execute

Runs a raw shell command on a specified connection. You provide the command string and select which saved connection it should run on. The step succeeds if the command exits with code 0.

Step: Execute
Connection: production-web-01
Command: cd /app && git pull origin main
Timeout: 60s
On Failure: Abort

Snippet

Runs a saved snippet by name on a connection. If the snippet contains variables, you can provide static values in the step’s variable map. The workflow engine looks up the snippet by name (case-insensitive) and executes the resolved command.

Step: Snippet
Connection: staging-db
Snippet: "Restart Service"
Variables: { "service": "postgresql" }
Timeout: 30s
On Failure: Continue

Delay

Pauses workflow execution for a configurable number of seconds. Useful for waiting between a deploy and a health check, or for spacing out commands to avoid rate limits.

Step: Delay
Wait: 10 seconds

The delay step always succeeds.

Notify

Fires a local notification on the device. If you provide a custom message in the command field, that message is used. Otherwise, the notification body contains the output from the previous step (truncated to 500 characters).

Step: Notify
Message: "Deployment complete -- check the dashboard"

The notify step always succeeds and does not require a connection.

Failure Handling

Each step has an On Failure setting that controls what happens when the step fails (non-zero exit code, timeout, connection error, or exception):

Abort (default) — stops the workflow immediately. All remaining steps are marked as “skipped” in the results. This is the safest option for sequential dependencies where a later step relies on an earlier one succeeding.

Continue to Next Step — logs the failure and moves to the next step. Use this for non-critical steps like notifications or optional checks.

Go to Step — jumps to a specific step by its ID. This enables retry logic or fallback branches. If the target step ID is not found, the workflow aborts. Be careful with goto loops — there is no built-in loop detection, so a circular reference will run until cancelled or a step times out.

Execution Engine

The workflow engine (WorkflowService) processes steps sequentially using AutomationService for the actual SSH execution:

1. Before each step, it checks a CancellationToken to see if the user (or system) has requested early termination. If cancelled, all remaining steps are marked as skipped and the workflow returns with cancelled: true.

2. Each step runs with its own timeout (default 30 seconds). The timeout covers connection, authentication, and command execution combined.

3. A StepProgressCallback fires after each step completes, allowing the UI to update a progress indicator in real time.

4. After all steps finish, the engine evaluates the overall result. The workflow succeeds only if no steps were aborted and all non-skipped steps succeeded.

5. Based on the workflow’s notifyOnSuccess and notifyOnFailure flags, a local notification is sent with a summary (e.g., “Deploy Production finished successfully — 5/5 steps”).

Workflow Results

When a workflow completes, the result includes:

• Overall success/failure status and whether it was cancelled.
• Per-step results with stdout, stderr, exit code, and elapsed time.
• Aggregate counts: succeeded, failed, and skipped steps.
• Total elapsed time for the entire run.

Results are logged to the automation history database (capped at 500 entries) and can be viewed in the Automation History screen.

Triggering Workflows

From the App

Open the Workflows screen from Settings or the Automation section. Tap the play button on any workflow to start it. While running, a progress indicator shows the current step. Tap cancel to stop execution after the current step finishes.

Via Deep Link

zestssh://workflow?name=Deploy+Production&key=YOUR_API_KEY

Or by workflow ID:

zestssh://workflow?id=abc123-def456&key=YOUR_API_KEY

The workflow is looked up by name (case-insensitive) or UUID. An API key is required.

Via Android Intent

Action: com.affluentlabs.zestssh.WORKFLOW
Extras:
  key=YOUR_API_KEY
  workflow_name=Deploy Production

Via iOS Shortcuts

Workflows can be triggered through the URL scheme by creating a Shortcut that opens the zestssh://workflow URL.

Via Scheduled Tasks

On Android, use the task scheduler to run a workflow on a recurring interval. See Scheduled Tasks.

Creating a Workflow

Use the Automation Wizard to build workflows step by step, or create them directly from the Workflows screen:

1. Tap New Workflow and enter a name and optional description.
2. Add steps by choosing a type, selecting a connection (for execute/snippet), entering the command or snippet name, and setting the timeout and failure action.
3. Reorder steps by dragging. Delete steps by swiping.
4. Toggle notification preferences.
5. Save the workflow.

Best Practices

• Set the first step’s failure action to Abort if later steps depend on it.
• Use Delay steps between deploy and verification to give services time to start.
• Add a Notify step at the end so you get a push notification when the workflow finishes.
• Keep timeouts generous for commands that may take variable time (database migrations, builds).
• Test workflows manually before scheduling them.