| Rev # | Date | Description |
|---|---|---|
| 1.0 | Jan 2021 | Updated and revised for customer publication. |
| 1.1 | Jul 2024 | Document validated for the current release. No major changes were made. |
Note
All SolidPractices are written as guidelines. It is a strong recommendation to use these documents only after properly evaluating your requirements. Distribution of this document is limited to Dassault Systèmes SolidWorks employees, VARs, and customers that are on active subscription. You may not post this document on blogs or any internal or external forums without prior written authorization from Dassault Systèmes SolidWorks Corporation.
This document was updated using version SOLIDWORKS 2024 SP03. All of the GUI, Windows® registry and SWPDM menu commands are unchanged for the 2024 release. If you have questions or need assistance in understanding the content, please get in touch with your designated reseller.
Preface
Cold storage in the SOLIDWORKS PDM software allows you to set up a scheduled operation that deletes or moves older versions of files from the file vault archives to free up disk space in the archive storage location.
The intent of this document is to help you understand the available options. This information is useful when determining the best way to implement cold storage.
Your Feedback Requested
We would like to hear your feedback and suggestions for new topics. After reviewing this document, please take a few minutes to fill out a brief survey. Your feedback will help us create the content that directly addresses your challenges.
Considerations
Before implementing cold storage, it is useful to understand what cold storage can and cannot do. Benefits and drawbacks of using cold storage include the following:
Cold storage deletes or moves older versions only from the physical archive server folders. All the database metadata entries for each processed file (check in information, card values, etc.) remain in the database. You cannot use cold storage to delete older history entries. If you want to delete all older versions of a file but keep the latest version, it is a good practice to make a copy of the file and delete the original to create a new version history for the copy.
Cold storage processes all files matching the selected folders and removes a defined number of older versions. This also applies to all subfolders of the selected folder and cannot be restricted to certain file types or files in certain states. The only exception to this rule is that you have the option to not process file versions that have an assigned revision number or label.
If you select to delete older file versions, the operation is irreversible. The only way to recover versions that were deleted by cold storage is to restore them manually from a backup of the archive server that was processed. There is no tool available to batch restore multiple deleted versions.
Do not use cold storage as a way to restrict file access. If that is the intent, use workflow state permissions instead to restrict access to versions that you do not want to make accessible by certain users.
Only use cold storage if the versions that are deleted or moved are not used frequently. While it is possible to recover a moved version, it could become a complex procedure depending on how often the version is required.
Before implementing cold storage, consider enabling compression instead. Compression still reduces disk space, and the versions remain accessible in the case of need.
In a replicated environment, cold storage operations are set up per individual archive server. This makes it possible to implement cold storage only on one out of multiple servers. However, versions that are cold stored would not be accessible from client computers attached to that server.
How Much Space Does the Vault Archive Consume?
When you check out, modify, and check in a file, SOLIDWORKS PDM creates a new version of that file. All file versions that have changes to physical content are stored in the file vault archives. Each physical file in the file vault has a unique file archive folder ID where the individual versions are stored. Within the file archive folder, one or more physical files are stored with the version number as the file name. For example, version 1 is stored as 00000001.ext, version 5 as 00000005.ext, and so on.
The following image shows a file that has six versions and the vault
view will have a file archive that contains one or more of the six
versions.
that have the same physical content as the previous version, the file
archive index.xml file instead stores a reference
pointer to the previous version, saving disk space. This means that
while a file may have 10 versions, the archive might only contain five
physical version copies instead of all ten.
The next image shows a file that has four versions. The file archive
contains the physical versions 1 and
4. Versions 2 and 3
have the same physical content as version 1, and have a
reference pointer to this version instead.
The archive server service manages the file vault archives.
The file vault archives consist of an archive folder with the same name
as the file vault name, and (normally) 16 subfolders named
0 (zero) through F. Each file archive
is stored under one of the 16 subfolders depending on the archive folder
ID.
If you are unsure of the location of the vault archives on the
archive server, you can use the archive server configuration
tool. Expand the root folder in the left-hand tree, right-click the
vault name and then click Properties. If the archives
are split up or relocated, they may spread over multiple
locations.
You can also view the ArchiveTable registry key for the location of the archives:
HKEY_LOCAL_MACHINE\SOFTWARE\SolidWorks\Applications\PDMWorks Enterprise\ArchiveServer\Vaults\[VaultName]\ArchiveTable
Incorrectly editing the registry can severely damage your operating system. The SOLIDWORKS Technical Support team strongly suggests that you back up the registry data before making any changes to the registry.
To find how much space the physical vault archives take up on disk,
view the properties of the main archive folder of the vault.
How Much Space Does Cold Storage Save?
The amount of disk space that cold storage frees up varies greatly depending on how many file versions you maintain in the file archives, and on what folders are included in the cold storage schemas.
To get a rough estimate of the potential space that cold storing a
specific folder will free up, refer to the SQL report in SOLIDWORKS
Knowledge Base QA article QA00000114280.
The report shows the amount of space possible to free up if physically
storing all versions in the archive folders, based on the file
size registered in the database. Be aware that the actual size on disk
could be less depending on reference pointers, or if files are
compressed, etc.
Setting Up Cold Storage
To configure the cold storage schemas, use the administration tool on a client computer.
Log in to the vault in the administration tool as a user that has
administrative permission to update cold storage. Right-click the
Cold Storage Schemas node and then select New
Cold Storage Schema.
The Cold Storage Schema dialog box appears, from
which you can configure how the cold storage operation works.
Assign a Name
Give the new schema a name that makes it easy to identify. If you are
configuring cold storage in a multi-server replicated environment, it is
a recommendation that you include the archive server name in the cold
storage schema name because schemas are server-specific.
Select a Server
Select the archive server to which this cold storage schema applies.
The schema is specific to the selected server. If the vault is
replicated, the menu shows the name of all archive servers that are
replicating the vault. Make sure to select the correct server.
If you are modifying an existing schema, always ensure to select the correct archive server before saving and closing the dialog box.
Cold Storage Method
This option controls what the cold storage operation does with the older file versions. Cold storage can either Delete the versions, which is irreversible, or Move the versions to a location outside the archives for cold storage. The recommendation is to use the Move option because you can recover a moved file if available.
Delete
This option deletes the older file versions from the file archive.
After deletion, you cannot retrieve those versions.
A file archive has six versions of a file.
the three oldest versions of this file.
The physical versions 1, 2 and 3 are deleted from the file archive and are no longer available. This leaves versions 4, 5 and 6 still in the archive folder.
Move
This option moves the older file versions from the file archive to a
local folder outside the archives. From there, it is possible to place
the moved files on removable media such as another hard disk drive, a
tape backup or a network location. In other words, the moved versions
become cold stored and are no longer stored in the
active online archive folders. The recommendation is to use
this option when configuring cold storage.
Consider the following example.
A file archive has six versions of a file.
You run a cold storage operation that moves the three oldest versions.
Versions 1, 2 and 3 are moved from the file archive into the cold storage folder. Versions 4, 5 and 6 remain in the archive folder.
Output Path For Moved Files
When cold storage moves older file versions, the operation places them according to an output path you define in the schema by entering a folder path and a media name. The complete path can contain dynamic values such as the year or date that change depending on when the cold storage schema runs.
Considerations about the output path:
In the ideal case, the output path is a locally attached drive to the archive server where the cold storage schema runs.
If you want to output to a network share, use UNC formatted paths. Cold storage does not support network drive mappings because the archive server service cannot access them. See section 11 for more information about this.
The archive server service must have read and write permission to the output path that is defined in the cold store schema. Both to create new folders and to create or copy new files. In the default installation, the archive server service under the System account, which normally has sufficient permissions to access local drives. If cold storing to a UNC network share, it is a good practice to change the logon account for the archive server service to use a domain account with access to the share. To run the service, the logon user must also have local administrative permissions.
It is extremely important to ensure that the hard disk drive or storage location for the output path has sufficient free space to store the cold stored versions. Confirm this before configuring the cold store schema because running out of disk space could lead to failure to move versions and in worse cases, to become lost.
Folder
The folder field defines the parent output path under which
each cold store media folder is created later. The output path should
contain the drive letter (or the UNC path if using a network share). You
can add dynamic values by clicking folders
for the cold stored versions under the main folder.
Media name
The media name defines the subfolder to which the cold stored
archives are moved. It should be a single folder name (without drive
letter). You can add dynamic values by clicking into the media folder, and then creates a folder with the
archive ID and moves the cold stored versions into the folder.
Versions
The Versions group specifies the number of versions to cold store
(delete or move). The specifications apply to all files under the
specified vault folders that are part of the schema.
Number of versions to keep per archive
In this field, enter a positive version number one or higher.
The number specified is the number of versions to keep in each file archive, counting backwards from the latest version of each processed file.
The number of physical versions stored in the file archive folder, is irrelevant. There may be fewer physical versions. In cases where the physical differences between two versions are the same, the archive server stores a version pointer to the previous version. With a replicated archive folder, it is possible that only some of the total number of versions are replicated.
It is not possible to cold store the latest (topmost) version of a file.
Consider the following example.
This text file has eight versions in the file vault.
, 5 and 8 are identical to the previous version and instead of storing the physical file as a file; the index.xml file contains a reference pointer to the previous matching version. In other words, version 8 has the same content as version 7 and therefore references version 7 (ref=”7”).
The cold storage schema configuration keeps six versions per file.
When the cold storage schema runs, the operation cold stores any version older than the six most recent versions. Versions 1 and 2 become cold stored (eight versions minus six to keep means that the two oldest versions are cold stored).
and 4 of this file are also cold stored. (ten versions minus six versions to keep, means that the four oldest versions are now cold stored).
shows four archived versions.
The cold store output location now contains the four moved versions.
Never move versions with revisions to cold storage
When this option is active, the cold store process skips any version
that has a SOLIDWORKS PDM revision or a label that
links explicitly to the version.
Normally, you want to get those versions that have revisions. Therefore, it is best to activate this option always.
Consider the following example.
A file has 12 versions in the vault.
The cold storage schema configuration keeps the six most recent versions and the Never move versions with revisions to cold storage option is active.
through 6 (12 versions minus six versions to keep means that the six oldest versions become cold stored). However, version 4 has a revision (A) and version 6 has a label (“Keep for prototype”).
Folders
In this area, add the file vault folders that contain files to
process with this cold storage schema. This also processes all
subfolders within the selected folders. It is not possible to exclude a
particular subfolder. All file versions older than the versions to
keep specification become cold stored in these folders.
Schema Interval
This option defines an interval schedule for when this cold storage
schema runs.
You can select from a list of predefined interval strings.
You can also specify a custom interval by selecting the User defined schedule option.
The interval string consists of three parts in the form: minute hour weekday. You can use an asterisk (*) character as a wildcard and a minus (-) character for a range.
Minute: Defines at what minute of the hour the schema runs. The acceptable values are 0 (on the hour) to 59.
Hour: Defines at what hour of the day the schema runs. The acceptable values are 0 (for midnight) to 23 (11pm).
Weekday: Defines on what day of the week the schema runs. The acceptable values are 1 (Monday) to 7 (Sunday).
Examples:
0 18 6 The schema runs every Saturday (6) at 6 pm (18) on the hour (0)
0 23 1-5 The schema runs every Monday (1) through Friday (5) at 11pm (23) on the hour
30 20 * The schema runs every day (*) at 8.30pm
Notes
The interval defines the time at which cold storage operation starts. You only need to define the start time once. It is best to not run the schema too frequently.
When the cold store operation starts, all file archives within the defined vault folders are processed, and cold storage runs until the last archive folder is processed.
Consider performing the cold storage operation no more than once or twice a week, and at most once per day.
Avoid starting the operation at midnight and 3:00 am because other scheduled operations often run at those times.
The start time in the interval uses the local time of the archive.
If you want to keep the cold storage schema, but not run it, you can define the interval value as off.
What Happens During the Cold Storage Process
A cold storage operation consists of the following four basic steps:
The following example shows the detail of what happens on the archive server and in the database when a file is cold stored.
A cold storage schema specifies to keep the six most recent versions and to move older versions to a cold storage folder.
value of 4040 in the database. The archive folder storing the versions is 00000FC8.
The schema runs at the defined interval. The archive server contacts the SQL server and gets a list of files and their versions from the vault database to process.
and version numbers of the files to process are added to the ColdStorage table. While in process on the archive server, the InProgress value is 1 (true) to indicate that the files are being cold stored.
The list of files (to process) is written to a temporary work log called with the name ColdStorageTransaction.log that exists in the ..\0 folder in the vault archive. This file only exists while the cold storage process is running. When the process is complete, the file is deleted. If the archive server service restarts during a cold storage operation, the cold storage process resumes based on the current progress in the ColdStorageTransaction.log file.
The archive server service then continues processing all entries in that log until complete.
within the media folder. This file contains the name and path of the cold storage media. This helps to identify the media folder at a later point when it has moved to remote media.
(matching the DocumentID 4040).
file is updated in the original file archive folder with a status=“archived” entry for the cold stored versions. This indicates that these versions are no longer available in the file archive folder. Be aware that the archived status also shows for cold stored versions that are deleted instead of moved.
After processing all entries in the ColdStorageTransaction.log file, the archive server contacts the SQL server and updates the vault database with the result. The process then deletes the log file.
In the ColdStorage table of the vault database, for each successfully cold stored version, the InProcess value displays 0 (false) and the Completed value displays the time that the cold storage process completed. Note that timestamps in the database are always in UTC format. The MediaID value is a reference to the ColdStorageMedia table, which contains the media and server information. The StoreAction value of 0 means that the versions were moved. A value of 1 means that the versions were deleted.
The archive server log adds an entry each time a cold storage schema runs and lists how many items (versions) were processed.
How Do I know If a File Version Is Cold Stored?
Individual Files
In the file vault, you can see which versions of a file are cold
stored from the Get Version menu. All cold stored
versions appear in the Versions in Cold Storage
submenu.
The file history also shows an entry for each cold stored version
with details about the server and media folder to which it is cold
stored.
Files With References
If the attached version of a referenced file is cold stored, the
Contains tab displays a warning that the version is in
cold storage.
The Get version dialog box also shows a warning if
the get operation tries to retrieve a cold stored version.
If cold storage deleted the referenced file version, it is not possible to cache that version and you have to get a more recent version instead. If cold storage moved the requested version, you must recover the version before it can be cached on the client computer.
List All Files That Were Cold Stored
Refer to the SOLIDWORKS Knowledge Base article QA00000104971
for a report file that you can use to list file versions that are cold
stored in a vault.
Cold Storage in a Replicated Environment
Cold storage schemas are specific to an archive server. In a
replicated environment, you select which archive server to which the
cold storage schema applies. You need to define one cold storage schema
per server. To help identify which schema belongs to which server, it is
a good practice to include the server name in the cold storage schema
name.
For the servers that replicate the version, but do not cold store it, you can retrieve the version to the local vault view from a client computer that is attached to that server.
If a version is cold stored before replication to another server, it cannot be replicated. Scheduled replication excludes cold stored versions. On-demand replication opens the Get from cold storage dialog box from which you can restore the version on the remote server for subsequent replication.
Consider the following example.
A file that has five versions is replicated between two servers.
A cold storage schema keeps three versions and moves older versions to cold storage on the second server.
and 2 (five versions minus three versions to keep means that the two oldest versions will be cold stored). The history shows the archive server on which the version is cold stored.
and 2 cold stored.
menu shows the two versions as cold stored because the list shows the global cold storage information about the file versions and cannot differentiate the server to which the client computer is attached.
dialog box.
Restoring Files From Cold Storage
Normally, a file version in cold storage would no longer be required. However, if the cold store media folder is available, a user with administrative permissions can use a built-in method to recover a cold stored version.
Restoring a Moved Version
.
menu or the Get option in the file history, select the cold stored version to restore.
dialog box shows that the requested file version is cold stored and displays details about the server and media folder name to which the version is cold stored (moved).
On the archive server where the file is cold stored, an administrator needs to copy the media name folder back to the archive server restore path from the cold storage media (if it was moved to an external media).
dialog box, click Restore. This action copies the cold stored version back to the file archive folder.
status is removed from the index.xml entry for that version.
The restored version is retrieved to the local cache on the client computer.
If the cold storage schema is still active, the next time the schema runs, the restored version will likely be cold stored again.
Restoring a Deleted Version
It is not possible to restore a version that is deleted (instead of
moved) by a cold storage schema because no physical copy of that version
remains. The history entry for the cold stored version shows that the
version was deleted.
Using the Get version command on a deleted version
still opens the Get From Cold Storage dialog box,
however you can recognize a deleted cold storage version by the empty
media name and restore path. Clicking Restore displays
an Error accessing cold stored file warning.
If you must recover the deleted version, and if you have a backup of the file archive folder from before deletion by the cold storage schema, or if the deleted version is replicated to another server, you can use the manual restore instructions in the next section to restore the version.
Manually Restoring a Cold Stored Version
Use the manual method only if the built-in restore option does not work. Make sure that you back up the database before making any modifications in the database.
For instructions about how to manually restore a version in cold storage, see the SOLIDWORKS Knowledge Base article QA00000112306.
Cold Storing To Network Shares
Cold storage schemas support the use of network shares if you specify
the path in the UNC format (\\SERVER\SHARE). The archive server service
must run under an administrative domain user account with full access to
the UNC share. Cold storage does not support the use of a mapped network
drive letter for the cold storage path.
Troubleshooting Cold Storage
The following tips are useful when troubleshooting cold storage problems.
) is running and can connect to the archive server to which the schema applies.
The database server service is responsible for announcing schema changes. However, if the service cannot communicate with the archive server, the change does not take effect.
The Windows application log shows an event if the service connects to each archive server on startup.If the database server service succeeds with updating the archive server, a log entry in the archive server log shows Reloading cold storage schedules and includes a timestamp matching the time of the schema update.
Restarting the archive server service ensures that the latest cold storage schemas are loaded.
Review the archive server log for errors that relate to cold storage. If cold storage runs correctly, you see an entry stating Cold storage operation complete with the number of items processed.
Ensure that sufficient free space exists in the output path to hold the moved versions.
Make sure that the archive server service has access to the schema output path. If using a UNC network share, make sure that the archive server service runs under an administrative account with permission to read and write to the share.
Be aware that versions with revisions or labels are likely excluded and are not cold stored if the Never move versions with revisions to cold storage option is active for the schema.
We hope that you find this document informational and useful and request that you leave a brief feedback about the topics that you want us to cover in the next revision of this document. Click here for a complete list of SolidPractices documents available from DS SOLIDWORKS Corp.
