User Job Mapping



On This Page

Overview

User Job Mapping jobs do not transfer any data. They are used to map user accounts on the source and destination platforms. The User Job Mapping job automatically generates child jobs based on the settings you’ve chosen for the job. These child jobs perform all the data transfers. You can select an account map to use for automatic user mapping rules and exceptions and filter out users by explicitly including or excluding them.

User Job Mapping jobs are ideal for migrations where you wish to control the transfer at a granular level without the effort of creating individual jobs. DryvIQ will automatically create a unique job for each user account that can be matched between the source and destination connections. Users on the destination are matched to either users on the source, folder names on the source, or LDAP records on the source.

 

User job mapping jobs require connections with the ability to impersonate other users.



If you want to create a User Job Mapping job that integrates with LDAP, you must use a REST API call to create the job and add the mapping. See Account and Group Maps Using LDAP for more information. 

 

Create a User Job Mapping Job

A User Job Mapping job supports Impersonation, and all the job features defined while creating the parent job will be applied to the child jobs it creates.

 

Define your Source and Destination Paths

If you are an administrator using Impersonation, enable Run as user..., and choose the user you wish to access.

Source / Destination Path: If you wish to transfer all content, leave the source path blank. A child job will be created for every user account. If a directory is selected for the source path, a child job will be created for every user account within the parent directory. 

Child Job Source / Destination Path: This directory within each user account will be used as the source. If the directory does not exist on the destination, DryvIQ will create it.

Target the root of each user account: The child job will be created for the first level folder/account relative to the source path.

Target a specific directory within each user account: If there is a folder that exists in every user account, you can define it with this option.

 

Save and Configure Mappings for the Job

After configuring policies, behaviors, and advanced features, select the option to Save job and configure mappings. Assign a name to the parent job. If desired, you can set a schedule for the job. This schedule will be applied to the child jobs.

 

User Job Mapping Job Configuration

This is where you configure the settings that determine the general rules for how the child jobs are generated. The user mappings and filters allow you to override automatic user mapping rules and filter out users by explicitly including or excluding them.

The job status and button you see on this screen vary based on the settings for the job. If you have not selected a user map for the job, the job status will be “Awaiting user interaction,” and you will see a Return to job button. You will not be able to run the job until you add a user map.

 

Once a user map has been assigned to the job, the status will be “Paused,” and you will see a Run job button so you can run the job. See Run User Job Mapping Jobs below for more information.

Configurations

  • Map specific users to one another: Select this option to use an existing account/user map you already created to map users. Select the map you want to use for this job from the list. 

  • Create new user map policy: Select this option to create a new user map. Refer to Permission | Account Map/Group Map for more information about the options used to create the user map. 

  • User Account Job Generation: Use this section to identify which connection should be used to determine user accounts. If you select Source, DryvIQ will use the source connection as the source of user accounts when generating user account jobs. If you select Destination, DryvIQ will use the destination connection as the source of user accounts when generating user account jobs.

  • Remove user account jobs that are no longer valid: This is an on/off setting that deletes jobs that are no longer valid.

  • Email Domain: Specify an email domain to limit the generation of User job mapping child jobs to only users with this email domain. For example, enter "example.com" to create a job for the user "test@example.com" but not for the user "test@something.com."

  • Import user filters: Import an inclusion or exclusion mapping file that should be applied to the job. You can upload the file from your computer or use a file on the source platform. (See Account Map/Group Map CSV Guidelines for information about generating mapping files used to include or exclude users.)
    An inclusion map specifies users to include when generating child jobs. Child jobs are only created for users in the map that can be matched. All other users will be excluded. 
    An exclusion map specifies users to exclude when generating child jobs. Child jobs will not be created for the users in this map. Jobs will be created for all other users. 

Run User Job Mapping Job

After configuring your user job mapping job, run the job. This will execute the parent job, which will create the child jobs. After the child jobs are created, the default schedule is set to run every 6 hours so it can review the source for any new content. The parent and child job schedules can be changed at any time.


Creating a User Job Mapping Job Through the REST API

The code below shows an example of how to create a User Job Mapping job using the REST API. Keep in mind the following points while reviewing the sample to help you understand how it affects the parent and child jobs.

  • The “schedule” in the transfer block is for child jobs. In this case, all child jobs would be on auto schedule. The “schedule” outside transfer block is for convention job itself. In this case, the convention job would be on manual schedule.

  • The Destination path is relative to the root of matched user's account. In this example, if we found that user1@example.com exists on source and destination, we would create a child job that transfers from user1's '/my docs' on box to user1's “Documents' on o365.

  • If matching to source accounts, source path is relative to that user's root. If matching to source folder names, source path is path to where user folders are located.

POST /jobs

{ "name": "personal_drive box to o365", "kind": "personal_drive", "transfer": { "transfer_type": "copy", "source": { "connection": { "id": "{{cloud_connection_source}}" } }, "destination": { "connection": { "id": "{{cloud_connection_destination}}" } }, "schedule": { "mode": "auto" } }, "schedule": { "mode": "manual" }, "convention": { "match": "account", "map_by": { "email": true }, "users": "source", "remove_invalid": true, "unmapped_policy": "warn", "type": "personal_drive" } }

Additional Settings

Match

convention.match controls how to match source and destination. Possible values are container, account, or ldap.

Container matches folder name on source to users on destination and would be used for a Network Home Drive Mapping job.

Account matches users on source to destination and would be used for a User Job Mapping job.

if the Ldap setting is omitted, DryvIQ will default to account if account querying is supported by source connection; otherwise, it will default to container.

Map_by

convention.map_by refines how to match source to destinations.

"convention:" { ... "map_by": { "id": true, "name": true, "email": true, "fuzzy": true } }

 

Option

Values

Description

Option

Values

Description

default

true/false

Optional. Enables default mapping by all fields.

Equivalent to setting all the the following to true: id, name, username, caption and email 

id

true/false

Optional. Match accounts by id.

name

true/false

Optional. Match accounts by name.

username

true/false

Optional. Match accounts by username.

caption

true/false

Optional. Match accounts by caption / display name.

email

true/false

Optional. Match accounts by email.

fuzzy

true/false

Optional. Allows for partial match on supported platforms. This would apply to all selected fields.

built_in

true/false

Optional. Allows to use built_in accounts on supported platforms.

passthrough

true/false

Optional. Allows to create child jobs for folders for which DryvIQ couldn't match an account (FS or NFS; both sides only)

external_passthrough

true/false

Optional. Allows external emails that have never been associated as a guest account to get passed through

Note: External email already associated as a guest account in OfB/O365 will work regardless of whether external_passthrough is on

ldap

true/false

Not fully supported 

 

Search Domain

convention.search_domain allows to specify domain name when matching folders without domain to email address. For example, the following setting would match folder with name 'test' to email “test@example.com.”

"convention:" { ... "map_by": { "email": true }, "search_domain": "example.com" }

 

Users

convention.users is an optional setting that defines the source the user conventions use to create the map. Valid values include sourcedestination, and ldap.

Value

Description

Value

Description

source

Use the source platform as the source of user accounts when generating the personal drive jobs.

destination

Use the destination platform as the source of user accounts when generating the personal drive jobs.

ldap

Use an ldap server as the source of the user accounts when generating the personal drive jobs.

Inclusions/Exclusions

convention.inclusions is an optional setting that limits user mapping to this list only.

 

convention.exclusions is optional setting that excludes user mappings specified in this list.

 

By default, inclusions and exclusions are applied to source users. This can by changed to use destination users.

 

Inclusion/Exclusions can be imported via CSV.

 

CSV Format

 

Inclusions for Personal Drive Matches include 3 optional fields that allow user-specific Categories, Source, and Destination Paths. When specified (via JSON or CSV), these values will override the convention values.

 

Inclusions and exclusions are mutually exclusive, meaning that either inclusions or exclusions will be used during the matching process of the job.  If both are defined during job creation, whichever is defined last is the the one that will be honored.

 

Exceptions

convention.exceptions is an optional setting that defines a map of source to destination users. This is useful where a match cannot be done automatically.

 

Path Conventions

convention.path_conventions is an optional setting that defines the source and destination paths for the account match jobs (child jobs).

 

Unmapped Policy

convention.unmapped_policy is an optional setting that determines what to do when an account cannot be mapped to a destination account.

Value

Description

Value

Description

ignore

Do not create a job for the unmapped convention.

warn

Do not create a job for the unmapped convention and log a warning in the audit log.

default

Not applicable

add

Provision the account on the destination and create the job for the mapped convention.

Remove Invalid

convention.remove_invalid is an optional flag that specifies whether to remove existing jobs that no longer have a valid convention at the source.

 

Filter by Pattern

convention.filter.pattern  is an optional setting for filtering user drive accounts by pattern. The convention.policy property specifies whether this is an inclusion or exclusion filter. If a filter policy is not specified, it defaults to exclude. The following example includes all users named user1, user2, user3, etc.

 

Filter by Metadata

convention.filter.metadata is an optional setting for filtering user-drive folders (the root folder anyway) by their metadata properties. The following example includes all items and containers whose Author metadata property equals "Angus Young.”

 

The following example shows a more complex metadata filter. It excludes all items whose Author metadata property is empty. For more examples of simple and complex filters, see Job Filters.

 

Folder Metadata

NFS and FS folders have special metadata provided by their underlying operating systems (e.g., Windows).  The property values of this metadata can be used in the metadata filters above.  Here is a description of these metadata properties:

Property Name

Property Type

Description

Property Name

Property Type

Description

ID

string

internal ID of the folder.  may not be useful

Name

string

name of the folder

Owner

string

full name of the folder's owner

CreatedBy

string

full name of the folder's creator

CreatedOn

DateTime

time of folder's creation

ModifiedBy

string

full name of the last user to modify the folder

ModifiedOn

DateTime

time of last folder modification

IsShared

boolean

indicates whether folder is shared or not

IsHidden

boolean

indicates whether the folder is hidden or not

 

Viewing the Details of a User Job Mapping Job

Inclusions/Exclusions

There is currently no flag returned indicating whether the matches list returned is used for inclusions or exclusions.

 

Exceptions

 

Updating a User Job Mapping job

Inclusions/Exclusions

New inclusions/exclusions can be added to the list.

POST /transfers/jobId/personal_drives/matches

 

The following REST API call provides the ability to remove an inclusion/exclusion from the matches list.

 

Exceptions

New exceptions can be added to the list.

POST /transfers/jobId/personal_drives/exceptions

 

The following REST API call provides the ability to remove an exception from the list.

 

 

DryvIQ Migrate Version: 5.6.2.4175
Release Date: March 7, 2024