Account Map and Group Map CSV File Guidelines
On This Page
- 1 Overview
- 2 Understanding the File Elements
- 3 Determining Which Fields to Use
- 4 Using an Exported File as a Template
- 5 Account Map Samples
- 6 Group Map Samples
- 6.1 Network File Share (NFS) to Cloud Platform
- 6.2 Network File Share (NFS) to Box
- 6.3 Cloud Platform to Cloud Platform Using Name and Caption
- 6.4 Cloud Platform to Cloud Platform Using Source ID and Destination Name
- 6.5 Microsoft Entra Security Group or Microsoft 365 Group Using Claims-Format ID
- 6.6 Group Map Exclusions Sample Using Various Fields
On This Page
- 1 Overview
- 2 Understanding the File Elements
- 3 Determining Which Fields to Use
- 4 Using an Exported File as a Template
- 5 Account Map Samples
- 6 Group Map Samples
- 6.1 Network File Share (NFS) to Cloud Platform
- 6.2 Network File Share (NFS) to Box
- 6.3 Cloud Platform to Cloud Platform Using Name and Caption
- 6.4 Cloud Platform to Cloud Platform Using Source ID and Destination Name
- 6.5 Microsoft Entra Security Group or Microsoft 365 Group Using Claims-Format ID
- 6.6 Group Map Exclusions Sample Using Various Fields
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 ("") 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 build your import files.
Import Errors
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 it before attempting to import it again.
Understanding the File Elements
Both mapping 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 | Accounts: Platform-specific unique identifier for 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 Google, provide the ID as part of the security settings. Refer to the documentation for your specific platforms to identify if they use an ID and how to find it. For NFS, the ID will be the user directory. Groups: Platform-specific unique identifier for the group. |
123456789
domain\joesmith |
username | Accounts: User sign-in name or email address, when supported by the platform. Groups: Not supported for group mappings. Leave this field empty. | jsmith |
name | Accounts: User name. For a network file share, the name will be the user directory. Groups: Group name. |
domain\joesmith |
caption | Accounts: Display name for the account. For web-based platforms, this is the name that displays (usually in the upper-right corner) when you are signed in to the platform. For NFS, this is the user's name. Groups: Display name for the group. | 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. All exclusions must be in the import file when using a CSV file for exclusions. 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) or group map requires you to specify both the source and destination values, so the CSV file contains eight columns. The fields are identified by adding the source_ and destination_ prefixes to each 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 populate one field or a combination of fields (such as name and caption) to create a mapping or exclusion.
Each platform exposes different account and group information, and not every field is available for every platform. For example, some platforms do not expose an ID through the user interface. Determine which fields are available for your source and destination platforms before creating your CSV file. Refer to “Determining Which Fields to Use” later in this article for platform-specific guidance and recommendations.
If you receive an error when importing a CSV file, verify that the file follows the required format by comparing it to one of the sample files provided before attempting the import again.
Determining Which Fields to Use
DryvIQ reads the fields in the import file in the following order, using the first field that produces a match:
idnamecaptionusername
You can populate a single field or a combination of fields to create a mapping or exclusion. The fields you use depend on the information available from your source and destination platforms.
User (Account) Maps
Provide either a name or an ID for each side of the map. If the source_name or destination_name field does not contain an email address, you must supply a value in the corresponding source_id or destination_id field so DryvIQ can resolve the account.
For a group map where Box is the destination, you must provide the Box ID for the map to work.
Account Name and Username
For account maps, username is the user's email address. The name field is the account name.
SharePoint Online Group Maps
SharePoint Online supports several group types, and the recommended mapping field depends on the type of group being mapped.
Group Type | Recommended Source Field |
|---|---|
Microsoft Entra security group |
|
Microsoft 365 group |
|
Classic SharePoint group |
|
For Microsoft Entra security groups and Microsoft 365 groups, populate the source_id field with the claims-format group ID returned by the /groups API. Do not use the Microsoft Entra Object ID.
For classic SharePoint groups, use source_name or source_caption. Classic SharePoint groups do not support ID-based mapping.
source_caption is the only field that can be used consistently across Microsoft Entra security groups, Microsoft 365 groups, and classic SharePoint groups.
username is not supported for group maps. Leave this field empty.
Unique Group Names and Captions
Group names and captions are not guaranteed to be unique in SharePoint Online. Before using source_name or source_caption, verify that the value uniquely identifies the intended group. If duplicate names or captions exist, use the claims-format group ID whenever possible.
Using an Exported File as a Template
Rather than creating a CSV file from scratch, create a single mapping or exclusion entry and then download the file. The downloaded file contains the correct column order and formatting, making it an ideal template for adding additional entries before importing it again.
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","Joe Smith","","","jsmith@company.com","Joe Smith"
"","company\\JaneDoe","jdoe@company.com","Jane Doe","","","jdoe@company.com","Jane Doe"
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) so that DryvIQ can 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 samples of group map import files. 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 with Box as the destination, you must provide the Box ID 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) so that DryvIQ can 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"
Microsoft Entra Security Group or Microsoft 365 Group Using Claims-Format ID
Use this approach when mapping Microsoft Entra security groups or Microsoft 365 groups. Populate the source_id field with the claims-format group ID returned by the /groups API. Do not use the Microsoft Entra Object ID.
source_id,source_username,source_name,source_caption,destination_id,destination_username,destination_name,destination_caption
"c:0t.c|tenant|6d4efa20-9d7d-4a5c-a123-123456789abc","","","","","","Finance Team",""
"c:0t.c|tenant|7cee19d5-8b9c-4f3d-b456-23456789abcd","","","","","","Human Resources",""
"c:0t.c|tenant|a045ec69-2d8a-49de-c789-3456789abcde","","","","","","Engineering",""Choosing a Mapping Field
For classic SharePoint groups, use the source_caption field. Unlike source_id, source_caption can be used consistently across Microsoft Entra security groups, Microsoft 365 groups, and classic SharePoint groups.
Group Map Exclusions Sample Using Various Fields
id,username,name,caption,location
"123456789,"",Group 1,"","source"
"","","Group 2","","destination"