Metadata Upload

Introduction

When uploading files into Aprimo DAM, you can also upload the metadata that’s associated with those files. Use a comma-separated values (CSV) file to store this metadata associated with files, e.g. field values, properties, classifications, etc.

Metadata upload is supported in two scenarios:

  1. File upload using the PowerShell Script for File Uploads
  2. File upload through the REST API.

Use cases

Metadata upload can be used in the following situations:

Bulk ingestion

You have a folder full of files you want to upload and you have exported metadata for these files from an external system.

In this case, it’s recommended to use the PowerShell Script for File Uploads and pass the metadata file and metadata schema as a parameter. The files and their related metadata will be saved as new records.

Hotfolder

You want users to add files to a hotfolder, together with a CSV file containing the metadata. The files and the metadata should be automatically uploaded to Aprimo DAM.

You can set up a scheduled task to run the PowerShell Script for File Uploads every hour (or more often, whatever is preferred) and pass only the metadata schema to the script as a parameter. You can add a metadata file to the Hotfolder or pass it to the script as a parameter. The files and related metadata will be added to new records.

Upload through REST

To upload files together with associated metadata in a CSV file, you can create your own custom code using the REST API, with the following logic:

  • upload the CSV file, receive a token (like with any other file upload)
  • upload the image, receive a token (like with any other file upload)
  • create a new record using REST, adding the image token, the CSV file token and the name of the schema to be used.

Prerequisites

In order to use the metadata upload, you should make sure that:

  • all files to be uploaded have a unique filename
  • the CSV file with the metadata has the correct format
  • Aprimo DAM contains an XML schema that defines how to parse the CSV file

The following field definition types are supported for Metadata Upload:

  • Text
  • Numeric
  • Duration
  • Date
  • Time
  • DateTime
  • Option List
  • Text List
  • Classification List

The following field scopes are supported for Metadata Upload:

  • Record Content – Global
  • Record Content – Class Dependent
  • Record Content – Floating
  • Record – Content Type Dependent

CSV file

The metadata file should be a Comma-Separated Values file, with these specifications:

  • The first row should be column headers, separated by a semicolon.
  • Field values should be surrounded by quotes, each set again separated by a semicolon. If you want to provide multiple values for one field, separate the values with a comma.
  • One column must always contain the filenames of the files that are being uploaded, and the schema definition should point to the CSV’s filename column with the isFilter.
  • The CSV file may contain more columns than the schema (column nodes) or the record (fields/properties). In that case the extra columns will simply be ignored.

An example of a metadata CSV file:

 FileName;ProductNr;Stock;ProductName;ManufactorDate;Colors
 "france.jpg";"2";"100";"Product 1";"02/05/2017";"Blue,Green"
 “germany.jpg”;”4”;”99”;”Product 2”;”30/04/2017”;"Red,Yellow"

An example of the column node in the schema, with the isFilter parameter set to true for the FileName column.

 <column name="FileName" type="property" value="Files.LatestMaster.FileName" isFilter="true" />

Using this setup:

  • Aprimo DAM will save the file france.jpg in a new record. As a consequence, the Files.LatestMaster.FileName of that record has the value france.jpg.
  • It will then check the schema: the FileName column will be used to find the right row in the CSV file, being the row where the FileName (france.jpg) corresponds to Files.LatestMaster.FileName property of the record (france.jpg).
  • The other columns of this row are associated with the record’s fields and properties, as specified in the schema.

Field data types

Time and DateTime fields

When uploading values for Time or DateTime fields, the values will be interpreted according to the culture of the user that performs the upload. More concretely, when uploading the date 03-05-2018, it will result in:

  • March 5th, 2018 if the user has the culture en-US
  • May 3d, 2018 if the user has the culture nl-BE.

Classification List fields

When uploading values for Classification List fields, you can use either the classification Id (guid) or the full label path as values. When providing multiple classifications, separate them with a comma, e.g.
“/DAM/Images/Stock photos, /Types/Document”.
The label path offered in the metadata file should be relative to the root that was chosen in the Classification List field, and also in the UI language of the user running the import process, e.g.

if an Italian label path is offered, while the user running the process has English as UI language, the classification will not be found and will not be added as value to the Classification List field.

Option List fields

When uploading values for Option List fields, you have to use the option label as value, not the name. The label in the metadata file should be in the UI language of the user running the import process.

Schema

The XML schema for Metadata Upload is accessible in Aprimo DAM’s System, in the XML Setting .dataExchangeSchemas (setting category Data Exchange Schemas). See the Administrator Guide for more information.

Use

Metadata upload is supported in two scenarios:

  1.  PowerShell Script for File Uploads
  2. File upload through the REST API.

PowerShell Script for File Uploads

In order to use Metadata Upload in combination with the PowerShell Script for uploads, you must specify the MetaDataSchemaName parameter in the command.

If you don’t provide an explicit path as a parameter, the script will assume that the metadata file is in the same folder as the files that need to be uploaded. See Script execution of the PowerShell Script for File Uploads.

Tip: when using a scheduled script, it’s recommended to place the metadata CSV file in the upload folder before copying over the files that should be uploaded. This avoids that the upload starts importing files before the metadata file is present. In that case the upload script will create records without metadata.

Apply metadata file through REST

You can upload a metadata file for a record by

  1. First uploading the metadata file through REST or the Upload Service. Once completed, you will receive an upload token.
  2. Use the received token in a Record create or modify call by setting the metadata object property. This metadata object should contain 2 properties, name and token. The name refers to the schema in .dataExchangeSchemas. The token refers to the token received when uploading the metadata file.
POST /record
"metadata": {
"name": "example1",
"token": "NzZBN0Y0NDctRjQyMy00NTJDLThDNEMtMUY4MkQ0MjA4OUU0"
}

See the REST API documentation for more information.