Workflow Inputs

Workflow inputs are reusable workflow-level values that you define once and fill in before each run. Use them for values that change between executions — like test emails, user roles, environment URLs, or any other value you do not want to hard-code into a flow.

Inputs appear in the Configure tab when no node is selected, under the Workflow Inputs section.

01Defining inputs

Open your workflow in Flow Designer, then click the canvas background so no step is selected. In the Configure tab, use Workflow Inputs to add and manage workflow-level inputs.

Click + to add a new input, then fill in these fields:

Define inputs for any value that should be supplied at run time and reused across multiple steps. Then use workflow scenarios to save named sets of those input values, pair them with credentials, choose a default scenario, and control whether each scenario runs in a suite.

Use inputs for the fields that can vary across test cases. Use scenarios when you want to package those inputs into reusable run variations such as accounts, environments, regions, or roles.

When you add, remove, or rename workflow inputs, review any saved scenarios that use them so each scenario still has the values you expect.

02Referencing inputs in steps

Once defined, workflow inputs are available throughout your workflow. Type $var. in any macro-enabled field to see them in the typeahead, or reference them directly:

$var.user_email
$var.environment_url
$var.user_role

Use workflow inputs anywhere you need the same run-time value in multiple places, such as form fields, URLs, assertions, seed scripts, or setup flows. Prefer inputs over hard-coded values when you want to reuse the same flow for different users, environments, or test cases.

03Running with inputs

Click Run Flow to start a workflow that has inputs defined. Before the run begins, Flow Designer opens a run configuration step where you can choose the target environment, select a saved scenario, and review workflow input values.

Use scenarios to save named sets of workflow input values for repeated runs. A scenario can also include credentials, so you can reuse both the data and the authenticated context together. Mark one scenario as the default when you want it to load automatically for the workflow.

When you start a run, values resolve in this order:

1. Start with the workflow input's Default value.
2. Apply values from the selected scenario, if one is chosen.
3. Apply any run-time edits you make before clicking Run Flow.

If the selected scenario includes credentials, the run uses those credentials for that execution. If you switch scenarios before starting the run, Canary updates both the scenario-backed input values and the associated credentials for the new selection.

Review the resolved values, update any fields for this run, then confirm to start execution. Your run-time edits apply only to that run. They do not change the workflow input definition or overwrite the saved scenario.

Use this run configuration step to tailor one reusable flow to the exact case you want to execute, without editing the flow itself.

04Validation and requirements

Flow Designer validates workflow inputs while you configure them and again before a run starts.

• Turn on Required when a value must always be present.
• Leave Default value blank if you want users to enter a value at run time or supply it through a scenario.
• If Required is enabled and neither the selected scenario nor the workflow input default supplies a value, you must enter one before you can continue.
• If a scenario provides a value, it replaces the workflow input default for that run.
• Type-specific fields still expect matching values, such as a valid email for Email inputs or a number for Number inputs.

05Inputs in test suites

When a workflow with inputs runs as part of a test suite, Canary uses workflow scenarios to determine which input sets participate. This lets you expand suite coverage across multiple named variations instead of relying on a single default path.

• Suites can run one or more scenarios for the same workflow.
• Mark a scenario to include or exclude it from suite execution.
• Set a default scenario for ad hoc runs when you want one variation to load automatically.
• If no suite scenario supplies a value, Canary falls back to the workflow input default.
• No manual prompt appears during suite execution.

Use scenario inclusion settings to control exactly which accounts, environments, or test cases run as part of automated coverage.

06Inputs vs. other variable sources

07API usage

Pass input values when triggering a run via the API:

curl -X POST https://api.trycanary.ai/workflows/{id}/execute \
  -H "Content-Type: application/json" \
  -d '{"inputValues": {"user_email": "custom@example.com", "user_role": "admin"}}'

Any inputs not provided in the request body will use their default values.

08Related

• /docs/reference/workflows
• /docs/reference/flow-designer
• /docs/reference/workflow-scenarios
• /docs/reference/credentials