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.

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. 

{
  "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.  

{
    "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.  

{
    "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. 

{
  "name":"{{account_map_name}}",
  "unmapped_policy": "add",
  "map_by": {
        "email": false,
        "username": true,
        "caption": true,
	    "external_passthrough": false
   }
}

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."

GET {{url}}v1/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.

DELETE {{url}}v1/account_maps/{{account_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. 

	"convention:" {
    	...
		"unmapped_policy": "warn"
	}

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.

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).

{
  "name":"{{account_map_name}}",
  "type": "account_map",
  "unmapped_policy": "default",
  "destination": {
    "default": {
      "id": "{{default_account_id}}",
      "name": "{{default_account_name}}",
      "email": "{{default_account_email}}",
      "username": "{{default_account_username}}"
    }
  }
}

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.

{
    "name": "{{group_map_name}}",
    "type": "group_map",
    "source": {
        "connection": {
            "id": "{{connection_id}}"
        }
    },
    "destination": {
        "connection": {
            "id": "{{connection_id}}"
        }
    },
    "unmapped_policy": "warn",
    "map_by": {
        "default": true
    }
}

Default Group Example

{
    "name": "{{group_map_name}}",
    "type": "groups_map",
    "source": {
        "connection": {
            "id": "{{connection_id}}"
        }
    },
    "destination": {
        "default": {
            "id": "{{default_group_id}}",
            "name": "{{default_group_name}}",
            "caption": "{{default_group_caption}}",
            "type": "group"
        }
    },
    "unmapped_policy": "default"
}

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

• Permissions | Account Map/Group Map

• Account Map / Group Map | Exceptions

• Account Map / Group Map | Exclusions

• Account Map / Group Map | CSV File Guidelines