Getting started with the Supersede utility
- Matt Siebert
The Supersede utility is distributed as a single executable file (Supersede.exe). No installation is required, however, it does require the .NET 6 runtime to be installed. See deploying the Supersede utility for more information.
A default configuration file (Supersede.json) is also distributed along with the executable file. This file is optional, however, it must be placed in the same folder as the executable file.
You can also configure supersede behaviour for specific folders by placing a similar configuration file in the desired folder.
These configuration files use the JSON format.
Move superseded files
Consider the following files and folders:
📁P:\Projects
📁P123
📁Exports
📄A001 - Title Sheet (1).pdf
📄A001 - Title Sheet (2).pdf
📄A002 - Site Plan (1).pdf
📄A002 - Site Plan (2).pdf
This folder contains PDF files exported from two sheets (A001 - Title Sheet and A002 - Site Plan) and there are two revisions of each sheet.
We can use the Supersede utility to move the earlier revisions to an Archived folder by configuring the following rule in a .supersede-config file in the 📁P:\Projects\P123 folder:
{
"Rules": [
{
"Pattern": "(?<SheetNumber>.+) - (?<SheetName>.+) \\((?<Revision>.+)\\)",
"Extensions": [ ".pdf" ],
"Supersede": {
"Enabled": true,
"MatchFields": ["SheetNumber"],
"Mode": "Move",
"Path": "Archived"
}
}
]
}This rule could also be configured in the Supersede.json configuration file located in the same folder as the Supersede.exe file, however, the Rules object would need to be placed inside a Supersede object.
See configuring the Supersede utility and folder specific configuration for more information.
This rule specifies a regular expression pattern to match .pdf files. For each file that is matched to this pattern, the Supersede utility will then look for other related .pdf files in the same folder that also match this pattern and share the same SheetNumber. Older revisions of the related files will then be moved to the 📁Archived folder.
Running the command
For this example, we can run the Supersede utility using the Command Prompt in Windows to run the following command line:
Supersede.exe Folder P:\Projects\P123\Exports
The revision 1 files have now been moved into the new 📁Exports\Archived folder:
📁P:\Projects
📁P123
📁Exports
📄A001 - Title Sheet (2).pdf
📄A002 - Site Plan (2).pdf
📁Archived
📄A001 - Title Sheet (1).pdf
📄A002 - Site Plan (1).pdf
Copy files to a 📁Current folder
Another common approach is to export files directly to a location where they will remain even after they have been superseded, and use the Supersede utility to maintain a separate current folder that contains the current revision of each file.
In this scenario, we might have the following files and folders:
📁P:\Projects
📁P123
📁Exports
📁2022-02-03
📄A001 - Title Sheet (2).pdf
📄A002 - Site Plan (2).pdf
📁Current
📄A001 - Title Sheet (1).pdf
📄A002 - Site Plan (1).pdf
New files are exported to a date-specific folder within 📁Exports. Following an export, we want to run the Supersede utility to copy the new files into the 📁Current folder and then remove older revisions of the same file from 📁Current.
We can modify the rule from the previous example to first copy matched files to 📁Current and then delete superseded files:
{
"Rules": [
{
"Pattern": "(?<SheetNumber>.+) - (?<SheetName>.+) \\((?<Revision>.+)\\)",
"Extensions": [ ".pdf" ],
"Copy": {
"Enabled": true,
"Path": "..\\Current"
},
"Supersede": {
"Enabled": true,
"MatchFields": ["SheetNumber"],
"Mode": "Delete"
}
}
]
}As noted in the previous example, this rule could also be configured in the global Supersede.json configuration file by nesting the Rules object inside a Supersede object.
See configuring the Supersede utility and folder specific configuration for more information.
As before, we can run the Supersede utility using the Command Prompt with the following command line:
The revision 2 files have now been copied into the 📁Current folder and the revision 1 files have been deleted:
📁P:\Projects
📁P123
📁Exports
📁2022-02-03
📄A001 - Title Sheet (2).pdf
📄A002 - Site Plan (2).pdf
📁Current
📄A001 - Title Sheet (2).pdf
📄A002 - Site Plan (2).pdf
Instead of deleting the superseded files, you could configure the rule to move them to a 📁..\Superseded folder.
Don’t forget to escape backslash characters in paths.
Working with multiple rules
You can specify multiple Extensions in the configuration to match different types of files with the same rule:
You can also configure multiple rules to match different patterns with different copy or supersede configuration:
If your rules share the same behaviour then you can configure default (non-rule-specific) copy and supersede settings:
Overriding configuration for a specific folder
The Supersede utility supports folder specific configuration in .supersede-config files. The utility will combine all of the relevant configuration files for each file it processes.
This allows you to specify some global default behaviour and rules in the global Supersede.json configuration file, and then in a folder specific .supersede-config file you can simply add or override the specific parts that are different for that folder.
For example, consider the following global Supersede.json configuration:
If we have a special project where we don’t want to keep superseded files (because they will remain in their initial location anyway), then we could use a folder specific .supersede-config file with the following configuration:
Note that in order to override configuration for a specific rule, you need to specify the same Pattern as defined in the global configuration file: