Enterprise Workflow with Configuration Packages (SD-WAN example)
This page describes a scalable enterprise workflow for delivering tSM configuration with multiple independent teams, versioned Configuration Packages, and a cross-cutting SD-WAN solution.
The goal is to enable:
-
parallel work across teams without constant conflicts
-
repeatable deployments into shared environments
-
clear ownership of configuration
-
predictable upgrades with a clear answer to:
- what changed
- what was deployed
- which version is installed
The SD-WAN example illustrates a common telco reality: SD-WAN affects CRM, product catalog, ordering, service catalog, provisioning, and ticketing, but is still best delivered as one coherent solution package.
See also:
Concepts
ConfigTypes
ConfigTypes define where configuration belongs.
Every configuration entity in tSM contains:
configType(String) — the ConfigType code of the owning configuration area
ConfigType codes are hierarchical:
-
a child code includes the full parent code as a prefix
-
example:
BSS.OrderingBSS.Ordering.Fulfillment
In enterprise projects, ConfigTypes provide:
- ownership
- navigation
- filtering
- package scope
Configuration Packages
Configuration Packages define what is released and installed.
They are defined by:
packages/<PackageId>/package.yaml
A package contains:
- package identity and version
- dependencies
- areas
- policy
An area defines:
- where content is stored in Git
- which ConfigTypes belong there
- whether a ConfigType includes its subtree
During sync, tSM Studio creates entity-type subfolders automatically inside each area.
So the design is:
- ConfigType → ownership and taxonomy
- Configuration Package → release boundary
- Area → business-oriented storage in Git
- entity-type subfolders → generated automatically by Studio
Ownership model
A typical enterprise ownership model looks like this:
| Team | Owns ConfigTypes | Ships Configuration Packages |
|---|---|---|
| Platform core team | System.* | System |
| Platform / infrastructure team | Infra.* | InfraCommon |
| BSS team | BSS.* | BSSBase |
| OSS team | OSS.* | OSSBase |
| Ticketing team | Ticketing.* | TicketingBase |
| SD-WAN solution team | SDWAN.* | SDWAN |
Rule: SD-WAN-specific configuration must live under the
SDWAN.*root, even when it integrates with BSS, OSS, or Ticketing.
This is the key to avoiding package confusion:
- base capabilities stay in their own roots
- SD-WAN specifics stay in
SDWAN.* - the SD-WAN package depends on the base packages rather than mixing its content into their trees
ConfigTypes for the enterprise SD-WAN example
Core and base ConfigTypes
| Code | Name | Purpose |
|---|---|---|
System | System | Core tSM baseline configuration delivered with the application and refined per project. |
Infra | Infrastructure | Shared platform configuration used across multiple business domains. |
BSS | BSS | Business Support root. |
BSS.CRM | CRM | CRM configuration. |
BSS.ProductCatalog | Product Catalog | Product catalog configuration. |
BSS.Ordering | Ordering | Ordering configuration. |
OSS | OSS | Operations Support root. |
OSS.ServiceCatalog | Service Catalog | Service definitions and service models. |
OSS.Provisioning | Provisioning | Provisioning and orchestration configuration. |
Ticketing | Ticketing | Ticketing configuration. |
SD-WAN ConfigTypes
| Code | Name | Purpose |
|---|---|---|
SDWAN | SD-WAN | Root for SD-WAN-specific configuration. |
SDWAN.ProductCatalog | SD-WAN Product Catalog | SD-WAN commercial offer specifics, mappings, and attributes. |
SDWAN.Ordering | SD-WAN Ordering | SD-WAN ordering forms, validations, and process-specific behavior. |
SDWAN.ServiceCatalog | SD-WAN Service Catalog | SD-WAN service templates and service models. |
SDWAN.Provisioning | SD-WAN Provisioning | SD-WAN provisioning specifics. |
SDWAN.Ticketing | SD-WAN Ticketing | SD-WAN incident types, workflows, and forms. |
Why SDWAN.* is a separate root
The SD-WAN solution is cross-domain, but it should still be packaged as a coherent solution.
That means:
- generic CRM stays under
BSS.CRM - generic ordering stays under
BSS.Ordering - generic service catalog stays under
OSS.ServiceCatalog - generic ticketing stays under
Ticketing - SD-WAN-specific assets go under
SDWAN.*
This gives you:
- clear ownership
- clean package boundaries
- simpler upgrade logic
- fewer conflicts between teams
Repository layout
A typical enterprise workspace can look like this:
packages/
System/
package.yaml
system/
InfraCommon/
package.yaml
infra/
BSSBase/
package.yaml
crm/
product-catalog/
ordering/
OSSBase/
package.yaml
service-catalog/
provisioning/
TicketingBase/
package.yaml
ticketing/
SDWAN/
package.yaml
product-catalog/
ordering/
service-catalog/
provisioning/
ticketing/
tsm-project.yaml
For the full project.yaml and package.yaml schema, see Configuration Reference.
Notes
- each package contains one
package.yaml - each package contains one or more areas
- areas are business-oriented
- inside each area, Studio creates entity-type subfolders automatically during sync
For example, after sync the SD-WAN package may contain:
packages/
SDWAN/
product-catalog/
EntityCatalogCategory/
EntityCatalogSpecification/
EntitySpecification/
Characteristic/
Form/
ordering/
Form/
Process/
Script/
service-catalog/
EntityCatalogSpecification/
EntitySpecification/
Characteristic/
Form/
provisioning/
Process/
Script/
Register/
ticketing/
Form/
Process/
Register/
The package defines the business areas. Studio handles the technical subfoldering automatically.
Package definitions
The enterprise example uses these packages:
SystemInfraCommonBSSBaseOSSBaseTicketingBaseSDWAN
1) System
The System package contains tSM baseline configuration delivered with the application and refined per project.
packageId: System
name: System
version: 1.0.0
description: Core tSM baseline configuration.
ownerTeam: PlatformCore
areas:
- id: system
path: system
description: Core platform configuration.
configTypes:
- code: System
includeSubtree: true
policy:
managed: true
allowDelete: false
enforceDependencies: true
2) InfraCommon
The InfraCommon package contains shared platform configuration used across multiple business domains.
packageId: InfraCommon
name: Infrastructure Common
version: 1.0.0
description: Shared platform and infrastructure configuration.
ownerTeam: PlatformInfra
dependencies:
- packageId: System
versionRange: ">=1.0.0 <2.0.0"
kind: required
areas:
- id: infra
path: infra
description: Shared platform and integration configuration.
configTypes:
- code: Infra
includeSubtree: true
policy:
managed: true
allowDelete: false
enforceDependencies: true
3) BSSBase
The BSSBase package contains the generic BSS foundation.
packageId: BSSBase
name: BSS Base
version: 1.0.0
description: Generic CRM, product catalog, and ordering configuration.
ownerTeam: BSS
dependencies:
- packageId: System
versionRange: ">=1.0.0 <2.0.0"
kind: required
- packageId: InfraCommon
versionRange: ">=1.0.0 <2.0.0"
kind: required
areas:
- id: crm
path: crm
description: Generic CRM configuration.
configTypes:
- code: BSS.CRM
includeSubtree: true
- id: product-catalog
path: product-catalog
description: Generic product catalog configuration.
configTypes:
- code: BSS.ProductCatalog
includeSubtree: true
- id: ordering
path: ordering
description: Generic ordering configuration.
configTypes:
- code: BSS.Ordering
includeSubtree: true
policy:
managed: true
allowDelete: false
enforceDependencies: true
4) OSSBase
The OSSBase package contains the generic OSS foundation.
packageId: OSSBase
name: OSS Base
version: 1.0.0
description: Generic service catalog and provisioning configuration.
ownerTeam: OSS
dependencies:
- packageId: System
versionRange: ">=1.0.0 <2.0.0"
kind: required
- packageId: InfraCommon
versionRange: ">=1.0.0 <2.0.0"
kind: required
areas:
- id: service-catalog
path: service-catalog
description: Generic service catalog configuration.
configTypes:
- code: OSS.ServiceCatalog
includeSubtree: true
- id: provisioning
path: provisioning
description: Generic provisioning configuration.
configTypes:
- code: OSS.Provisioning
includeSubtree: true
policy:
managed: true
allowDelete: false
enforceDependencies: true
5) TicketingBase
The TicketingBase package contains the generic ticketing foundation.
packageId: TicketingBase
name: Ticketing Base
version: 1.0.0
description: Generic ticketing configuration.
ownerTeam: Ticketing
dependencies:
- packageId: System
versionRange: ">=1.0.0 <2.0.0"
kind: required
- packageId: InfraCommon
versionRange: ">=1.0.0 <2.0.0"
kind: required
areas:
- id: ticketing
path: ticketing
description: Generic ticketing configuration.
configTypes:
- code: Ticketing
includeSubtree: true
policy:
managed: true
allowDelete: false
enforceDependencies: true
6) SDWAN
The SDWAN package contains all SD-WAN-specific solution content.
packageId: SDWAN
name: SD-WAN Solution
version: 1.0.0
description: SD-WAN-specific solution configuration.
ownerTeam: SDWAN
dependencies:
- packageId: System
versionRange: ">=1.0.0 <2.0.0"
kind: required
- packageId: InfraCommon
versionRange: ">=1.0.0 <2.0.0"
kind: required
- packageId: BSSBase
versionRange: ">=1.0.0 <2.0.0"
kind: required
- packageId: OSSBase
versionRange: ">=1.0.0 <2.0.0"
kind: required
- packageId: TicketingBase
versionRange: ">=1.0.0 <2.0.0"
kind: required
areas:
- id: product-catalog
path: product-catalog
description: SD-WAN-specific product catalog configuration.
configTypes:
- code: SDWAN.ProductCatalog
includeSubtree: true
- id: ordering
path: ordering
description: SD-WAN-specific ordering configuration.
configTypes:
- code: SDWAN.Ordering
includeSubtree: true
- id: service-catalog
path: service-catalog
description: SD-WAN-specific service catalog configuration.
configTypes:
- code: SDWAN.ServiceCatalog
includeSubtree: true
- id: provisioning
path: provisioning
description: SD-WAN-specific provisioning configuration.
configTypes:
- code: SDWAN.Provisioning
includeSubtree: true
- id: ticketing
path: ticketing
description: SD-WAN-specific ticketing configuration.
configTypes:
- code: SDWAN.Ticketing
includeSubtree: true
policy:
managed: true
allowDelete: false
enforceDependencies: true
What “SD-WAN across all basics” means
All SD-WAN-specific assets stay under the SDWAN.* root, even when they work together with BSS, OSS, and Ticketing foundations.
| Area | Example asset | configType |
|---|---|---|
| Product catalog | SD-WAN offer mappings and attributes | SDWAN.ProductCatalog |
| Ordering | SD-WAN order wizard, validations, and steps | SDWAN.Ordering |
| Service catalog | SD-WAN service template | SDWAN.ServiceCatalog |
| Provisioning | SD-WAN provisioning orchestration | SDWAN.Provisioning |
| Ticketing | SD-WAN incident type and workflow | SDWAN.Ticketing |
The base packages provide the generic foundation. The SD-WAN package adds only the SD-WAN-specific solution layer.
Installability and dependency closure
Package scope defines what belongs to the package.
Installability additionally requires that:
- required dependencies are installed
- referenced foundation content is available
- package versions are compatible
This is why dependencies are explicit and versioned.
An SD-WAN release should always say exactly which base versions it is intended to run with.
Workflow 1: Feature branch + Scratch environment
Scratch environments are an experimental capability. They provide stronger isolation for parallel development but add environment management overhead. Evaluate whether the team benefits justify the additional complexity.
This workflow is optimized for parallel work with minimal conflicts.
A Scratch environment is a short-lived, isolated environment created for a single feature branch and rebuilt on demand.
Flow
-
Sync main from Git Developers start from the current mainline configuration.
-
Create a feature branch The branch becomes the unit of isolation and review.
-
Create a Scratch environment Scratch starts clean and is used only for this feature.
-
Install baseline packages into Scratch Install what is needed for the feature:
SystemInfraCommonBSSBaseOSSBaseTicketingBase- optionally
SDWANif the feature depends on an existing SD-WAN release
-
Develop Two equivalent modes are possible:
- filesystem-first — edit files, upload/apply into Scratch, verify
- scratch-first — configure in Scratch UI, download into tSM Studio, commit
-
Create MR (Merge Request) The MR contains file changes and package version updates where needed.
-
Merge After review and checks pass, merge into main.
-
Build and install The pipeline builds immutable deployment artifacts and installs or upgrades them into target environments.
Recommended Scratch checks
- changed items use the correct
configType - package areas contain only expected content
- dependency validation passes
- install simulation works from baseline to changed package set
- post-install verification by download/diff shows only expected changes
Workflow 2: Feature branch on DEV
This workflow is used when Scratch isolation is not enough, typically because you must test:
- real integration endpoints reachable only from DEV
- shared data interactions
- end-to-end flows across multiple systems
Flow
-
Sync main from Git
-
Create a feature branch
-
Modify configuration in DEV
- every changed or new item must have the correct
configType
- every changed or new item must have the correct
-
Download changes to tSM Studio
- download from DEV into the workspace
- review diffs locally
-
Create MR
-
Merge
-
Build and install/upgrade to target environments
Risks and controls
| Risk on DEV | What can go wrong | Control |
|---|---|---|
| Multiple teams modify DEV in parallel | Changes collide; one team depends on another’s unfinished work | Keep changes small, download frequently, require MR review, prefer Scratch where possible |
| “It works in DEV but wasn’t committed” | PROD install misses critical changes | Git is the source of truth; releases happen only through package versions |
| Accidental edits to shared foundation | Breaks multiple domains | Strict ownership by ConfigType root; changes to System.* and Infra.* are controlled by the responsible teams |
| Hidden drift in DEV | DEV differs from known baseline | Periodic download-and-compare against mainline before release |
From DEV to PROD: SD-WAN deployment scenarios
The previous sections describe how developers work — either in Scratch or shared DEV. This section shows how the SD-WAN enterprise example uses the deployment toolbox in practice — from full baseline releases to single-story hotfixes.
For general concepts — change types in a development environment, the full tool comparison, environment promotion, and common anti-patterns — see Configuration Lifecycle.
Deployment scenarios
Scenario 1: Full baseline release
Situation: First deployment to a new environment, or a complete environment reset. All six packages are ready.
Teams involved: All — each team builds their own package.
# Download and commit
tsm package download System
tsm package download InfraCommon
tsm package download BSSBase
tsm package download OSSBase
tsm package download TicketingBase
tsm package download SDWAN
git add packages/ && git commit -m "REL 1.0.0 — initial baseline"
git tag v1.0.0
# Build full artifacts
tsm package artifact System --target-env test
tsm package artifact InfraCommon --target-env test
tsm package artifact BSSBase --target-env test
tsm package artifact OSSBase --target-env test
tsm package artifact TicketingBase --target-env test
tsm package artifact SDWAN --target-env test
# Install to TEST in dependency order
tsm package install --file build/System-1.0.0-test.zip --target-env test --notes "REL 1.0.0"
tsm package install --file build/InfraCommon-1.0.0-test.zip --target-env test --notes "REL 1.0.0"
tsm package install --file build/BSSBase-1.0.0-test.zip --target-env test --notes "REL 1.0.0"
tsm package install --file build/OSSBase-1.0.0-test.zip --target-env test --notes "REL 1.0.0"
tsm package install --file build/TicketingBase-1.0.0-test.zip --target-env test --notes "REL 1.0.0"
tsm package install --file build/SDWAN-1.0.0-test.zip --target-env test --notes "REL 1.0.0"
After TEST validation, promote the same artifacts to PROD.
Scenario 2: Sprint release — all stories tested together
Situation: The sprint is done. Multiple stories across multiple teams are merged to main. Everything is tested together. Time to release.
Teams involved: Each team that had changes in the sprint.
Choosing full vs. incremental:
| Choice | When | Benefit |
|---|---|---|
| Full artifact | You want TEST/PROD to fully converge to the package state. | Guaranteed clean state. Catches any drift. |
| Diff-to-target | Target is in a known state and you only want to apply the sprint delta. | Smaller artifact, faster install, easier review. |
Recommendation: Use full artifacts for sprint releases unless the team is confident the target is aligned and drift-free. Full artifacts guarantee convergence.
# Full artifact per changed package
tsm package artifact BSSBase --target-env test
tsm package artifact SDWAN --target-env test
# Incremental alternative
tsm package artifact BSSBase --target-env test --diff
tsm package artifact SDWAN --target-env test --diff
Only packages that actually changed need new artifacts. Unchanged packages (e.g. System, InfraCommon) do not need to be re-deployed.
Scenario 3: Story-level release — independent per Change Set
Situation: Bob finished US-1234 (SD-WAN site setup). Alice is still working on US-5678. Bob needs to release now without waiting.
Teams involved: One developer, one package.
# Download only the US-1234 items
git checkout -b feature/US-1234
tsm package download SDWAN --changeset US-1234
git add packages/SDWAN
git commit -m "US-1234: SD-WAN site setup"
# Build incremental artifact
tsm package artifact SDWAN --target-env test --diff
# Install to TEST
tsm package install --file build/SDWAN-1.5.0-test.zip --target-env test \
--notes "US-1234: SD-WAN site setup"
# After testing: merge to main and promote to PROD
git checkout main && git merge feature/US-1234
tsm package install --file build/SDWAN-1.5.0-test.zip --target-env prod \
--notes "US-1234: SD-WAN site setup"
Why this works: The --changeset flag downloads only Bob's 4 entities. The --diff artifact contains only the actual changes. Alice's unfinished work (US-5678) is not affected. After deployment, tsm package installed items shows exactly which items were included.
Scenario 4: Hotfix — urgent fix to PROD
Situation: A critical defect in production. The fix is a single form change. There is no time for a full sprint release.
Teams involved: One developer, one package.
git checkout -b hotfix/PROJ-999 main
# Fix locally or download the fixed entity
tsm package download SDWAN --entity-types Form
# Commit only the fix
git add packages/SDWAN/ordering/Form/SDWAN_OrderEntry.json
git commit -m "PROJ-999: fix order entry validation rule"
# Build targeted artifact — should contain exactly 1 item
tsm package artifact SDWAN --target-env prod --diff
# Install directly to PROD
tsm package install --file build/SDWAN-1.5.1-prod.zip --target-env prod \
--notes "Hotfix PROJ-999: order entry validation rule"
# Merge back
git checkout main && git merge hotfix/PROJ-999
Key: The --diff artifact contains only the one changed form. Nothing else in PROD is touched.
Scenario 5: Multi-team coordinated release
Situation: The Platform team upgrades System and InfraCommon with changes that affect shared registers. Downstream packages (BSSBase, OSSBase, TicketingBase, SDWAN) need to adapt and release together.
Teams involved: All teams.
Each team:
- Updates their package to work with the new foundation.
- Updates the
dependenciesversion range inpackage.yaml. - Builds a full artifact (recommended for coordinated releases — full artifacts ensure convergence).
- Publishes to the artifact repository.
The deployment pipeline installs in dependency order:
# Phase 1
tsm package install --file build/System-2.0.0-test.zip --target-env test --notes "Coordinated release 2.0"
tsm package install --file build/InfraCommon-2.0.0-test.zip --target-env test --notes "Coordinated release 2.0"
# Phase 2 (can be parallel — no mutual dependencies)
tsm package install --file build/BSSBase-2.0.0-test.zip --target-env test --notes "Coordinated release 2.0"
tsm package install --file build/OSSBase-2.0.0-test.zip --target-env test --notes "Coordinated release 2.0"
tsm package install --file build/TicketingBase-2.0.0-test.zip --target-env test --notes "Coordinated release 2.0"
# Phase 3
tsm package install --file build/SDWAN-2.0.0-test.zip --target-env test --notes "Coordinated release 2.0"
After full integration testing, promote all artifacts to PROD in the same order.
Scenario 6: Cross-package story
Situation: A single story (US-2000) requires changes in both BSSBase (new form) and SDWAN (new process that references the form). One developer, two packages.
Teams involved: One developer, but two package owners must review.
# One Change Set tracks all changes
tsm changeset create --code US-2000 --name "Cross-package: shared form + SD-WAN process"
# After development, download each package's changes
git checkout -b feature/US-2000
tsm package download BSSBase --changeset US-2000
tsm package download SDWAN --changeset US-2000
git add packages/ && git commit -m "US-2000: shared form + SD-WAN process"
# Build artifacts for both packages
tsm package artifact BSSBase --target-env test --diff
tsm package artifact SDWAN --target-env test --diff
# Install in dependency order (BSSBase before SDWAN)
tsm package install --file build/BSSBase-2.1.0-test.zip --target-env test \
--notes "US-2000: shared ordering form"
tsm package install --file build/SDWAN-1.6.0-test.zip --target-env test \
--notes "US-2000: SD-WAN process using shared form"
Both artifacts are promoted together. The install notes and Change Set audit trail link them back to the same story.
Release order and upgrade pattern
A common stable deployment order is:
SystemInfraCommonBSSBase,OSSBase,TicketingBaseSDWAN
For upgrades, install new versions in dependency order:
- foundation first
- solution packages afterwards
Versioning expectations
- If a team changes only configuration inside its own ConfigTypes, it usually bumps only its own package.
- If a change affects shared foundation behavior, the provider package must be bumped and dependent package version ranges reviewed.
- SD-WAN-specific changes usually bump
SDWAN. - Base packages bump only when their own behavior or contract changes.
Best practices
Keep package boundaries aligned to ConfigType roots
A package should usually follow one clear ConfigType subtree.
Keep areas business-oriented
Inside a package, use areas such as:
crmorderingservice-catalogprovisioning
rather than technical areas like forms or processes.
Studio already creates entity-type subfolders automatically.
Keep SD-WAN specifics under SDWAN.*
Do not place SD-WAN-specific assets under BSS.*, OSS.*, or Ticketing.*.
Keep System separate
Core tSM baseline configuration should remain clearly separated from project-owned and business-owned configuration.
Prefer dependencies over content mixing
If SD-WAN needs ordering, service catalog, and ticketing foundations, express that through dependencies, not by moving generic assets into SDWAN.*.
Summary
This enterprise model combines:
- ConfigTypes for ownership and organization
- Configuration Packages for release and deployment
- business-oriented areas inside packages
- automatic entity-type subfolders created by Studio during sync
The SD-WAN example works well because:
- base capabilities stay in their own package roots
- SD-WAN specifics stay under
SDWAN.* - dependencies make the release relationship explicit
- teams can work in parallel with clearer boundaries
Two workflows are supported:
- Scratch workflow for parallel, low-conflict development
- DEV workflow when integration constraints require work in a shared environment
The deployment scenarios show how to apply the deployment toolbox — from full baseline releases to single-story hotfixes — with concrete multi-team coordination patterns using the SD-WAN packages.