Transactions and Orchestration

rauto provides three increasingly powerful execution layers:

• tx
• tx-workflow
• orchestrate

These are not replacements for one another. They scale from single-target transaction blocks to multi-target, multi-stage orchestration.

tx: single-target transaction block

rauto tx is best for a compact, rollback-aware unit of change on a single target.

Command mode

rauto tx \
  --name vlan-change \
  --command "vlan 120" \
  --command "name campus-users" \
  --rollback-command "no vlan 120" \
  --rollback-command "default name" \
  --rollback-on-failure \
  --mode Config \
  --connection core-01

Best for:

• a small number of steps
• explicit rollback commands
• cases where a full workflow JSON would be unnecessary

Command-flow mode

tx can also run a command flow as the transaction step itself:

rauto tx \
  --run-kind command-flow \
  --flow-template cisco_like_copy \
  --flow-vars ./flow-vars.json \
  --rollback-flow-file ./rollback-flow.toml \
  --connection core-01

Best for:

• changes where the step itself is interactive
• cases where both forward and rollback paths are more than static commands

Additional source-backed tx controls include:

• --rollback-commands-file for one rollback command per line
• --rollback-commands-json for a JSON string array of rollback commands
• --rollback-trigger-step-index for whole-resource rollback trigger selection
• --resource-rollback-command for explicit whole-resource rollback behavior
• --json for machine-readable execution output

This matters in enterprise use because teams often evolve from a few explicit rollback commands into externally reviewed rollback artifacts.

tx-workflow: structured transaction workflow

When a change grows beyond “a short list of steps” and starts needing multiple blocks or different rollback policies, tx-workflow is usually the better choice.

rauto tx-workflow ./workflow.json --view
rauto tx-workflow ./workflow.json --dry-run
rauto tx-workflow ./workflow.json --connection core-01

A typical workflow shape

{
  "name": "campus-core-vlan",
  "fail_fast": true,
  "blocks": [
    {
      "name": "create-vlan",
      "rollback_policy": "per_step"
    },
    {
      "name": "create-svi",
      "rollback_policy": {
        "whole_resource": {
          "rollback": {
            "kind": "command",
            "mode": "Config",
            "command": "default interface vlan 120"
          }
        }
      }
    }
  ]
}

Best for:

• splitting a change into named blocks
• using different rollback strategies per block
• maintaining the process as a reusable JSON artifact

The current README also emphasizes that tx-workflow is not limited to raw files forever. Workflows can evolve into reusable execution templates and Web-delivered payloads after the structure stabilizes.

orchestrate: multi-device, multi-stage orchestration

Once the target expands from one device to a fleet, move to rauto orchestrate.

rauto orchestrate ./orchestration.json --view
rauto orchestrate ./orchestration.json --dry-run
rauto orchestrate ./orchestration.json --record-level full

A typical orchestration shape

{
  "name": "campus-vlan-rollout",
  "fail_fast": true,
  "rollback_on_stage_failure": true,
  "stages": [
    {
      "name": "core",
      "strategy": "serial"
    },
    {
      "name": "access",
      "strategy": "serial"
    }
  ]
}

Orchestration introduces these core concepts:

• stage for major rollout phases
• job for executable units inside a stage
• targets / target_groups for execution scope
• strategy for serial vs parallel behavior
• max_parallel for concurrency caps
• action for the actual execution type, such as tx_block or tx_workflow

The README additionally documents:

• rollback_completed_stages_on_failure for compensating successful targets from already-completed earlier stages when a later stage fails
• inline targets with per-target vars
• inventory_file and inline inventory structures for group-based targeting
• action source modes for both tx_block and tx_workflow

Action source modes in orchestration

For tx_block jobs, the current README documents two main source patterns:

• command mode (template / commands + vars)
• tx block template mode (tx_block_template_name / tx_block_template_content + tx_block_template_vars)

For tx_workflow jobs, the current README documents four mutually exclusive source modes:

• workflow_file
• inline workflow
• workflow_template_name
• workflow_template_content with workflow_vars

This is a major enterprise-facing capability because it allows orchestration to consume either local files, reviewed inline payloads, or centrally governed reusable templates.

How to choose between them

Scenario	Recommended layer
Single target, few steps, needs rollback	tx
Single target, block-based, more complex flow	tx-workflow
Multiple devices, multiple stages, concurrency control	orchestrate

Why --dry-run and --view matter

For all three layers, validate first with:

• --view to inspect the structured plan
• --dry-run to print the plan without executing it
• --json to produce raw JSON or structured output for integration

This is a strong habit to keep for production change control.

Relation to inventory and saved connections

During multi-device execution, orchestrate usually works together with:

• saved connections
• groups
• inventory defaults and group defaults
• runtime variables

The repository examples show both styles:

• direct targets lists for smaller plans
• target_groups plus inventory_file for larger staged delivery

This is also why rauto becomes more useful as an execution foundation rather than just a simple command sender.

Example families to study

The repository ships examples that are worth treating as documentation artifacts, not just test assets:

• core-vlan-workflow.json
• fabric-change-workflow.json
• campus-vlan-orchestration.json
• campus-inventory.json
• fabric-advanced-orchestration.json
• fabric-advanced-inventory.json
• linux-image-rollout-orchestration.json
• linux-image-export-and-transfer-workflow.json
• linux-image-export-and-transfer-with-password-scp-workflow.json
• linux-image-load-and-restart-workflow.json

For a cataloged view of these, continue with Example Library.

If you want to understand how those underlying data sources are stored and merged, continue with Runtime Data and Configuration.