# Smart Filter
## Overview
One challenge when comparing backups of a certain Project is managing project items whose values change for in every backup or that aren't necessary to track changes for across backups.
For example, tag values such as timer accumulators and counters may change every backup, but these changes aren't significant enough to warrant a backup being counted as Modified. The Ignore Tag Value Changes toggle in the backup View Options allows for you to hide all tags that only have value changes, but is only applied in the backup viewer after the backup has completed.
With Copia's Smart Filter feature, you can apply various rules to your project to refine your backups to only keep track of changes that are relevant to you. Currently this feature is limited to **Rockwell projects only**.
## Configuring the Smart Filter
The Smart Filter configuration file is located at `.copia/smart-filter.yaml` in your Source Control repository. To access the configuration file for a specific project, you can click *Manage Smart Filter* in the popup menu. Please note this is currently only available for Rockwell projects:
Before enabling the Smart Filter, you'll first need to declare your configurations. Choose the *Add Config to Enable Smart Filter* link.
This will take you either to the existing Smart Filter configuration file for this project or prompt you to create a new one depending on if there's already a configuration in the repo associated with your project.
The Smart Filter configuration file is a YAML file that applies a set of rules to the entire repo. **It must live in the default branch of your repo (this is usually *****master***** or *****main*****)**. An example configuration file is as follows:
```yaml
# Smart Filter Configuration
# For more information about Smart Filter, see the documentation: https://docs.copia.io/docs/devicelink/advanced/smart-filter
version: 1
projects:
# All .ACD files, regardless of extension capitalization, within any directory
'**/*.[aA][cC][dD]':
type: acd
exclude:
# Ignore tag and force value changes by default
- /RSLogix5000Content//Tags/Tag/Data
- /RSLogix5000Content//Tags/Tag/ForceData
# Ignore all module changes by default
- /RSLogix5000Content//Modules/Module
# Ignore changes to EncodedData (Source Protected Items) by default
- /RSLogix5000Content//EncodedData/text()
# Ignore Tag metadata that cannot be rendered
- /RSLogix5000Content//Tags/Tag/ConsumeInfo
include:
# Example: Watch for value changes to the X_Pos Controller tag
# - /RSLogix5000Content/Controller/Tags/Tag[@Name="X_Pos"]
```
The `version` field specifies which version of the Smart Filter config you are using (currently, it should always be `version: 1`).\
\
The `projects` field is a map of file globs—expressed relative to the repository root—to a set of Smart Filter rules. You can refer to for a detailed understanding of glob syntax. If the glob matches the path to your project in the repository, the corresponding Smart Filter rules will be applied during a backup. In cases where multiple project globs correspond to your file, the project rule appearing last in the Smart Filter configuration file will take precedence.\
\
Copia project globs also support recursive patterns using the \`\*\*\` operator. For instance, the pattern `my_directory/**/*.ACD` will match any .ACD file in `my_directory` or any of its subdirectories. The pattern `my_directory/*.ACD` restricts the search to .ACD files specifically within `my_directory` itself.
For each project, there is a `type` field which specifies what kind of project this configuration will be applied to. Currently, only `acd` for Rockwell projects is supported.
### ACD Projects
Projects of type `acd` are Rockwell Logix Designer projects in the ACD file format. The Smart Filter will remove certain attributes such as the `ExportDate`, `Owner`, `LastModifiedDate`, and `ProjectCreationDate` by default, since these are known to change with every backup.
ACD projects have two configuration options `exclude` and `include`. Both are a list of XPath queries that reference the internal L5X structure of an ACD file. The XPaths in the `exclude` filter will hide any matching elements from the XPath query from the backup view and the XPaths in the `include` filter will force those elements to remain in the backup. The `include` filter always takes precedence over the `exclude` filter.
The default Rockwell Smart Filter configuration file will ignore tag value changes and module changes. It can be overridden to include a specific tag value by simply adding a line to the `include` list. For example, to watch for value changes to a Controller tag named `X_Pos`, you can add the following line to the `include` list:
```yaml
include:
- /RSLogix5000Content/Controller/Tags/Tag[@Name="X_Pos"]
```
#### **Common XPath Queries**
| XPath Rule | Meaning |
| --------------------------------------------------------------- | -------------------------------------------------------------- |
| `/RSLogix5000Content/Controller/Tags/Tag[@Name="TagName"]` | Select a Controller tag with the name TagName |
| `/RSLogix5000Content//Tags/Tag/Data` | Select all Tag data |
| `/RSLogix5000Content//Tags/Tag[starts-with(@Name, 'ai_')]/Data` | Select all Tag data for Tags with names that start with *ai\_* |
| `/RSLogix5000Content//Modules/Module` | Select all Modules |
| `/RSLogix5000Content//Comment` | Select all Comments |
| `/RSLogix5000Content/Controller//EncodedData` | Select all Source-Protected content |
### Migrating From the Old varignore.yaml Format
Previously, Copia supported the Smart Filter through the a varignore.yaml file present in the root of repositories. In most cases, migrating from the previous format will be very simple. Any tags that were manually specified in the varignore file will need to be converted to XPaths and added to the `exclude` section of your Smart Filter.
Below is a list of common varignore entries and their XPath equivalents:
| Varignore Entry | XPath Equivalent | Description |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| Controller.Tags.TagName | //RSLogix5000Content/Controller/Tags/Tag\[@Name="TagName"]/Data | Ignores a controller tag named `TagName.` |
| Controller.Tags.\* | //RSLogix5000Content/Controller/Tags/Tag/Data | Ignores all controller tags. |
| Controller.Tags.\*\_Pos | //RSLogix5000Content/Controller/Tags/Tag\[ends-with(@Name, '\_Pos')]/Data | Ignore all controller tags with names ending in `_Pos`. |
| Controller.Programs.ProgramName.Tags.TagName | //RSLogix5000Content/Controller/Programs/Program\[@Name="ProgramName"]/Tags/Tag\[@Name="TagName"]/Data | Ignores a tag named `TagName` in the program named `ProgramName`. |
| Controller.Programs.\*.Tags.\* | //RSLogix5000Content/Controller/Programs/Program/Tags/Tag/Data | Ignores all program tags. |
## Change Detection
The config for the Smart Filter will also impact whether the backup reports differences found in the Project. Any tags that are filtered from the diff view will also be filtered when checking for differences between the Project in the repository and the Project on the Device.
