Change Sets

A Change Set is a story-level tracking unit in tSM. It captures the exact set of configuration changes made for a single user story or task, giving teams visibility into what changed and a clear scope for review.

While Configuration Packages define long-lived, capability-oriented release boundaries, a Change Set provides a lighter-weight grouping that tracks individual stories within those packages.

Concept	Role
ConfigType	Ownership and taxonomy — where configuration belongs.
Configuration Package	Long-lived deployable capability — what is released.
Change Set	Story-level tracking unit — what changed for this story.
Installed Package	Operational history — what is installed in a target environment.

See also:

• Configuration Explorer
• ConfigType
• Installed Package
• Configuration Lifecycle

---

Why Change Sets exist

Configuration Packages work well when a release maps to a single capability boundary. In practice, this model has a gap:

• A user story often touches items across multiple ConfigTypes or even multiple packages.
• Several stories may be developed in parallel against the same shared package.
• Teams need to see which changes belong to which story.

Without Change Sets, there is no record of which configuration changes belong together. Change Sets close this gap by providing a story-scoped grouping on top of the existing package model.

---

Core idea

A Change Set is not a replacement for packages. It is a tracking layer that:

1. collects the exact entities touched by a story
2. provides a clear scope for review
3. records the baseline state of each entity at the time the Change Set was opened

After the story is complete and reviewed, the Change Set is closed. The entities remain part of their Configuration Packages as before.

---

Change Set lifecycle

OPEN  →  IN_REVIEW  →  CLOSED

State	Meaning
OPEN	Active. Entities are being tracked.
IN_REVIEW	Submitted for review. No further entity additions.
CLOSED	Review is complete. Change Set is archived for audit.

A Change Set can also be abandoned at any point before closing.

---

What a Change Set contains

ChangeSet (attributes)

Field	Type	Description
id	UUID	Internal identifier.
code	String	Short identifier, typically matching the story or ticket (e.g. US-1234).
name	String	Human-readable description.
status	Enum	Current lifecycle state (OPEN, IN_REVIEW, CLOSED).
branch	String	Git branch or workspace this Change Set belongs to.
ownerUserId	String	The developer who owns the Change Set.
ownerUserGroup	String	User group that owns the Change Set.
items	List<ChangeSetItem>	The configuration entities included in the Change Set.
createdAt	DateTime	When the Change Set was created.
notes	String	Free-text notes (e.g. story description, release notes).

ChangeSetItem

Each item in a Change Set references one configuration entity:

Field	Type	Description
entityType	String	Entity type (e.g. Form, Process, Script).
entityId	String	Entity identifier.
code	String	Human-friendly entity code.
configType	String	ConfigType code of the entity.
changeType	Enum	ADDED, MODIFIED, or REMOVED.
baseVersion	DateTime	Timestamp of the entity state when the Change Set was opened.

---

How entities enter a Change Set

Entities can enter a Change Set in two ways:

Automatic tracking

When a user selects a Change Set as active in the UI, the system automatically tracks every configuration item that is created, modified, or deleted while that Change Set is active. This requires no manual bookkeeping.

Automatic tracking uses the same configType mapping that Configuration Packages use. The tracking engine observes entity-level changes and adds them to the active Change Set.

Manual addition

Developers can also manually add entities to a Change Set. This is useful when:

• an entity needs to be included for consistency but was not directly modified
• the developer wants to explicitly control the scope before review

---

Relationship to existing concepts

ConfigType

ConfigType still defines where every entity belongs. Change Sets do not alter ConfigType assignment. They use ConfigType for:

• filtering and displaying Change Set contents
• validating that entities have correct ownership

Configuration Packages

Packages remain the stable, long-lived deployment boundary. Change Sets provide a story-level view within that boundary. After a Change Set is closed, the entities are still tracked under their normal Configuration Package.

Installed Packages

Change Sets are independent of installation. Deployment is handled through the normal package installation pipeline. The installSource on an Installed Package may indicate the originating Change Set for traceability.

---

Configuration Explorer integration

The Configuration Explorer can display Change Set information alongside package and drift metadata:

SiteSetupWizard ⚠ SDWAN  [US-1234]
OrderHeader     ✓ BSS
ValidateOrder   ✓ Infra  [US-5678]

Change Set indicators show:

• which Change Set currently tracks an entity
• whether the entity is part of an open or closed Change Set

---

CLI

Change Sets can also be managed from the command line. For details, see tSM CLI.

---

Example: two stories in parallel

Two developers work on independent stories in the same project:

Story	Developer	Change Set
US-1234	Bob	US-1234
US-5678	Alice	US-5678

Bob modifies forms and processes in the SDWAN package. Alice modifies registers and scripts in BSSBase.

Both work in parallel with their respective Change Sets active in the UI.

When Bob finishes:

1. Bob submits US-1234 for review (OPEN → IN_REVIEW).
2. Reviewer inspects the tracked items and confirms the scope is correct.
3. US-1234 is closed (IN_REVIEW → CLOSED).
4. The SDWAN package is released and installed through the normal deployment pipeline.

When Alice finishes:

1. Alice submits US-5678 for review.
2. Review is complete.
3. US-5678 is closed.
4. The BSSBase package is released and installed.

Both stories are tracked independently. The Change Sets provide a clear audit trail of which entities were changed for each story.

---

Best practices

Keep Change Sets small

A Change Set should ideally map to a single user story or task. Small Change Sets are easier to review and provide clearer audit trails.

Use automatic tracking

Prefer automatic tracking over manual entity management. Select the active Change Set in the UI and let the system capture exactly what changed.

Do not bypass packages

Change Sets do not replace Configuration Packages. Every entity still belongs to a package via ConfigType and area mapping. Change Sets add story-level tracking on top.

Review before closing

Use the IN_REVIEW state to coordinate review across team members before closing the Change Set. This ensures all relevant changes are captured and reviewed.

---

Summary

Change Sets add story-level tracking to the tSM configuration model:

• Users select an active Change Set in the UI and changes are tracked automatically.
• Each story has its own Change Set with explicit entity references and baseline timestamps.
• The lifecycle is simple: OPEN → IN_REVIEW → CLOSED.
• Deployment continues through the normal Configuration Package pipeline.
• Change Sets provide an audit trail of which entities were changed for each story.

The result is clear visibility into parallel work without adding complexity to the deployment model. Packages remain capability-oriented. Change Sets handle story-level granularity.