Version: 2.4

Basic workflow for a simple project with Configuration Packages

This page describes a minimal, business-friendly setup for a small tSM project where:

teams configure the solution in DEV
changes are captured in tSM Studio and versioned in Git
versioned Configuration Packages are installed into PROD
later updates follow the same repeatable workflow

The goal is a clean release process with clear answers to:

What exactly was deployed?
Which configuration belongs to which area?
How do we safely update PROD after the first release?

The example uses only two environments:

DEV
PROD

Overview

What you define

A simple ConfigType structure to organize configuration:

System
Common
CRM
Catalog
Ordering
Ticketing
Other

Two Configuration Packages:

System — core tSM configuration that comes preconfigured with the application and may be refined by the installation
AllConfig — all business/project configuration, including Common

A small set of package areas inside each package to store content in Git.

What you do

configure in DEV
download to Studio
commit to Git
build package versions
install them into PROD

For later changes:

modify in DEV
download to Studio
commit to Git
bump versions
upgrade PROD

ConfigTypes for a simple project

This example uses a small, root-level ConfigType structure. Even in a simple project, codes should be stable from the beginning.

ConfigTypes

Code	Name	Purpose
`System`	System	Core tSM configuration delivered with the application. This includes baseline platform configuration that should remain clearly separated from business/project customization.
`Common`	Common	Shared business configuration reused by multiple areas, such as common statuses, shared registers, shared scripts, shared forms, and reusable fragments.
`CRM`	CRM	CRM-related configuration such as customer/account forms, sales views, and related rules.
`Catalog`	Catalog	Catalog records, product attributes, and reference data for offerings.
`Ordering`	Ordering	Ordering forms, validations, processes, and orchestration rules.
`Ticketing`	Ticketing	Ticket types, workflows, forms, and state models.
`Other`	Other	Configuration that does not fit into the main business areas.

Rule: Every configuration entity in tSM contains configType and should have it set correctly.

Although this example uses only root-level ConfigTypes, the package model already supports future growth into a hierarchy.

Configuration Packages in this example

This example uses two packages:

System — configuration that belongs to the tSM platform baseline
AllConfig — all business and project-specific configuration, including shared Common

This keeps the release model simple:

platform/core configuration is clearly separated from business customization
business/project configuration is delivered as one main package
PROD always shows which versions are installed

Why `System` is separate

The System package is different from ordinary business configuration.

It represents configuration that is:

core to tSM
delivered with the application
expected to exist as part of the platform baseline
sometimes refined or adjusted by the installation

The key point is that System configuration should not be mixed with business configuration such as CRM, ordering, ticketing, or shared project rules.

This separation helps keep a clean boundary between:

platform baseline
installation-specific business solution

In practice:

System changes are rarer and more controlled
AllConfig changes are the normal project release flow

Workspace layout

A simple workspace can look like this:

packages/
  System/
    package.yaml
    system/

  AllConfig/
    package.yaml
    common/
    crm/
    catalog/
    ordering/
    ticketing/
    other/

tsm-project.yaml

For the full project.yaml and package.yaml schema, see Configuration Reference.

Notes

each package has one package.yaml
each package contains one or more areas
in AllConfig, each business ConfigType has its own area
during sync, tSM Studio creates entity-type subfolders automatically inside those areas

For example, after synchronization an area may contain subfolders such as:

packages/
  AllConfig/
    catalog/
      EntityCatalogCategory/
      EntityCatalogSpecification/
      EntitySpecification/
      Characteristic/
      Form/

    ordering/
      Form/
      Process/
      Script/
      Register/

This means areas should represent a business/configuration area, not one technical type.

How package membership works

Package membership is determined area by area.

Each area defines:

where content is stored in Git
which ConfigTypes belong there
whether each ConfigType should include its subtree

During synchronization:

the package area is created if it does not exist
each configured area is created
matching items are selected by ConfigType
Studio creates entity-type subfolders automatically inside the area
matching items are written there

Selection rules

For each area:

the area lists one or more ConfigTypes
for each listed ConfigType:
- if includeSubtree: false, only the exact ConfigType matches
- if includeSubtree: true, descendants also match
matching items are downloaded into that area

In this simple example, the structure is effectively root-level, so matching is usually exact. Using includeSubtree: true is still reasonable because it keeps the package ready for future hierarchy growth.

Package definition: `System`

Purpose

The System package contains tSM core configuration that comes preconfigured with the application and may be refined by the installation.

This package should remain clearly separated from business/project configuration.

`packages/System/package.yaml`

packageId: System
name: System
version: 0.0.1
description: Core tSM baseline configuration delivered with the application and refined by the installation.
ownerTeam: Platform

areas:
  - id: system
    path: system
    description: Core platform configuration.
    configTypes:
      - code: System
        includeSubtree: true

policy:
  managed: true
  allowDelete: false
  enforceDependencies: true

What this means

This package:

stores its content in packages/System/system/
includes all items with configType = System
also supports future child ConfigTypes under System.*
remains separate from business/project configuration

Package definition: `AllConfig`

Purpose

The AllConfig package contains all business/project configuration, including shared Common.

Instead of one generic business area, this package uses separate areas per ConfigType.

`packages/AllConfig/package.yaml`

packageId: AllConfig
name: All Configuration
version: 0.0.1
description: Main package containing all business and project-specific configuration.
ownerTeam: SolutionTeam

dependencies:
  - packageId: System
    versionRange: ">=0.0.1 <1.0.0"
    kind: required

areas:
  - id: common
    path: common
    description: Shared business configuration reused across multiple areas.
    configTypes:
      - code: Common
        includeSubtree: true

  - id: crm
    path: crm
    description: CRM-related configuration.
    configTypes:
      - code: CRM
        includeSubtree: true

  - id: catalog
    path: catalog
    description: Catalog-related configuration.
    configTypes:
      - code: Catalog
        includeSubtree: true

  - id: ordering
    path: ordering
    description: Ordering-related configuration.
    configTypes:
      - code: Ordering
        includeSubtree: true

  - id: ticketing
    path: ticketing
    description: Ticketing-related configuration.
    configTypes:
      - code: Ticketing
        includeSubtree: true

  - id: other
    path: other
    description: Configuration that does not fit into the main business areas.
    configTypes:
      - code: Other
        includeSubtree: true

policy:
  managed: true
  allowDelete: false
  enforceDependencies: true

What this means

This package:

contains all business/project configuration
includes Common together with the main business areas
separates content in Git by business area:
- common/
- crm/
- catalog/
- ordering/
- ticketing/
- other/
depends on System

This structure is still simple, but more readable than putting everything into one generic solution/ area.

Example Git structure after sync

After synchronization, the workspace may look like this:

packages/
  System/
    package.yaml
    system/
      Register/
      Script/
      Form/

  AllConfig/
    package.yaml

    common/
      Register/
      Script/
      Form/

    crm/
      Form/
      Script/

    catalog/
      EntityCatalogCategory/
      EntityCatalogSpecification/
      EntitySpecification/
      Characteristic/
      Form/

    ordering/
      Form/
      Process/
      Script/
      Register/

    ticketing/
      Form/
      Process/
      Register/

    other/
      Form/
      Register/

The important point is:

package areas are defined explicitly by business area
entity-type subfolders are created automatically by Studio

Workflow: initial release (DEV → PROD)

1) Configure in DEV

In the DEV environment:

create or modify configuration items
set configType correctly for each item

Recommended approach:

core platform/baseline item → System
shared business item reused across multiple areas → Common
otherwise assign the item to the most specific business area:
- CRM
- Catalog
- Ordering
- Ticketing
- Other

2) Download changes to tSM Studio

In tSM Studio, connect to DEV and download configuration into the workspace.

Using the CLI:

tsm package download System
tsm package download AllConfig

Review the local changes in:

packages/System/...
packages/AllConfig/...

Because package areas are already defined, Studio places the downloaded items into the correct Git location automatically.

3) Commit to Git

Commit the downloaded changes to Git.

Example commit messages:

System: refine baseline platform configuration
AllConfig: initial project configuration
Catalog: initial catalog setup
Ordering: initial order flow

4) Build version `0.0.1`

Confirm the versions:

packages/System/package.yaml → version: 0.0.1
packages/AllConfig/package.yaml → version: 0.0.1

Then build installation artifacts:

tsm package artifact System --target-env prod
tsm package artifact AllConfig --target-env prod

This produces files in build/:

System-0.0.1-prod.zip
AllConfig-0.0.1-prod.zip

5) Install to PROD

First validate and review what will change:

tsm package validate --file build/System-0.0.1-prod.zip --target-env prod
tsm package diff --file build/System-0.0.1-prod.zip --target-env prod

tsm package validate --file build/AllConfig-0.0.1-prod.zip --target-env prod
tsm package diff --file build/AllConfig-0.0.1-prod.zip --target-env prod

Then install — System first, because AllConfig depends on it:

tsm package install --file build/System-0.0.1-prod.zip \
  --target-env prod \
  --notes "System 0.0.1 — initial PROD deployment"

tsm package install --file build/AllConfig-0.0.1-prod.zip \
  --target-env prod \
  --notes "AllConfig 0.0.1 — initial PROD deployment"

After installation, verify:

tsm package installed list

INSTALLED PACKAGES
PACKAGE     VERSION   INSTALLED AT             NOTES
System      0.0.1     2026-01-15T10:00:00Z     System 0.0.1 — initial PROD deployment
AllConfig   0.0.1     2026-01-15T10:05:00Z     AllConfig 0.0.1 — initial PROD deployment

Workflow: update after initial installation

This is the normal workflow for every later change.

1) Make changes in DEV

In DEV:

modify existing items or add new ones
keep configType correct

Typical examples:

platform baseline refinement → System
shared business change → Common
customer/account change → CRM
product/catalog change → Catalog
order flow change → Ordering
ticket flow change → Ticketing

2) Download changes to tSM Studio

In Studio, connected to DEV, download the updated configuration:

tsm package download AllConfig

Review local diffs in the workspace.

3) Commit to Git

Commit the changes with a meaningful message.

Examples:

System: adjust baseline status configuration
Common: add shared validation script
Ordering: add new field to order form
Catalog: add new product characteristic

4) Bump package versions

Increase the versions of the packages that changed.

Using the CLI:

tsm package set version \
  --package-yaml packages/AllConfig/package.yaml \
  --bump patch

Or set an explicit version:

tsm package set version \
  --package-yaml packages/AllConfig/package.yaml \
  --version 0.0.2

Typical cases

If only business/project configuration changed:

bump AllConfig

If only platform baseline configuration changed:

bump System
usually also review whether AllConfig should depend on the newer System version

If both changed:

bump both packages

Example

# System
version: 0.0.2

# AllConfig
version: 0.0.2

dependencies:
  - packageId: System
    versionRange: ">=0.0.2 <1.0.0"
    kind: required

5) Build new versions

Build the new artifacts:

# Only if System changed
tsm package artifact System --target-env prod

# Only if AllConfig changed
tsm package artifact AllConfig --target-env prod

6) Upgrade PROD

Validate, diff, and install:

# If System changed
tsm package validate --file build/System-0.0.2-prod.zip --target-env prod
tsm package diff --file build/System-0.0.2-prod.zip --target-env prod
tsm package install --file build/System-0.0.2-prod.zip \
  --target-env prod \
  --notes "System 0.0.2 — baseline status refinement"

# If AllConfig changed
tsm package validate --file build/AllConfig-0.0.2-prod.zip --target-env prod
tsm package diff --file build/AllConfig-0.0.2-prod.zip --target-env prod
tsm package install --file build/AllConfig-0.0.2-prod.zip \
  --target-env prod \
  --notes "AllConfig 0.0.2 — ordering form update"

After the upgrade, PROD clearly reflects:

which package versions are installed
what release was deployed

Best practices for this simple setup

Keep `System` separate

Do not mix tSM baseline/platform configuration with business/project configuration.

Keep `Common` inside the business package

Common is shared business configuration, so it belongs with the rest of business/project customization in AllConfig.

Keep areas business-oriented

Use one area per main ConfigType area in AllConfig. This keeps the Git structure easy to understand.

Keep ConfigTypes stable

Do not rename ConfigType codes unless necessary. Renames can change package membership and Git structure.

Keep the main package simple

For a small project, one main business package (AllConfig) is enough. Split it only when there is a real release need.

Use dependencies instead of duplication

If a business package needs the platform baseline, depend on System. Do not duplicate platform configuration into AllConfig.

Commit after each meaningful sync

Git should remain the source of truth for what is going to be released.

When this simple model is enough

This setup is a good fit when:

one project team owns most of the business solution
there are only a few business areas
the release process is straightforward
you want a clear DEV → Git → PROD workflow
you still want a clean separation between platform baseline and business customization

If the solution later grows, you can evolve this model by:

adding child ConfigTypes
splitting AllConfig into more business packages
introducing more specific dependencies between packages

Summary

This simple project setup uses:

a small set of ConfigTypes for ownership and organization
one platform package (System)
one main business package (AllConfig)
separate business areas inside AllConfig
automatic entity-type subfolders created by Studio during sync

The release flow stays simple:

configure in DEV
download to Studio
commit to Git
build package versions
install or upgrade in PROD

This gives a small project a predictable release process from the first deployment onward.

Overview​

What you define​

What you do​

ConfigTypes for a simple project​

ConfigTypes​

Configuration Packages in this example​

Why System is separate​

Workspace layout​

Notes​

How package membership works​

Selection rules​

Package definition: System​

Purpose​

packages/System/package.yaml​

What this means​

Package definition: AllConfig​

Purpose​

packages/AllConfig/package.yaml​

What this means​

Example Git structure after sync​

Workflow: initial release (DEV → PROD)​

1) Configure in DEV​

2) Download changes to tSM Studio​

3) Commit to Git​

4) Build version 0.0.1​

5) Install to PROD​

Workflow: update after initial installation​

1) Make changes in DEV​

2) Download changes to tSM Studio​

3) Commit to Git​

4) Bump package versions​

Typical cases​

Example​

5) Build new versions​

6) Upgrade PROD​

Best practices for this simple setup​

Keep System separate​

Keep Common inside the business package​

Keep areas business-oriented​

Keep ConfigTypes stable​

Keep the main package simple​

Use dependencies instead of duplication​

Commit after each meaningful sync​

When this simple model is enough​

Summary​

Overview

What you define

What you do

ConfigTypes for a simple project

ConfigTypes

Configuration Packages in this example

Why `System` is separate

Workspace layout

Notes

How package membership works

Selection rules

Package definition: `System`

Purpose

`packages/System/package.yaml`

What this means

Package definition: `AllConfig`

Purpose

`packages/AllConfig/package.yaml`

What this means

Example Git structure after sync

Workflow: initial release (DEV → PROD)

1) Configure in DEV

2) Download changes to tSM Studio

3) Commit to Git

4) Build version `0.0.1`

5) Install to PROD

Workflow: update after initial installation

1) Make changes in DEV

2) Download changes to tSM Studio

3) Commit to Git

4) Bump package versions

Typical cases

Example

5) Build new versions

6) Upgrade PROD

Best practices for this simple setup

Keep `System` separate

Keep `Common` inside the business package

Keep areas business-oriented

Keep ConfigTypes stable

Keep the main package simple

Use dependencies instead of duplication

Commit after each meaningful sync

When this simple model is enough

Summary