Installed Package
An Installed Package represents a specific configuration package version that has been applied to a particular tSM environment. It is the authoritative record that answers:
- What package is installed here?
- Which version is installed?
- When and by whom was it installed?
- Which configuration items were installed as part of the package?
- Were any of those items modified after installation?
Installed Packages enable repeatable upgrades, dependency validation, and transparent operations across environments.
See also:
Key Concepts
Configuration Package vs Installed Package
- Configuration Package: a distributable package definition (
package.yaml) released as immutable versions. - Installed Package: an environment-side record created when a package version is installed.
Item-level tracking
Installed Packages store the exact list of configuration items installed with that package version. Each item stores its own post-installation state so drift can be evaluated per item.
Drift (item comparison)
Drift is calculated by comparing each installed item against the version that was installed:
- item is unchanged if the environment item still matches what the package installed
- item is changed if it differs (based on item-level comparison rules)
- item is missing if it was installed but is not present in the environment
Post-install modifications (timestamp signal)
In addition to structural comparison, the UI can highlight items modified after the last install by comparing timestamps:
item.lastModifiedAt(current environment)installedItem.installedAt(installation timestamp)- and optionally
installedItem.sourceLastModifiedAtcaptured at install time
This allows fast “was touched after install?” checks even before a deep diff.
Reference
InstalledPackage (attributes)
| Field | Type | Required | Read-only | Description |
|---|---|---|---|---|
id | UUID | – | Yes | Internal identifier. |
packageId | String | Yes | Yes | Configuration package identifier. |
packageName | String | – | Yes | Display name captured at install time (optional). |
version | String | Yes | Yes | Installed package version (e.g. 1.4.0). |
installedAt | DateTime | Yes | Yes | Timestamp of installation. |
installedBy | String | Yes | Yes | User/service that performed the installation. |
installSource | Enum | – | Yes | Origin: CLI, API, TSM_STUDIO, CI_PIPELINE. |
status | Enum | Yes | Yes | Installation record status. |
scope | ScopeSnapshot | – | Yes | Snapshot of package scope used for this install. |
dependencies | List<DependencySnapshot> | – | Yes | Dependencies resolved at install time (optional snapshot). |
items | List<InstalledPackageItem> | Yes | Yes | List of configuration items installed with the package. |
notes | String | – | – | Optional release note / incident reference. |
auditInfo | Object | – | Yes | Standard audit metadata. |
InstalledPackageItem (attributes)
Each entry represents one configuration item that was installed by the package version.
| Field | Type | Required | Read-only | Description |
|---|---|---|---|---|
entityType | String | Yes | Yes | Entity type (e.g. Form, Process, Script). |
entityId | String | Yes | Yes | Environment identifier of the item. |
code | String | – | Yes | Human-friendly key (if available). |
configType | String | Yes | Yes | ConfigType code of the item at install time. |
installedState | Object | Yes | Yes | Canonical representation captured at install time (used for item comparison). |
installedAt | DateTime | Yes | Yes | Timestamp when this item was installed (usually equals package installedAt). |
sourceModifiedAt | DateTime | – | Yes | Last modified timestamp of the source artifact at time of install (optional). |
currentModifiedAt | DateTime | – | Yes | Last modified timestamp currently observed in the environment (captured at last drift scan). |
compareStatus | Enum | Yes | Yes | Result of item-level comparison (see below). |
compareDetails | Object | – | Yes | Optional structured diagnostics (changed fields, missing refs, etc.). |
CompareStatus
| Value | Meaning |
|---|---|
UNCHANGED | Current environment item matches the installed state. |
CHANGED | Item differs from installed state (deep compare). |
MISSING | Item installed by the package is not present in the environment. |
UNKNOWN | Not evaluated yet / comparison not available. |
ScopeSnapshot (attributes)
| Field | Type | Description |
|---|---|---|
configTypes | List<String> | Root ConfigType codes used for selection. |
includeChildren | Bool | Whether descendant config types were included. |
excludeConfigTypes | List<String> | Optional exclusions used at install time. |
selectionMode | Enum | How scope was evaluated (e.g. PREFIX_MATCH). |
DependencySnapshot (attributes)
| Field | Type | Description |
|---|---|---|
packageId | String | Dependent package ID. |
version | String | Installed dependency version at time of install. |
kind | Enum | required / optional. |
Behavior
Installation record creation
When a package version is installed:
-
tSM applies the package content to the environment.
-
tSM creates an InstalledPackage record.
-
For each item installed, tSM stores an InstalledPackageItem entry containing:
installedState(canonical representation captured at install time)- timestamps and classification fields needed for drift detection
Item-level drift evaluation
Drift is computed by comparing each InstalledPackageItem to the current environment item.
Comparison inputs
For each item:
installedItem.installedState(what the package installed)- current environment representation of the item (downloaded for comparison)
Comparison output
compareStatusset toUNCHANGED,CHANGED, orMISSING- optional
compareDetailspopulated for diagnostics
Timestamp-based highlighting
Independently of deep comparison, the UI can flag items that were modified after installation:
- if
currentItem.lastModifiedAt > installedItem.installedAtthen “Modified after install”
This is a fast and understandable signal, useful even when deep compare is expensive.
UI representation
Installed Packages view (environment)
The environment UI shows, per installed package:
-
packageId, name, installed version
-
install time and installer
-
summary of items:
- total items
- unchanged / changed / missing
Selecting a package opens the item list with filter by status.
Configuration Item view (Form / Process / …)
For any configuration item, the UI can display:
Latest installed package
- Latest Installed Package: the most recent package/version that contained this item
Installation history for the item
A list derived from InstalledPackageItem records across versions:
-
in which package versions the item was included
-
in which version it was actually modified by installation
- determined by comparing
installedStatebetween versions, or by install logs
- determined by comparing
Modified after last installation
A clear flag based on timestamps:
- “Modified after last installation” if current
lastModifiedAtis later than the last install time for this item
Quick actions
- show diff: current vs last installed state
- show diff: last installed version vs previous installed version
Example
Installed Package summary
| Field | Value |
|---|---|
packageId | SDWAN |
version | 1.4.0 |
installedAt | 2026-01-08T12:34:56Z |
status | INSTALLED |
| Items | 128 total (115 unchanged, 12 changed, 1 missing) |
Example InstalledPackageItem
| Field | Value |
|---|---|
entityType | form |
code | SDWAN.SiteSetupWizard |
configType | SDWAN.Ordering |
compareStatus | CHANGED |
installedAt | 2026-01-08T12:34:56Z |
currentModifiedAt | 2026-01-08T13:10:02Z |
Notes on ConfigType renaming impact
Because configType is stored on every configuration item and used for selection and reporting, renaming ConfigType codes can affect package membership, installed-item tracking, and UI history. Renames should be handled cautiously due to potentially broad impact.