How dhairyabhanderi/saviynt-scenario-runner works
Purpose and entry points
Saviynt Scenario Runner is a Python automation system for declarative Saviynt Enterprise Identity Cloud (EIC) scenarios. It compiles intent-oriented YAML or explicit step YAML, executes EIC REST calls safely, waits for asynchronous provisioning, validates outcomes, and persists reports/audit data.
CLI entry points are saviynt_scenario_runner/__main__.py and saviynt_scenario_runner/cli.py. The optional localhost-only FastAPI interface starts from saviynt_scenario_runner/web/app.py.
Scenario authoring and compilation
Two input boundaries converge on an executable scenario IR: Flow YAML is parsed, expanded through lifecycle presets, and compiled into classic steps; classic YAML is loaded directly. The operation registry is the authoritative mapping between authoring operations, required fields, entity bindings, defaults, and inserted verification/wait behavior.
Core paths: saviynt_scenario_runner/planning/flow_spec.py, saviynt_scenario_runner/planning/compiler.py, saviynt_scenario_runner/planning/field_spec.py, saviynt_scenario_runner/template/loader.py, saviynt_scenario_runner/models/scenario.py.
Execution engine and state
The runner executes compiled steps in order, resolves runtime context/interpolation and dates, evaluates conditions, captures outputs, and runs cleanup even after failure. It supports dry runs and live execution, stop-on-failure, expected-error semantics, polling, retry controls, and reconciliation for ambiguous non-idempotent submits.
Core paths: saviynt_scenario_runner/execution/runner.py, saviynt_scenario_runner/execution/context.py, saviynt_scenario_runner/execution/retry.py, saviynt_scenario_runner/execution/poller.py, saviynt_scenario_runner/execution/reconcile.py.
Actions and Saviynt API boundary
Actions isolate scenario semantics from HTTP details. The action registry dispatches operations such as user lifecycle changes, access changes, requests/approvals, task checks, jobs, bulk uploads, assertions, and raw/generic API calls. The API client owns authentication, token refresh, endpoint construction, request building, response normalization, and error classification; this is the external-service boundary to Saviynt EIC REST APIs.
Core paths: saviynt_scenario_runner/actions/registry.py, saviynt_scenario_runner/actions/base.py, saviynt_scenario_runner/actions/account_lifecycle.py, saviynt_scenario_runner/api/client.py, saviynt_scenario_runner/api/endpoints.py.
Validation, outcomes, and durable observability
Validation actions apply assertion operators to API results and captured context. Execution produces step-level results and an outcome summary for console and JSON reporting. Audit, report, run-history, and saved-scenario persistence are local filesystem artifacts under the user home directory; secrets are sourced from environment/.env or optional OS keychain, while named connection metadata is stored separately from passwords.
Core paths: saviynt_scenario_runner/validation/assertions.py, saviynt_scenario_runner/reporting/outcome.py, saviynt_scenario_runner/reporting/json_report.py, saviynt_scenario_runner/observability.py, saviynt_scenario_runner/secrets.py.
Local web control plane and assistant
The FastAPI UI is a local control plane for YAML editing, scenario/run persistence, dry/live execution, live step streaming, and tenant connection management. Its security boundary is loopback binding plus Host allow-list and Origin checks; it has no standalone authentication. The assistant subsystem is a substantial adjacent orchestration layer: it ingests/searches knowledge, compiles context, manages scoped memory, plans tool use, and exposes assistant routes. Its memory adapter can use Everos Cloud, making that an optional external service.
Core paths: saviynt_scenario_runner/web/app.py, saviynt_scenario_runner/web/run_manager.py, saviynt_scenario_runner/web/connections.py, saviynt_scenario_runner/web/assistant/orchestrator.py, saviynt_scenario_runner/web/assistant/context_compiler.py, saviynt_scenario_runner/web/assistant/memory/everos_cloud.py.
Main entry points: runner.py Scenario runner · app.py Local FastAPI control plane · compiler.py Scenario compiler · scenario.py Executable scenario IR
Components 20
Scenario Authoring
- Flow YAML parser · Expands intent-oriented lifecycle flows.
saviynt_scenario_runner/planning/flow_spec.py - Scenario compiler · Compiles flow operations into executable classic steps.
saviynt_scenario_runner/planning/compiler.py - Operation registry · Defines operation fields, bindings, defaults, waits, and verification.
saviynt_scenario_runner/planning/field_spec.py - Classic YAML loader · Loads explicit step scenarios directly.
saviynt_scenario_runner/template/loader.py - Executable scenario IR
saviynt_scenario_runner/models/scenario.py
Execution
- Scenario runner · Runs ordered steps, cleanup, dry/live modes, and failure policy.
saviynt_scenario_runner/execution/runner.py - Runtime context · Resolves interpolation, dates, conditions, and captured outputs.
saviynt_scenario_runner/execution/context.py - Polling & reconciliation · Handles retries, asynchronous waits, and ambiguous submissions.
saviynt_scenario_runner/execution/reconcile.py - Action registry · Maps scenario operations to lifecycle, access, request, job, assertion, and raw API actions.
saviynt_scenario_runner/actions/registry.py - Saviynt API client · Owns authentication, token refresh, endpoints, requests, and error classification.
saviynt_scenario_runner/api/client.py - Assertions · Evaluates assertion operators against API results and runtime context.
saviynt_scenario_runner/validation/assertions.py - Outcomes & JSON reports · Builds step results and console/JSON summaries.
saviynt_scenario_runner/reporting/outcome.py
Local Web & Assistant
- Local FastAPI control plane · Loopback-only UI with Host and Origin checks.
saviynt_scenario_runner/web/app.py - Web run manager · Coordinates YAML runs and live step streaming.
saviynt_scenario_runner/web/run_manager.py - Assistant orchestrator · Plans tool use with compiled knowledge context and scoped memory.
saviynt_scenario_runner/web/assistant/orchestrator.py
External Services
- Saviynt EIC REST APIs
- Everos Cloud
Other components
- CLI entry points · Starts scenario runs and local web mode.
saviynt_scenario_runner/cli.py - Local audit & run storage · Persists audit data, reports, run history, and saved scenarios under user home.
saviynt_scenario_runner/observability.py - Secrets & connections · Reads environment, .env, or keychain secrets separately from connection metadata.
saviynt_scenario_runner/secrets.py
Connections 22
- CLI entry points → Flow YAML parser: loads flow YAML
- CLI entry points → Classic YAML loader: loads classic YAML
- Flow YAML parser → Scenario compiler: expanded flow
- Operation registry → Scenario compiler: operation definitions
- Scenario compiler → Executable scenario IR: compiled steps
- Classic YAML loader → Executable scenario IR: explicit steps
- Executable scenario IR → Scenario runner: execution plan
- Scenario runner → Runtime context: resolves and captures state
- Scenario runner → Polling & reconciliation: waits, retries, reconciles
- Scenario runner → Action registry: dispatches steps
- Action registry → Saviynt API client: performs API actions
- Saviynt API client → Saviynt EIC REST APIs: REST calls
- Scenario runner → Assertions: runs assertions
- Runtime context → Assertions: captured values
- Scenario runner → Outcomes & JSON reports: step results
- Outcomes & JSON reports → Local audit & run storage: reports and audit
- Secrets & connections → Saviynt API client: credentials
- Local FastAPI control plane → Web run manager: run requests and streaming
- Web run manager → Scenario runner: dry/live execution
- Local FastAPI control plane → Assistant orchestrator: assistant routes
- Assistant orchestrator → Everos Cloud: optional memory adapter
- Local FastAPI control plane → Local audit & run storage: scenarios, runs, connections