Skip to content

Templates and catalog

English translation pending

Full content currently exists only in Russian. Use the language selector at the top of the page → Русский. The summary below covers the essentials; the Russian manual has the full reference.

Two reuse mechanisms in Axon. Templates (module_catalog) — anonymized snapshots (workflow / chain / project) applied inside the instance as "a copy for a new project," using variables and anonymisation rules. Workflow Definition Catalog (workflow_definition_catalog) — instance-wide publication of a reusable WorkflowDefinition: a developer publishes via axon push --catalog, a manager installs into their project via Console. The catalog is the seam between developer and manager, not a marketplace, not cross-instance. Canon: ARCHITECTURE-V6 §15 (Templates) and §8 (DDL).

1. What it is and why

  • Module Library (module_catalog) — simple reusable-module registry without maturity lifecycle (V6 removed the heavy V5 Domain Pack). module_type ∈ {connector, tool, workflow_template, chain_template, project_template, policy_template}. config_schema is the configure-time JSON Schema; content is the serialized module body.
  • Three template levels — workflow template (one definition + variables), chain template (a chain of definitions + bindings), project template (full project with workflows + roles + connector requirements + policy defaults).
  • Workflow Definition Catalog — separate table, global scope (project_id IS NULL); cards of published WorkflowDefinition snapshots; manager opens Catalog → Install to project. Not a marketplace, not cross-instance, no auto-update (snapshot copy). Mode A only — catalog rejects inline credential_id, $credential_ref, and connector_key.

2. Roles and access

Action Permission owner admin manager operator reviewer read_only
Workflow / chain / project templates: create/apply/archive manage_templates ✅ ✅ ❌ ❌ ❌ ❌
Catalog: publish / archive catalog:manage ✅ ✅ ❌ ❌ ❌ ❌
Catalog: install into a project catalog:install ✅ ✅ ✅ ❌ ❌ ❌

Engineer is not an RBAC role; they work in code (modules/workflows/, git) and run axon push --catalog. For automation, a system actor with catalog:manage is used. All mutations go through CommandEnvelope (commands: publish_to_catalog, archive_catalog_entry, install_catalog_entry).

3. Where in Console

  • Templates (Module Library, admin/owner): list, apply-template modal (target project + variables + auto-mapping of connectors), create-from-existing wizard.
  • Catalog (anyone can read, actions per role):
  • Catalog list — name, definition_key, latest version, tags, published_at/by; each card shows a requirement summary (connector_requirement[*] + adapter type) before install.
  • Catalog entry detail — definition JSON (read-only), connector requirements, version history, Install to project (manager+), Archive (admin+).
  • Install to project modal — choose target project, optional definition_key_override for name collision, preview of requirements that the manager will need to bind afterwards.

CLI: axon push <path> --catalog (mutually exclusive with --project / AXON_PROJECT).

4. Concepts

  • config_schema vs content — config_schema drives the UI form for configure-time vars; content is the serialized module body (connector defaults / tool spec / template body with {{ var }} placeholders).
  • Auto-mapping — at template apply / catalog install: per connector_requirement the system searches the project for usable CI of the matching adapter type. 1 candidate → auto-bind (auto_configured=true); N → user choice; 0 → "requires connection" badge.
  • Latest-by-default + collision policy — CLI picks latest_version + 1 automatically; UI installs the latest. Install collision (definition_key_already_exists_in_project) returns 409 with suggested_definition_key = "<key>_from_catalog".
  • Mode A only in catalog — portability requires connector_requirement slots. Mode B (credential_id inline), Mode B-ref ($credential_ref), and Mode C (connector_key) all rejected at publish (CatalogModeBInlineRejected / CatalogModeBRefRejected / CatalogModeCRejected).
  • Install is publish_definition underneath — InstallCatalogEntryToProjectHandler copies the snapshot, stamps installed_from_catalog_entry_id / installed_from_catalog_version into metadata, and invokes PublishDefinitionHandler (source="catalog_install") in the same transaction. No validation bypass.

5. Flows

  1. Apply a workflow template — Templates → choose → Apply (target project + variables + anonymisation). Handler materializes a WorkflowDefinition and calls publish_definition.
  2. Create project from project template — Templates → Project template → Apply. Spawns a full project skeleton (workflows + declared requirements + policies). No credentials are migrated.
  3. Publish to catalog (developer + admin/owner) — axon push <path> --catalog. CLI computes content_hash, picks version = latest+1 (or 1 if new), submits publish_to_catalog (target_type='workflow_definition_catalog_entry', project_id=null). Failure codes: catalog_portability_invalid, version_conflict, version_archived; same-hash re-push is idempotent (already_published: true).
  4. Install into a project (manager+) — Catalog → entry → Install. Idempotent re-install returns the existing definition_id. Collision → 409 with suggested_definition_key. After install: open Bindings, bind requirements to project CIs.
  5. Upgrade to a new catalog version — Install the new version. Same definition_key → collision → use definition_key_override (parallel versions) or retire the old one first. No auto-upgrade; install is a snapshot copy.
  6. Archive (admin/owner) — archive_catalog_entry. Soft-delete of the card; installed copies in projects keep working.

6. Options reference

See the Russian manual §6 for full field-level tables (app.workflow_definition_catalog, app.module_catalog) and CLI flag reference. Key columns of the catalog table: catalog_entry_id (wdcat_<ulid>), definition_key, version, definition JSONB, metadata JSONB (project_id forbidden), content_hash, requirements_fingerprint, deleted_at/archive_reason.

7. Lifecycle and operations

Templates lifecycle is manual: create → apply → optionally archive (manage_templates). No built-in versioning. Catalog lifecycle is append-only by version; latest = max non-archived; archived versions are hidden from UI but retained for audit. Installed copies are independent of the catalog at runtime (only a metadata stamp remains). The read projection read.workflow_definition_catalog_list (alembic 038) is rebuildable and carries metadata + requirement summary, not the full JSON.

8. Troubleshooting

Symptom Cause Fix
axon push --catalog errors with «mutually exclusive with --project and AXON_PROJECT» AXON_PROJECT env set or --project passed unset AXON_PROJECT and drop --project
Publish → catalog_portability_invalid with CatalogModeBInlineRejected / CatalogModeBRefRejected / CatalogModeCRejected Definition uses Mode B or Mode C Rewrite as Mode A: declare connector_requirements[] and reference them by connector_requirement in steps
Publish → catalog_portability_invalid («raw secrets detected») Token-like string in definition or metadata Remove the literal secret; use Mode A binding instead
Publish → version_conflict Same (definition_key, version) exists with a different content_hash Use --force-new-version or bump the version
Publish → version_archived Trying to reuse an archived version number Use the next version
Install → 409 definition_key_already_exists_in_project Same definition_key already in target project Pass definition_key_override (UI suggests <key>_from_catalog) or retire the old definition
Install → 404 catalog_entry_not_found / catalog_entry_archived Entry was archived Use a non-archived version or republish
Auto-mapping suggests nothing No usable CI of the right type in the project Create credential + CI (Connectors-Credentials.md §3) and return to Bindings

9. Constraints and invariants

  • Templates carry no secrets — references/placeholders only.
  • Catalog is Mode A only. Catalog publish target project_id MUST be NULL; install target is workflow_definition with the target project.
  • No auto-upgrade for installed copies (snapshot semantics).
  • Install reuses publish_definition — same validation, no bypass.
  • Archive is soft. Installed copies survive.
  • Idempotency. Publish: (definition_key, version, content_hash). Install: (catalog_entry_id, version, target_project_id).
  • No cross-instance distribution. Catalog is instance-wide; cross-instance marketplace is out of scope.