Triggers & execution

​

How a workflow starts

Every workflow execution begins with a trigger — something that tells the platform to run the workflow with specific input. MagOneAI supports five trigger sources so you can wire workflows into whatever surface your users already use. The trigger only decides how the workflow is started. Once it’s running, every trigger type executes the same workflow — so you can expose the same automation via multiple triggers without duplicating logic.

​

Defining what inputs the workflow expects

Every workflow has a Start node that declares what input it accepts. This input schema drives two things:

• The run form in Studio — Studio renders a form based on the schema so you can run the workflow with the right inputs.
• Validation at trigger time — API calls, chat-extracted parameters, scheduled runs with static inputs, and webhook payloads are all validated against the schema before the workflow starts. Bad inputs fail fast with a clear error.

Keep the schema tight: list the fields you actually use, mark the required ones, and include descriptions. That description becomes the label on the run form and helps chat triggers extract the right parameter from natural language.

​

Using inputs inside the workflow

Inputs and trigger metadata are available to any activity in the workflow through template variables:

• {{input.<field>}} — values from the trigger input (whatever the Start node accepted).
• {{system.user_id}}, {{system.execution_id}}, {{system.project_id}}, {{system.timestamp}} — contextual values the platform injects automatically.
• {{<activity_id>.<field>}} — output from an upstream activity.

Use these templates anywhere a value is accepted — prompts, tool parameters, condition expressions, human-task assignees. You’re writing the workflow once; the platform fills in the right values at run time.

​

Trigger types in detail

​

Manual (Studio)

Run the workflow directly from Studio’s run panel. Fill in the input form, submit, and watch execution live on the canvas. You can target the currently published version or the latest draft — see Versions & publishing for how to test drafts safely. Use manual runs when developing, debugging, demoing, or processing a one-off request.

​

API

Expose the workflow to other systems via MagOneAI’s workflow API. Your backend (or any HTTP client) sends the input payload and the platform starts execution, returning an execution identifier you can poll for status. Typical patterns:

• Trigger a workflow from your own application when a record changes.
• Queue one execution per item in a batch job.
• Wire workflows behind your existing API gateway so downstream services don’t need to know about MagOneAI.

​

Chat

Any workflow in a project can be reachable from MagOneAI Hub. When a user sends a message, the Hub matches the intent to the right workflow, extracts parameters into the workflow’s input schema, and starts execution. Results stream back into the conversation when the workflow completes. Pair chat triggers with workflows that are naturally request-response — summaries, lookups, approvals, and guided actions work particularly well.

​

Schedule

Add a schedule to a workflow to run it at cron times. You configure:

• A cron expression for when to run.
• A timezone so “9am” means the local business hour, not UTC.
• A static input payload that the scheduled runs use, if any.
• Whether the schedule is enabled — disable temporarily without deleting the configuration.

Scheduled runs use the currently published version of the workflow, so improvements you publish to the workflow take effect on the next scheduled run with no schedule changes needed.

​

Webhook

For workflows that should react to external events, enable the webhook trigger. MagOneAI gives you a URL to register with the upstream service; incoming requests are authenticated (via HMAC signature) and their payload becomes the workflow input. Use webhooks when an external system already knows how to push events — issue trackers, CRMs, payment providers, CI systems — so you don’t have to poll.

​

Watching an execution live

While a workflow runs, Studio shows it live on the canvas. For workflows that pause on a Human Task, the assigned user sees the task in their queue. Once they respond, execution resumes automatically.

​

Retry and error handling

Real-world tools fail occasionally — rate limits, timeouts, transient network issues. MagOneAI lets you set an error-handling strategy per activity, so important steps can be resilient without wrapping them in custom logic.

​

Strategies

• Retry — Try the activity again, with a configurable number of attempts and backoff between them. Best for transient errors like rate limits or timeouts.
• Respond — Stop the workflow gracefully with a predefined response. Useful when you want a clean user-facing failure rather than a crash.
• Abort — Fail the execution immediately. Appropriate for errors that should not be silently retried, such as invalid input or authorization failures.

Pick the strategy that matches the activity’s nature. A flaky API call probably wants retry; a step that validates business rules probably wants abort or respond.

​

Conditional routing around errors

For more nuanced recovery, use a Condition node after the risky activity to route based on the outcome — success goes one way, failure goes to a fallback path that escalates to a human, tries an alternative, or records the failure for later review.

​

Execution history

Every workflow keeps a history of its runs so you can audit, debug, and improve over time. From the use case’s Executions view you can:

• Filter by status (running, completed, failed, waiting), by trigger type, by date range, or by fields in the input.
• Drill into any execution to see the timeline, the input/output of each activity, agent reasoning, and tool calls with their parameters and responses.
• Inspect the variable store at each step — what values {{input.*}}, {{system.*}}, and upstream activity outputs held when this activity ran.
• See which version ran — useful when debugging a change: was this the new workflow, or the previously published one?
• Replay a failed run with the same input after fixing the underlying issue.

Execution history is also where LLM usage and cost surface — each run records the models called, the tokens consumed, and the cost so you can track spend per workflow and per activity.

​

Good patterns

• Start simple, then add triggers. Get the workflow working with a manual run in Studio first. Expose it via API, chat, schedule, or webhook only once it’s trustworthy.
• Keep input schemas honest. The schema is your contract with every trigger source — narrow, well-described fields make API integration easier and help chat triggers extract the right parameters.
• Use retry for transience, not logic errors. Retrying a genuine validation failure just delays the problem.
• Pair with versions & publishing. Scheduled runs, chat triggers, and API callers all resolve to the published version, so iterating safely means publishing deliberately.

​

Next steps