Metadata field groups [VC 21.3 GEN]

Field groups are named sets of fields and groups. The structure of groups is defined using a metadata schema.

Access to field groups can be restricted using access controls.

Managing field groups

List all field groups

GET /metadata-field/field-group

Retrieves all metadata field groups known by the system.

Query Parameters:	content (boolean) – `true` - Return the groups and their members. `false` (default) - Return the group names only. traverse (boolean) – `true` - Traverse any sub-groups in order to retrieve the entire hierarchy. `false` (default) - Only retrieves the names of the members. data (string) – Comma-separated list of any additional data to include. accepts wildcard characters. e.g. ``, `myapp_`, `*_version`. (New in 4.17.)
Produces:	application/xml, application/json – MetadataFieldGroupListDocument text/plain – CRLF-delimited list of field group names.
Role:	_metadata_field_group_read

Create an empty field group

PUT /metadata-field/field-group/(group-name)

Creates a new group with the given name. If a group with that name already exists, this operation does nothing.

Status Codes:	200 OK – Group created successfully.
Role:	_metadata_field_group_write

Update or create a field group

PUT /metadata-field/field-group/(group-name)

Creates a new group with the given name, if it does not already exists, and adds any specified fields and access control entries to it. If the fields does not exist, they will be created. Furthermore any additional data for the fields will be set as well.

Query Parameters:	clear (boolean) – `true` - If the group already exists, clear all content from it before updating. `false` (default) - If the group already exists, append child groups/fields from the input document.
Status Codes:	200 OK – Group created successfully.
Accepts:	application/xml, application/json – MetadataFieldGroupDocument
Role:	_metadata_field_group_write

Example

PUT /metadata-field/field-group/myfieldgroup
Content-Type: application/xml

<MetadataFieldGroupDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <data>
    <key>myextradata</key>
    <value>Extradata for the group</value>
  </data>
  <field>
    <name>title</name>
    <data>
      <key>text</key>
      <value>Here is some text.</value>
    </data>
  </field>
  <field>
    <name>durationSeconds</name>
  </field>
  <field>
    <name>this_field_does_not_exist_yet</name>
    <type>string</type>
    <data>
      <key>myextradata</key>
      <value>Some additional data</value>
    </data>
  </field>
  <access>
    <user>admin</user>
    <permission>DELETE</permission>
  </access>
</MetadataFieldGroupDocument>

200 OK

Delete a field group

DELETE /metadata-field/field-group/(group-name)

Deletes the group with the given name.

Status Codes:	200 OK – Group deleted successfully. 404 Not found – No group with that name exists.
Role:	_metadata_field_group_write

Group contents

List all fields of a group

GET /metadata-field/field-group/(group-name)

Retrieves the specified field group.

Query Parameters:	includeValues (boolean) – Return the value enumeration for each field. Default is `false` traverse (boolean) – `true` - Traverse any sub-groups in order to retrieve the entire hierarchy. `false` (default) - Only retrieves the names of the members. data (string) – Comma-separated list of any additional data to include. accepts wildcard characters. e.g. ``, `myapp_`, `*_version`. (New in 4.17.)
Produces:	application/xml, application/json – MetadataFieldGroupDocument
Role:	_metadata_field_group_read

Add a field to a group

PUT /metadata-field/field-group/(group-name)/(field-name)

Adds the field with the specified name to the group. If the field is already contained within the group this operation does nothing.

Status Codes:	200 OK – Field added successfully.
Role:	_metadata_field_group_write

Remove a field from a group

DELETE /metadata-field/field-group/(group-name)/(field-name)

Removes the field with the specified name from the group.

Status Codes:	200 OK – Field removed successfully. 404 Not found – No field with that name is contained within the group.
Role:	_metadata_field_group_write

Add a group to a group

PUT /metadata-field/field-group/(parent-group-name)/group/(child-group-name)

Adds the group with the specified name to the group. If the group is already contained within the group this operation does nothing.

Status Codes:	200 OK – Group added successfully.
Role:	_metadata_field_group_write

Remove a group from a group

DELETE /metadata-field/field-group/(parent-group-name)/group/(child-group-name)

Removes the group with the specified name from the group.

Status Codes:	200 OK – Group removed successfully.
Role:	_metadata_field_group_write

Searching for field groups

Search for groups used in metadata

PUT /metadata-field/field-group

Much like searching for items, specific fields can be used when searching. The result is a list of used metadata groups that matches the query. Optionally the definition of the group and the value of the group can be retrieved.

Results will only be returned if field group indexing has not been disabled.

Query Parameters:	first (integer) – From the resulting list of items, start return list from specified offset. Default is `1`, start return list from beginning. number (integer) – The number of entities to fetch. Default is `100`. traverse (boolean) – `true` - Traverse any sub-groups in order to retrieve the entire hierarchy. `false` (default) - Only retrieves the names of the members. data (string) – Comma-separated list of any additional data to include. accepts wildcard characters. e.g. ``, `myapp_`, `_version`. (New in 4.17.) group* (string) – Comma-separated list of group names to restrict search in. includeValue (boolean) – `true` - The value is included in the result. I.e., how the group is specified in the metadata. `false` (default) - The value is not included. includeDefinition (boolean) – `true` - The definition of the group is included in the result. `false` (default) - The definition is not included. includeSource (boolean) – `true` - Information about which entity that contains the matching metadata group is included in the result. `false` (default) - Entity information is not included. source (string) – `item` - Only search for groups in item metadata. `collection` - Only search for groups in collection metadata. `global` - Only search for groups in the global metadata. `document` - Only search for groups in the document metadata.
Accepts:	application/xml, application/json – MetadataFieldGroupSearchDocument
Produces:	application/xml, application/json – MetadataFieldResultDocument
Role:	_item_search

Example

Searching for employees named Andrew (please note that the parameter group is set to employee to only search for employees named Andrew):

PUT /metadata-field/field-group?includeValue=true&includeDefinition=true&traverse=false&group=employee&includeSource=true
Content-Type: application/xml

<MetadataFieldGroupSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <name>example_name</name>
    <value>Andrew</value>
  </field>
</MetadataFieldGroupSearchDocument>

<MetadataFieldResultDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <hits>1</hits>
  <group name="employee" uuid="db26c542-3507-4d3c-a772-55d4627b3d59" start="-INF" end="+INF">
    <value uuid="db26c542-3507-4d3c-a772-55d4627b3d59" user="admin" timestamp="2011-01-10T12:30:01.483+01:00" change="VX-11">
      <name>employee</name>
      <field uuid="82738de5-8ce3-4f28-badc-c97924bb5837" user="admin" timestamp="2011-01-10T12:30:01.483+01:00" change="VX-11">
        <name>example_title</name>
        <value uuid="552f5d06-50d5-4109-9017-8b8ce7d101ff" user="admin" timestamp="2011-01-10T12:30:01.483+01:00" change="VX-11">Editor</value>
      </field>
      <field uuid="9ff7fced-4500-4d11-a8e9-eb8821b42cbc" user="admin" timestamp="2011-01-10T12:30:01.483+01:00" change="VX-11">
        <name>example_name</name>
        <value uuid="45379c11-b30a-4b6c-a93a-eb5229a61905" user="admin" timestamp="2011-01-10T12:30:01.483+01:00" change="VX-11">Andrew</value>
      </field>
    </value>
    <definition>
      <name>employee</name>
      <schema min="0" max="-1" name="employee"/>
      <field sortable="false">
        <name>example_title</name>
        <schema reference="false" min="0" max="1" name="example_title"/>
        <type>string</type>
      </field>
      <field sortable="false">
        <name>example_name</name>
        <schema reference="false" min="1" max="1" name="example_name"/>
        <type>string</type>
      </field>
    </definition>
    <source>
      <id>VX-15</id>
      <type>item</type>
    </source>
  </group>
</MetadataFieldResultDocument>