10.02 Creating a Workflow

Requires: Workflows Extra

The visual workflow builder, the trigger catalog, and the action handlers all live in the Workflows Extra at simplerisk/extras/workflows/. See What the Workflows Extra Does for the conceptual overview before reading this article.

Why this matters

The first workflow takes the longest. The visual editor has many controls, the trigger catalog is large, and the action set is unfamiliar until you've built one. After your first workflow, building the second takes 10 minutes; after a few, the patterns crystallize and additional workflows are routine.

This article walks through building a representative workflow end-to-end (Slack notification on Critical risk submission), so the next workflow is the second one, not the first.

Before you start

Have these in hand:

Admin access to Configure → Workflows (or wherever the Extra surfaces its admin page; typically /admin/workflows.php).
The Workflows Extra activated. See Installing Extras.
The cron worker running — workflows execute via the cron queue worker; without it, workflows queue but never run. See The Cron Jobs.
A clear trigger and a clear set of actions in mind. Don't open the builder and explore; sketch the workflow on paper first (trigger, conditions, action sequence). The builder is for transcribing the design.
Test data in a non-production instance. The first time you fire a workflow, you want it to fire against a test risk, not a real one.

Step-by-step

We'll build "When a Critical risk is created, post a message to Slack and email the security lead."

1. Open the workflow builder

Sidebar: Configure → Workflows opens the workflow list. Click Create Workflow (or equivalent button) to open the builder for a new workflow.

The builder is a canvas with a sidebar of available nodes (triggers, actions, branches, delays, ends).

2. Name and describe the workflow

In the workflow's metadata fields:

Name: Critical risk → Slack + email security lead. Operationally meaningful; future-you and other operators should immediately understand the purpose.
Description: a sentence or two describing the workflow's intent. Helpful for the next operator who looks at it.
Enabled: leave off for now; you'll enable after testing.

3. Pick the trigger

Drag the Trigger node onto the canvas (or it may be present by default). Configure it:

Trigger type: risk.created. (Other risk-event triggers like risk.updated, risk.closed, etc. are also options; risk.created is what we want for this workflow.)

The trigger node is the workflow's entry point. The execution starts here when the matching event fires.

4. Add a condition

We only want to fire for Critical risks (high score), not every risk. Add a condition:

Drag a Branch node onto the canvas after the trigger.
Configure the condition: risk.calculated_risk >= 8 (or the threshold matching your install's risk-level configuration for Critical).
The branch produces two outputs: true (condition matches) and false (doesn't match).

Connect the trigger to the branch. The true path will continue to the actions; the false path goes straight to End (no action for non-Critical risks).

5. Add the Slack action

Drag a Send Slack action onto the canvas (in the true path):

Webhook URL: the Slack incoming webhook URL for your target channel. (Slack's setup: https://api.slack.com/messaging/webhooks.)
Message: the message body. Use variable substitution to include risk details: :rotating_light: New Critical risk submitted: ** (ID , score , owner ). Review at . Variables in are substituted at execution time with the actual values from the risk's context.

Connect the branch's true output to this action.

6. Add the email action

Drag a Send Email action onto the canvas in parallel with (or after) the Slack action:

Recipients: security-lead@example.com (or pick from the team / owner / additional-stakeholders fields if your design uses dynamic recipient lists).
Subject: Critical risk submitted: .
Body: pick a template from workflow_email_templates or write inline: ``` A Critical risk was submitted in SimpleRisk:

ID: Subject: Score: Owner: Description:

Review the risk at . ```

Connect to the action chain.

7. Connect to End

Drag an End node onto the canvas. Connect the action chain (and the branch's false output) to End. This terminates the workflow.

The completed graph: Trigger → Branch (condition: critical) → [true: Send Slack → Send Email → End] / [false: End].

8. Save and validate

Click Save. The builder validates the graph (every node has connected edges, every action's required fields are filled in). Fix any reported issues; save again.

The workflow is saved but not yet enabled.

9. Test in non-production

Don't enable in production yet:

Create a Critical test risk in a non-production SimpleRisk instance with the workflow enabled.
Wait for the cron worker to pick up the queued execution (typically within a minute).
Verify the Slack message arrived in the configured channel.
Verify the email arrived at the configured address.
Check workflow_executions in the database to see the execution status (success or failed).

If the execution is failed, look at the error message; common causes: invalid Slack webhook URL, SMTP not configured (see Email and the Notification Extra), variable substitution issues.

Iterate until the workflow fires correctly. Then deploy to production.

10. Enable in production

Replicate the workflow in production:

Option A: build it again in the production builder (slower but explicit).
Option B: export the workflow JSON from non-production and import to production (faster, requires a workflow-export feature in the Extra; check the version).
Option C: use a deployment pipeline that manages workflow JSON in version control.

Once in production, set Enabled to true. The workflow now runs against new Critical risk submissions.

11. Monitor and tune

Check workflow_executions periodically. Look for:

Failures — investigate and fix.
High volume — if the workflow fires too often, refine the conditions.
Latency — if executions queue up faster than the worker processes them, scale the worker or simplify workflows.

Workflows are configuration; they evolve. Plan for periodic review.

Variations on the basic pattern

Once you've built one workflow, common variations:

Add delay: insert a Delay node between actions to wait N hours/days before sending a follow-up reminder.
Add wait-for-event: insert a Wait node to pause until a specific downstream event fires (e.g., wait until the risk is reviewed).
Multiple branches: complex routing based on multiple conditions.
Webhook to external system: instead of Slack/email, dispatch to your SOAR platform, ticketing system, or custom integration.
Email template reuse: define common templates in workflow_email_templates; reference them by name across multiple workflows.

Common pitfalls

A handful of patterns recur with workflow creation.

Building in production without testing. The first execution may produce unexpected output; testing in non-production catches the issues without affecting real users.
Forgetting to enable the workflow. A defined-but-disabled workflow doesn't run. Verify enabled status after creation.
Using a Slack/Teams webhook URL in version-controlled workflow definitions. The webhook URL is a secret; treat it as one. Some Extras let you reference settings or environment variables for these values.
Variable substitution typos. works; doesn't. The variable names are documented in the Extra's reference; verify before firing.
Conditions that never match. A condition like risk.calculated_risk > 100 (when scores are 0–10) never matches, so the workflow's action branch never executes. Test the condition logic.
Long delays without monitoring. A workflow that pauses for 30 days then sends a reminder might fail at month-end if SimpleRisk is upgraded mid-pause. Verify long-running executions survive upgrades.
Building workflows that loop. A workflow that fires on risk.updated and dispatches a webhook that calls the SimpleRisk API to update the same risk produces infinite loops. Test for self-triggering.
Sending high-volume notifications. Slack channels overflow; recipients ignore alerts. Tune trigger conditions to match what genuinely warrants attention.
Not documenting the workflow's intent in the description. Future operators see the JSON definition but no context for why the workflow exists. Use the description field.
Letting the cron worker fall behind. If executions queue faster than they process, the workflow effect is delayed. Monitor queue depth.

Reference

Permission required: check_admin for the workflow builder.
API endpoint(s): The Extra exposes workflow-management endpoints (typically under /api/v2/admin/workflows/...); the builder UI is server-rendered.
Implementing files: simplerisk/extras/workflows/index.php (the Extra's main file); simplerisk/admin/workflows.php (the visual builder UI); simplerisk/includes/workflows.php (the trigger catalog and helper functions); simplerisk/includes/workflows/executor.php (the runtime executor).
Database tables: workflow_definitions (workflow definitions); workflow_executions (execution instances); workflow_email_templates (email body templates); workflow_step_outputs (per-step output for variable substitution).
config_settings keys: workflows (Extra activation flag).
External dependencies: The cron queue worker (cron_queue_worker.php); for action targets: SMTP for email, Slack/Teams webhook URLs for chat, target URLs for webhook actions.