Admin Object Reference

by | Jan 30, 2015 | REST Admin API |

BROWSE CATDV SUPPORT MANUALS

The Admin REST API sends and receives data formatted as JSON objects of various types. This section describes each of the different types of objects used.

API Objects

This section details the structure of the objects used by the Admin REST API.

User Object

Represents a user who can log in to the CatDV system. Each User object contains the following fields

Field Type Description
ID Integer Unique ID of user
name String User’s name
notes String Additional notes about the user
roleID Integer ID of this User’s Role
role String Name of this User’s Role

Production Group Object

Represents a Production Group in to the CatDV system. Each Production Group object contains the following fields

Field Type Description
ID Integer Unique ID of Production Group
name String Name of this Production Group
notes String Additional notes about the group
defaultPermissions String[] List of permissions that new members of this group get.

Role Object

Represents a Role, which can be thought of as a permission template that a number of users can share. Each Role object contains the following fields

Field Type Description
ID Integer Unique ID of Role
name String Name of this Role
notes String Additional notes about the Role
permissions String[] List of permissions for this Role with respect to a particular Production Group. This field is only used in contexts where the Production Group is specified, generally as an additional parameter to the REST API call.

Available Role Permissions are:

  • readOthersCatalogs – can read catalogs belonging to others.
  • createCatalogs – can create catalogs.
  • editCatalogs – can edit clips and catalog details of catalogs owned by them.
  • editOthersCatalogs – can edit clips and catalog details of catalogs owned by others.
  • deleteCatalogs – can delete catalogs owned by them.
  • deleteOthersCatalogs – can delete catalogs owned by others.
  • deleteClips – can delete clips.
  • createClips – can create new clips.
  • editTapes – can edit tapes.
  • editPicklist – can edit locked picklists.
  • editLockedFields – can edit locked fields.
  • admin – can perform administration tasks such as editing users and production groups.

Field Definition Object

Represents a, usually user-defined, field on a particular type of CatDV object (e.g. Clip, SourceMedia, Marker etc.) Each Field Definition object contains the following fields

Field Type Description
ID String Unique ID of this FieldDefinition. For built-in fields this is the familiar CatDV field short code (e.g. NM1, STS etc.). For user-defined fields it the unique numeric ID of the object.
fieldGroupID Integer Unique ID of this FieldGroup that this FieldDefinition belongs to.
memberOf String Type of object this field definition belongs to. Possible values are:

  • catalog
  • clip
  • media
  • importSource
  • marker
identifier String Unique (within the given object type) name (or ‘slug’) for this field definition.
To ensure that the identifier is unique it is generally built up from a domain-specific prefix, such as the field’s group, or the vender reverse domain, followed by a simplified version of the field’s name, with spaces converted to periods and all lowercase.For user-defined fields this value as the ‘name’ of the property in an object’s metadata object, whereas for built-in fields this value is the name of the field in the relevant object. For example the Field Definition for clip.name (NM1), would have memberOf=”clip” and identifier=”name”.
name String Descriptive name for the field. Used as the label when the field is displayed in the UI.
description String Longer description of the field. Used as the tooltip when the field is displayed in the UI.
fieldType String Type of data stored in this field and how the field should be presented to the user. Possible values are:

  • text – plain text
  • multiline – multi-line plain text field
  • date – a date
  • time – time of day
  • number – a number
  • identifier – arbitrary string
  • hidden – hidden field
  • checkbox – a checkbox
  • multi-checkbox – a set of checkboxes
  • radio – set of radio buttons
  • picklist – single value selected from a drop down list
  • multi-picklist – multiple values selected from a drop down list
  • hierarchy – single value selected from a hierarchical list
  • multi-hierarchy – multiple values selected from a hierarchical list
  • linked-multi-hierarchy – multiple values selected from a hierarchical list linked to another field
  • auto-suggest – a value which may be one selected from a list of values
  • multi-auto-suggest – multiple values which may be ones selected from a list of values
  • html – a rich formatted HTML field
isBuiltIn Boolean True if this Field Definition represents a built-in field.
canQuery Boolean True if this field can be used in a clip query.
isSortable Boolean True if this field can be used to sort the results of a clip query.
isCalculated Boolean (Only present for built-in fields). Hint to tell client that this built-in field
is not directly represented by a field on the relevant object. For example the “IO” field displays
the In timecode and the Out timecode in a single field. The value to display must therefore be calculated by the client.
isEditable Boolean True if any user can edit this field (assuming they have the necessary permissions).
isMandatory Boolean True if the user must enter a value in this field.
isMultiValue Boolean True if multiple values can be stored against this field. This is a calculated field based on the type of the field.
isList Boolean True if a list of possible values is associated with this field. This is a calculated field based on the type of the field.
values String[] For list fields this field can optionally be populated with all the list values.

Picklist Object

Represents the list of values for fields where the user selects a value from a list (e.g. picklist, hierarchy etc.).
Each View Set object contains the following fields (Note that not all client support all options):

Field Boolean Description
isExtensible Boolean True is user is allowed to enter values that are not in the list.
isKeptSorted Boolean Values are kept sorted in alphabetical order.
savesValues String[] Non-list values get added to the list.
isLocked Boolean Only administrators can add values.
values Integer The list of values.

View Set Object

Represents a set of views (ViewDefinitions) where each view may be a list a grid or filmstrip. View Sets exists to make it easier to manage which views should appear under what situations. For example one might wish to define one View Set that defines the views that appear for a particular
Production Group, or one a particular type of client (e.g. Web or iOS). Each View Set object contains the following fields

Field Type Description
ID Integer Unique ID of this ViewSet.
name String Name of this ViewSet.
description String Longer description of this ViewSet.
visibility VisibilityRules Set of rule that determine when this ViewSet should be displayed.
order Integer Used to specify the position that this ViewSet will appear in lists of ViewSets.
views ViewDefinition[] List of the ViewDefinitions that make up this View Set.

View Definition Object

Represents the fields to be displayed with each item in a list, grid or filmstrip list of clips.
Note that currently only the desktop CatDV client supports all the available view options. The Web Client and Web 2 interface currently only support customisation of Normal, Concise and Full views.

Each View Definition object contains the following fields

Field Type Description
ID Integer Unique ID of this ViewDefinition.
name String Name of this ViewDefinition.
description String Longer description of this ViewDefinition.
type String What type of panel or view does this ViewDefinition define. Possible values:

  • builtin – a built-in CatDV view
  • list – a tabular list view
  • grid – a grid view
  • list – a filmstrip view
options JSONObject Set of options that can be applied to the various view types. Possible values are:

  • list
    • spacing – normal or wide
  • grid
    • size – small, medium, large or huge
    • text – none, right or below
  • filmstrip
    • size – small, medium or large
    • allThumbnails -true or false
    • poster -true or false
visibility VisibilityRules Set of rule that determine when this ViewDefinition should be displayed.
order Integer Used to specify the position that this ViewSet will appear in lists of ViewSets.
fields ViewField[] List of the ViewFields that make up this View Definition.

View Field Object

Represents an individual fiels within the view. Each View Field object contains the following fields:

Field Type Description
ID Integer Unique ID of this ViewSet.
viewDefID Integer ID of the containing ViewDefinition.
fieldDefID Integer ID of the FieldDefinition of the field.
fieldDefinition FieldDefinition Optionally a copy of the FieldDefinition object for this field.

Panel Set Object

Represents a set of panels (PanelDefinitions). Panel Sets exists to make it easier to manage which panels should appear under what situations. For example one might wish to define one Panel Set that defines the panels that appear for a particular Production Group, or one a particular type of client (e.g. Web or iOS). Each Panel Set object contains the following fields

Field Type Description
ID Integer Unique ID of this PanelSet.
name String Name of this PanelSet.
description String Longer description of this PanelSet.
visibility VisibilityRules Set of rule that determine when this PanelSet should be displayed.
order Integer Used to specify the position that this PanelSet will appear in lists of PanelSets.
panels PanelDefinition[] List of the PanelDefinitions that make up this Panel Set.

Panel Definition Object

Represents the fields to be displayed on the panel (tab). Each Panel Definition object contains the following fields

Field Type Description
ID Integer Unique ID of this PanelDefinition.
name String Name of this PanelDefinition.
description String Longer description of this PanelDefinition.
type String What type of panel or panel does this PanelDefinition define. Possible values:

  • builtin – a built-in CatDV panel
  • normal– a normal CatDV metadata panel
  • html– a read-only formatted HTML panel
visibility VisibilityRules Set of rule that determine when this PanelDefinition should be displayed.
order Integer Used to specify the position that this PanelSet will appear in lists of PanelSets.
fields PanelField[] List of the PanelFields that make up this Panel Definition.

Panel Field Object

Represents an individual fiels within the panel. Each Panel Field object contains the following fields:

Field Type Description
ID Integer Unique ID of this PanelSet.
panelDefID Integer ID of the containing panel.
fieldDefID Integer ID of the FieldDefinition of the field.
readOnly Boolean True if user is not allowed to edit this field.
hideIfBlank Boolean True if field should be hidden if it is blank.
spanTwoColumns Boolean True if field show span two columns.
multiline Boolean True if field should be displayed over multiple lines
fieldDefinition FieldDefinition Optionally a copy of the FieldDefinition object for this field.

Visibility Rules

The visibility of View and Panel Sets and Definitions is controlled by a set of Visibility Rules stored against
each item. Each set of Visibility Rules contains three sets of rules:

  • Production Group Rules – relate to a catalog’s Production Group
  • User Role Rules – relate to the user’s Role.
  • Client Rules – relates to the current client:
    • CDV – CatDV Desktop Client
    • WC1 – CatDV Web Client
    • WC2 – CatDV Web 2
    • IOS – CatDV iOS Apps
    • TRI – CatDV Tricaster Plug-in
    • PRE – CatDV Premiere Pro Plug-in

Each set of rules consists of two lists:

  • Visible To – item is visible to the groups, roles or clients in this list
  • Hidden From – item is hidden from the groups, roles or clients in this list

Note: If a ‘visible to’ list is empty then the item is always visible.

Each Visibility Rule object contains the following fields:

Field Type Description
visibleToGroups String[] List of Production Groups that this item is visible to.
hiddenFromGroups String[] List of Production Groups that this item is hidden from.
visibleToRoles String[] List of Roles that this item is visible to.
hiddenFromRoles String[] List of Roles that this item is hidden from.
visibleToClients String[] List of Clients that this item is visible to.
hiddenFromClients String[] List of Clients that this item is hidden from.

Media Store Object

Represents a logical storage volume where media is held. Each store contains one or more Media Paths that
refer to physical locations on shared storage. Each Media Store object contains the following fields:

Field Boolean Description
name String Name of this Media Store.
paths MediaPath[] List of Media Paths contained by this Media Store.

Media Path Object

Represents a location on shared storage where a particular type of media is held (e.g. hi-res, proxy etc.) as seen by a particular type of client (e.g. Windows, Mac OS etc.). For example, if a location
on shared storage was mounted on Mac clients as /Volumes/SAN/Media, but on Windows machines
as \sanmedia, then you would store two paths, one targeting client.win and one targeting client.mac.

Each Media Path object contains the following fields:

Field Boolean Description
mediaStoreID Integer ID of containing Media Store.
path String Path of this location.
mediaType String Type of media stored at this location:

  • hires – original hi-resolution media
  • proxy – lower-resolution proxy media
  • proxy.web – lower-resolution proxy encoded for web use
target String Target machine/service that this path is intended for.

  • client – Path as seen by CatDV Desktop Client (with optional .mac, .win or .http suffix)
  • web – URL that can be accessed from a browser
  • worker – reserved for future use
  • server – path as seen by Server
  • anywhere – eamedia path as seen by Anywhere Server
pathOrder Number Sort of paths – defines priority where multiple candidate paths exist.