The Paths tab enables you to configure permissions to various paths for specific groups and users. In addition to managing permissions for paths, you an also use the Paths sheet to configure different target accounts or destination paths for a path, or skip a path entirely. CFP will generate a map of the shares present on the source, but you are free to change that sharing to whatever you want on the target, even adding folders to the Permissions tab that are not shared on the source, but you want them shared on the target. Here’s an example of a completed spreadsheet:
In summary, the actions that you can take for each path listed are:
- Leave a path alone. This will cause CFP to use the Users tab to find the “target account” for the email listed in the Source Account column. It will then put the item in the Source Path field in that target account with the permissions specified in the various rows. Note that if there is a Target Owner specified in the Paths tab for a given path, that setting will override any configuration in the Users tab.
- Delete an entire row. This will cause CFP to move the path wherever it would be under it’s parent. Any explicit ACLs will be lost.
- Add a new row. This will cause CFP to move the specified source row item to the target and apply the ACLs added. This is the only time that you should type in the Source Account, Source Owner or Source Path columns. This should be done ONLY when you are retargeting a path or adding permissions that did not exist on the source. Depending on what the source system is for your job, you may not have Source Account or Source Owner listed. You do not need to add these columns if they are not already there.
- Add a Target Owner and Target Path. Do this to retarget the path to a different location.
- Add or remove individual ACLs. Do this to change the ACLs for this path so that they do not match the source.
The Most Common Error in Spreadsheet Editing
The most common error for people who are new to APM spreadsheet editing is to apply redirects to every line of the spreadsheet. This can result in restructured data that was not intended.
This is the wrong way to edit your spreadsheet:
A Target Owner and Target Path should not be entered for both the top level directories and the children of every path. This will flatten the directory structure and will result in target paths of /Joe’s files/UserA, /Joe’s files/FolderB, and /Joe’s files/FolderD.
Instead, only apply redirects for Target Owner and Target Path to the parent directories in the spreadsheet:
So for UserA’s files in this second example:
- the source directory /User/UserA will result in a target path of /Joe’s files/UserA in the target account email@example.com.
- NOTE: Any time you have a Target Path redirect, only the terminal stanza (the last component of the path directory structure) – UserA in this example – is used to build the target path. Nothing prior to the terminal stanza is used.
- The child directory, /Users/UserA/FolderA, will automatically follow the parent into firstname.lastname@example.org’s account unless you add a redirect for the child directory to the spreadsheet. So the target path will be /Joe’s files/UserA/FolderA, and the directory structure from the source will be preserved.
- Likewise, the source path /Users/UserB will have a target path of /Caitlin’s files/UserB, and /Users/UserB/FolderA and /Users/UserB/FolderA/FolderB will have target paths of /Caitlin’s files/UserB/FolderA and /Caitlin’s files/UserB/FolderA/FolderB respectively in the target account email@example.com.
- Merging folders and files from the same owner: If you explicitly merge the contents of two folders from the same owner into a single target location via redirects – for example, if you have a redirect for /Project1/foldera and /Project2/foldera on the source to both go to /Projects on the target, the contents of these two folders will be merged into a /Projects/foldera folder. There will be a message in the event log:
2 Tasks are merged into target [accountname]:/merged tasks:1,2 – this would merge source contents, if this is intended you may ignore this warning.On the other hand, if you merge two files from the same owner via redirects – e.g., if you have redirects for /Project1/file1 and /Project2/file1 on the source to both go to /Projects on the target, that creates two single-file tasks. If versioning is enabled, the versions of these two files can also get merged, so CFP will explicitly prevent that with a message Merging of file tasks not allowed, and you will need to fix the spreadsheet to transfer the files that would have been merged.For the reasons just illustrated, merging the contents of two folders from the same owner is not recommended, but CFP will only specifically prevent merging common data for two or more single-file tasks of the same target filename.
- Merging folders and files from different owners: If you redirect folders from two or more different accounts/owners – or if you merge two entire accounts into a common target folder – CFP will automatically invoke something called namespacing, where it will automatically create a folder for each owner labeled with the user’s account name / user name (e.g., if the contents of UserA and UserB’s accounts are both directed to a common target folder /Archive in the map, the contents of UserA’s account will go to a target folder /Archive/UserA, while the contents of UserB’s account will go to a folder /Archive/UserB. CFP will automatically create the UserA and UserB folders to separate the two accounts’ content even though the Target Path for both accounts is ‘/Archive.’) If you do not want namespacing, you will need to break the job up so that only one account is directed to the common target in each job. There is no way to block the namespacing logic.
- Namespacing only works if two or more accounts are merged in the same job. It will not detect if a single third account is directed to /Archive in a separate job. That said, when used judiciously and verified with simulation, namespacing provides a convenient way to compartmentalize and archive the contents of multiple source accounts to the target for individuals who have left the company or are not otherwise going to have their own accounts on the target.
- Default label for namespaced folders is user or account name. If a user name does not exist, email will be used.
- As for any job, always run simulations to verify expected results.
A Few Other Things to Know:
- For security reasons, users who are still in invited status may be ignored as sharers of data. In some cases, invited users may be blocked from creating shared folders at all. It dramatically simplifies the migration if you convert all users over to full member status before beginning the migration. Invited users are all marked as such on the Owners tab.
- Many cloud providers use waterfall permissions – meaning that subfolders that are further down in the directory tree can have more permissions than their parents, but not fewer permissions. If you share a root folder with someone, he or she will have access to the entire folder. Note that this is the reverse of the way Windows permissions work. Consult your cloud provider for details on their sharing policies before starting your migration.
- If you have selected Path-based mapping in your spreadsheet generation, the Paths tab will list all folders at the depth you specified in the Target Mapping Depth field of the Accounts and Files screen. If you have selected Owner-based mapping with permissions, the Paths tab only lists folders that are shared, not all of the data in the migration. The data to be transferred is selected in source node configuration while you are setting up the job itself.
Additional columns in Paths tab
TARGET PATH: This provides a redirect for any specifications in the job configuration. Example 1:
- Target directory in the job configuration is ‘/Migration’
- Source path in spreadsheet is /Home/caitlin/Documents
- You enter a target path of ‘CJones’ in the spreadsheet (no leading /)
- Resulting path on target will be /Migration/CJones/Documents. With no leading ‘/,’ the target directory in the job configuration prepends the Target Path entered in the spreadsheet.
- Target directory in the job configuration is ‘/Migration’
- Source path in spreadsheet is /Home/caitlin/Documents
- You enter a target path of ‘/CJones’ in the spreadsheet (with leading /)
- Resulting path on target will be /CJones/Documents.
SKIP? Some folders may be listed with a ‘Yes’ in the Skip? column. This typically occurs if the folder has fewer permissions than a parent folder or, in the case of migrations going to Dropbox target, if a nested share is present for a folder tree. If you want to transfer a skipped folder, simply remove the ‘Yes,’ but it may result in unintended access to the child folder.
You can also add folders to the spreadsheet that you want to omit from the transfer. Simply enter the folder owner, the full path for the folder, and then enter ‘Yes’ in the ‘Skip?’ column. When adding paths for skips, it’s essential that you enter the path exactly, or CFP will not recognize the skip and will transfer the folder.
When using skips, CFP will not scan the skipped folder to reduce time to job completion. That means the total byte and file counts reported may be lower than what it actually on the source.
If you skip a folder, you can unskip a child of that folder by listing that child path and setting the Skip? field to “N,” in which case only that one folder will be transferred.
RENAME: Renaming will omit the terminal directory (the last element of the path) from the Source Path in the Target’s path structure.
For example: Your source path could be: /Users/Documents/joe – in this case “joe” is the terminal directory.
Source Path: Users/Documents/joe
Target Path: /Home Files
If Rename is set to ‘Y,’ the source path Users/Documents/joe/joe.txt will be /Home Files/Documents/joe.txt on the target. The terminal ‘joe’ directory from the source path will be omitted from the target directory structure.
If Rename is blank, the same source path will be /Home Files/Documents/joe/joe.txt on the target.
CLEAR PERMISSIONS? (Y/N): Clear Permissions is a column that only appears on cloud providers such as Google and Egnyte that support file sharing. If you want to clear permissions for a given file, you may enter “Y” in the Clear Permissions column. If the column is blank, the default value of No will be applied, and permissions will be retained on the file. Note that permissions will only be applied to the file if the target supports file sharing. If Clear Permissions is set to “Y,” any subsequent permissions listed for that row of the spreadsheet will be ignored. In other words, the current permissions on the target file will be deleted, and no permissions will be added. If you want to add permissions for that file, you will need to apply them in a subsequent run to when the permissions are cleared.
- You will see columns listed for different target permission roles on the right side of the Paths tab. These will vary according to the target cloud provider in your job. CFP will list permissions from the source that most closely match the roles available on the target, but you may edit the spreadsheet to whatever fits your needs. If the data has been stored on a given source for any length of time, permissions of some source users may need to be adjusted up or down to reflect their current functions in the organization.
- If you share a subdirectory with someone, that subdirectory will appear in the top level of that user’s account for most cloud providers. So if you share Project1/financials/ and Project2/financials with the same user, this may generate an error in your job, because it can result in two folders of the same name in a single account. To eliminate confusion, it’s best to ensure that shared folders either have different names or redirects to different paths.
- If you want to redirect a folder – such as confidential information – to an entirely different location, you can use the Target Account and Target Path fields in the spreadsheet. In the spreadsheet example above, the /employees/personal folder is going to the ‘/private’ folder in the account firstname.lastname@example.org. Note that this is also a way to override the Source Owner -> Target Account mapping for this particular folder. The following rules define where your data will ultimately end up:
- If Target Path is blank, the files will be sent to the Destination Folder specified in the job.
- If you enter a forward slash (‘/’) in the Target Path, the folder/files will go to the root of the designated account.
- If you enter a forward slash followed by a directory (‘/directory’), the folder/files will go to the Target Path directory in the root of the designated account. So if you are transferring ‘/sourceFolder1/sourceFolder2’ and the Target Path directory is /directory, your data will go to /directory/sourceFolder2 in the designated account.
- If you enter a directory that is not preceded by a forward slash, the directory will be appended to the Destination Folder you configured for the job. So if you are transferring ‘/sourceFolder1/sourceFolder2,’ the Destination Folder is ‘/destinationFolder,’ and the Target Path is ‘directory,’ your data will go to /destinationFolder/directory/sourceFolder2.’
See Account Mapping – Path-Based Mapping for additional information on this feature.
External Users: You can apply external users (e.g., vendors, clients) as shares on the target, even if they are not a member of your corporate account. Leave the external user as an unmapped source user on the Users tab (i.e, the Target User cell for an external user should remain blank), and leave them as a sharer on the Paths tab. The designated user will be an external sharer on the target.
A few caveats:
- External user sharing must be selected when configuring the job, or the map will fail validation
- External user sharing is only available for select source and target combinations. The account mapping setup will have an option for external users if it is supported. Contact email@example.com for details. Tervela does not transfer data owned by external users.
- The external user generally must have a valid account with the target cloud provider, and in some cases they may need to have the space available in their account for the shared files. Consult your cloud provider for details.
See Account Mapping – Team Folders for information on Team folder mapping in Dropbox.