Change Set Workflow

This page describes a practical workflow for tracking and reviewing independent user stories using Change Sets on top of the existing Configuration Package model.

The workflow applies when:

• multiple developers work in parallel on the same project
• each story needs clear tracking of what changed
• teams want story-level review and audit trail
• deployment still follows the normal Configuration Package pipeline

The examples build on the enterprise SD-WAN project from the Enterprise Workflow.

See also:

• Change Sets
• Configuration Packages
• Enterprise Workflow
• tSM CLI
• Installed Package

---

Overview

Without Change Sets

In the basic and enterprise workflows, the release unit is the entire Configuration Package. A version bump captures everything that changed in that package since the last release.

This works well when:

• one team owns one package and releases infrequently
• all changes in a package are ready to ship together

It breaks down when:

• several stories modify the same package in parallel
• teams need to know which changes belong to which story
• reviewers need to see the exact scope of one story

With Change Sets

Each developer activates a Change Set linked to their story in the tSM UI. The system tracks which entities were touched. When the story is ready:

1. The developer reviews the tracked items.
2. The Change Set is submitted for review.
3. After review, the Change Set is closed.
4. Deployment continues through the normal package pipeline — download, validate, diff, install.

Change Sets provide tracking and review. Deployment remains separate and package-based.

---

Walkthrough: two parallel stories

The stories

Story	Owner	Scope	Package
US-1234	Bob	Add a new SD-WAN site setup form and provisioning process.	SDWAN
US-5678	Alice	Revise common status registers and add a shared validation script.	BSSBase

Both stories are developed in parallel. Both need independent tracking and review.

---

Step 1: Open Change Sets

Each developer creates a Change Set linked to their story. This can be done in the tSM UI or via CLI:

# Bob
tsm changeset create \
  --code US-1234 \
  --name "SD-WAN site setup form and provisioning" \
  --branch feature/US-1234

# Alice
tsm changeset create \
  --code US-5678 \
  --name "Revise common statuses and add shared validation" \
  --branch feature/US-5678

Each developer then selects their Change Set as active in the tSM UI.

---

Step 2: Develop

Bob works in the shared DEV environment with US-1234 active:

• Creates Form/SDWAN_SiteSetup
• Creates Characteristic/SiteRole
• Creates Process/SDWAN_OrderProvisioning
• Modifies Register/SDWANStatuses

Alice works in the shared DEV environment with US-5678 active:

• Modifies Register/CommonStatuses
• Creates Script/SharedAddressValidation
• Modifies Form/OrderEntry (adds a validation reference)

All changes are tracked automatically under each developer's active Change Set.

---

Step 3: Review Change Set contents

Before submitting, each developer reviews what was captured:

tsm changeset show US-1234

Change Set: US-1234
Name:        SD-WAN site setup form and provisioning
Status:      OPEN
Owner:       bob
Branch:      feature/US-1234

ITEMS (4):
  CHANGE     ENTITY TYPE      CODE                        CONFIG TYPE          BASE VERSION
  ADDED      Form             SDWAN_SiteSetup             SDWAN.Ordering       —
  ADDED      Characteristic   SiteRole                    SDWAN.Ordering       —
  ADDED      Process          SDWAN_OrderProvisioning     SDWAN.Provisioning   —
  MODIFIED   Register         SDWANStatuses               SDWAN                2026-03-01T10:00:00Z

tsm changeset show US-5678

Change Set: US-5678
Name:        Revise common statuses and add shared validation
Status:      OPEN
Owner:       alice
Branch:      feature/US-5678

ITEMS (3):
  CHANGE     ENTITY TYPE    CODE                       CONFIG TYPE      BASE VERSION
  MODIFIED   Register       CommonStatuses              Common           2026-02-15T14:00:00Z
  ADDED      Script         SharedAddressValidation     Common           —
  MODIFIED   Form           OrderEntry                  BSS.Ordering     2026-03-01T09:30:00Z

---

Step 4: Submit for review

When a story is complete, the developer submits the Change Set for review:

tsm changeset submit US-1234
tsm changeset submit US-5678

The Change Sets move to IN_REVIEW. No further entity additions are allowed.

A reviewer can inspect the tracked items using tsm changeset show or the tSM UI and verify that the scope is correct and complete.

---

Step 5: Close Change Sets

After review:

tsm changeset close US-1234
tsm changeset close US-5678

The Change Sets move to CLOSED and are archived for audit.

---

Step 6: Deploy through the normal package pipeline

Deployment is handled separately through the standard package workflow:

# Download latest configuration from DEV
tsm package download SDWAN
tsm package download BSSBase

# Validate against PROD
tsm package validate --target-env prod SDWAN
tsm package validate --target-env prod BSSBase

# Review what would change
tsm package diff --target-env prod SDWAN
tsm package diff --target-env prod BSSBase

# Install
tsm package install --target-env prod SDWAN \
  --notes "US-1234: SD-WAN site setup and provisioning"

tsm package install --target-env prod BSSBase \
  --notes "US-5678: revised common statuses, shared validation"

---

Step 7: Verify

tsm package installed list --target-env prod

INSTALLED PACKAGES
PACKAGE     VERSION   INSTALLED AT             NOTES
SDWAN       1.5.0     2026-03-10T14:30:00Z     US-1234: SD-WAN site setup and provisioning
BSSBase     2.1.0     2026-03-11T09:15:00Z     US-5678: revised common statuses, shared validation
System      0.1.0     2026-02-01T10:00:00Z     baseline
...

Both stories are tracked back to their Change Sets via the install notes. The Change Sets themselves provide the detailed per-entity audit trail.

---

Downloading only Change Set items

When a package is large and most items are unchanged, use the --changeset flag to download only the entities tracked by a specific Change Set:

tsm package download SDWAN --changeset US-1234

This downloads only the 4 items that Bob touched, rather than the full SDWAN package. This is useful for targeted review or for creating a minimal diff artifact.

---

Artifact-based deployment with Change Sets

For production pipelines, combine Change Set tracking with the artifact-based approach:

# Download only the Change Set items
tsm package download SDWAN --changeset US-1234

# Build an artifact against PROD
tsm package artifact SDWAN --target-env prod

# Publish
tsm package publish build/SDWAN-1.5.0-prod.zip --repository nexus

# Install
tsm package install --file build/SDWAN-1.5.0-prod.zip \
  --target-env prod \
  --notes "US-1234: SD-WAN site setup and provisioning"

For more on the artifact workflow, see Installation Artifacts.

---

CI/CD integration

Change Set tracking integrates naturally with CI/CD pipelines. The pipeline deploys packages; Change Sets provide traceability.

GitLab CI example

stages:
  - validate
  - deploy

variables:
  TSM_URL: https://tsm.example.com

validate:
  stage: validate
  script:
    - tsm package validate --target-env test $PACKAGE_ID

deploy:
  stage: deploy
  needs: [validate]
  when: manual
  script:
    - tsm package diff --target-env test $PACKAGE_ID
    - tsm package install --target-env test $PACKAGE_ID
      --notes "Pipeline $CI_PIPELINE_ID — $CHANGESET_CODE"

---

Typical end-to-end flow

1. Developer creates a Change Set (linked to ticket)
2. Developer selects the Change Set as active in the tSM UI
3. Developer configures in the environment
   → changes tracked automatically
4. Developer reviews Change Set contents
5. Developer submits for review (OPEN → IN_REVIEW)
6. Reviewer inspects and approves
7. Change Set is closed (IN_REVIEW → CLOSED)
8. Package is released through normal pipeline:
   download → validate → diff → install
9. Installed Package record with story reference provides traceability

---

When to use Change Sets vs. whole-package release

Situation	Recommendation
Single team, no parallel work, all changes ready together.	Whole-package release.
Multiple stories in parallel touching the same package.	Change Sets for tracking.
Hotfix to one entity in a large shared package.	Change Set for audit trail.
Initial project setup, first release.	Whole-package release.
Regular sprint release with all stories finished and tested together.	Either — team preference.

---

Best practices

One Change Set per story

Keep the mapping 1:1 between user stories and Change Sets. Combining multiple stories into one Change Set defeats the purpose of story-level tracking.

Use automatic tracking

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

Submit promptly for review

When a story is finished, submit the Change Set for review immediately. This keeps the review scope clear and reduces confusion about which changes belong to which story.

Use install notes for traceability

When deploying packages, include the Change Set code in the --notes flag. This links the Installed Package record back to the story.

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.

---

Summary

The Change Set workflow adds story-level tracking and review to the existing package model:

• Automatic tracking captures exactly what changed per story.
• Review workflow (OPEN → IN_REVIEW → CLOSED) provides structured review.
• Deployment continues through the normal Configuration Package pipeline.
• Audit trail links installed packages back to individual stories.

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