Metadata Mapping Using REST API
Learn how to map metadata for a migration job using the DryvIQ REST API.
Written by Andrea Harvey
Updated at May 2nd, 2025
Table of Contents
Overview
Use metadata mapping to associate a set of properties in a file whose values you would like to transfer between the source and destination. You provide a set of metadata properties between the source and destination. When a file is transferred from source to destination (or vice versa), its property values are also transferred based on the defined map.
If a library requires specific metadata but the metadata is missing from a file being copied into the library, the file will be flagged and will not transfer on subsequent job runs. If you have files stuck in a flagged state due to missing metadata, you may need to transfer the files and add the required metadata manually.
Metadata Map
You can define a transfer job's metadata mapping in a job's transfer options JSON object.
| Property | Description |
|---|---|
| schemas | A list of metadata schemas. |
"metadata_map": {
"schemas": [
{
"mappings": [
{
"source": {
"property": {
"type": "string",
"name": "Text"
}
},
"destination": {
"property": {
"type": "string",
"name": "Text"
}
}
}
]
}
]
}Schema Mapping ("schemas" in Metadata Map)
A schema mapping defines a metadata mapping between the source and destination. You can provide a source and/or destination schema ID so the transfer engine can retrieve additional schema information about the properties in the mapping from the platform provider.
Whether metadata from one schema or multiple schemas per file is imported is dependent on the platform. If the platform supports multiple schemas, the metadata from multiple schemas will be imported. In the case of Office 365, where only one schema is supported, the metadata importer first looks for custom metadata fields and then for metadata in the order specified in the schemas block.
| Property | Description | Example |
|---|---|---|
| source | The source schema definition to use in this mapping. When specified, it is used to load type information for all properties in the schema. | |
| destination | The destination schema definition to use in this mapping. When specified, it is used to load type information for all properties in the schema. | |
| default | Defines the schema as the fallback schema to use when mapping properties from source to destination if a mapper that matches the specified schema is not found. | |
| mappings | A list of property associations between the source and destination. You can provide the type of property, though it is not required. | |
Property Definition Mapping ("mappings" in Schema)
A property definition mapping defines the map between a source and destination property.
| Property | Description | Example |
|---|---|---|
| source | The source property. | |
| destination | The destination property the source maps to. | |
| choices | A map of choices. This is used when the property is a choice of values (e.g. yes, no) and you need to map these values between the source and destination because they differ. | |
Property Choice ("choices" in Property Definition Mapping)
A property choice defines the map between a source and destination choice value. For instance, if the property has valid values of true/false in the source and yes/no in the destination, you can use a property choice to map them respectively.
| Property | Description | Example |
|---|---|---|
| source | The name and value of the source. | |
| destination | The name and value of the destination. | |
Property Value Map ("source" and "destination" in Property Definition Mapping)
A property value map defines the actual property to map to (in either the source or destination) and specifies the actions to take when a value is missing or invalid during transfer.
| Property | Description | Valid Values | Example |
|---|---|---|---|
| property | The property to map to. | |
|
| when_missing | Action to take when the property value is missing during transfer. |
skip default (default value) calculate fail |
|
| when_invalid | Action to take when the property value is invalid or cannot be coerced to the destination type during transfer. |
fail (default value) warn skip default |
|
Property Definition ("property" in Property Value Map)
| Property | Description | Valid Values | Example |
|---|---|---|---|
| name | The name of the property. This is the only required field. You can alternatively use query_name, id or caption. | |
|
| type | An optional type. This is optional and typically provided by the schema definition from the platform if the schema id is specified in the schema mapping. |
unknown (default value) boolean id integer datetime decimal html string uri lookup account |
|
Example JSON
{
"name": "Box -> Sharepoint (Metadata)",
"kind":"transfer",
"transfer":{
"transfer_type": "copy",
"source": {
"connection": {
"id": "36405b306fe84df69d55e007ed27967e",
},
"target": {
"path": "/Source"
}
},
"destination": {
"connection": {
"id": "92edba5e132645dda035580bfb14a063",
},
"target": {
"path": "/Metadata Test/Destination"
}
},
"audit_level": "trace",
"performance": {
"parallel_writes": {
"requested": 2
}
},
"metadata_map": {
"schemas": [ {
"mappings": [ {
"source": {
"property": {
"name": "Text"
}
},
"destination": {
"property": {
"name": "Caption"
}
}
}]
}]
}
},
"schedule":{
"mode":"manual"
}
}Example JSON: Box to Office 365
This example includes custom metadata and template metadata from Box to Microsoft Office 365. First, the metadata columns must be defined in the library to import metadata into Microsoft Office 365. The table below identifies the source metadata from Box. It lists the template name followed by the metadata field name.
| Files | custom_attribute1 | Legal|Affiliates | Legal|Classification | Legal|Agreement Type | Presales - RFI Response Archive|Initiative |
|---|---|---|---|---|---|
| file1 | custom attribute1 value1 | ||||
| file2 | custom attribute1 value2 | Talbot Underwriting Ltd | Restricted | Europe Distributor | |
| file3 | custom attribute1 value3 | Data Warehousing | |||
| file4 | custom attribute1 value4 | Ross Products; Abbot Diabetics Care | Restricted | Partner | Data Replication |
| file5 | AMES | Restricted | Cloud | ||
| file6 | Agility Logistics Ltd | Restricted | License | Data Quality | |
| file7 | Master Data Management |
The table below identifies the destination metadata on Microsoft Office 365. The schemas will be imported in the order of custom, Presales, and Legal.
| Files | custom_attribute2 | Affiliates | Classification | Agreement Type | Initiative |
|---|---|---|---|---|---|
| file1 | custom attribute1 value1 | ||||
| file2 | custom attribute1 value2 | ||||
| file3 | custom attribute1 value3 | ||||
| file4 | custom attribute1 value4 | ||||
| file5 | AMES | ||||
| file6 | Restricted | License | Data Quality | ||
| file7 | Master Data Management |
{
"name": "metadata mapping BOX -> O365",
"kind": "transfer",
"transfer":
{
"metadata_map": {
"schemas": [
{
"mappings": [
{
"source": {
"property": {
"name": "Initiative"
}
},
"destination": {
"property": {
"name": "Initiative"
}
}
}
],
"source": {
"id": "Presales - RFI Response Archive"
}
},{
"mappings": [
{
"source": {
"property": {
"name": "Affiliates"
}
},
"destination": {
"property": {
"name": "Affiliates"
}
}
},{
"source": {
"property": {
"name": "AgreementType"
}
},
"destination": {
"property": {
"name": "Agreement Type"
}
}
},{
"source": {
"property": {
"name": "Classification"
}
},
"destination": {
"property": {
"name": "Classification"
}
}
}
],
"source": {
"id": "Legal"
}
},{
"mappings": [
{
"source": {
"property": {
"name": "custom_attribute1"
}
},
"destination": {
"property": {
"name": "custom_attribute2"
}
}
}
]
}
]
},
"source":
{
"connection":
{
"id": "a7410cdc3d0c4d649b4544d98388d726"
},
"target": {
"item": {
"root": true,
"name": "Box -> O365 - Metadata"
}
}
},
"destination":
{
"connection":
{
"id": "a92c9e36b52d44488168bcbd3a8dcfd5"
},
"target": {
"path": "/Documents/Box -> O365 - Metadata"
}
}
},
"schedule": {
"mode": "manual"
}
}If multiple versions of a file exist and are uploaded during the same job run, only the most current metadata is preserved and applied to all versions of the file being uploaded during that job run.