1. Home
  2. Account and Permissions Mapping
  3. Using Location and User Templates in Migrate Permissions Jobs

Using Location and User Templates in Migrate Permissions Jobs

A Migrate Permissions job moves data from a source platform to Box, and transforms the permissions held by users on the source to respective users on Box.  You can choose how to specify the locations you want – i.e., the paths for data on the source and their destinations on Box.  You can also choose how to specify source to Box user permission mappings – i.e., if joe.lee@company.com is a sharee on the source, what account will be the sharee of the same data once it is moved to Box?  Your choices for defining Locations and Users and are:

  • via UI or
  • via a spreadsheet that is uploaded into the UI

You can use the UI and spreadsheets in any combination that works best for you.  This article will focus on configuring Locations and Users with spreadsheets.

The bulk upload (spreadsheet) feature is an option and is not available on all Shuttle accounts.

Locations

On the Select and map file locations screen, download the spreadsheet template and open it:

  1. The first tab of the template, Instructions, contains examples of how to configure source and target paths.  For best results, review the examples and follow the formats outlined there for configuring your paths in the tabs that follow. The contents of this tab are ignored by Shuttle and will not be applied to the job.
  2. Depending on your data source, you may have one or two additional tabs in the template.  Sources such as Windows will only have one tab, while sources such as Dropbox will have one tab for personal accounts and a second tab for common shared spaces (Team Folders).  Where there are two additional tabs, you may leave one tab blank, but you must specify paths on the correct tab.  In other words, if you have a Dropbox Team Folder path, you must specify it on the Shared Locations tab; the Locations tab is only for personal accounts.
  3. For each source path (or source account/path in the case of cloud based sources) that you add, specify a target account on Box and a target path.
  4. You can choose to not transfer a path by entering ‘Yes’ in the ‘Skip?’ column.  So if you have a path /Legal entered as a source path on one line of the spreadsheet with a target account and path, you can enter /Legal/confidential on another line and set ‘Skip?’ to Yes.  The result is that all of the /Legal folder except for Legal/confidential will transfer to the designated destination on Box.
  5. When the spreadsheet is complete, save it and upload by clicking the ‘Upload XLSX’ button.  If it validates, you are ready to move on to the next step of your migration.  If it fails to validate, you will get an error sheet.  Fix the errors and upload again until you get a valid spreadsheet loaded.  You can then move on to the next step in configuration.
    NOTE:  Because you are uploading the Locations sheet before the job has run, Shuttle will not validate for paths that are formatted correctly, but do not exist.  Simulations will ensure that you transfer all of the data expected and will flag any path listings in the Locations sheet that are not found.

About Move Contents Only

Migrate Permissions jobs structure paths on the target according to a strategy called ‘Move Contents Only.’  That means it will move the contents of the terminal source folder to the path you designate in Box.

Most users will want to add the terminal stanza from each source path to the target to preserve the structure.  Here are some examples of source and target paths, and the results:

Source Path Target Account (Box) Target Path Result
/Folder/subfolder joe@company.com / contents of subfolder will reside in root of account joe@company.com
/Folder/subfolder joe@company.com /Box contents of subfolder will reside in a folder /Box in account joe@company.com
/Folder/subfolder joe@company.com /Box/subfolder contents of subfolder will reside in /Box/subfolder in account joe@company.com
/Folder/subfolder joe@company.com /Box/Folder/subfolder contents of subfolder will reside in /Box/Folder/subfolder in account joe@company.com

About Files

For source paths that are files – i.e., /Folder/filename, the following conventions apply:

  1. If the target is an existing file, Shuttle will write the source file to Box as a new version.  So if you specify /Folder/filename on the source and /Folder/filename on the target and filename is a file, Shuttle will write the source filename as a new version of filename on the target.
  2. If the target is an existing folder, this will cause a write-error.  So if you specify /Folder/filename on the source and /Folder/filename on the target and filename on the target is a folder, you will get a write-error.  This also applies to if you try to write a file to the root; /Folder/filename to root (/) will cause a write-error.
  3. If the target does not exist, the file will be written as the last stanza in the target path.  So if you specify /Folder/filename on the source and /Boxtarget/filename on the target and filename does not exist on the target,

Best practices are that if you have a source path that includes a file, always specify a target filename in the path like this:

/Folder/document.docx > /BoxTarget/document.docx
/Folder/document.docx > /BoxTarget/myDocumentOnBox.docx

Avoiding Merged Data: specify a different target account/path for each source path

A second best practice is to avoid specifying the same target account and directory for two different paths, because it results in merging the contents of the two directories.  For example, if you have two source paths of /Folder/subfolder1 and /Folder/subfolder2 that both have a target account of username@company.com and target path of /Boxfolder:

  • the contents of subfolder1 and subfolder2 will be merged into /Boxfolder and
  • the permissions of subfolder1 and subfolder2 will try to be merged and applied to /Boxfolder, but if they conflict, they will fail

Let’s look at the first bullet item.

If you have folders /Folder/subfolder1/subfoldera and /Folder/subfolder2/subfoldera in your data set, using the above directives,  the contents of subfolder1 and subfolder2 will merge – meaning that you will have a single path of /Boxfolder/subfoldera that contains the contents of both subfoldera’s from the source.  Moreover, any filenames that match in the two subfoldera’s will also be merged –  meaning you will get a single file that contains the merged versions of the two files from the source.

This can create a lot of confusion and can be avoided by configuring a unique destination – consisting of source account/target path for each of your source paths.

Namespacing

If you are transferring more than one cloud account (such as Box. Dropbox, OneDrive, and Google Drive) to a common target account and path on Box, Shuttle will invoke a feature called namespacing.  Namespacing automatically creates a target directory on Box with each source username as follows:

Source Account Target Account (Box) Target Path Result
/joe.lee@company.com archive@company.com /Dropbox Accounts /Dropbox Accounts/Joe Lee/[contents of Joe Lee’s source account
/diego.ruiz@company.com archive@company.com /Dropbox Accounts /Dropbox Accounts/Diego Ruiz/[contents of Diego Ruiz’s source account]
/tjohnson@company.com archive@company.com /Dropbox Accounts /Dropbox Accounts/Terri Johnson/[contents of Terri Johnson’s source account]

Namespacing prevents the contents of multiple source accounts from getting merged into a common path.  It happens automatically and cannot be suppressed.

Final  Word: Simulations!

Running a simulation is essential to confirming that the target paths you expected are in fact invoked.  While Shuttle does not force you to run a simulation, they can highlight configuration errors and ultimately save time in reconfiguration.

Users and Groups

To configure user and group mappings, you will also download a template:

It will be pre-populated with all of the users and groups who share data in the source data set.  Map each user and group respectively to a target Box user and group, or enter a ‘Y’  in the ‘Skip’ column to prevent any permissions for that source user/group from propagating to Box.  All listed users and groups must either be matched to an internal target account or skipped for the uploaded sheet to validate.

When the spreadsheet is complete, save it and upload by clicking the ‘Upload XLSX’ button.  If it validates, you are ready to move on to the next step of your migration.  If it fails to validate, you will get an error sheet that can be downloaded:

Fix the errors and upload again until you get a valid spreadsheet loaded.  You can then move on to the next step in configuration.

Updated on February 17, 2022

Related Articles