WATS Client API Package file handling

This article explains how the WATS Client Software API and Package Manager handle package files, including installation locations, version management, and file attribute behaviors.

Root folder

The Root folder is the local path where all software packages are installed. By default it is
C:\Users\Public\Documents\SoftwareDistribution

The root folder can be changed programmatically with the Software API or in WATS Client Configure. If you do, all contents of the current root folder will be moved, not just package files.

Package files are installed based on the following hierarchy:

1. If the package is set to "Install on root" in Production Manager, it will install its contents directly in the root folder.
2. Otherwise it will create a folder with the same name as the package in the root folder and install its content into that folder.

Examples:

• Without "Install on root": C:\Users\Public\Documents\SoftwareDistribution\MyPackage\Folder1\file.txt
• With "Install on root": C:\Users\Public\Documents\SoftwareDistribution\Folder1\file.txt

NOTE: When multiple packages have "Install on root", all their files are installed directly into the root folder without package-specific sub-folders. This creates the potential for file naming conflicts.

Installing Packages

When installing a package, the API performs a smart comparison to minimize unnecessary downloads:

• File doesn't exist: Download
• File exists with matching timestamp: No download needed
• File exists but timestamp differs: Downloaded and overwritten, unless:
  • File has OverwriteNever attribute: No download
  • File has OverwriteOnNewPackageVersion attribute and it's a reinstall of the same package version: No download

The timestamp comparison uses the local file's Date Modified time (called LastWriteTimeUtc in .NET) against the Modified UTC time from the Production Manager. This means if the file is edited after installation, for example a config file is modified, then the file would be overwritten if the package is reinstalled. This also means files in a new package version that have not been modified will not be downloaded.

When installing a new version of an installed package, files that have been removed from the new package version are deleted. Empty folders are also deleted.

In some cases, multiple packages may intentionally share files (e.g., common libraries, shared configuration). For these scenarios:

• Use consistent file attributes across all packages that share the file
• Ensure all packages deliver the same version of the shared file with identical timestamps
• Consider using OverwriteOnNewPackageVersion to ensure only actual version updates replace the file
• Use the package with highest Priority to control which version installs last

File attributes

File attributes control execution and overwrite behavior. Here's when each attribute triggers:

ExecuteOnce

• Triggers: When the file is downloaded
• Does not trigger: If the file already exists locally and has not been modified

ExecuteAlways

• Triggers: Every time the package is installed, regardless of whether the file is downloaded
• Does not trigger: Only if package installation is skipped entirely

ExecuteOncePerVersion

• Triggers:
  • When installing a new version of the package
  • When the file doesn't exist locally (first install)
• Does NOT trigger: On reinstall of the same version if file already exists

TopLevelFile

• Triggers: Every time the package is installed (file is added to TopLevelSequences list)
• Purpose: Marks files as top-level sequences for test execution frameworks
• Note: This attribute doesn't execute the file - it identifies it for external use

OverwriteNever

• Prevents: Overwriting the file if it exists locally, even if modified or outdated
• Allows: Initial download if file doesn't exist

OverwriteOnNewPackageVersion

• Prevents: Overwriting on reinstall of the same package version
• Allows: Overwriting when installing a newer package version