Configuration Lifecycle
This page provides an overview of how configuration is managed, versioned, and deployed in tSM — from development through production.
tSM Studio and the tSM CLI together provide a complete model for moving configuration between environments — reliably, repeatably, and with full traceability. This page introduces the core concepts and how they fit together. Detailed pages cover each topic in depth.
The problem
In any non-trivial tSM project, configuration must move from development to production. Without a structured model, this raises difficult questions:
- What exactly was deployed?
- Which version is running in production?
- Who owns which part of the configuration?
- How do we upgrade safely without breaking related items?
- How do parallel teams release independently?
The packaging model answers all of these.
Core concepts
The model is built from six concepts:
| Concept | Role |
|---|---|
| ConfigType | Ownership taxonomy — where every configuration entity belongs. |
| Configuration Package | Source unit in Git — what is versioned, built, and released. |
| Configuration Area | Logical subdivision inside a package — where content is stored on disk. |
| Change Set | Story-level tracking — what changed for one user story or task. |
| Package | Immutable deployable artifact — the built result ready for installation. |
| Installed Package | Deployment record — what is actually installed in an environment. |
How they relate
ConfigType
└── defines ownership of every configuration entity
Configuration Package (package.yaml in Git)
├── contains one or more Configuration Areas
│ └── each area scopes content by ConfigType
├── declares dependencies on other packages
└── build → produces an immutable Package artifact
Change Set (optional, story-level)
└── selects a subset of changes for independent release
Package (immutable artifact)
└── install → creates an Installed Package record
ConfigType is the foundation. It assigns every configuration entity to an owner.
Configuration Package uses ConfigType to decide what belongs inside. A package is defined by package.yaml and stored in Git. It contains one or more Configuration Areas, each scoped to a set of ConfigTypes. Areas determine where content is stored on disk — entity-type subfolders are created automatically by Studio during sync.
Change Set is an optional layer for parallel development. When multiple stories are in progress inside the same package, each developer opens a Change Set that tracks exactly which entities were touched. This enables independent, story-level releases without waiting for other work to finish.
Package is the immutable artifact produced by a build. It contains the configuration content exactly as it was at build time.
Installed Package is the record created when a package is installed into a target environment. It provides the deployment history, version tracking, and drift detection for each environment.
Lifecycle
A typical configuration delivery lifecycle looks like this:
- Configure — developers create or modify configuration in a development environment.
- Version — changes are downloaded into tSM Studio, committed to Git, and tracked under a Configuration Package.
- Build — the CLI or pipeline produces an immutable package artifact from the committed state.
- Deploy — the package is validated, diffed, and installed into the target environment.
- Track — an Installed Package record captures exactly what was deployed, when, and by whom.
For later updates, the same cycle repeats: modify in DEV, commit, bump version, build, install.
ConfigType — the ownership foundation
Every configuration entity in tSM has a configType field. ConfigType codes are hierarchical:
BSS
BSS.CRM
BSS.ProductCatalog
BSS.Ordering
SDWAN
SDWAN.ProductCatalog
SDWAN.Ordering
ConfigType determines:
- ownership — who is responsible for an entity
- navigation — how users browse configuration in Configuration Explorer
- packaging scope — which package an entity belongs to
ConfigType is not defined by the packaging model — it exists independently. Packages build on top of it.
Configuration Package — the release unit
A Configuration Package is defined by a package.yaml file inside a Git repository:
packages/
ordering-sdwan/
package.yaml # package definition
sdwan-product/ # configuration area
sdwan-fulfillment/ # configuration area
A package declares:
- identity and version —
packageId,name,version - areas — where content is stored, scoped by ConfigType
- dependencies — other packages that must be present
- policy — install and upgrade behavior
A package contains one or more areas, and each area should follow one clear ConfigType subtree. A good area is easy to explain — "everything under SDWAN.ProductCatalog.*" or "everything under BSS.Ordering.*".
→ Configuration Packages — full model, areas, membership rules, examples, and schema reference
Configuration Area — content organization
Inside a package, areas subdivide the content into logical groups. Each area:
- is scoped to one or more ConfigTypes
- maps to a directory on disk
- gets entity-type subfolders created automatically during sync
areas:
- id: sdwan-product
path: sdwan-product
configTypes:
- code: SDWAN.ProductCatalog
includeSubtree: true
Areas should be business-oriented — sdwan-product, shared, ticketing-flow — not technical (forms, registers). Studio handles entity-type separation automatically inside each area.
Change Set — story-level tracking
When multiple developers work in parallel on the same project, a Change Set provides story-level tracking:
- each developer opens a Change Set linked to their user story
- the system automatically tracks which entities are created, modified, or deleted
- Change Sets go through a review workflow:
OPEN → IN_REVIEW → CLOSED - deployment follows the normal package pipeline — Change Sets provide the audit trail
Change Sets do not replace packages. They are a tracking and review layer that sits on top of the existing package model.
→ Change Sets — lifecycle, entity model, review workflow
Installed Package — deployment record
When a package is installed into an environment, tSM creates an Installed Package record. This record answers:
- which package was installed
- which version
- when and by whom
- which individual items were included
Over time, the Installed Package history provides a complete audit trail for any environment.
→ Installed Package — entity model and attributes
Workflows
The packaging model supports different team sizes and release strategies.
Basic workflow
A small team with two packages (System and AllConfig) and a straight DEV → PROD flow.
Example packages: System (platform baseline) and AllConfig (all business configuration). A single team configures in DEV, syncs to Studio, builds both packages, then installs into PROD. For updates, the same cycle repeats with a version bump.
Enterprise workflow
Multiple independent teams, each owning distinct ConfigType subtrees and shipping their own packages. The SD-WAN solution spans several domains but is delivered as one coherent package that depends on the base packages.
Five teams own six packages. Each team configures in DEV, builds their packages, and installs through TEST into PROD:
| Team | Packages | ConfigType root |
|---|---|---|
| Platform | System, InfraCommon | System.*, Infra.* |
| BSS | BSSBase | BSS.* |
| OSS | OSSBase | OSS.* |
| Ticketing | TicketingBase | Ticketing.* |
| SD-WAN | SDWAN | SDWAN.* |
The SDWAN package declares dependencies on BSSBase, OSSBase, and TicketingBase. tSM enforces install order automatically — base packages must be installed before SDWAN.
Change Set workflow
Story-level tracking on top of any package structure. Multiple developers work in the same shared DEV environment. Each developer opens a Change Set linked to their user story — the system automatically tracks which entities each story touches. Stories are reviewed and closed independently. Deployment follows the normal package pipeline.
Example: Bob adds an SD-WAN site setup form (US-1234) while Alice revises common statuses (US-5678). Both work in the same shared DEV. Each Change Set captures only the touched entities. After review, Change Sets are closed and packages are deployed through the standard pipeline — independently and without blocking each other.
Tooling
| Tool | Purpose | Page |
|---|---|---|
| tSM Studio | VS Code extension for editing configuration locally, managing packages, and working with change sets. | tSM Studio |
| tSM CLI | Command-line tool for package authoring, validation, diff, installation, and change set management. | tSM CLI |
| Configuration Reference | Full schema for package.yaml, tsm-project.yaml, and ~/.tsm/ settings. | Configuration Reference |
Where to start
- New to packaging? Start with the Basic Workflow — it walks through a minimal project from scratch.
- Designing a multi-team project? Read the Enterprise Workflow for a real SD-WAN example.
- Need story-level tracking? See Change Sets and the Change Set Workflow.
- Looking for schema details? Go to the Configuration Reference.
For stronger isolation, each developer can optionally work in a scratch environment — a short-lived copy of the shared baseline (e.g. DEV-bob, DEV-alice). Changes in a scratch environment do not affect other developers until explicitly merged. This model is experimental and is useful when stories may conflict at runtime — but it adds environment management overhead.