Workflow Lifecycle Event Triggers

Overview

Workflow lifecycle event triggers let you automatically respond when workflows in your environment are created, enabled or disabled, renamed, published, or when access to them changes. These events describe changes to the workflows themselves, not workflow executions, so you can build automation around workflow management.

In this article, we'll be covering the five workflow lifecycle events, what each one includes, how to set up a lifecycle event trigger, and common automation patterns.

Understanding workflow lifecycle events

gaiia publishes five workflow lifecycle events that can be used as event triggers:

• workflow.created: Fires when a workflow is created
• workflow.status_changed: Fires when a workflow is enabled or disabled
• workflow.metadata_updated: Fires when a workflow's name, description, icon, or labels change
• workflow.published: Fires when a new version of a workflow is published (from a draft, a direct save, or a version restore)
• workflow.permissions_changed: Fires when workflow permissions are granted to or revoked from users or user groups

The workflow.metadata_updated event only fires when the name, description, icon, or labels actually change. Saving a workflow without changing them does not trigger the event.

Event payloads

Every lifecycle event includes a workflow object with the workflow's id (its Global ID), key, and name. Each event adds its own fields:

workflow.created

Adds createdAt, the time the workflow was created.

workflow.status_changed

Adds isEnabled, which is true when the workflow was enabled and false when it was disabled, and updatedAt.

workflow.metadata_updated

Adds updatedAt. The event tells you that the name, description, icon, or labels changed; it does not list the old and new values. The workflow object shows the workflow's name after the change.

workflow.published

Adds publishedAt and a workflowDefinition object with the new version's id and version number.

workflow.permissions_changed

Adds action (EDIT_WORKFLOW or EDIT_WORKFLOW_EXECUTION), changeType (GRANTED or REVOKED), the userIds and userGroupIds affected, and updatedAt.

Setting up a workflow lifecycle trigger

1. Create a new workflow and select Event as the trigger type.
2. Select the lifecycle event you want to respond to from the list of events. Lifecycle event names start with workflow., and execution events start with workflow_execution..
3. Configure your workflow logic to respond to the event.
4. Access the event data using state.input in your workflow nodes.

The workflow fires whenever the selected lifecycle event occurs in your environment.

Common use cases

Monitoring workflow deployments

Send notifications when workflows are published:

• Trigger: workflow.published
• Format a message with the workflow name and the new version number
• Send it to a Slack channel or Teams for visibility

Tracking workflow creation

Log all new workflows for platform monitoring:

• Trigger: workflow.created
• Record the workflow name, key, and creation time
• Post to a monitoring channel or tracking database

Alerting on critical workflow changes

Watch for production workflows being disabled:

• Trigger: workflow.status_changed
• Check whether the workflow is on a critical list using a Condition node
• If isEnabled is false, send an urgent alert to on-call

Noticing renames and label changes

Know when a workflow's details change:

• Trigger: workflow.metadata_updated
• Log the workflow key, its current name, and the time of the change
• Update external documentation systems that reference the workflow

Auditing access changes

Keep a record of who was given or lost access to a workflow:

• Trigger: workflow.permissions_changed
• Log the workflow, the action, whether access was granted or revoked, and the users and user groups affected
• Send changes to your audit database or a security channel

Filtering lifecycle events

Use the skip execution mapper on your trigger to filter which lifecycle events actually run your workflow. The skip execution mapper receives the event payload in state.input and returns true to skip the execution or false to proceed.

Examples:

• Only run for a specific workflow: return state.input.workflow.key !== 'critical-provisioning-workflow';
• Only run when a workflow is disabled: return state.input.isEnabled;
• Only run when access is revoked: return state.input.changeType !== 'REVOKED';

Returning true skips the execution; returning false proceeds with it.

Accessing workflow details

Lifecycle events include the workflow's Global ID in workflow.id. To get more details about the workflow, use that ID with the gaiia GraphQL API node.

Permissions

• View: Users need Workflows > View permission to see workflows that use these events
• Create: Users need Workflows > Edit permission to create workflows that respond to lifecycle events

Limitations

• Workflow lifecycle events describe changes to workflows, not workflow executions. To trigger on execution results, use the workflow_execution.success, workflow_execution.failed, or workflow_execution.cancelled events instead.
• The workflow.metadata_updated event does not include the old and new values of what changed.