Workflow agent triggers
Workflow triggers start an Optimizely Opal workflow agent when their defined conditions are met. Each trigger listens for a specific event, such as a chat command, a scheduled time, a webhook call, or an email. When that event occurs, the workflow agent runs.
Trigger | Best for | Example |
|---|---|---|
On-demand runs from Opal Chat. | Type @workflow generate weekly brief to kick off automation. | |
Time-based and recurring tasks. | Nightly sync at 10:00 PM. | |
Immediate reactions to external events. | Trigger on incoming webhook or when a build pipeline completes. | |
Human approvals and attachment-driven flows. | Reviewer emails approval or sends a CSV to process. |
Trigger limitations and considerations
Connections
When configuring a trigger for your workflow agent, the trigger establishes a connection to a specific associated Optimizely instance during its creation.
If you change the connection after creating a trigger, the trigger may continue to reference the original instance. This can lead to unexpected behavior or issues where the workflow agent does not interact with the intended instance.
To prevent this, ensure that your connections to all associated instances are established before creating workflow triggers. If you must change a connection, recreate any affected triggers to ensure they are correctly linked to the updated instance.
See the Connections section in the Get started with Optimizely Opal for administrators documentation.
Creator
A workflow agent's actions display as performed by the user who created the trigger. For example, if User1 creates a trigger and the workflow agent creates a page in Optimizely Content Management System (SaaS), User1 displays as the page's creator.
Field importance for AI
Descriptions and other configuration fields play an important role in how Opal processes workflow agents. All description fields contribute to clarity, maintainability, and future functionality. Required fields are meaningful either immediately or for upcoming platform capabilities. Because of this, enter complete and accurate descriptions for all fields, including those in specialized agents and tools.
Trigger priority
Trigger priority lets you control which workflow agent runs execute first when your Opal instance reaches its concurrency limit. The concurrency limit is the fixed number of workflow agent runs that an instance executes at the same time. Set a priority on each trigger so that user-facing workflow agents run without delay and automated, high-volume workflow agents wait for capacity.
Each trigger has a Priority setting with two options:
- Standard – The run takes precedence when slots are limited. Use it for workflow agents where someone waits for a response.
- Background – The run yields to standard runs when slots are limited. Use it for automated or batch workflow agents where a short delay is acceptable.
Why trigger priority matters
Workflow agents share a fixed number of execution slots per instance. Without priority, every run competes equally for those slots. For example, a scheduled workflow agent starts dozens of runs at midnight. Those runs block a teammate who starts a workflow agent from Opal Chat the next morning, even though the chat interaction needs an immediate response.
When a background run reaches a slot while a standard run waits, the background run releases the slot and reschedules. Interactive workflow agents always get first access to execution capacity.
Default priority by trigger type
Each trigger type has a default priority that matches its typical use. Change the priority on any trigger at any time.
Trigger | Default priority | Reason |
|---|---|---|
Chat | Standard | Someone starts the run and waits for a response. |
Scheduler | Background | Runs automatically on a recurring cadence. |
Webhook | Background | Runs automatically and often in high volume. |
Background | Processes incoming email automatically. |
Trigger priority examples
Priority matters most when an interactive workflow agent and an automated one share the same instance. The following examples demonstrate how the default priorities keep interactive runs responsive during heavy automated activity.
- A content team generates SEO metadata on demand with a chat trigger. A separate scheduled workflow agent audits broken links every 30 minutes. Keep the audit at Background so it yields whenever someone requests metadata.
- A webhook trigger ingests product feed updates and can receive hundreds of events at once. Merchandisers ask inventory questions through a chat trigger. Keep the webhook trigger at Background so feed processing never blocks merchandiser queries.
How Opal schedules runs by priority
When a run starts, Opal assigns it an execution class based on the trigger's priority. The execution class determines how the run behaves at each concurrency gate, which is a point where Opal checks for an available slot.
- The run reaches a concurrency gate at workflow start, before a step executes, or after a step completes.
- A standard run proceeds into the next available slot.
- For a background run, Opal checks whether any standard runs wait for a slot on the same instance.
- If a standard run waits, the background run releases its slot and reschedules.
- If no standard run waits, the background run proceeds.
Opal repeats this check throughout the run, not only at the start. A background run that is already in progress yields to a standard run that arrives between steps.
Trigger priority considerations
Keep the following in mind when selecting a trigger's priority:
- Priority affects scheduling only when your instance is at or near its concurrency limit. When slots are available, both execution classes run immediately.
- Opal defers a background run instead of canceling it. The run retries until a slot opens.
- A priority change applies to runs created after the change. Runs already in progress keep their original execution class.
- When a trigger has no explicit priority, Opal uses the default for that trigger type.
- Priority applies to top-level runs. A nested workflow agent inherits the execution context of the parent run.
Chat trigger
The Chat Trigger starts a workflow when you or a teammate sends a specific message or command in Opal Chat.
Configure a chat input trigger
- Enter a Name.
- (Optional) Enter a Description.
- (Optional) Select a Priority from the drop-down list. See Trigger priority for more information.
- (Optional) Enter a Helper Message. This message displays when someone @mentions the agent in Opal Chat to guide their input.
The Preview displays how your helper message displays to users in Opal Chat.
- Click Save.
Use cases for a chat trigger
The chat trigger is ideal for workflow agents to run on demand from Opal Chat without a manual click or external system event. Use it for tasks such as clearing old data or generating reports.
Scheduler trigger
The scheduler trigger starts a workflow automatically at a specific time or on a recurring schedule. This is useful for workflows that run consistently without manual intervention, like sending weekly reports or syncing data every night.
Note
The scheduler trigger's time settings are in Coordinated Universal Time (UTC).
Configure a scheduled trigger
- Enter a Name.
- (Optional) Enter a Description.
- (Optional) Select a Product Instance. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Opal instance.
- (Optional) Select a Priority from the drop-down list. See Trigger priority for more information.
- (Optional) Enter a Trigger Message. The trigger message is standard plain text written in natural language that the workflow sends to the next agents when the trigger occurs. No special syntax or templating language is required. Write your request exactly as you would type a chat message to an AI agent.
- Sending the message – Type your instruction directly into the Trigger Message field. For example, The target audience is Marketers.
- Receiving the message – The agent processes this exact text as its initial prompt and acts on its configured capabilities. If one of the following agents has an input variable of target audience, it uses the value Marketers.
- Configure the one time trigger date or recurring time.
- One time trigger
- Keep the Recurring toggle off.
- Enter a Trigger Date or click the Calendar to select a date.
- Use the Trigger Time drop-down lists to select a time. Times are listed in your local time zone.
- Recurring – Standard
- Toggle Recurring on.
- Select the Standard tab.
- Enter or use the arrows to select how often the trigger occurs.
- Select how often the trigger occurs from the drop-down list.
- Select which days the trigger occurs.
- Select an End Type from the drop-down list.
- If you select Max Occurrences, enter the number of occurrences.
- If you select End Date, enter the end date.
- Review the Preview and ensure the dates and times look correct.
- Recurring – Advanced (Cron)
- Toggle Recurring on.
- Select the Advanced (Cron) tab.
- Enter a Cron Expression for how often you want the trigger to occur. See Advanced (Cron) expressions for the scheduled trigger for information.
- Select an End Type from the drop-down list. Based on the end type you selected, complete the following:
- No End – Skip to step 5.
- Max Occurrences – Enter the number of occurrences.
- End Date – Enter the end date.
- Review the Preview and ensure the dates and times look correct.
- Click Save.
Advanced (Cron) expressions for the scheduled trigger
Cron expressions are a standardized way to define repeating schedules. They consist of five fields that represent a time pattern.
* * * * *
| | | | |
| | | | └─ Day of week (0–6, where 0 = Sunday)
| | | └── Month (1–12)
| | └─── Day of month (1–31)
| └──── Hour (0–23)
└───── Minute (0–59)The following table includes common cron expressions:
Goal | Cron Expression | Explanation |
|---|---|---|
Run every day at midnight | 0 0 * * * | At 12:00 AM every day |
Run once a week (Sunday) | 0 9 * * 0 | At 9:00 AM every Sunday |
Run once a month | 0 8 1 * * | At 8:00 AM on the 1st of every month |
Run every other day | 0 7 */2 * * | At 7:00 AM every two days |
Run every weekday (Monday–Friday) | 0 6 * * 1-5 | At 6:00 AM, Monday through Friday |
Note
Use Opal to help you formulate your cron expression.
For example, enter What would be the cron expression for running the job every night at 10 pm?
Use cases for a scheduler trigger
A scheduler trigger is ideal when you want workflow agents to
- Run consistently without requiring manual intervention to start them.
- Automate maintenance tasks like clearing old data or generating reports.
- Align with business cycles, such as monthly billing or weekly marketing updates.
Webhook trigger
The webhook trigger starts a workflow when an external system sends an HTTP request to a unique endpoint. Use this trigger to respond to events that occur outside of Opal. For example, a content update event in Optimizely Graph, a flag update in Feature Experimentation, or a build pipeline completion event.
Configure a webhook trigger
- Enter a Name.
- (Optional) Enter a Description.
- (Optional) Select a Product Instance from the drop-down list. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Opal instance.
- (Optional) Select a Priority from the drop-down list. See Trigger priority for more information.
- (Optional) Select your Timezone from the drop-down list. The agent uses the timezone when it talks about dates and times, like "today" or "this morning". If that the timezone is not known, the agent says so rather than guess. Systems calling this webhook trigger can override it by sending a Time-Zone header with an IANA name, for example Asia/Dhaka.
- (Optional) Select the Payload Content Type from the drop-down list. This specifies the format of the data (payload) the webhook expects to receive. Common types include application/json (for JSON data). See Example payload content types.
- (Optional) Enter a Payload Schema to define the structure and data types of the expected payload. A schema helps validate incoming data and ensures the webhook processes information correctly. Enter this in JSON schema format.
- (Optional) Enter a secret value for the Auth Key that authenticates incoming webhook requests (for example, a token or API key). This enhances security by ensuring only authorized senders can trigger the webhook.
- (Optional) Select the Auth Header Name of the HTTP header that sends the auth key. Common examples include Authorization or X-Webhook-Secret.
- (Optional) Enter the string template for the Auth Header Format to construct the header.
- Click Save. The system generates the Webhook URL automatically.
- Copy this URL and use it in the external system.
Note
You cannot update the Auth Key, Auth Header Name, and Auth Header Format after saving the trigger. To edit them, delete the existing webhook trigger and create one with the correct fields.
Example payload content types
Content type | Parsed as | Example header |
|---|---|---|
application/json | JSON object. | Content-Type: application/json |
application/x-www-form-urlencoded | Key and value map. | Content-Type: application/x-www-form-urlencoded |
text/plain | Raw string. | Content-Type: text/plain |
Use cases for a webhook trigger
Choose the webhook trigger when you want workflow agents to start immediately in response to external events, without polling or manual action. The webhook trigger works well for real-time syncs, notifications, and event-driven automation.
Email trigger
The Email trigger starts a workflow when an email is sent to the email address that you set as the Trigger Recipient.
The trigger activates only when the following conditions are met:
- An email is sent to the Trigger Recipient.
- The email matches the Sender Filters and optionally the Subject Filters.
This ensures that only valid or expected messages start the workflow.
The system does not support custom domains and Reply-To headers. Opal's domains use DomainKeys Identified Mail (DKIM), Domain-based Message Authentication, Reporting, and Conformance (DMARC), and Sender Policy Framework (SPF) to maintain deliverability. For security, Opal restricts sending from arbitrary addresses.
Important
Before using the email trigger, you must configure the email domain. See Email domain for information. After you set your Email Domain, you cannot update it.
Configure an email trigger
Each workflow agent can have one email address recipient. Enter the following data and click Save.
- Enter a Short Description for the email trigger.
- (Optional) Select a Product Instance. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Opal instance.
- (Optional) Select a Priority from the drop-down list. See Trigger priority for more information.
- Enter the email address for the Trigger Recipient. This is the part before the "@" symbol.
- Click Copy to copy the email address to your clipboard.
- Define criteria to filter incoming emails based on sender's email address in the Sender Filters. Only emails matching these conditions trigger the workflow agent.
- (Optional) Click Add Filter for Sender Filters to add additional filters.
- (Optional) Click Add Filter for Subject Filters to define criteria to filter incoming emails based on their subject line. Only emails matching these conditions trigger the workflow agent. For example, you can require subject lines that contain Approved or Request Details.
- (Optional) Select Match case to limit results to text with the exact capitalization you entered.
- Click Save.
Use cases for an email trigger
- Approvals and sign-offs – A reviewer sends "approve" or "deny", and the workflow agent branches accordingly.
- Vendor intake through email – A partner emails a CSV or PDF to a monitored alias, and the workflow agent starts and processes the attachment.
- Change requests with notes – A stakeholder replies that an item needs changes with comments. The workflow agent routes back to the owner.
- Lightweight ticket creation – Inbound emails trigger triage, labeling, and assignment without a separate helpdesk.
Difference between an email trigger and the send_email tool
The email trigger and the send_email tool serve different purposes.
- The Email Trigger starts a workflow agent when an email is sent to the automatically generated trigger address.
- The send_email tool sends emails from within a workflow agent. Send these emails to any external address. The tool is not limited to sending messages to the trigger address.
Next steps
See Create a workflow agent.
Note
If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applicationsTurn generative AI off across Optimizely applications.