Elvis 5 API - The basic data model

The basic object model in Elvis is very simple, it contains:

• assets
• collections
• relations
• folders

Assets

Each file imported in to the server is called an asset. Each asset has metadata, which is a flat list of property names with a value.

Each metadata property has a unique name. For each metadata field, the server knows:

• how to handle it when indexing and searching,
• what type of data it contains (text, number, date, ...),
• how it is embedded in certain file types,
• and so on...

Elvis has a long list of standard metadata fields that are commonly used in a DAM system, and it already knows how to handle these. If none of these fields suits your needs, you can create as many additional custom metadata fields as you need.

Collections

Collections are assets like all other files. This means they can have metadata and can be searched for as normal assets can be. The contents of a collection are defined by 'contains' relations linking to the contained assets.

Relations

Relations are 'links' between assets. A relation knows both of the assets that it links together. This means a relation can always be discovered from both ends of its link.

For more information, see How files are related to each other in Elvis DAM.

Asset path

The location of each asset is described in the assetPath metadata property. It describes the location of an asset relative to the root:

/Demo Zone/Images/Beaches/Kauai.jpg

An assetPath always starts with a slash and never ends with one. It always uses forward slashes to separate folders (also on Windows), similar to a URL.

Note: The assetPath is stored as metadata of an asset and has no relation to how the it is stored on the file store.

Folders

Folders are a representation of the segments of the assetPath. The folders are stored in the index only and have no relation to what is actually stored on the file store.

How Elvis knows where to store a file

When you import and create assets in Elvis using the API, there are several combinations of metadata that can be specified to build up an assetPath and determine where the file will be stored. The following table indicates the various ways in which this info can be specified. If none of these combinations are available, the server will not be able to create the asset.

	Asset path	File name	Name	Asset type	Extension	Folder path
Case 1: assetPath	specified	ignored	ignored	ignored	ignored	ignored	When assetPath is specified, the other fields are ignored, instead they are calculated.
Case 2: filename	not specified	specified	ignored	ignored	ignored	optional	The filename provides enough info the calculate the assetType, extension and name. When no folderPath is specified the system will place the file in a default location (<user-security-zone>/auto-stored/<year>/<yyyyMMdd>/)
Case 3: name	not specified	not specified	specified	specified /optional	specified /optional	optional	When only a name is specified and no folderPath is specified, either assetType or extension should be specified.
Case 4: (invalid)	not specified	not specified	not specified	ignored	ignored	ignored	When none of assetPath, filename or name is specified, the asset cannot be created.

Auto-organize behavior

Within root folders, you can create as many subfolders as you want to organize your content.

The actual location of the file is not important, people or automated processes may just dump all files in one place. After all, even without knowing where it is stored, assets can easily be found using the search engine, the metadata or text content of assets.

Depending on the file system that is used, there may be limits to how many files can be stored efficiently in a single folder. To prevent too many files from being imported into top-level folders, the server uses a few simple mechanisms to automatically organize files that are dumped into the system without specifications.

Top-level folders

If an asset is imported into a top-level folder, it will automatically be moved to the "Auto organized" folder. For example if the user tries to import a file to one of these location:

/Zone A

/Zone A/Auto organized

The system will automatically create a folder for the current day and store the assets in there:

/Zone A/Auto organized/2011/2011-01-18

This also works in the root of each users private user folder:

/Users/<username>/Auto organized/2011/2011-01-18

When you import assets into a specific subfolder, auto-organize is not used.

The root and /Users folder

The root and Users folder are off-limits to anyone. If someone tries to import a file into the root folder ("/") or into the /Users folder, this is considered a mistake and the file will instead be imported to the private folder of that user (/Users/<username>/Auto organized/...).

Document history

• 5 November 2018: Updated section 'Folders'.
• 5 November 2018: Added a note to section 'Asset path'.