File Rules

Overview

File Rules provide administrators with an easy mechanism for specifying files and/or directories that should be included or excluded in a migration based on several possible criteria:

• Location
• File type
• Date last modified
• Size

File Rules can also be used to remap files from a source location (e.g. C:\Project Files to <My Documents>\Project Files).

Note
File rules override the selection of what should be extracted. For instance, if you select that all PowerPoint files should be extracted by selecting Applications | Microsoft Office | PowerPoint | PowerPoint Data Files and then define a file rule to exclude all *.pptx files larger than 10 MB, only .pptx files smaller than 10 MB will be included in the extraction.

See Application Migration with Rules for an example of how to use File and Registry Rules to migrate settings for an application.

How File Rules Work

Every file that Migration Manager finds during an extraction is evaluated against the defined File Rules with the order of the rules being significant. File Rules override the selections made in the content tree (see Selecting Content to Extract) and can be used to limit the scope of the data extracted.

Include/Exclude Rules

A File Rule can define which files to include or exclude in an extraction.

An include rule is used to include files of a specific type or from a specific location (e.g. include all *.abc files in the user’s My Documents folder).

An exclude rule is usually used together with an include rule to limit the scope of the include rule. For example, to include all files from the C:\Project Data directory except for any *.wav files, define an include rule to include all files from C:\Project Data followed by an exclude rule for any *.wav files in the same directory.

Exclude rules can also be used by themselves. For example, to exclude all *.mp3 files from the user’s My Documents folder to avoid extracting large amounts of music files.

The order of rule definitions is important, see File Rules Evaluation Order for more detail.

File Rule Criteria

File Rules can evaluate files based on the following criteria:

• Location (e.g. the user’s My Documents folder)
• File type (e.g. *.mp3)
• Last modified date (before or after a specific date)
• File size (greater or smaller than a specific size)

Note
It’s possible to specify multiple file types in a single file rule by separating each file extension by a ; e.g. *.mp3;*.wav;*.wma.

It’s not necessary to use all possible criteria in a rule, but at a minimum a Source Path must be defined for inclusion or exclusion.

Note
When defining the Source Path for the rule, define if the rule applies to any sub-directories by checking or unchecking the Include Subdirectories check box.

File Rule Evaluation Order

The order in which File Rules are defined is important as this impacts the effect of the defined rules (See Changing File Rule Evaluation Order for information how to change the order of File Rules). When two (or more) mutually exclusive rules match a file, the first defined rule takes precedence.

Note
If content has been selected (e.g. *.docx files) in the “Select for Extraction” tab, this functions as an implicit include File Rule that can be overridden by an explicit exclude rule. You can, for instance, select *.docx files in the content tree and define an exclude rule for *.docx files larger than 50 MB. The result is only *.docx files smaller than 50 MB are included in the extraction.

As an example to illustrate this, assume that the following 2 rules are defined (in this order):

1. Include all *.xlsx files in C:\Project Data
2. Exclude all files from C:\Project Data

With this order, all *.xlsx from C:\Project Data will be included in the extraction, but all other files in C:\Project Data will be excluded.

If the order of the rules is reversed to:

1. Exclude all files from C:\Project Data
2. Include all *.xlsx files in C:\Project Data

This will have the effect of the exclude rule taking precedence and no files from C:\Project Data will be included at all.

File Rule Path Tokens

User specific paths differ between users and can change if migrating to new usernames. To support path changes, Migration Manager supports the use of tokens when defining file rules:

Token	Description	Examples
%DESKTOP%	The Desktop “directory”	C:\Users\hdowd\Desktop
%USERDESKTOP%	The Desktop “directory”	C:\Users\hdowd\Desktop
%USERNAME%	The user name of the user that is selected for extraction.	Hdowd
%MYDOCUMENTS%	The default document storage folder	C:\Users\hdowd\Documents
%USERDOCUMENTS%	The default document storage folder	C:\Users\hdowd\Documents
%MYMUSIC%	The default music storage folder	C:\Users\hdowd\Music
%USERMUSIC%	The default music storage folder	C:\Users\hdowd\Music
%MYPICTURES%	The default pictures storage folder	C:\Users\hdowd\Pictures
%USERPICTURES%	The default pictures storage folder	C:\Users\hdowd\Pictures
%MYVIDEOS%	The default videos storage folder	C:\Users\hdowd\Videos
%USERVIDEOS%	The default videos storage folder	C:\Users\hdowd\Videos
%WINDOWS%	The Windows directory	C:\Windows
%SYSTEM%	The 32-bit System32 directory	C:\Windows\System32 [on 32-bit systems] C:\Windows\SysWOW64 [on 64-bit systems]
%SYSTEM64%	The 64-bit System32 directory Note: Only valid on 64-bit systems.	C:\Windows\System32
%SYSTEMDRIVE%	The system drive letter	C:\
%PROGRAMFILES32%	The 32-bit Program Files Directory	C:\Program Files [on 32-bit systems] C:\Program Files (x86) [on 64-bit systems]
%PROGRAMFILES64%	The 64-bit Program Files Directory Note: Only valid on 64-bit systems.	C:\Program Files
%FIXEDDISKS%	All local fixed drives (can only be used in the source path of a file rule)	n/a
%HOMEDRIVE%	Redirect files to a user's local or network home drive (used only in the Destination Path of a file rule)	n/a
%USERPROFILE%	The user's profile folder	C:\Users\hdowd
%SYSTEMTEMPLATES%	The folder where shared templates are stored	C:\ProgramData\Microsoft\Windows\Templates
%USERROAMINGAPPDATA%	The file system directory that serves as a common repository for application-specific data.	C:\Users\hdowd\AppData\Roaming
%USERRECENTFILES%	The file system directory that contains shortcuts to the user's most recently used documents.	C:\Users\hdowd\AppData\Roaming\Microsoft\Windows\Recent
%SYSTEMALLUSERS%	The root directory for the profile folders that are shared by all users.	C:\Users\Public
%USERLOCALAPPDATA%	The file system directory that serves as a data repository for local (nonroaming) applications	C:\Users\hdowd\AppData\Local
%SYSTEMDESKTOP%	The file system directory that contains files and folders that appear on the desktop for all users	C:\Users\Public\Desktop
%USERTEMPLATES%	The file system directory that serves as a common repository for document templates	C:\Users\hdowd\AppData\Roaming\Microsoft\Windows\Templates
%USERPROGRAMS%	The file system directory that contains the user's program groups	C:\Users\hdowd\AppData\Roaming\Microsoft\Windows\Start Menu\Programs
%USERCOOKIES%	The file system directory that serves as a common repository for Internet cookies	C:\Users\hdowd\AppData\Roaming\Microsoft\Windows\Cookies
%SYSTEMAPPDATA%	The file system directory that contains application data for all users	C:\ProgramData
%USERHISTORY%	The file system directory that serves as a common repository for Internet history items	C:\Users\hdowd\AppData\Local\Microsoft\Windows\History
%USERFAVORITES%	The file system directory that serves as a common repository for the user's favorite items	C:\Users\hdowd\Favorites
%USERSTARTMENU%	The file system directory that contains Start menu items	C:\Users\hdowd\AppData\Roaming\Microsoft\Windows\Start Menu

For instance, to define a rule to exclude all *.mp3 files in the user’s profile folder, the location can be defined as %USERPROFILE%\*.mp3.

Using tokens as opposed to hard-coding paths make File Rules more robust and reusable for different versions of Windows (see Importing and Exporting Rules for more information about reusing rules).

Note
The 64-bit path tokens (%SYSTEM64% and %PROGRAMFILES64%) are only valid on 64-bit systems. On 32-bit systems these path tokens don't have a valid value and instead expand into an empty string that will not match any files when the tokens are used in file rules.

Using Wild Cards in File Rules

File Rules support the use of the following wild card characters:

• ? – matches a single character/digit
• * – matches any number of characters/digits

Examples:

File or Folder Specification	Include Subdirectories	Matches
C:\Readme.*	Yes	Readme.doc, Readme.rtf, Readme.txt, etc. anywhere on the C: drive (since subdirectories are included).
C:\Read*.doc	Yes	Readme.doc. Readthis.doc, etc. anywhere on the C: drive.
C:\Readme.???	Yes	Readme.doc, Readme.wri, Readme.txt, etc. anywhere on the C: drive. Will not include the files Readme.html, Readme.jpeg, etc.
C:\Read??.txt	Yes	Readme.txt anywhere on the C: drive. Will not find Readthis.txt.

Moving Files on the Target System

The final major feature of File Rules is the ability to move files when they are injected to the target system. For example, this feature can move user files located outside the user’s profile folder on the source system into the user’s profile folder on the target system.

A file rule could be defined as:

Include / Exclude	Source Path	Include Subdirectories	Destination Path	Preserve Subdirectories
INCLUDE	C:\*.doc;*.dot;*.docx;*.dotx	Yes	%MYDOCUMENTS%\Word Documents	No

The result of this rule would be to move all *.doc, *.dot, *.docx and *.dotx files found outside of the user’s My Documents folder and place them in a directory named Word Documents in the user’s My Documents folder on the target system. When injecting multiple users, any files migrated from a common location to a user profile location, a copy of the file will be injected to each user's profile location.

Source System	Target System
C:\Project Data\Project Overview.doc	C:\Users\hdowd\Documents\Word Documents\Project Overview.doc C:\Users\pbowman\Documents\Word Documents\Project Overview.doc
C:\Project Data\Reports\Q1 2001 Progress.docx	C:\Users\hdowd\Documents\Word Documents\Q1 2001 Progress.docx C:\Users\pbowman\Documents\Word Documents\Q1 2001 Progress.docx
C:\Users\hdowd\Desktop\Progress Report.docx	C:\Users\hdowd\Documents\Word Documents\Progress Report.docx

Note
When using hardlinks and redirecting files from a common location to multiple (user specific) locations, such as from C:\Project Data to %MYDOCUMENTS%\Word Documents, all of the injected files will be hardlinked together. Meaning, if one user edits the file under their profile folder, all users on the computer will see the same edits to the file in their profile folders.

Below, the definition of the rule is changed to preserve the subdirectory structure:

Include / Exclude	Source Path	Include Subdirectories	Destination Path	Preserve Subdirectories
INCLUDE	C:\*.doc;*.dot;*.docx;*.dotx	Yes	%MYDOCUMENTS%\Word Documents	Yes

The result is that the files are placed like this on the target system:

Source System	Target System
C:\Project Data\Project Overview.doc	C:\Users\hdowd\Documents\Word Documents\Project Data\Project Overview.doc C:\Users\pbowman\Documents\Word Documents\Project Data\Project Overview.doc
C:\Project Data\Reports\Q1 2001 Progress.docx	C:\Users\hdowd\Documents\Word Documents\Project Data\Reports\Q1 2001 Progress.docx C:\Users\pbowman\Documents\Word Documents\Project Data\Reports\Q1 2001 Progress.docx
C:\Users\hdowd\Desktop\Progress Report.docx	C:\Users\hdowd\Documents\Users\hdowd\Desktop\Progress Report.docx

Note how the directory structure relative to the source location (C:\ in this particular case) is preserved when the files are moved according to the rule.

Files that Match Multiple File Rules

If a file is impacted by multiple File Rules, only the first rule (in order of evaluation) is used for the file and the file is only migrated once.

Defining File Rules

File Rules are defined through the Migration Manager user interface by going to Edit | File Rules or by clicking the File Rules button in the toolbar:

The main File Rules dialog displays the currently defined File Rules:

There are 4 different operations that can be performed in this dialog:

• Add a new File Rule
• Edit an existing File Rule
• Delete a File Rule
• Change the priority of a File Rule

Adding New File Rules

The steps below describe how to add a file rule to include all *.wpd and *.wpt files from anywhere on the user’s system:

• Click the “Add Rule” button in the File Rules dialog
• Enter the definition for the rule in the File Rule dialog:

• Click OK to add the new rule to the list of rules:

• Click OK again to save the list of File Rules

Editing File Rules

Follow these steps to modify the rule created in the previous section so that it only includes files that have been modified since June 15, 2011 and that are smaller than 100 MB:

• Select the rule in the File Rules dialog and click the Edit Rule button
• Check the “Limit by date” checkbox and enter 6/15/2011 in the date field:

• Check the “Limit by file size” check box, enter 100 as the size and select MB as the size unit in the drop-down:

• Click OK to save the changes and return to the File Rules dialog:

• Click OK again to save the list of File Rules

Deleting File Rules

To delete an existing File Rule, follow these steps:

• Select the rule in the File Rules dialog and click the Delete Rule button
• Click OK in the File Rules dialog to save the change to the File Rules

Changing File Rule Evaluation Order

As discussed in File Rule Evaluation Order, the order in which File Rules are defined determines the effect the rules have on what files get extracted. To change the order of the rules, follow these steps:

• Select the rule that should be moved in the File Rules dialog
• Click the “up” button to move the selected rule up in the order of evaluation and the “down” button to move it down in the order of evaluation:

File Rule Editor

This section describes the individual fields in the File Rule editor.

Include or Exclude

The first selection in the dialog is to determine if the rule includes or excludes files:

Source Path

This field defines the location to which the rule applies. See How File Rules Work for more information on how locations and file types can be defined.

The “Include Subdirectories” check box determines whether the rule applies to any subdirectories below the Source Path. For instance, specifying a location like C:\*.doc without including subdirectories will only match *.doc files in the root of the C drive. When subdirectories are included, the rule matches *.doc files anywhere on the C drive.

Note
Multiple file types can be specified by separating each file type with a semicolon (‘;’) like this: *.doc;*.docx;*.dot;*.dotx.

Note
When using the “Browse…” button to select a source folder, Migration Manager will offer to use the path token that best matches the selected folder (if any). Using path tokens make file rules more generically useful for different users and operating systems. See File Rule Path Tokens for more information.

Date Criteria

A File Rule can limit extraction by the last modified date of a file.

The options for the date comparison are On or before the specified date or On or after the specified date.

Size Criteria

A File Rule can use the size of the file to evaluate the rule. Note that the size unit can be defined in KB, MB or GB.

Similar to the date comparison, the options are Less than or equal to or Greater than or equal to.

Remapping Files

As mentioned in Moving Files on the Target System, File Rules can move files when they are injected on the target system:

To enable this, check the “Remap destination” checkbox and specify the desired destination path and optionally choose to preserve the original subdirectory structuretureture.

Note
The token %FIXEDDISKS% cannot be used in the destination path field. All other tokens described in File Rule Path Tokens can be used.