Advanced 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. %FixedDisks%\*.xlsx to cloud\Excel Files).

How File Rules Work

Every file that OnRamp finds during an extraction is evaluated against the defined File Rules with the order of the rules being significant.

Built-in File Rules

OnRamp comes with the most common file rules included to allow you to move to the cloud quickly. The files rules that are included transfer all files within common user profile folders.

These file rules may be edited as described in Editing File Rules, or deleted as described in Deleting File Rules.

Include/Exclude Rules

A File Rule can define which files to include or exclude from the source machine.

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, create the following rules:

  1. Exclude C:\Project Data\*.wav
  2. Include C:\Project Data\*.*

The order of rule definitions is important, see File Rule 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 (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 the Description and 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 subdirectories 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. When two (or more) mutually exclusive rules match a file, the first defined rule takes precedence. 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 Source Path Tokens

Paths differ on various versions of Windows (e.g. the use of C:\Documents and Settings in Windows XP vs. C:\Users in Windows Vista and later) as well as for each user. To support moving any user from any version of windows, OnRamp supports the use of tokens when defining the source path for file rules:

Token Description Examples
%DESKTOP% The Desktop “directory” [XP] C:\Documents and Settings\hdowd\Desktop
[W8] C:\Users\hdowd\Desktop
%USERDESKTOP% The Desktop “directory” [XP] C:\Documents and Settings\hdowd\Desktop
[W8] C:\Users\hdowd\Desktop
%USERNAME% The user name of the user that is selected for extraction. Hdowd
%MYDOCUMENTS% The default document storage folder [XP] C:\Documents and Settings\hdowd\My Documents
[W8] C:\Users\hdowd\Document
%USERDOCUMENTS% The default document storage folder [XP] C:\Documents and Settings\hdowd\My Documents
[W8] C:\Users\hdowd\Documents
%MYMUSIC% The default music storage folder [XP] C:\Documents and Settings\hdowd\My Documents\My Music
[W8] C:\Users\hdowd\Music
%USERMUSIC% The default music storage folder [XP] C:\Documents and Settings\hdowd\My Documents\My Music
[W8] C:\Users\hdowd\Music
%MYPICTURES% The default pictures storage folder [XP] C:\Documents and Settings\hdowd\My Documents\My Pictures
[W8] C:\Users\hdowd\Pictures
%USERPICTURES% The default pictures storage folder [XP] C:\Documents and Settings\hdowd\My Documents\My Pictures
[W8] C:\Users\hdowd\Pictures
%MYVIDEOS% The default videos storage folder [XP] n/a
[W8] C:\Users\hdowd\Videos
%USERVIDEOS% The default videos storage folder [XP] n/a
[W8] 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
%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 [XP] C:\Documents and Settings\hdowd
[W8] C:\Users\hdowd
%SYSTEMTEMPLATES% The folder where shared templates are stored [XP] C:\Documents and Settings\All Users\Templates
[W8] C:\ProgramData\Microsoft\Windows\Templates
%USERROAMINGAPPDATA% The file system directory that serves as a common repository for application-specific data. [XP] C:\Documents and Settings\hdowd\Application Data
[W8] C:\Users\hdowd\AppData\Roaming
%USERRECENTFILES% The file system directory that contains shortcuts to the user's most recently used documents. [XP] C:\Documents and Settings\hdowd\Recent
[W8] C:\Users\hdowd\AppData\Roaming\Microsoft\Windows\Recent
%SYSTEMALLUSERS% The root directory for the profile folders that are shared by all users. [XP] C:\Documents and Settings\All Users
[W8] C:\Users\Public
%USERLOCALAPPDATA% The file system directory that serves as a data repository for local (nonroaming) applications [XP] C:\Documents and Settings\hdowd\Local Settings\Application Data
[W8] C:\Users\hdowd\AppData\Local
%SYSTEMDESKTOP% The file system directory that contains files and folders that appear on the desktop for all users [XP] C:\Documents and Settings\All Users\Desktop
[W8] C:\Users\Public\Desktop
%USERTEMPLATES% The file system directory that serves as a common repository for document templates [XP] C:\Documents and Settings\hdowd\Templates
[W8] C:\Users\hdowd\AppData\Roaming\Micros oft\Windows\Templates
%USERPROGRAMS% The file system directory that contains the user's program groups [XP] C:\Documents and Settings\hdowd\Start Menu\Programs
[W8] C:\Users\hdowd\AppData\Roaming\Micros oft\Windows\Start Menu\Programs
%USERCOOKIES% The file system directory that serves as a common repository for Internet cookies [XP] C:\Documents and Settings\hdowd\Cookies
[W8] C:\Users\hdowd\AppData\Roaming\Micros oft\Windows\Cookies
%SYSTEMAPPDATA% The file system directory that contains application data for all users [XP] C:\Documents and Settings\All Users\Application Data
[W8] C:\ProgramData
%USERHISTORY% The file system directory that serves as a common repository for Internet history items [XP] C:\Documents and Settings\hdowd\Local Settings\History
[W8] 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 [XP] C:\Documents and Settings\hdowd\Favorites
[W8] C:\Users\hdowd\Favorites
%USERSTARTMENU% The file system directory that contains Start menu items [XP] C:\Documents and Settings\hdowd\Start Menu
[W8] C:\Users\hdowd\AppData\Roaming\Microsoft\Windows\Start Menu
%USERCONTACTS% The file system directory that contains the user’s contacts (only on Windows Vista and later) [W8] C:\Users\hdowd\Contacts
%USERSEARCHES% The file system directory that contains the user’s saved searches (only on Windows Vista and later) [W8] C:\Users\hdowd\Searches

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 Automation for information on using different configuration files).

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 in the Cloud

The final major feature of File Rules is the ability to change the location of files when they are transferred to the cloud. For example, this feature can move user files located in multiple locations on the source system into one folder in the cloud. A file rule could be defined as:

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

The result of this rule would be to move all *.doc, *.dot, *.docx and *.dotx files found anywhere on the user's C drive and place them in a directory named Word Documents in the cloud:

Source System Cloud
C:\Project Data\Project Overview.doc cloud\Word Documents\Project Overview.doc
C:\Project Data\Reports\Q1 2001 Progress.docx cloud\Word Documents\Q1 2001 Progress.docx
C:\Documents and Settings\hdowd\My Documents\Progress Report.docx cloud\Word Documents\Progress Report.docx

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 cloud\Word
Documents		 Yes

The result is that the files are placed like this in the cloud:

Source System Cloud
C:\Project Data\Project Overview.doc cloud\Word Documents\Project Data\Project Overview.doc
C:\Project Data\Reports\Q1 2001 Progress.docx cloud\Word Documents\Project Data\Reports\Q1 2001 Progress.docx
C:\Documents and Settings\hdowd\My Documents\Progress Report.docx cloud\Word Documents\Documents and Settings\hdowd\My Documents\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 OnRamp user interface by going to File Migration Rules.

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

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

  • Add a new File Rule
  • Change the File Rule evaluation order
  • Edit an existing File Rule
  • Disable/Enable existing File Rules
  • Delete 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 “New” button in the File Rules dialog

  • Enter a description for the rule

  • Enter the definition for the rule in the File Rule dialog

  • Click "Save" to add the new rule to the list of 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 transferred. 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

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, 2015 and that are smaller than 100 MB:

  • Select the rule in the File Rules dialog
  • Change the “Filter by Date” drop-down to "Later than" and enter 6/15/2015 in the date field

  • Under "Filter by Size", enter 100 as the size and select MB as the size unit in the drop-down

  • Click Save to save the changes and return to the File Rules dialog

Disable/Enable File Rules

Each file rule may be disabled which can aid in testing your configuration, allow running a partial migration, and more. To disable, and re-enable a file rule, follow the steps below.

To Disable:

  • Select an active rule in the File Rules dialog
  • Click the "Disable Rule" button

The rule will stay disabled until re-enabled. This includes subsequent running of the product, or running automated.

To Enable:

  • Select a disabled rule in the File Rules dialog
  • Click the "Enable Rule" button

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

File Rule Editor

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

Description

The description entered for the file rule is what will appear in the list of Current File Rules.

Include or Exclude

This 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, OnRamp 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 Source Path Tokens for more information about path tokens.

Date Criteria

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

The options for the date comparison are None, Equal to, Earlier than or Later than the specified date.

Size Criteria

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

Cloud Location

As mentioned in Moving Files in the Cloud, File Rules can move file locations to a different folder when they are injected in the cloud.

To use this, specify the desired destination path under "Cloud Location" and optionally choose to preserve the original subdirectory structure.