A metadata import allows you to upload attribute information directly into Asset Bank, either to assets already in the system or to newly created assets. This may be useful for a number of purposes, such as migrating assets from another system, migrating data from one Asset Bank to another, restoring backups or offline metadata editing.

Often (for example, when migrating assets between systems) the metadata import process is preceded by a 'bulk upload', which is used to first add the asset files. Once the bulk upload is complete (and assuming the metadata import file is correctly formed - see below) a metadata import can be run to add metadata to the newly imported asset files. This 2-stage process has the advantage that the metadata can, if necessary, be imported multiple times without the need to re-upload the asset files.

See also: Step by step guide to Metadata Import and How to migrate files and metadata into Asset Bank

To perform a metadata import, a plain-text tab-delimited file is uploaded to Asset Bank via the page: Admin > Attributes > Metadata Import > Start new metadata import (if you are an Org Unit admin then the link is located in Admin > Org Units). This page allows you to select the file for upload, and also provides the following options for the import:

• Add any missing assets automatically. Selecting this will result in new asset records being created for each record found in the metadata file that does not match up with an existing record. Mostly this can be left unchecked, but when assets are being imported into Asset Bank for which there are no corresponding files (metadata-only assets) this option may be necessary.
• Add any missing categories automatically. Similarly, selecting this option will result in any imported Categories (descriptive or permissive) for which there is no match being added during the import process. This is likely to be required when migrating assets between systems if the Category information is to be preserved.
• Remove assets from existing categories and folders, if new ones are specified. If this option is selected, any Categories found in the metadata file for matching assets will replace (rather than append to) any Categories currently assigned to those assets. This may be required, for example, if the assets were originally assigned a temporary category during a preceding bulk upload.
• Skip check (import the data immediately). Normally, when you submit a metadata import the first step in the process is for the system to check the file you have uploaded and report any errors or mis-matches before you import the data. If this option is selected there will be no such check and the data will be imported without confirmation. Only choose this option if you are sure there are no problems with the file.

Data File Format 

The data file must conform to the following formatting rules:

• It must be a plain-text file (without Excel proprietary formatting).
• It must be in UTF-8 format (encoding). See how to save a tab-delimited file as UTF-8 in Excel
• All fields (columns) should be separated by a tab character.
• If any data in a column contains one or more tab or newline characters, the column data must start and end with " (double quote) characters.
• If any data in a column includes a " (double quote) it must be escaped by doubling it up. E.g. change " to ""
• Each record should start on a new line.
• The first line should contain a string defining the format of the AssetId column, for example the string: filenameFormat:none
• The second line of the file should contain the column headers that identify the fields of the record being updated. There are several standard headers for standard attributes, and you can also add headers that match your custom metadata fields. A description of how this is done can be found in the next section.
• A "file" and an "AssetId" column must be present in the imported data file to identify the record in the system. This will typically be the full 'original filename' of the asset, and the id of the asset (e.g. if reimporting a data file exported from Asset Bank). If it does contain either of these then make sure the first line of the file contains the string filenameFormat:none
• Where either the Categories or AccessLevels columns are present, data should be included as follows: separate categories should be delimited using a semi-colon (;). If the category is not at the root level, the name of its parent(s) should be included in front of its name, separated by a forward-slash (/). For example, if you have a subcategory of "Animals" called "Cats", the field value to specify this category should be "Animals/Cats". To also include this record in a "Photo" category the complete field value would be "Animals/Cats;Photo"
• Where a date is provided, it should be in the format that matches the application (by default, "DD/MM/YYYY HH:MM")

When a metadata file has been generated by the metadata export process, the first line will contain a cell with a value such as "filenameFormat:none". This tells Asset Bank how to interpret the import file when trying to match up the rows with existing assets.

• If the value of the filename format is 'none' the import process will look for assets with an Id that matches data in the AssetId column in the metadata file, OR which have a 'original filename' that matches this value.
• If the value contains filename token characters 'i', 'f' and/or 't' the import process will try to match against assets whose filenames (during the bulk upload process) match a combination of the Id, Filename and Title (aka Name, as configured in Admin > Attributes > Display Attributes).

So for example, if the first line contains "filenameFormat:it" and the Name attribute is set as Title, the import process will look for existing assets whose filename matches the data in the AssetId column followed by the data in the Title column. It will assume that these parts of the filename are delimited by a '.' character (although this delimiter can be changed by our Customer Support Team). If a match is found, the existing asset will be updated with the metadata from the import file.

Data Column Headers

Each column in the data file requires a header, entered on the first or second line of the file. These headers will either be one of the standard headers, or a custom one matching an attribute under your control. The standard headers (relating to the standard attributes) are listed below:

• accessLevels
• categories
• addedBy
• lastModifiedBy
• dateAdded
• dateModified
• assetId
• filename
• author
• approved
• expiryDate
• isPreviewRestricted (Assumed "false" if anything other than "true")

The following are some additional columns can be present, depending on the relevant functionality being enabled:

• relatedAssets (this will be a comma-separated list of assets, each identified by a name whose format matches the filenameFormat as above, or the ID of the asset if filenameFormat=none). For example, if you want to use filenames to refer to all assets then set: filenameFormat=i in the header and then put the original filename in the AssetId column and a comma separated list of 'original filenames' in the RelatedAssets column. This applies to ChildAssets and ParentAssets below.
• childAssets (as above)
• parentAssets (as above)
• agreementType (if agreements are enabled)
• agreements (as above)
• isSensitive (if asset sensitivity is enabled. Assumed "false" if anything other than "true")
• sensitivityNotes (as above)
• price
• entityName (this is the name of the Asset Type for the asset and is required if your Asset Bank makes use of multiple Asset Types)

• currentVersionToReplace Can either be an asset filename or an ID depending on the value of filenameFormat. This column represents an asset for which a new version will be created using the metadata as defined in the row. If the metadata row corresponds to an existing asset, then that asset will become a new version of the asset which matches this column. All the relationships which applied to the old asset will be replaced with the relationships of the new asset.
  
  Please note: if you are using the 'currentVersionToReplace' column to update existing assets to become older versions of an existing asset the order of the rows should reflect the order of the 'age' of the assets i.e. starting with the oldest asset and ending with the newest. The 'currentVersionToReplace' column should contain the AssetId of the 'oldest' asset version with the exception of the 'oldest' asset itself where it can be left blank. Make sure that the last row in the file is the 'newest' asset version.

In order to populate a custom attribute from the data file, the column header for the attribute must start with "att:" followed by the attribute name. For example, to populate an attribute "Title", a column header for the data must be called "att:Title". Note that the attribute name should match the name in the application exactly, including any spaces and capitalisation.

NOTE: the attributes 'Id' and 'Filename' cannot be updated.

Translated Attribute Data

When Asset Bank is set up to be multi-lingual, it is possible to provide translations for any text-based attribute values by providing additional columns with a sub-prefix of "lang_" plus the (typically 2-letter) code for the language. For example, in order to provide a translation for a Title attribute in French (code: fr) you would need to add a column with header "att:lang_fr:Title". You would have needed to set up French as a language first, but the language can be suspended whilst the import takes place.

Importing Relationships Using Attribute Values

You can use the standard columns of RelatedAssets, ChildAssets and ParentAssets to import relationships between assets using the Id or filename of the assets in question. However, it is also possible to use arbitrary attribute values to relate assets imported from the metadata file. You can do this by using the header prefixes "parent:", "child:" or "peer:", followed by the name of an attribute that is relevant in the related asset. The target attribute should in general uniquely identify the assets to link to - this technique allows the import to be independent of system generated ids or filenames.

Note: this technique will only work if the target assets are already present in the system when the import line is trying to refer to them.

Examples:

a) parent:JOB_NUMBER = 51

The system will attempt to find an asset with attribute JOB_NUMBER=51, and set that to be the parent of the imported asset.

b) child:OLD_ID = 6666,6689

The system will look for assets which have 6666 or 6689 as value for the OLD_ID attribute, and relate them to the imported asset using the child relationship.

c) peer:BATCH_SEQ = 24,25,26

The system will look for existing assets with BATCH_SEQ values in the set {24,25,26}, and will relate them to the imported asset using the peer relationship.

A small example import file (spaces represent tab characters) follows. This will set an attribute called IMAGEBASE_ID on three existing assets, then relate them all together as peers:

Description filenameFormat:none
Id att:IMAGEBASE_ID peer:IMAGEBASE_ID
27 101
28 102
29 103 101,102

Updating approval status

Asset approval statuses can be updated using the metadata import. Include the column approved in your data file with the value set as follows depending on the approval level:

• For 'full approval' specify "TRUE" in the column to approve the asset for all workflows it is involved in
• For 'submit for approval' specify "FALSE" in the data column, which will submit the asset in question for approval for any workflow it is involved in
• For 'partial approval' specify the names of the folders that the asset should be approved for as a semi-colon separated list (i.e. "Universal;Marketing" etc.). All approval statuses for folders/workflows that aren't specified will be left unchanged.

Importing Agreement Data

If agreements are enabled (agreement-enabled=true in the application settings) it is possible to import an asset's agreement data using the metadata import. This process is designed to work in tandem with the metadata export, but can be done manually if required using the following rules.

There should be a column named AgreementType, which contains one of the following values:

• '1' for 'unrestricted', i.e. needing no agreement
• '2' for 'agreement applies', in which case the Agreements column should also be populated as below.
• '3' for 'restricted', i.e. cannot be used irrespective of any agreement

Each asset that has an agreement should have a value of '2' in the AgreementType column. It should also have an xml document contained a the column named Agreements. An example of the xml document is given below, showing a situation where an asset has a current and previous agreement (first and second in the xml respectively). This example should be self-explanatory when related to Asset Bank's agreements functionality, although please get in touch if further details are required.

<?xml version="1.0" encoding="UTF-8"?>
<agreements>
    <agreement title="Current agreement" activated="18/02/2010 08:12:12" availableToAll="false" sharedWithOU="false">
        <body>
            <![CDATA[<p>This is the agreement body text</p>]]>
        </body>
    </agreement>
    <agreement title="Previous agreement" expiry="17/02/2010 00:00:00" activated="16/02/2010 13:11:17" availableToAll="false" sharedWithOU="false">
        <body>
            <![CDATA[<p>This is the previous agreement text</p>]]>
        </body>
    </agreement>
</agreements>

Spatial Area Attributes

If you have any custom attributes of type 'Spatial Area', then the values in the relevant att: column(s) are required to be in a certain format, with the following rules:

• Leave empty for an empty Spatial Area value.
• Otherwise a comma-delimited string with 4 parts in the following order: 'West bound,South bound,East bound,North bound' - there must be exactly three commas.
• Any part may be empty, otherwise a valid signed decimal degrees number.
• West and East bounds should be longitudes between -180 and 180. South and North bounds should be latitudes between -90 and 90.
• A point may be represented by populating just the West and South bounds, or making East=West and North=South.

Examples

• Bounded area: '-10.0,0.0,10.0,90.0'
• Equatorial Band: ',-10,,10'
• Points: '10,10,,', '-10.5,0,-10.5,0'.

Creating a Tab Delimited File using Excel

You can generate a tab-delimited text file from Excel by choosing "Save as..." and then selecting "Text (Tab delimited)" for the field "Save as type".

When you have generated the text file from Excel you should check it using a text editor. Use "search and replace" to replace any characters that Excel may have added to the data - for example, it often adds " (quote) characters around fields. Also check that the format of date columns is as you intended (i.e. matching the import-date-format setting).

Also see: Step by step guide to Metadata Import