Create an Account Map or Group Map Using REST API
- Andrea Harvey
On This Page
Overview
A user account or group map provides the ability to explicitly associate users and groups for the purposes of setting ownership and permissions on items transferred. These mappings can happen automatically using rules or explicitly using an exception. Accounts or groups can be excluded by specifying an exclusion, and unmapped users can be defaulted to a known user. Here are a few things to consider when creating an account or group map:
A source and destination connection are required and need to match the source and destination of the job that will be referencing the user or group map.
A map can be created before or during the creation of the job.
A map can be used across multiple jobs.
Once updated, the updates will not be reapplied to content that has already been transferred.
"map_by" Options
The table below lists the options available to use in the "map_by" element when creating or editing map. Note that all options are flagged as optional; however, if you are not using the default option, you must select at least one of the following options in order for the map to work: id, username, name, displayname, email, externalpassthrough, or passthrough.
Option | Map | Values | Required? | User-Interface Options | Description |
|---|---|---|---|---|---|
default
| Account | true/false | Optional | N/A | Enables default mapping by all fields. Equivalent to setting all the the following to true: id, name, username, caption and email |
id | Account | true/false | Optional | Link matching user IDs | Match accounts by id. |
name | Account | true/false | Optional | Link matching user names For example, 'John Smith' | Match accounts by name. |
username | Account | true/false | Optional | Link matching user usernames For example, 'JSmith' | Match accounts by username. |
caption | Group | true/false | Optional | Link matching group display names or captions | Match accounts by caption / display name. |
Account | true/false | Optional | Link matching user email addresses | Match accounts by email. | |
fuzzy | Account | true/false | Optional | Use fuzzy matching | Fuzzy matching performs partial matching on all fields selected on supported platforms. |
built_in | Account | true/false | Optional | Retain built-in accounts | Retain permissions and ownership related to platform built-in accounts such as administrators. |
passthrough | Account | true/false | Optional | Retain external users AND Do not attempt to resolve first | Retain guest account permissions and ownership utilizing an external account without first attempting to resolve the account against a destination account. Note: External email already associated as a guest account in OfB/O365 will work regardless of whether external_passthrough is on Most commonly used for Network File Share (NFS) |
external_passthrough | Account | true/false | Optional | Retain external users AND Attempt to resolve first | Retain guest account permissions and ownership but attempt to resolve the account against a destination account first before retaining the permissions and ownership utilizing an external user account. |
ldap | Account | true/false | Optional | N/A | This option is only available through the REST API. Please Contact Support to ensure proper configuration |
Create an Account Map
The following sample code shows how to create an account map. Replace the information with information relevant to the map you are creating.
POST {{url}}v1/account_maps |
|---|
{
"name":"{{account_map_name}}",
"type": "account_map",
"source": {
"connection": {
"id": "{{cloud_connection_source}}"
}
},
"destination": {
"connection": {
"id": "{{cloud_connection_destination}}"
}
},
"unmapped_policy": "warn",
"map_by": {
"email": true,
"external_passthrough": true
}
} |
Create an Account Map as Part of a Job
Account maps are can be added to the API call used to create a job. The following sample code shows an API call to create a job that includes account map information. To use the sample code, replace the information with information relevant to the job you are creating and the map you want to use.
POST {{url}}v1/jobs |
|---|
{
"name":"Example Job | Using both Group & Account Map References",
"kind": "transfer",
"transfer": {
"transfer_type": "copy",
"account_map": {
"name":"{{account_map_name}}",
"type": "account_map"
"unmapped_policy": "warn",
"map_by": {
"email": true,
"external_passthrough": true
}
},
"source": {
"connection": { "id": "{{cloud_connection_source}}" },
"target": {
"path": "/SourceFolder"
}
},
"destination": {
"connection": { "id": "{{cloud_connection_destination}}" },
"target": {
"path": "/Destination Folder"
}
}
},
"schedule": {
"mode": "manual"
}
} |
Reference an Existing Account Map from a Job
The following code shows an example of an API message to create a job that references an existing group map rather than creating a new one. To use the sample code, replace the information with information relevant to the job you are creating and the map you want to use.
POST {{url}}v1/jobs |
|---|
{
"name":"Example Job | Using both Group & Account Map References",
"kind": "transfer",
"transfer": {
"transfer_type": "copy",
"group_map": {
"id": "{{group_map_id}}",
"type": "group_map"
},
"account_map": {
"id": "{{account_map_id}}",
"type": "account_map"
},
"source": {
"connection": { "id": "{{cloud_connection_source}}" },
"target": {
"path": "/SourceFolder"
}
},
"destination": {
"connection": { "id": "{{cloud_connection_destination}}" },
"target": {
"path": "/Destination Folder"
}
}
},
"schedule": {
"mode": "manual"
}
} |
Update an Account Map
The sample code below shows an API message for updating an existing map.
PATCH {{url}}v1/account_maps |
|---|
View Account Maps
The call below returns the account maps created in the application. The sample shows the call for an account map, but you can use the same call to get group maps by swapping "group_maps" for "account_maps."
Delete an Account Map
The code below shows how to delete a map. You can delete either an account or group map by sending the corresponding account_map_id or group-map_id.
Unmapped Policies
convention.unmapped_policy is an optional setting that determines what to do when an account cannot be mapped to a destination account. The sample code below shows an example of how to use this option. The table provides the complete list of available options.
Value | Description |
|---|---|
default | Match unmapped account / group with specified default account / group |
ignore | Do not create a job for the unmapped convention. |
add | Provision the account on the destination and create the job for the mapped convention. |
warn | Do not create a job for the unmapped convention and log a warning in the audit log. |
Default Unmapped Policy
If an account or group cannot be mapped, an unmapped policy of `default` can be used to map it to a specific account or group.
Default accounts must be used with combination of other mappers (by email, by id etc) or exception maps. Default mapper is a fallback mechanism and will trigger only when other mappers were unable to map the account/group.
When DryvIQ migrates permissions, it will not use defaulted account / group to avoid duplication. Default unmapped policy is only used for author preservation, user drive mapping, and lock owner preservation.
Specify Default Account
Set the unmapped_policy to "default" and specify a default account. The default account should contain at least one appropriate identifier (such as id, email, username etc).
POST v1/account_maps |
Group Map
A group map is managed in the much the same way as an account map but must be managed separately. All above documentation applies to group maps as well; just substitute "group_maps" in the URL for "account_maps" and "group_map" as the type, if the type is required in the JSON.
POST {{url}}v1/group_maps |
Default Group Example
POST v1/group_maps |
Notes on expected behavior
If the user is NOT in the account map but the shared item to this missing user is NOT the root, each item will be logged on the overview individually, and each item has log history showing permission failure.
If users are NOT in the account map but shared to the root folder, there will only be one entry on the overview. Each item will still have a log entry warning.
Related