...

On This Page

Table of Contents

Overview

The permissions import feature allows a user to establish permissions from platforms that wouldn't otherwise support reading permissions, and it does so based on the contents of a delimited text file or a database table. This can be useful when importing data that is produced during an export routine such as exporting content from a platform that is not yet supported by the application. Permissions import runs after all content has been processed. It will iterate over each row from the import source and attempt to determine the impacted file along with the desired permissions. If the file can be determined, it will map the users and groups and then apply the permissions.

...

Note
The destination connection must be made with an account that has administrative privileges.

Image RemovedImage Added

File Format

The import source can be any delimited file or a database table. The import source needs to contain 2 types of information for each row in the file: the file path and the associated permissions.

File Path

The first column(s) in the import source must be the file path. This can be specified using the column name(s). The file path can either be relative to the job source or an absolute path within the source platform. For example, if the job source is /C/files/users/ and the file in question is /C/files/users/jdoe/locations.xls, then the file path in the import source could be /jdoe/locations.xls or /C/files/users/jdoe/locations.xls.

...

If using one column for the path, the first column should contain the full path. Valid column names when using one column are FilePath, Path, FullPath, File_Path, and Full_Path.
If using two columns for the path,
- the first column should be used for the directory name. Valid directory column names are FolderName, Folder_Name, and Folder_Structure.
- The second column should then be used for the file name. Valid file column names are FileName, File_Name.

Permissions

The remaining columns identify the associated permissions.

Permission	Description	Valid Values	Required
access	This column identifies the access rights. Multiple values can be included by adding + between the values. For example, you can set the access value to read+write.	read, write, append, delete, read_permissions, write_permissions, read_write, full	Required
allow	This column identifies if access should be granted or denied.	0, 1, true, false, allow, deny (Allow is the default value. )	Optional
disinherit	This column identifies whether permissions should be inherited from the parent or not.	0, 1, true, false (0 is the default value.)	Optional
user[*]	Any column that starts with "user" will be parsed as a user account. Multiple values can be included as long as they are separated by a semicolon.		Optional
group[*]	Any column that starts with "group" will be parsed as a group. Multiple values can be included as long as they are separated by a semicolon.		Optional

...

Info
If the import file contains a column named "SHA1" or "Hash", the system will validate that the hash in the import file matches the hash of the file on the destination platform. If the hash does not match, a warning message will be logged.

Example Import File

Below is an example CSV file. Notice that any empty fields in the CSV file are empty quotes. Currently, the CSV parser does not allow empty fields to be unquoted.

⬇️ Download | Permissions Import Sample CSV

...

Code Block

path,access,allow,user1,user2,group
/C/files/users/jdoe/locations1.xls,read+write,allow,jdoe@aoljdoe@company.com,jane@aoljane@company.com,Users;Developers
/C/files/users/jdoe/locations2.xls,full,allow,jdoe@aoljdoe@company.com,"",""

Info
If you receive an error when importing a CSV file, the file does not meet the expected format. Compare your file to the sample files provided, and edit the file before attempting to import it again.

Using the Permissions Level Transfer Export to Import Permissions

You can export the Permissions Level Transfer export from the Sharing Insights tab for an individual job or a report group. You can then edit the file to include the applicable permissions, and use the file as your permissions import.

Below is an example of exported report. The import only reads the five columns identified in the table below. Just edit the information for these columns as needed. All other columns are skipped regardless of the information in the columns.

Example Transfer Level Permissions Export

...

Column	Description	Notes
source_name	This column identifies the user or group to whom permissions are being applied.
rights	This column identifies the access rights for a given item.	Valid values are read, write, append, delete, read_permissions, write_permissions, read_write, and full.
access_control	This column indicates if access should be granted or denied.	Valid “allow” values are 1, true, and allow. (Allow is the default value.) Valid deny values are 0, false, and deny.
audit_trail	This column is used to determine if the record should be skipped when applying permissions of if it should be included.	If there is a value in this field, the record will be skipped when applying permissions, and no permissions will be applied. If this column is empty, the indicated permissions will be applied. It is important that this column be empty for all records that need to have permissions applied.
platform_path	This column identifies the transfer item’s source path defined in the job.

API Usage

To create a transfer job with permissions import using the REST API, include the following in your "transfer" block in postman:

Info
The default delimiter is a comma.

Code Block

{
    "name":"Sample Job | Permissions Import via CSV File",
    "kind": "transfer",
    "transfer": {
      "transfer_type": "copy",
      "audit_level": "trace",
      "batch_mode": "always",
      "conflict_resolution": "latest",
      "delete_propagation": "ignore_both",
      "failure_policy": "continue",
      "large_item": "skip",
      "lock_propagation": "ignore",
      "max_items_per_container": 10000,
      "performance": {
                "parallel_writes": {
                    "requested": 2
                }
      },          
      "permissions": {
    		"policy": "add",
    		"links": true,
    		"failures": "none",
			"import": {
				"source": {
					"text": {
						"delimiter": ",",
						"target": {
							"path": "/permissions.csv"
						}
					}
				},
				"output": {
					"format": "text"
				}
    		}	
      },
      "preserve_owners": true,
      "timestamps": true,
      "empty_containers": "create",
      "duplicate_names": "rename",
      "item_overwrite": "overwrite",
      "restricted_content": "convert",
      "segment_transform": true,
      "versioning": {
    		"preserve": "native",
    		"select": "all"
      },
      "account_map": {
         "id": "{{account_map_id}}",
         "type": "account_map"
    },
        "filter":{
         "source":[
            {
               "action":"exclude",
               "rules":[
                  {
                     "type":"filter_shared"
                  }
               ],
               "type":"filter_rule"
            }
         ],
         "destination":[
            {
               "action":"exclude",
               "rules":[
                  {
                     "type":"filter_shared"
                  }
               ],
               "type":"filter_rule"
            }
         ]
        },        
        "source": {
            "connection": { "id": "{{cloud_connection_source}}" },
            "target": {
                "path": "/sourcePath"
            }
        },
        "destination": {
            "connection": { "id": "{{cloud_connection_destination}}" },
            "target": {
                "path": "/destinationPath"
            }
        },
        "simulation_mode": false
    },
    "schedule": {
        "mode": "manual"
    },
    "stop_policy": {
        "on_success": 5,
        "on_failure": 5,
        "on_execute": 25
    },
    "category": {
      "id": 4,
      "name": "Category Name"
    }
}

...

The import source can also be from a database table.

Code Block

{
    "name":"Sample Job | Permissions Import via Database Table",
    "kind": "transfer",
    "transfer": {
      "transfer_type": "copy",
      "audit_level": "trace",
      "batch_mode": "always",
      "conflict_resolution": "latest",
      "delete_propagation": "ignore_both",
      "failure_policy": "continue",
      "large_item": "skip",
      "lock_propagation": "ignore",
      "max_items_per_container": 10000,
      "performance": {
                "parallel_writes": {
                    "requested": 2
                }
      },          
      "permissions": {
    		"policy": "add",
    		"links": true,
    		"failures": "none",
    		"import": {
				"source": {
					"db": {
						"type": "sqlserver",
						"connection_string": "SERVER=(local);DATABASE=ContentPermissions;Integrated Security=SSPI",
						"table": "FilePermissions"
					}
				},
				"output": {
					"format": "text"
				}
    		}	
      },
      "preserve_owners": true,
      "timestamps": true,
      "empty_containers": "create",
      "duplicate_names": "rename",
      "item_overwrite": "overwrite",
      "restricted_content": "convert",
      "segment_transform": true,
      "versioning": {
    		"preserve": "native",
    		"select": "all"
      },
      "account_map": {
         "id": "{{account_map_id}}",
         "type": "account_map"
    },
        "filter":{
         "source":[
            {
               "action":"exclude",
               "rules":[
                  {
                     "type":"filter_shared"
                  }
               ],
               "type":"filter_rule"
            }
         ],
         "destination":[
            {
               "action":"exclude",
               "rules":[
                  {
                     "type":"filter_shared"
                  }
               ],
               "type":"filter_rule"
            }
         ]
        },        
        "source": {
            "connection": { "id": "{{cloud_connection_source}}" },
            "target": {
                "path": "/sourcePath"
            }
        },
        "destination": {
            "connection": { "id": "{{cloud_connection_destination}}" },
            "target": {
                "path": "/destinationPath"
            }
        },
        "simulation_mode": false
    },
    "schedule": {
        "mode": "manual"
    },
    "stop_policy": {
        "on_success": 5,
        "on_failure": 5,
        "on_execute": 25
    },
    "category": {
      "id": 4,
      "name": "Category Name"
    }
}

Info
If you do not want to combine permission import settings with permission policy settings, you can still use "permissions_import" under "transfer" options. See Permissions Propagation / Permission Preservation Policy.

User Experience

Here is an example of how to create a job with permissions import.

Create a folder with some test data on your local machine.
Create a file describing permissions data in that same folder.

Permission Import File | Example

permissions_import.csv

Code Block
FilePath,access,allow,user1,group /PermissionsTest/subPermissions,full,allow,someone@company.com,qatest

Permissions Import Useful Notes

Specify a permissions policy of none for simple scenarios. See Permissions | Permissions Preservation.
Create and utilize an account map with the option map_by:passthrough for simple scenarios (File Share or NFS; both sides only). See Permissions | Account Map / Group Map.
When using the REST API to create a Job with permissions import, it is advisable to utilize the JSON configuration path transfer.permissions.import.source.text.target.path.

Info
The alternate Permissions Import JSON configuration path `transfer.permission_import` is a valid option for importing a file; however, Job Duplication/Clone capabilities will not replicate the Permissions Import configuration to the new job when utilized.

Check Results

In Windows Explorer, check your source NFS folder. The presence of one of the following files indicates the import success or failure.

A permissions_import-XX-export.csv file indicates permissions import success.
A permissions_import-XX-failures.csv file indicates permission import did not succeed.

Login to your Box account, and select the /PermissionsImport_Destination/subPermissions folder.

...

.

Versions Compared

Old Version 1

New Version 2

Key

Overview

File Format

File Path

Permissions

Example Import File

Using the Permissions Level Transfer Export to Import Permissions

API Usage

User Experience

Permissions Import Useful Notes

Check Results

Page Comparison

Versions Compared

Old Version 1

New Version 2

Key

Overview

File Format

File Path

Permissions

Example Import File

Using the Permissions Level Transfer Export to Import Permissions

API Usage

User Experience

Permissions Import Useful Notes

Check Results