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, and scheduled runs with static inputs 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.

Input field types

Each Start-node field has a type. Alongside scalars (string, number, integer, boolean, file, image) and structured objects, a field can be an array — a list of values of a chosen element type:

When you set a field's type to array, choose its item type — string, number, boolean, object, file, or image — to tell the platform how to render the input and how to resolve the values at run time. Array fields are a natural fit for the Foreach node, which iterates over a list, and for agents that need to reason over several files, images, or structured records at once.

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 the execution.

Requests are authenticated with a project API key and an HMAC signature over the body. The call is async by default: it returns a poll token you poll for the result, or you add a wait parameter to block briefly and get the result inline.

An API-triggered run behaves like any other. It runs the use case's published version, it can pass files in and hand files back, it can hold a conversational session across calls for a chat or hybrid use case, and it can pause on a Human Task for an external system to answer.

See API keys and the hooks API for the endpoints, the exact signing rule, the file and human-task flows, and the error codes.

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.

A schedule is either active or paused. You can pause a schedule to stop it temporarily without deleting the configuration and resume it later, or trigger it to run now outside its cron times.

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.

Inbound webhook

An inbound webhook gives the use case a stable public URL that an outside system POSTs to. The sender authenticates with its own signature over the request body, or with a static header value, and MagOneAI maps the sender's payload onto the Start node inputs.

A use case can carry several inbound webhooks, one per sender, each with its own secret, mappings, rate limit budget and delivery log.

Two requirements apply, and both are checked rather than assumed:

• The use case must be published, because a delivery is validated against the published schema.
• The interface type must be form. A chat or hybrid use case is refused, because a webhook has no resumable chat session.

Deliveries are deduplicated, so a sender's retry replays the original execution rather than starting a second one. Every request that reaches signature verification is recorded in a delivery log, which is where you debug a sender's integration.

See Inbound webhooks for authentication modes, field mapping, response codes and limits.

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.

State mode

The Start node has a State Mode setting that decides how a run carries variables between activities. Most workflows never need to touch it.

Use Temporal unless you have a reason not to. It is the default because it is the simplest thing that works, and Temporal's history is already the durable record of the run.

Redis mode exists for workflows whose state grows large enough that pushing every value through workflow history becomes the bottleneck. It moves the bulk out of history and into Redis, at the cost of a dependency the run now needs.

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.
• Pick a date range from a preset, or set your own bounds. A range covers the whole of each local day you chose, so "yesterday" includes every run from that day in your own timezone rather than a UTC window that clips both ends.
• 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. See per-step token usage for what each step records and why it can differ from the billed total.

Response feedback

Users can rate the outcome of a completed execution with a thumbs up or thumbs down and an optional comment. Feedback is anchored to the execution, so the same mechanism works whether the run came from chat, a form, or the API, and it shows up wherever the result is seen — MagOneAI Hub, the builder, and other surfaces.

• One rating per user, per execution. Rating again updates your previous rating rather than adding a second one; you can also clear it to un-rate. Comments are capped at 2,000 characters.
• Review in the builder. A project-scoped feedback list lets builders see what users flagged, filterable by rating and by use case, so you can find the runs worth investigating and improve the workflow.

Good patterns

• Start simple, then add triggers. Get the workflow working with a manual run in Studio first. Expose it via API, chat, or schedule 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