Skip to main content
Version: 2.4

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.Ordering
    • BSS.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:

TeamOwns ConfigTypesShips Configuration Packages
Platform core teamSystem.*System
Platform / infrastructure teamInfra.*InfraCommon
BSS teamBSS.*BSSBase
OSS teamOSS.*OSSBase
Ticketing teamTicketing.*TicketingBase
SD-WAN solution teamSDWAN.*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

CodeNamePurpose
SystemSystemCore tSM baseline configuration delivered with the application and refined per project.
InfraInfrastructureShared platform configuration used across multiple business domains.
BSSBSSBusiness Support root.
BSS.CRMCRMCRM configuration.
BSS.ProductCatalogProduct CatalogProduct catalog configuration.
BSS.OrderingOrderingOrdering configuration.
OSSOSSOperations Support root.
OSS.ServiceCatalogService CatalogService definitions and service models.
OSS.ProvisioningProvisioningProvisioning and orchestration configuration.
TicketingTicketingTicketing configuration.

SD-WAN ConfigTypes

CodeNamePurpose
SDWANSD-WANRoot for SD-WAN-specific configuration.
SDWAN.ProductCatalogSD-WAN Product CatalogSD-WAN commercial offer specifics, mappings, and attributes.
SDWAN.OrderingSD-WAN OrderingSD-WAN ordering forms, validations, and process-specific behavior.
SDWAN.ServiceCatalogSD-WAN Service CatalogSD-WAN service templates and service models.
SDWAN.ProvisioningSD-WAN ProvisioningSD-WAN provisioning specifics.
SDWAN.TicketingSD-WAN TicketingSD-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:

  • System
  • InfraCommon
  • BSSBase
  • OSSBase
  • TicketingBase
  • SDWAN

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.

AreaExample assetconfigType
Product catalogSD-WAN offer mappings and attributesSDWAN.ProductCatalog
OrderingSD-WAN order wizard, validations, and stepsSDWAN.Ordering
Service catalogSD-WAN service templateSDWAN.ServiceCatalog
ProvisioningSD-WAN provisioning orchestrationSDWAN.Provisioning
TicketingSD-WAN incident type and workflowSDWAN.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

Experimental

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

  1. Sync main from Git Developers start from the current mainline configuration.

  2. Create a feature branch The branch becomes the unit of isolation and review.

  3. Create a Scratch environment Scratch starts clean and is used only for this feature.

  4. Install baseline packages into Scratch Install what is needed for the feature:

    • System
    • InfraCommon
    • BSSBase
    • OSSBase
    • TicketingBase
    • optionally SDWAN if the feature depends on an existing SD-WAN release
  5. 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
  6. Create MR (Merge Request) The MR contains file changes and package version updates where needed.

  7. Merge After review and checks pass, merge into main.

  8. Build and install The pipeline builds immutable deployment artifacts and installs or upgrades them into target environments.

  • 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

  1. Sync main from Git

  2. Create a feature branch

  3. Modify configuration in DEV

    • every changed or new item must have the correct configType
  4. Download changes to tSM Studio

    • download from DEV into the workspace
    • review diffs locally
  5. Create MR

  6. Merge

  7. Build and install/upgrade to target environments

Risks and controls

Risk on DEVWhat can go wrongControl
Multiple teams modify DEV in parallelChanges collide; one team depends on another’s unfinished workKeep changes small, download frequently, require MR review, prefer Scratch where possible
“It works in DEV but wasn’t committed”PROD install misses critical changesGit is the source of truth; releases happen only through package versions
Accidental edits to shared foundationBreaks multiple domainsStrict ownership by ConfigType root; changes to System.* and Infra.* are controlled by the responsible teams
Hidden drift in DEVDEV differs from known baselinePeriodic 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:

ChoiceWhenBenefit
Full artifactYou want TEST/PROD to fully converge to the package state.Guaranteed clean state. Catches any drift.
Diff-to-targetTarget 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:

  1. Updates their package to work with the new foundation.
  2. Updates the dependencies version range in package.yaml.
  3. Builds a full artifact (recommended for coordinated releases — full artifacts ensure convergence).
  4. 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:

  1. System
  2. InfraCommon
  3. BSSBase, OSSBase, TicketingBase
  4. SDWAN

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:

  • crm
  • ordering
  • service-catalog
  • provisioning

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.