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 four 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, boolean, file, image), 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 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 or images 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 execution. Authentication. Each API trigger uses a project API key. Requests are authenticated with an HMAC signature: send the request with X-Signature and X-Timestamp headers, where the signature is the HMAC-SHA256 of "<timestamp>." + <request body> computed with your key’s secret. The key id travels in the URL; the secret is shown only once, when you create the key — store it securely. Async by default. The call returns immediately with a poll token / poll URL you can poll for status and the final result. If you’d rather get the result inline, pass a wait option to block briefly (up to ~60 seconds) — if the run finishes within that window the result comes back on the same call; otherwise you fall back to polling. Files. To send files, upload them first to the dedicated upload endpoint, which returns a file reference; pass that reference in the trigger input. Any files the workflow generates come back as downloadable links. Published version. API triggers run the use case’s currently published version — the call fails if nothing is published. Conversational sessions. For chat or hybrid use cases, an API caller can hold a conversational session and resume it across calls. Key management. Create, list, and delete API keys from the project. For who is allowed to manage keys, see Roles & permissions. 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.

​

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, 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