Skip to content

First project walkthrough

The path "from zero to the first running automated process" in Axon: who (owner/admin/manager/operator/engineer) does what and in what order. This is a "map on top of the other manuals" — the details of each step are in the corresponding linked manual.

1. What it is and why

VISION makes Time-to-Value the headline metric: "from zero to the first running automated process — three minutes" (Ladder step 1 "Baseline", a launch for a business user). This manual is the sequence of phases that gets you there: create the project → provision people → publish a workflow definition → connect credentials → create connector instances → enable the allowlist → configure the binding profile → run.

Most phases are configured once; every subsequent run is just "pick a case → Run". "Three minutes" is about that repeat path (and about the happy path where the definition is already published and the project has one instance per type — see §5).

2. Roles and access

Phase Who (role / permission)
Create the project, provision users owner / admin (create_project, manage_users)
Write the WorkflowDefinition, agent/prompt definitions in code engineer (git + deploy) — not an RBAC role
Publish a definition manager+ (publish_definition); catalog — catalog:install (manager+) / catalog:manage (admin/owner)
Connect credentials manager+ (credential:create); high-stakes approval — reviewer/manager+ (approve)
Create connector instances manager+ (connector:manage)
Enable the connector in the allowlist manager+ (project_connector:manage)
Configure the binding profile manager+ (workflow:configure_bindings)
Set project budgets owner/admin (and manager within the project — see Budgets-And-Cost.md)
Run a workflow operator+ (start_workflow + credential:use)

The full matrix — Roles-And-Permissions.md.

3. Where it is in Console

In order, you touch the sidebar sections: Projects (create the project) → Users (provision people) → (code: write the WorkflowDefinition) → Catalog / the definition page (publish / install) → Connectors (Add instance, Allowlist toggle) → Credentials (New credential) → Workflows → <definition> → Bindings (Auto-map / pick instances) → Budgets (limits) → Workflows → Run Wizard (run).

Each section in detail — in its own manual (see the links in §10).

4. Concepts (mental model)

What needs to be "assembled" for a workflow to run:

Project (created, not suspended)
  ├─ Users      — owner/admin provisioned a manager (and an operator for runs)
  ├─ WorkflowDefinition (published; declares ConnectorRequirement[] — named slots + logical types)
  ├─ Credentials (≥1 per needed type; status=active; for high-stakes — approved)
  ├─ ConnectorInstances (adapter+credential+non-secret config; usable per D42)
  ├─ project_connector_allowlist  → enabled=ON for each connector_key
  ├─ WorkflowBindingProfile  (slot → connector_instance; status=complete; may be auto_configured on first publish)
  └─ Budget  (set; otherwise side effects are fail-closed on budget)
        ↓
   Run Wizard: pick a case → Run → workflow_run_bindings_snapshot is pinned → execution

If the project has one usable instance per required type — on the first publish_definition the binding profile is created automatically (status=complete, auto_configured=true, "Review" banner), and phase 7 is skipped. That's the "happy path".

5. Flows: step-by-step scenarios

Flow 1 — The full path (by phase)

# Phase What's done Who More
0 Platform code Write connector adapters (modules/connectors/...), CredentialType (modules/credential_types/...), agent/prompt definitions; deploy. Shared by all projects. engineer (git+deploy) Connectors-Credentials.md §2.1, Agents-And-Prompts.md
1 Create the project An app.projects row, a basic ProjectConfig. owner/admin Projects-Lifecycle.md
2 Provision people Create a manager for the project (an operator — for runs, a reviewer — for approvals). owner/admin Users-And-Access-Management.md
3 Publish workflow definitions The engineer writes a WorkflowDefinition with ConnectorRequirement[] (named slots + logical types + required_actions); publishing via the API; or installing from the Catalog. engineer → manager+ Workflows.md, Templates-And-Catalog.md
4 Connect credentials Console → Credentials → New credential → pick a CredentialType → display name → OAuth consent / key entry → auto test_credential → status=active. Repeat for each account. High-stakes (requires_approval=true) → credential_proposal → approve. manager+; approval reviewer/manager+ Connectors-Credentials.md §5 Flow 2
5 Create connector instances Console → Connectors → Add instance → adapter + credential + non-secret config + display name → create_connector_instance. Repeat for each instance. manager+ Connectors-Credentials.md §5 Flow 3
6 Enable the allowlist Console → Connectors → Allowlist toggle ON for each connector_key. Without it webhooks are fail-closed, the connector is unavailable for bindings. manager+ Connectors-Credentials.md §3.1
7 Configure the binding profile Console → Workflows → <definition> → Bindings → Auto-map or pick an instance per slot manually → profile status=complete. (Skipped if the profile was auto_configured in phase 3.) manager+ Workflows.md, Connectors-Credentials.md §4
8 Set the project budget Console → Budgets → limits (period/categories/alert thresholds). Without a budget, side effects are fail-closed on the budget check. owner/admin/manager Budgets-And-Cost.md
9 Run a workflow Console → Run Wizard → pick a case → bindings from the profile (optional override) → Run → workflow_run_bindings_snapshot is pinned → execution (on a connector step the worker resolves the instance → takes the credential → policy/approval/audit/idempotency → side effect). operator+ Workflows.md, Cases.md, Approvals.md
10 Operations OAuth refresh (system); reauthorize on failure (Telegram alert → manager/admin); health monitoring; approvals; budgets; undo/compensation if needed. system + manager+ + reviewer Connectors-Credentials.md §7, Undo-And-Compensation.md

Flow 2 — The minimal happy path

owner creates the project and provisions a manager → manager: sets a budget → New credential → Add instance → Allowlist ON → (the binding profile is auto-created on the first publish if there's one instance per type) → operator: open the Run Wizard → pick a case → Run. On repeat runs only the last step remains — that's the "3 minutes to value".

Flow 3 — A project from a template

admin: Console → Templates → pick a project template → set variables/anonymization → apply. ConnectorMapper proposes a mapping required_connectors → real instances by type (a single candidate → auto; several → choice; none → "needs connecting"). Then — phases 4–9 as needed. Details — Templates-And-Catalog.md.

6. Options reference

"Can a workflow run" checklist — everything ✓:

# Condition Where to check
1 The project is created and not suspended/archived Projects
2 There's a user with start_workflow (operator+) with access to the project Users
3 The WorkflowDefinition is published Workflows
4 For each ConnectorRequirement type there's a usable connector instance (D42: active, not tombstoned, backing credential active/not purged) Connectors → instances
5 The corresponding connector_keys have Allowlist ON Connectors → allowlist
6 The definition's binding profile is status=complete (all slots mapped) Workflows → <def> → Bindings
7 The project budget is set Budgets
8 (if the workflow is case-aware) there's a suitable case Cases
9 (if there are agent steps) the agent definition is published, the executor profile is configured Agents

Failing any → the workflow either won't start ("binding profile incomplete", "connector disabled", "budget exhausted") or fails at a step.

7. Lifecycle and maintenance

After the first run: watch connector health and distressed credentials (Connectors-Credentials.md §7/§8); handle approvals (Approvals.md); watch the budget (Budgets-And-Cost.md); expand — add new workflow definitions, instances, cases; for erroneous runs — undo/compensation (Undo-And-Compensation.md). The project can be suspend/resume/archived (Projects-Lifecycle.md).

8. Troubleshooting

Symptom Cause What to do
A workflow won't start — "binding profile incomplete" not all slots are mapped to usable instances phase 7: Bindings → Auto-map / pick instances; check the §6 checklist items 4–6
"connector disabled" / webhook 401 Allowlist OFF for the connector_key phase 6: turn the toggle on
A workflow stopped — "budget exhausted" the project budget is not set or exhausted phase 8: set/raise the limit (Budgets-And-Cost.md)
I don't see the project / can't run role/scope don't allow it (the operator role isn't in project_scopes, or the role is below operator) owner/admin: Edit project scopes / elevate the role (Roles-And-Permissions.md)
An agent step fails "no agent definition" the agent definition isn't published for the project phase 0/3: publish it (Agents-And-Prompts.md)
Add instance rejects a credential the credential is not usable / of the wrong type Connectors-Credentials.md §8

9. Constraints and invariants

  • Security and budget — before execution (invariants 4 and 5): you can't "skip" policy/budget/RBAC; without a budget new side effects are fail-closed.
  • Secrets — only via the canonical path: credentials are created via create_credential (worker_apply_then_signal), plaintext is decrypted only in the worker; there are no secrets in the instance config or step.config.
  • All mutations go via CommandEnvelope; operator YAML edits of connectors (legacy) bypass the invariant and are scheduled for removal.
  • A project = the unit of isolation (one instance — one trust zone; projects inside it are isolated); cross-project leaks are forbidden.
  • Time-to-Value is the headline metric (invariant 7 — evolution as a byproduct; VISION §6): if the first run takes more than "minutes" — that's a signal to simplify the flow, not "that's how it should be".