Playbook Button Triggers

11 min

Playbook Button Triggers create interactive buttons in application records that, when clicked, execute a playbook with the current record's data. Unlike automatic triggers (like Record Event or Schedule triggers), button triggers give users control over when to execute a playbook, making them ideal for manual workflows, approvals, or user-initiated actions.

Key Benefits

Manual Control: Users decide when to execute the playbook by clicking the button

Record Context: Full access to the current record's data when the playbook runs

Seamless Integration: Buttons appear directly in the application record interface

Flexible Configuration: Create buttons from the playbook canvas or application builder

Reusable Buttons: Multiple playbooks can use the same button, or create new buttons as needed

No Flow Rebuilds: Buttons can be added or modified without requiring reconstruction of the entire flow

How to Create Playbook Button Triggers

You can create a Playbook Button using two methods:

From the playbook

From the application

Method 1: Create Playbook Button from a Playbook

From the Add section, drag and drop Playbook Button to the canvas.

Click on the added Playbook Button to view the Trigger configuration panel.

In the Application dropdown menu, select the desired application.

The dropdown shows all available applications in your tenant

You can filter applications by typing in the search box

Once selected, a link appears to "Open application in a new tab" for quick access

In the Button label dropdown menu:

Click Create new to create a new playbook button (a unique name will be generated automatically, e.g., "Button 1", "Button 2")

Or select an existing playbook button from the dropdown

Note: Buttons that are already triggering a different flow will be disabled and show a tooltip

If you selected Create new, a notice appears: "Saving this playbook will create a new button in the application."

Save the playbook to finalize the button creation.

Note: The button will appear in the selected application's record view once the playbook is saved.

Method 2: Create Playbook Button from the Application

To create a playbook button from the application builder:

Navigate to APPLICATIONS and APPLETS. Either select an existing application or click the plus icon to create a new one.

Click and drag Playbook Button to the FORM LAYOUT section.

On the FIELD PROPERTIES tab:

Edit the Button Label if desired (this is the text that appears on the button)

From the Playbook dropdown menu, select the playbook that this button will trigger when clicked on an application's record

The playbook must be published and enabled to be selectable

Click Save to finalize your button creation.

Note: When creating a button from the application builder, the button is immediately available in the application. If you later add a Playbook Button trigger to a playbook and select this existing button, the playbook will be associated with that button.

Playbook Button Trigger Outputs

When a playbook button is clicked, the playbook receives event data containing the current record's information. This data can be accessed in your playbook actions.

Event Data Structure

$event.data.application: Information about the application:

id: Application ID

uid: Application UID

name: Application name

$event.data.currentUser: Information about the user who clicked the button:

id: User ID

username: Username

isSystemUser: Boolean indicating if the action was performed by the system

$event.data.record: Current record data:

id: Record ID (internal identifier)

url: URL to view the record in the UI

values: Object containing all field values (keyed by field key)

Note: Unlike Record Event triggers, button triggers do not provide previous values since they are not triggered by record updates.

Accessing Record Data in Playbooks

You can access record data in your playbook actions using the $event.data prefix:

Examples:

Note: Field values are accessed using field keys (not field IDs or names). Field keys are typically lowercase with hyphens (e.g., priority-level, assigned-to).

Event Metadata

Event Type: record

Event Action: button (triggered by button click)

Event FQN: turbine.record.button

Event Source: turbine

Example 1: Manually Initiating a Critical Alert Workflow

Scenario: A SOC analyst needs to manually escalate certain incidents to a critical alert status when they determine that a high-severity incident requires immediate attention. The playbook button trigger allows them to initiate a remediation workflow directly from the incident management application.

Configuration:

Create the Playbook Button Trigger:

From the playbook canvas, drag and drop the Playbook Button trigger.

In the Application field, select the Incident Management application.

In the Button Label field, select Create new and name the button Escalate to Critical.

Save the playbook to create the button in the application.

Add a Condition Action:

Drag a Condition action into the flow.

Check if $event.data.record.values.incident-state does not equal "Critical".

If true, proceed with escalation; otherwise, inform the user.

Create Variables:

Drag a Create Variables action into the flow.

Create variables:

incident_id: $event.data.record.id

priority_level: $event.data.record.values.priority-level

incident_state: $event.data.record.values.incident-state

Add Update/Create Record Action:

Drag an Update/Create Record action into the flow.

Configure to update the incident state to Critical.

Use key field: $event.data.record.values.tracking-id

Patch value: incident-state = "Critical"

Add HTTP Action for Notification:

Drag an HTTP action into the flow.

Configure POST request to external notification system (e.g., PagerDuty or Slack).

Endpoint: https://api.pagerduty.com/incidents

Payload: {"incident_id": "{{$variables.incident_id}}", "priority_level": "{{$variables.priority_level}}", "status": "Critical"}

Add Send Notification Action:

Drag a Send Notification action into the flow.

Configure to notify the security team.

Title: "Incident Escalated to Critical"

Body: "Incident {{$variables.incident_id}} has been escalated to Critical status. Priority: {{$variables.priority_level}}"

Result: When the analyst clicks the "Escalate to Critical" button, the incident is automatically updated to Critical status, and notifications are sent to external systems and the security team. If the incident is already critical, the user is informed.

Example 2: Manual Incident Closure with Verification

Scenario: An analyst needs to manually close an incident after verifying resolution. The playbook button allows them to close the incident, update external systems, and notify stakeholders with a single click.

Configuration:

Create the Playbook Button Trigger:

From the playbook canvas, drag and drop the Playbook Button trigger.

In the Application field, select the Incident Management application.

In the Button Label field, select Create new and name the button Close Incident.

Save the playbook to create the button.

Add a Condition Action:

Drag a Condition action into the flow.

Check if $event.data.record.values.resolution-summary exists (is defined).

If true, proceed with closure; otherwise, inform the user that a resolution summary is required.

Create Variables:

Drag a Create Variables action into the flow.

Create variables:

incident_id: $event.data.record.id

closure_time: Current timestamp

resolution_summary: $event.data.record.values.resolution-summary

Add Update/Create Record Action:

Drag an Update/Create Record action into the flow.

Configure to update the incident status to Closed.

Use key field: $event.data.record.values.tracking-id

Patch value: incident-state = "Closed"

Add Parallel Action:

Drag a Parallel action to execute multiple tasks simultaneously:

Branch 1: Send Notification to stakeholders

Branch 2: HTTP Action to update external system (ServiceNow/Jira)

Branch 3: HTTP Action to log closure in separate system

Configure Branch 1 - Send Notification:

Drag a Send Notification action.

Configure to notify assigned users/groups.

Title: "Incident Closed: {{$variables.incident_id}}"

Body: "Incident has been closed. Resolution: {{$variables.resolution_summary}}"

Configure Branch 2 - Update External System:

Drag an HTTP action.

Configure PUT request to external ticketing system.

Endpoint: https://api.servicenow.com/api/now/table/incident/{{$event.data.record.values.external-ticket-id}}

Payload: {"state": "Closed", "close_code": "Resolved"}

Result: When the analyst clicks the "Close Incident" button, the incident is automatically closed, external systems are updated, and stakeholders are notified. If a resolution summary is missing, the user is prompted to add one first.

Example 3: Export Record Data to External System

Scenario: An analyst needs to export incident data to an external system for further analysis. The playbook button allows them to trigger the export with current record data.

Configuration:

Create the Playbook Button Trigger:

From the playbook canvas, drag and drop the Playbook Button trigger.

In the Application field, select the Incident Management application.

In the Button Label field, select Create new and name the button Export to External System.

Save the playbook to create the button.

Create Variables:

Drag a Create Variables action into the flow.

Create variables to store record data:

incident_id: $event.data.record.id

incident_data: $event.data.record.values (entire record values object)

Add HTTP Action:

Drag an HTTP action into the flow.

Configure POST request to external system API.

Endpoint: https://api.externalsystem.com/incidents

Method: POST

Body Type: JSON

Body:

Add Send Notification Action:

Drag a Send Notification action into the flow.

Configure to notify the user who clicked the button.

Title: "Export Successful"

Body: "Incident {{$variables.incident_id}} has been exported to the external system."

Result: When the analyst clicks the "Export to External System" button, the current incident data is sent to the external system, and the user receives a confirmation notification.

Best Practices

Clear Button Labels: Use descriptive button labels that clearly indicate what action will be performed (e.g., "Escalate to Critical" instead of "Button 1").

User Feedback: Always provide feedback to users after button clicks, either through notifications or by updating the record status.

Error Handling: Include error handling in your playbooks to handle cases where button actions might fail (e.g., external API failures, missing required fields).

Button Availability: Consider using conditions or record restrictions to control when buttons are available or enabled.

Avoid Infinite Loops: Be careful when updating records in playbooks triggered by buttons, as this won't create infinite loops but may cause unexpected behavior.

Test Thoroughly: Test button triggers with various record states to ensure they work correctly in all scenarios.

Documentation: Document what each button does so users understand the consequences of clicking it.

Access Control: Ensure users have appropriate permissions to execute the playbook and access the record data.

Troubleshooting

Button Not Appearing:

Verify the playbook is published and enabled

Check that the application is correct

Ensure the button label is configured

Refresh the record page

Button Disabled:

Buttons are disabled if they're already triggering a different flow

Check if another playbook is using the same button

Create a new button if needed

Playbook Not Executing:

Verify the playbook is published and enabled

Check playbook run history for errors

Verify user has permissions to execute the playbook

Check that the application and button configuration are correct

Field Values Not Accessible:

Verify you're using field keys (not field IDs or names)

Check that fields exist in the application

Ensure field keys match exactly (case-sensitive)

Use $event.data.record.values.fieldKey format

Record Data Missing:

Button triggers provide current record data only (no previous values)

Ensure the record is saved before clicking the button

Check that the record has the expected field values

External API Failures:

Add error handling in your playbook

Check API endpoints and authentication

Verify network connectivity

Use retry/repeat settings for HTTP actions