Quick Start - CTMS resources overview

Link rel prefixes

The CTMS API uses different prefixes for HAL links and resources for different functional areas:

aa: functionality for assets.
loc: functionality for the folder structure of a system.
protection: functionality for protecting assets and folders, like, for example, reservations in Avid Production Management.
relations: functionality for different kinds of relations between assets.
datamodel: functionality for the data model of a system.
taxonomies: functionality for taxonomies.
pa: specific functionality for Avid Production Management and MediaCentral | Production Management.
ma: specific functionality for MediaCentral | Asset Management.
ia: specific functionality for MediaCentral | Newsroom Management.

This page gives an overview of two of the core resources in CTMS: assets and items in the folder structure.

Assets: aa:asset

The CTMS representation of an asset is the aa:asset resource.

An asset is identified by the property "base" containing a quadruple of sub properties:

systemType: identifies the system type. For Avid Production Management this is always "avid-pmplus".
systemID: identifies the concrete system. For Avid Production Management it is a GUID that identifies the workgroup.
type: the type of the asset. Typical values are, for example, "masterclip" or "sequence".
id: identifies the asset. In Avid Production Management this is the MOB ID of the asset.

It has a set of common attributes and status values as properties. It contains a number of HAL links for all the information about an asset, including, for example, the raw attributes of the asset, time-based annotation like markers and restrictions, information about the thumbnail, relations to other assets, the data model for the asset, and more.

Folder structure: loc:item

The CTMS representation of an item in a folder is the loc:item resource. An item can be either a folder or a reference to an asset. An item is a folder if it contains a loc:collection link.

Folders

For a folder, the loc:item resource has a loc:collection link to the collection with the content of the folder.

The loc:collection resource is often embedded automatically. It again has a link loc:item with an array of URIs for the items in the collection and the content is also often embedded automatically.

For example, if you use the loc:item-by-id link to query a folder, you will receive a loc:item resource with the following structure:

common: common attributes with, for example, the name of the folder
_embedded:
- loc:collection: embedded loc:collection resource with the content of the folder
  - _links:
    
    loc:item: array of URIs of the items in the folder
  - _embedded:
    
    loc:item: array of embedded loc:item resources of the items in the folder

The entry point to the folder structure of the Avid Production Management system is the loc:root-item link that references the loc:item resource for the root folder.

A folder is identified by the property base containing a quadruple of sub properties:

systemType: identifies the system type. For Avid Production Management this is always "avid-pmplus".
systemID: identifies the concrete system. For Avid Production Management it is a GUID that identifies the workgroup.
type: the type of the folder. Most of the folders use "folder" as type, but a few special folders have their own type.
id: identifies the folder. In Avid Production Management this is the path of the folder with leading and trailing slash. Example: "/Projects/IPWS/".

Asset references

For a reference to an asset, the loc:item resource has a loc:referenced-object link with the URI of the aa:asset resource for the asset.

A reference to an asset is identified by the property base containing a quadruple of sub properties:

systemType: identifies the system type. For Avid Production Management this is always "avid-pmplus".
systemID: identifies the concrete system. For Avid Production Management it is a GUID that identifies the workgroup.
type: usually "folder-item".
id: identifies the reference to the asset in the folder. In Avid Production Management this is the path of the folder, followed by the MOB ID of the asset. Example: "/Projects/IPWS/060a2b340101010101010f0013-000000-e9850ae512384717-99486330bb6d-77f0".

Navigate between assets and asset references

There are two links that can be used to navigate between the asset space ("aa:" prefix) and the folder space ("loc:" prefix):

If you have a loc:item resource with the reference to an asset, you can use the loc:referenced-object link to get the aa:asset resource of the asset.
If you have an aa:asset resource, you can use the loc:referencing-items link to get the loc:item resources of all references to this asset that exist in all of the folders of the tree structure.

Previous page: HAL

Up: Quick start

Next page: Error handling