Skip to main content

Overview

Workflows enable automation of actions based on triggers. A workflow consists of:
  • Trigger: What starts the workflow (e.g., an API request, a new log event, or a new autodiscovered resource)
  • Actions: What the workflow does when triggered (e.g., send a Slack message, call the Formal API)
Workflows are defined in YAML and can be managed via Terraform or the Formal API.

Triggers vs Actions

A workflow has exactly one trigger and one or more actions. Actions can be chained together using depends_on and conditionally executed using if.

Workflow Structure

depends_on - Action Chaining

The depends_on field controls the execution order of actions. Actions with empty depends_on run immediately after the trigger. Subsequent actions run after their dependencies complete.

Referencing Previous Trigger and Action Outputs

Actions can reference previous triggers and actions outputs via the following syntax in CEL expressions:
  • trigger.<output_field>: reference any output field of the trigger
  • actions.<action_name>.<output_field>: reference any output field of an action by its name
Some arguments, such as if or the api-request allow argument, take CEL expressions by default. For arguments that take strings instead, embed CEL expressions via the ${{}} syntax.

Secrets

Store sensitive workflow data as secrets instead of writing them in the workflow YAML. Secrets are scoped to a single workflow. To add a secret, open the workflow in the editor and click Secrets. Click Create secret, then enter a name and value. Workflow editor header with the Secrets button highlighted Create workflow secret dialog with Name and Value fields Reference a secret in action args with secrets.<name> inside ${{}}:
Secret names must be valid CEL identifiers, such as soar_token. Values are never returned by the API or shown in the Control Plane. if conditions can’t read secrets.
If an action’s output or error contains a secret value, Formal replaces it with *** before storing the step result. Formal only masks the exact value, not encoded or transformed forms such as base64.

if - Conditional Execution

The if field is a CEL expression that determines whether a subsequent action should execute based on the previous actions or trigger.

Trigger Types

api-request

Triggered when a user calls the CreateWorkflowTrigger API endpoint. Useful for manually triggered workflows or integrations. Args: Outputs (available in actions): When the caller authenticates with an OIDC integration, user.oidc is also available: Example:
OIDC callers can reference verified claims directly instead of re-embedding them in payload:
Triggering via API:

new-log

Triggered when a new log event matches a specified condition. Useful for reacting to specific database queries, policy violations, or access patterns. Args: Outputs (available in actions): Example:

Unique logs

unique_by triggers the workflow only when a matching log’s key values are new, for example the first time a user loads a skill, or at most once an hour per user and resource. A key that is missing from a log, null, or an empty list counts as null, so logs missing the same key share it. To ignore such logs instead, check for the field in if, as the example below does. To give a missing key its own value, default it in the key expression, for example has(log.user.username) ? log.user.username : "unknown".
Keys are tracked from the moment the workflow is saved; logs from before then are not considered. Changing keys forgets every key seen so far, while changing reset_on or window keeps them. Encrypted key values differ on every log, so they are grouped as <encrypted>; key on unencrypted fields. A log whose keys expand to more than 100 combinations triggers one run without deduplication. Each workflow keeps at most one million keys, forgetting the least recently seen first.

new-autodiscovered-resource

Triggered when a new resource is autodiscovered via cloud integration (AWS, GCP, etc.). Useful for automatically onboarding new databases. Args: Outputs (available in actions): Example:

updated-autodiscovered-resource

Triggered when an existing autodiscovered resource is updated. Args: Outputs (available in actions): Example:

deleted-autodiscovered-resource

Triggered when an autodiscovered resource is deleted because it no longer exists in the cloud provider. Args: Outputs (available in actions): Example:

cron-schedule

Triggered on a recurring schedule defined by a standard 5-field cron expression (minute hour day-of-month month day-of-week). All times are evaluated in UTC. Useful for periodic checks, scheduled reports, and recurring maintenance tasks. Args: Outputs (available in actions): Example:
Recovery policy (optional): Under normal operation, cron triggers fire reliably every minute and recovery has no effect. It only matters in the unlikely event of a Formal platform outage where the workflow engine is temporarily unable to process scheduled triggers. When the platform recovers, any missed ticks are handled according to the recovery policy. If omitted, defaults to none. Missed triggers are capped at a 24-hour lookback window.
Cron schedules are always evaluated in UTC. To schedule at a local time, convert manually (e.g., 9am US Eastern = "0 14 * * *" during EDT or "0 13 * * *" during EST).

form-submission

Triggered when a user submits a Formal form via Slack. Useful for approval workflows, access requests, and other structured data collection scenarios. Args: Outputs (available in actions via trigger.form_submission): Example:
Referencing form values in actions:
See the Forms documentation for details on creating forms and the full Slack integration.

Action Types

send-slack-message

Sends a direct message to a Slack user or channel. Requires a Slack integration to be configured. Args: Outputs: Example:

ask-in-chat

Sends an interactive message with Yes/No buttons. The workflow pauses until the user responds. With denial_reason, choosing No opens a form where the approver gives a reason for the denial. Args: With several emails, each recipient gets the message as a direct message. The first answer decides the step, and every other copy is updated to show who answered. Outputs: Example:
To ask several approvers directly instead of a channel:

formal-app-command

Calls a Formal API endpoint using a machine user’s credentials. Args: Outputs: Example:

http-request

Sends an HTTPS request to any external API or webhook. Later actions can read the response. Args: Outputs: A non-2xx response doesn’t fail the action. Check status_code in a later action’s if. Example:

Terraform Examples

Inside a Terraform string, write $${{ so that Terraform passes ${{ through to the workflow instead of treating it as interpolation.

Next Steps

Policies

Learn about Formal policies for access control

Terraform Provider

Full Terraform provider documentation