Version: 2.4

Configuration Packages (GIT)

Configuration Packages are the unit of distribution in tSM. They let you version, build, publish, install, and upgrade a coherent subset of configuration across environments.

A Configuration Package is defined by a package.yaml file. It describes:

package identity and version
dependencies on other packages
package areas
which ConfigTypes belong to each area
optional entity-type-specific refinements
install and upgrade policy

For a configurator, the model is simple:

ConfigType says where configuration belongs
Configuration Package says what is released and installed
Area says where the package content is stored in Git

Relationship to ConfigType

Configuration Packages are built on top of ConfigType. Every configuration entity in tSM has a configType field, and this is what determines which package an entity belongs to.

A package does not replace ConfigType — it uses ConfigType to decide what is inside the package.

For a full introduction to how ConfigType, Configuration Package, Area, Change Set, and Installed Package relate, see the Packaging & Deployment Overview.

Key idea

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 core.common.*"
"everything under cap.ordering.sdwan.product.*"
"everything under cap.ordering.sdwan.fulfillment.*"

If an area needs many special rules to explain its content, the design is probably too complex.

Repository layout

A typical workspace looks like this:

packages/
  core-common/
    package.yaml
    shared/

  ordering-core/
    package.yaml
    ordering/

  ordering-sdwan/
    package.yaml
    sdwan/

tsm-project.yaml

Each package has:

one package.yaml
one or more areas

These areas are not usually split manually by entity type.

Instead, during sync, tSM Studio creates entity-type subfolders automatically inside each area.

That means an area should represent a business/configuration area, not just a technical type.

How areas work

A package contains one or more areas.

Each area defines:

where content is stored in Git
which ConfigTypes belong there
optional refinements for specific entity types

Important behavior during sync

When a package is synchronized:

the package area is created if it does not exist
each configured area is created
inside each area, Studio creates subfolders automatically by entity type
matching configuration items are written into those subfolders

When includeSubtree: true is used, Studio can also create ConfigType-based subdirectories for descendant ConfigTypes.

Naming rules for these ConfigType-based subdirectories:

by default, the directory name uses only the last segment of the ConfigType code
if two descendants would produce the same last segment, the second conflicting occurrence is named using the full ConfigType code with dots replaced by dashes

Example:

core.common.crm.shared → shared/
core.common.ordering.shared → core-common-ordering-shared/

So if one area contains a product-related ConfigType, its Git structure may contain subfolders like:

packages/
  ordering-sdwan/
    sdwan-product/
      EntityCatalogCategory/
      EntityCatalogSpecification/
      EntitySpecification/
      Characteristic/
      Form/

This is intentional.

The area represents one configuration area. The entity-type subfolders are generated automatically to keep the content organized.

Why this is useful

In a real solution, related items often belong together even though they are different entity types.

For example, one ConfigType may contain:

product category
product specification
associated configuration profile (EntitySpecification)
associated characteristics (Characteristic)
associated forms (Form)

These should stay together under one business area because they belong to the same configuration area.

How package membership works

Package membership is determined area by area.

For each area:

the area lists one or more ConfigTypes
for each ConfigType:
- if includeSubtree: false, only the exact ConfigType is included
- if includeSubtree: true, all descendant ConfigTypes are included too
optional entity-type-specific refinements are applied
matching items are written into the area, grouped automatically by entity type

So the main rule is:

ConfigType first, entity-type refinement second

Best practices

1. Keep areas close to ConfigType

Each area should follow one stable ConfigType subtree.

Good examples:

area shared → core.common.*
area sdwan-product → cap.ordering.sdwan.product.*
area sdwan-fulfillment → cap.ordering.sdwan.fulfillment.*

2. Keep areas business-oriented

Areas should represent a meaningful configuration area, not just a technical entity type.

Good area names:

shared
ordering
sdwan-product
service-catalog
ticketing-flow

Avoid using areas only like:

forms
registers
misc

unless that is genuinely the clearest business grouping.

Entity-type separation is already handled automatically inside the area.

3. Use subtree inclusion deliberately

Use includeSubtree: true when an area should cover a whole ConfigType branch.

Use includeSubtree: false when only the exact ConfigType belongs there.

4. Prefer dependencies over mixed scope

If one package needs another, declare a dependency.

Prefer:

ordering-sdwan depends on core-common
ordering-sdwan depends on ordering-core

Avoid mixing unrelated roots into one package just to make installation easier.

Entity-type-specific includes, excludes, and filters are useful for edge cases, but they should not become the main packaging mechanism.

If many exceptions are needed, improve the ConfigType structure instead.

6. Prefer codes over IDs

When selecting individual items, prefer business codes.

IDs are allowed, but codes are easier to read, review, and maintain in Git.

7. Treat ConfigType renames as high-impact

Because package membership depends on configType, renaming a ConfigType can change package content and Git structure.

Renames should be rare and carefully planned.

Example 1: SD-WAN ordering package

cap.ordering
  cap.ordering.catalog
  cap.ordering.forms
  cap.ordering.processes
  cap.ordering.sdwan
    cap.ordering.sdwan.product
    cap.ordering.sdwan.fulfillment

Goal

Package:

ordering-sdwan

Contains:

SD-WAN product configuration
related specifications
related characteristics
related forms
SD-WAN fulfillment processes

Depends on:

core-common
ordering-core

Example `package.yaml`

packageId: ordering-sdwan
name: Ordering / SD-WAN
version: 1.4.0
description: SD-WAN-specific ordering configuration.
ownerTeam: SDWAN

dependencies:
  - packageId: core-common
    versionRange: ">=1.0.0 <2.0.0"
    kind: required

  - packageId: ordering-core
    versionRange: ">=1.2.0 <2.0.0"
    kind: required

areas:
  - id: sdwan-product
    path: sdwan-product
    description: SD-WAN commercial and product-model configuration.
    configTypes:
      - code: cap.ordering.sdwan.product
        includeSubtree: true

  - id: sdwan-fulfillment
    path: sdwan-fulfillment
    description: SD-WAN-specific process and orchestration configuration.
    configTypes:
      - code: cap.ordering.sdwan.fulfillment
        includeSubtree: true
    entityRules:
      - entityType: Script
        include:
          - idOrCode: SDWAN.EligibilityCheck

policy:
  managed: true
  allowDelete: false
  enforceDependencies: true

Example Git structure after sync

packages/
  ordering-sdwan/
    package.yaml

    sdwan-product/
      EntityCatalogCategory/
        SDWAN_Category.json
      EntityCatalogSpecification/
        SDWAN_Offer.json
      EntitySpecification/
        SDWAN_Profile.json
      Characteristic/
        AccessBandwidth.json
        SiteRole.json
      Form/
        SDWAN_SiteSetup.json

    sdwan-fulfillment/
      Process/
        SDWAN_OrderProvisioning.json
      Script/
        SDWAN_EligibilityCheck.json

This is the preferred model:

one area per business/configuration area
entity-type subfolders created automatically
related content kept together

Example 2: shared common package

packageId: core-common
name: Core / Common
version: 1.0.0
description: Shared reusable platform configuration.
ownerTeam: Platform

areas:
  - id: shared
    path: shared
    description: Shared statuses, scripts, and common forms.
    configTypes:
      - code: core.common
        includeSubtree: true

policy:
  managed: true
  allowDelete: false
  enforceDependencies: true

This package is easy to understand:

one ConfigType root
one business area
automatic grouping by entity type
no entityRules needed — add them only when you need explicit overrides (include, exclude, filters)

Example subtree directories with `includeSubtree: true`

If this package includes descendants such as:

core.common.crm.shared
core.common.ordering.shared

then Studio can create ConfigType-based subdirectories like:

packages/
  core-common/
    shared/
      shared/
      core-common-ordering-shared/

Rule summary:

first unique suffix uses only the last ConfigType segment
conflicting suffixes use full code with dots replaced by dashes

Configuration reference

For the full package.yaml schema — including all field tables for Package, Area, AreaConfigType, EntityRule, Selector, Filter, Dependency, and Policy — see the Configuration Reference.

Summary

Configuration Packages are the unit of distribution
They are based on ConfigType
A package contains areas
An area is usually a business/configuration area
Each area lists one or more ConfigTypes
Each ConfigType says whether to include the subtree
Optional per-entity-type rules allow includes, excludes, and filters
Selectors use one field: idOrCode
During sync, Studio creates entity-type subfolders automatically inside each area
The best package design is usually:
- a few clear business areas, each scoped to one ConfigType subtree
- very few entity-rule exceptions

Relationship to ConfigType​

Key idea​

Repository layout​

How areas work​

Important behavior during sync​

Why this is useful​

How package membership works​

Best practices​

1. Keep areas close to ConfigType​

2. Keep areas business-oriented​

3. Use subtree inclusion deliberately​

4. Prefer dependencies over mixed scope​

5. Keep refinements exceptional​

6. Prefer codes over IDs​

7. Treat ConfigType renames as high-impact​

Example 1: SD-WAN ordering package​

Related ConfigTypes​

Goal​

Example package.yaml​

Example Git structure after sync​

Example 2: shared common package​

Example subtree directories with includeSubtree: true​

Summary​