On This Page
Overview
Mapping and exclusion imports must be a comma-separated values (CSV) file and follow a specific format. Data fields are wrapped in double quotation marks ("Value 1", "Value 2", "Value 3") and separated with commas. Empty fields must be qualified with two double quotation marks ("") in order to be accepted ("Field 1 Value","", "Field 3 Value"). This page provides information to help you understand the file structure and sample files you can use to help you build your own import files.
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.
Understanding the File Elements
Both mapping files and exclusion files utilize the same four fields: ID, username, name, and caption. The table below lists each field and identifies the information that can be used in each field.
Field | Description | Example Values |
|---|---|---|
id | The ID is the unique identification number assigned to the account. Not all platforms have IDs. Some platforms, such as Box, display the ID as part of the account details. Other platforms, such as G Suite, provide the ID as part of the security settings. Refer to documentation for your specific platforms to identify if the platform uses an ID and how to find it. For NFS, the ID will be the user directory. The domain must be escaped with additional backslash when creating the map. For example, user company\JoeSmith needs to be company\\JoeSmith. | 123456789
|
username | This is the username for the account. In most cases, this is the information used to sign in to the account and may be the email address for the account. | jsmith jsmith@company.com |
name | This is the account name--not the user’s name. For Web-based platforms, this is the email address associated with the account. For a network file share, the name will be the user directory. The domain must be escaped with additional backslash when creating the map. For example, user company\JoeSmith needs to be company\\JoeSmith. | jsmith@company.com domain\\joesmith |
caption | The caption for the account is the display name. For Web-based platforms, this is the name that displays (usually in the top-right corner) when you are logged on to the platform. For NFS, this is the user's name. | Joe Smith |
An exclusion file contains five columns–one for each field listed in the table above and a fifth "location" column. You use this column to indicate if the exclusion applies to the source or destination. When using a CSV file for exclusions, all exclusions must be in the import file. Exclusions configured in the job JSON will be ignored. Click here to download a blank exclusion file template.
id,username,name,caption,location
A user (account) map or group map requires you specify the values for both the source and destination, so this file will have eight columns. The fields are identified by including "source_" and "destination_" in the field name: source_id, source_username, source_name, source_caption, destination_id, destination_username, destination_name, and destination_caption. Click here to download a blank mapping template.
source_id,source_username,source_name,source_caption,destination_id,destination_username,destination_name,destination_caption
You can add values for one field or a combination of them (such as name and caption) to create a mapping or exclusion. Each platform is different, and not all information, such as ID, is accessible through the platform UI. You will need to understand the information available for your source and destination platforms to determine which fields will work best for your mapping. 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.
Determining Which Fields to Use
SkySync reads the import file in the following sequence:
name
id
username
caption.
Therefore, when possible, using name as the primary mapping element works best and can be supported by including other fields, such as caption. The exception is when creating a group map where Box is the destination. In this scenario, you must provide the Box ID in order for the map to work.
If the mapping import doesn’t contain an email address in the source_name or destination_name field, it must contain a name in the corresponding id field (source_id or destination_id) in order for SkySync to properly map the user. (See below for example maps that use this pattern.)
Account Map Samples
This section provides sample of account map import files. If you want to download one of the sample maps below, click the blue heading link.
Network File Share (NFS) to Cloud Platform
This sample shows a user (account) map with NFS as the source and a Web platform as the destination. The map uses name and caption. Note that the domain is escaped with an additional backslash and that empty fields contain "".
source_id,source_username,source_name,source_caption,destination_id,destination_username,destination_name,destination_caption "company\\JoeSmith","","","","","","jsmith@company.com","" "company\\JaneDoe","","","","","","jdoe@company.com",""
Cloud Platform to Cloud Platform Using Name and Caption
This sample shows a user (account) map for two Web-based platforms. It uses the name and caption to map the users. Note that empty fields contain "".
source_id,source_username,source_name,source_caption,destination_id,destination_username,destination_name,destination_caption "","","user00000@company.com","user 00000","","","user00000@company.com","user 00000" "","","user00001@company.com","user 00001","","","user00001@company.com","user 00001" "","","user00002@company.com","user 00002","","","user00002@company.com","user 00002" "","","user00003@company.com","user 00003","","","user00003@company.com","user 00003" "","","user00004@company.com","user 00004","","","user00004@company.com","user 00004" "","","user00005@company.com","user 00005","","","user00005@company.com","user 00005"
Cloud Platform to Cloud Platform Using Source ID and Destination Name
If the map doesn’t contain an email address in the source_name or destination_name field, it must contain a name in the corresponding id field (source_id or destination_id) in order for SkySync to properly map the user. The example map below illustrates how to use the id field when an email address is not provided as a name. Note that empty fields contain "".
source_id,source_username,source_name,source_caption,destination_id,destination_username,destination_name,destination_caption "user00000","","","user00000","","","user00000@company.com","user00000" "user00001","","","user00001","","","user00001@company.com","user00001" "user00002","","","user00002","","","user00002@company.com","user00002" "user00003","","","user00003","","","user00003@company.com","user00003" "user00004","","","user00004","","","user00004@company.com","user00004" "user00005","","","user00005","","","user00005@company.com","user00005"
Account Map Exclusions Sample Using Username and Name
id,username,name,caption "","user00000","user00000@company.com","destination" "","user00001","user00001@company.com","destination"
Group Map Samples
This section provides sample of group map import files. If you want to download one of the sample maps below, click the blue heading link.
Network File Share (NFS) to Cloud Platform
This sample shows a group map with NFS as the source and a Web platform as the destination. Note that the domain is escaped with an additional backslash and that empty fields contain "". This does not apply to Box. See Network File Share (NFS) to Box below for a sample group map for NFS to Box.
source_id,source_username,source_name,source_caption,destination_id,destination_username,destination_name,destination_caption "Domain\\Group Name 1","","","","","","Group Name 1","" "Domain\\Group Name 2","","","","","","Group Name 2","" "Domain\\Group Name 3","","","","","","Group Name 3",""
Network File Share (NFS) to Box
when creating a group map where Box is the destination. In this scenario, you must provide the Box ID in order for the map to work. In the sample below, the map is mapping from NFS to Box. Note that empty fields contain "".
source_id,source_username,source_name,source_caption,destination_id,destination_username,destination_name,destination_caption "Domain\\Group Name","","","","Box Group ID","","",""
Cloud Platform to Cloud Platform Using Name and Caption
This sample shows a group map for two Web-based platforms. It uses the name and caption to map the users. Note that empty fields contain "".
source_id,source_username,source_name,source_caption,destination_id,destination_username,destination_name,destination_caption "","","accounting_department@company.com","Accounting Department","","","accounting@domain.com","Accounting" "","","service_department@company.com","Service Department","","","customerservice@domain.com","Customer Service" "","","development_department@company.com","Development Department","","","development@domain.com","Development"
Cloud Platform to Cloud Platform Using Source ID and Destination Name
If the map doesn’t contain an email address in the source_name or destination_name field, it must contain a name in the corresponding id field (source_id or destination_id) in order for SkySync to properly map the user. The example map below illustrates how to use the id field when an email address is not provided as a name. Note that empty fields contain "".
source_id,source_username,source_name,source_caption,destination_id,destination_username,destination_name,destination_caption "Group1","Group1","","","","","Group1","Group1@domain.onmicrosoft.com" "Group2","Group2","","","","","Group2","Group2@domain.onmicrosoft.com" "Group3","Group3","","","","","Group3","Group3@domain.onmicrosoft.com"
Group Map Exclusions Sample Using Various Fields
id,username,name,caption,location "123456789,"",Group 1,"","source" "","","Group 2","","destination"
User Interface Tip
If you're using the user interface (UI), you can create one exclusion entry in your mapping manually, and then download the exclusions file to have a real world example to use as your template to complete the rest of the entries.
