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. We plan on expanding this feature to other vendor types in the future.

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:

# 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 https://en.wikipedia.org/wiki/Glob_(programming) 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:

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.