The Account and Permissions spreadsheet is the master index for your mapping job. It has five tabs:
- Users. This is the one tab of the spreadsheet that must be completed. It maps data owners on the source to accounts on the target. It also lists any users on the source who share data.
- Groups. This tab is used to map groups (e.g., Departments, Projects, Regional offices) on the source to groups on the target. It also lists groups, such as BUILTIN\Administrators on Windows, who are owners of data.
- Paths. This tab is where you define how specific folders from the source will be shared on the target. You can also add redirects that apply exceptions to ownership and paths directives specified elsewhere in the map and job configuration.
- Path Conflicts. This tab lists the conflicts that you will need to resolve before running the spreadsheet. They may be sharing relationships, such as reduced permissions, that cannot be replicated on the target platform, path not found due to a typo in entering the path, or some other directive that prevents CFP from executing the explicit instructions you’ve created for your migration.
- Target Paths. This tab lists the Team Folders for jobs going to a Dropbox target, or the Shared Drives for a Google Drive target.
A common misconception and source of confusion that we see is the role of the Paths tab. The Paths tab in the generated map reports out the paths that have been shared; in the case of Path based mapping, it also reports out folders at the designated folder depth, and attempts to redirect these folders to source owners that are a fuzzy match to the folder names. The Paths tab does not list all of the data to be transferred; that is determined by the source data selected in the job configuration. The Analysis report (select ‘Analysis’ from the white bordered box on the right side of your job configuration screen) will list out all of the data for the source.
The Users tab identifies and lists all of the owners of your data on the source, and then you must define an account on the target where each owner’s data will go. Users will appear in the Source Users column if:
- they own files or folders in the data set that has been selected for transfer or
- they are sharees of files or folders in the data set for transfer. In this case, they will also appear in the Paths tab.
- they are a creator or updater of a file. ‘Use Last Modifier’ must be turned on for the job to display creators and updaters; this option is only available for some adapters.
In the Users tab of the spreadsheet, CFP will list all of the Source Users in the left column, and all of the Target Account names on the right:
Where CFP can reasonably match a Source User to the available list of users found in the Target Account, it will do so. If it can’t find a close match for the Source User name, it will leave the corresponding Target User cell blank.
Accounts in the example above from line 6 – 9 are just a list of Target Accounts that CFP found on the scan, but that haven’t been matched to any Source Users. This list is informational only. You can just leave it as is and don’t have to edit these rows of the spreadsheet at all.
Completing the Users Tab
- Source Users who are owners or owners and sharees: Any Source User owner that does not have a corresponding target account must be completed; if you have data on the source, you have to tell CFP which account to send it to on the target, or the spreadsheet will not validate when you upload it. In the spreadsheet example above, DOMAIN\user1 and DOMAIN\user2 are both owners of data, and must be mapped. Do not delete the row, or the spreadsheet will not validate when you upload it.
- Source Users who are sharees only: Source users who are listed in the spreadsheet as sharees only (DOMAIN\user3 in the example above) may be handled in one of three ways:
- You can map the Source User to a valid Target User. Any shares for that user on the source will be propagated to the designated Target User account.
- You can enter a “Y” in the Skip? Column, which will ignore that sharee and not apply any ACLs for that user as a sharee for any paths in the job. This is helpful for users who are no longer associated with the company.
- NEW: You can leave the Target User cell blank for external users, in which case any ACLs for that Source User will be applied to the target as an external user sharee. Do not delete the row of the spreadsheet for external users, as this has been deprecated.
- Source users who are creators or updaters: These must be completed unless they are external Last Modifiers. External Last Modifiers may be left with blank Target Users. While the map will validate if you skip Last Modifier users in the spreadsheet, any files that contain the affected users will not transfer because you have not specified the Last Modifier. Last Modifiers who are listed as “Prior Collaborators” are users who were members of the tenant at one time, but have since been deleted. In this case, the name and email have been deleted from the file metadata, and only the user id remains. Tervela recommends that you map these Prior Collaborators to an admin or service account.
- Any Target User listed in column B in the generated spreadsheet Users tab is a valid Target User. If they are not in the list, CFP does not know they exist, and the spreadsheet will not validate when you upload it.
Most of the source to target account names will be similar, but you can map each owner to any account that you wish:
In the example above, all data owned by CFPWIN10B\administrator on the source will be sent to the account itguy@your company.com on the target (unless you override this with a directive on the Paths tab; see Account Mapping – Path-Based Mapping for details).
Skipping Users and Groups
Many people have obsolete sharers of data in their accounts that are no longer needed. In this case, you may skip that Source User by entering a ‘Y’ or ‘Yes’ in the Skip? column. Any shares for that user in the Paths or Path Conflicts tab will then be ignored, those shares will not be applied on the target, and the spreadsheet will still validate even though the source share is not mapped to a target account. You may do the same thing for share groups as well.
If an Owner is listed in the spreadsheet, that means they own data in what is being transferred, and you must either tell CFP whose account to transfer it to, or skip the user by entering a ‘Y’ in the Skip? column. If you skip an owner, any data owned by that user will not be transferred to the target.
Nuances Using Skip? with Windows Migrations
If a folder FolderA is owned by UserA, and you skip UserA, that entire folder will be skipped, regardless of who owns the content in the folder. However, given the many options available now with account mapping, it is highly recommended that you run a simulation for any job where users are skipped, Windows source or otherwise, to assess exactly how your job will behave.
Some spreadsheets will list IDs, such as 123456789, in the Source User field. These are users who have been deleted from the source account, but they still may be the owner, sharee, or creator/updater of folders and files. If they are owners of data (this primarily applies to Windows sources) they must be either mapped to a Target User or skipped.
Rescan Target Accounts/Groups
Note that when CFP generates a spreadsheet, a snapshot of your target account is saved to a database, and that is what is used for all further validations. If you add or modify target accounts after running the spreadsheet, they won’t be picked up in the existing database of target users. However, CFP has a function, Rescan Target Accounts/Groups, which will run an auxiliary scan of only the target users for the job. Because it’s only scanning target users, it’s much faster than the full scan of your job. At that point, you can add those users to the spreadsheet that you are editing, and when that spreadsheet is loaded, the new users will be recognized and will validate. The Rescan Target Accounts/Groups button is on the ‘Map Source to Target’ screen (click the Generate link in the breadcrumb box on the right side of the Map flow screen).
NOTE: If you run a rescan of target accounts and groups after you have uploaded your edited spreadsheet, you will need to upload it again. Generally, you can upload the same spreadsheet without further edits.
The Groups tab lists functional groups within the organization.
This tab is used if you are configuring permissions that include Groups, or if you have a group that owns data on the source. If the Group is a sharer of data in the transfer, map it to a Target Group. If the Group is an owner of data, map it to a Target Owner. Note that commas in Group Names are not supported in CFP.
Path Conflicts tab
The Path Conflicts tab lists all shares on the source that are incompatible with the target. This may include:
- file sharing
- nested sharing
- reduced sharing
- path not found (typically due to typos in manually entered paths)
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:
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.
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 top-level folders in your migration. If you have selected Owner-based mapping, 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.
- 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.
Target Paths Tab
The Target Paths tab lists Team folders for Dropbox target jobs. At one time, it was also used to apply permissions to target folders after data was transferred. Permissions can now be applied from the Paths tab, regardless of whether the data to be shared is already on the target, and is much easier to execute from the Paths tab.
- You can also use the Target Paths tab to create Team Folders. If you want to create a Team folder (Dropbox target only), enter ‘Yes’ in the Team Folder? column. You can also add a group to apply to that Team Folder in the Editor (Groups) column.
- NOTE: Tervela recommends that if you are transferring data to a Team Folder, you should create the Team Folders in Dropbox and not in the spreadsheet. The reason for this is that when you run a simulation, CFP will have the Team Folders and sharing Group(s) already available for inspection, and can verify that your data will go to the team folder. If you create the Team Folders via the spreadsheet, they won’t be created until the transfer, so CFP cannot verify the data will go to the team folders during simulation.
Creating Empty Folders on the Target
You can also create an empty folder on the target from the Target Paths tab.
- Enter the Target Owner and Target Path in the applicable columns for the folder you want to create. For the Target Path, the folder must have a trailing slash, like this: /My Empty Target Folder/. The Target Owner can be any valid account on the target, and doesn’t have to be an account that is selected for that job. You can create as many empty folders as you want; each folder created needs to be entered on a separate line.
- You must apply at least one share to each folder for it to transfer. If you do not want to share the folder on the target, share it with a service account, and then delete that user when the migration completes.
- Run the job in Apply ACL (not Data Only) mode. When the job runs, it must have at least one item that has a status of success (the item transferred to the target) or match-exists (the item already exists on the target) for the empty folder to be created.
Uploading the Spreadsheet and Running Your Job
1: Save your spreadsheet when you have completed all data. Click the Choose File button from the Accounts and Files page of the Mapping Wizard to upload the account mappings back to CFP:
2: Use the Files and Status button, on the far right side of the map flow, to monitor when your map has completed processing:
3: You’ll see the status update in the Map Status of the File Drawer:
This status will change to ‘Map is fully processed’ when the map is fully loaded and you can run the simulation or transfer job.
4: If you see an error at the top of the dashboard stating that you do not have a spreadsheet, you probably either have an error in your spreadsheet, or it hasn’t finished loading. Go back to the Account Mapping modal for your job and look for an Errors xlsx file, which will explain where the errors are. Correct the issue(s), save and re-load the spreadsheet, and re-run the job.