Create an Account Map or Group Map Using REST API



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

Option

Map

Values

Required?

User-Interface Options

Description

default

 

Account
Group

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
Group

true/false

Optional

Link matching user IDs

Match accounts by id.

name

Account
Group

true/false

Optional

Link matching user names
Link matching group 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.

email

Account

true/false

Optional

Link matching user email addresses

Match accounts by email.

fuzzy

Account
Group

true/false

Optional

Use fuzzy matching

Fuzzy matching performs partial matching on all fields selected on supported platforms. 

built_in

Account
Group

true/false

Optional

Retain built-in accounts

Retain permissions and ownership related to platform built-in accounts such as administrators.

passthrough

Account
Group

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
Group

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
Group

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

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

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

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

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

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

 

 

DryvIQ Migrate Version: 5.7.1
Release Date: May 17, 2024