Document metadata [VC 21.3 GEN]

Document metadata is similar to global metadata but instead of having a single, large global metadata document, it could be spread to multiple, small documents. This to reduce the size of the metadata and to improve performance.

Managing documents

List all documents

GET /document

Retrieves the list of metadata documents.

Query Parameters:	first (integer) – Return documents from that number in the document list. Default is `1`. number (integer) – Return at most that number of documents. Default is `100`.
Produces:	application/xml, application/json – DocumentListDocument
Role:	_document_read

Example

NONE

GET /document

HTML/XML

<?xml version="1.0" ?>
<DocumentListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <document>
        <name>producer</name>
        <uri>http://localhost:8080/API/document/producer</uri>
    </document>
    <document>
        <name>editor</name>
        <uri>http://localhost:8080/API/document/editor</uri>
    </document>
</DocumentListDocument>

Retrieve a document

GET /document/(name)

Retrieves the document with the specified name. This resource shares the same query parameters as the item metadata resource.

Query Parameters:	interval (string) – Comma-separated list time-span - Filter out metadata, return only metadata for specified time span. `generic` - Return all non-timed metadata. `all` (default) - Return all metadata, same as `interval=generic,-INF-+INF` `result` - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.) field (string) – Comma-separated list. field-name - Return specified field. field-name “:” new-name - Return specified field, renamed to a new name in return value. ”-” field-name - Exclude specified field. (default) - Return all fields. group (string) – Comma-separated list. group-name - Return specified group. group-name `+` - Return specified group and subgroups. group-name `:` new-name - Return specified group, renamed to a new name in return value. `-` group-name - Exclude specified group. (default) - Return all groups. track (string) – Comma-separated list. track-type track-number - Return metadata for specified track. Example of track is `A2`. track-type t1 `-` t2 - Return metadata for specified track interval, e.g. `A2-4`. track-type `` - Return metadata for all tracks of specified type, e.g. `A`. `generic` - Return all non-tracked metadata. `all` (default) - All metadata, with or without track specification, are returned. language (string) – Comma-separated list. language-tag - Return metadata for specific language, e.g. `en_US`. Wildcards may be used, e.g. `_CA` for both Canadian French and Canadian English. `none` - Return all metadata without language specification. `all` (default) - Return all metadata, with or without language specification. samplerate* (string) – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision. conflict (string) – `yes` (default) - Include all metadata conflicts, unresolved. `no` - Return conflicts resolved according to field rules. include (string) – A list of keys. Includes additional field specific data. Additionally, if set to `type` the type definition of the field will be retrieved. defaultValue (boolean) – `true` - For unset fields, return default values. `false` (default) - Do not return default values.
Produces:	application/xml, application/json – MetadataDocument
Role:	_document_read

Example

NONE

GET /document/editor

HTML/XML

<?xml version="1.0" ?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <revision>VX-20383</revision>
    <timespan end="+INF" start="-INF">
        <field change="VX-20383" timestamp="2014-11-18T10:29:45.166+01:00" user="admin" uuid="ff48980c-6431-4234-83ac-bd8d0af9462d">
            <name>editor_name</name>
            <value change="VX-20383" timestamp="2014-11-18T10:29:45.166+01:00" user="admin" uuid="5b9929ba-cce9-43eb-b63b-62a2426b9891">Bob</value>
        </field>
    </timespan>
</MetadataDocument>

Update or creates a document

PUT /document/(name)

Creates a new or modifies the existing document with the specified name.

Query Parameters:	revision (string) – The known revision. If not specified, the change set will attempt to override existing change sets. skipForbidden (boolean) – Skip fields or groups that the user doesn’t have write access to. Default is `false`.
Accepts:	application/xml, application/json – MetadataDocument
Produces:	application/xml, application/json – MetadataDocument
Role:	_document_write

Example

NONE

PUT /document/editor

HTML/XML

<?xml version="1.0" encoding="UTF-8"?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="-INF" end="+INF">
    <field>
      <name>editor_name</name>
      <value>Bob</value>
    </field>
  </timespan>
</MetadataDocument>

Response:

HTML/XML

<?xml version="1.0" ?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <revision>VX-20424</revision>
    <timespan end="+INF" start="-INF">
        <field change="VX-20424" timestamp="2014-11-18T13:36:46.130+01:00" user="admin" uuid="6279f922-621b-4f0a-b09c-41586736eb9e">
            <name>title</name>
            <value change="VX-20424" timestamp="2014-11-18T13:36:46.130+01:00" user="admin" uuid="0c662ed2-6623-45ac-9272-b6abc232488e">Bob</value>
        </field>
    </timespan>
</MetadataDocument>

Search for documents

PUT /document

Searches for documents matching a provided ItemSearchDocument.

Note that document indexing is disabled by default. Make sure to enable document indexing using indexDocumentMetadata and trigger a reindex so that any existing documents are added to the index.

New in version 5.0.

Query Parameters:	first (integer) – Start returning results from this index. Default is `1`. number (integer) – Return at most this number of documents. Default is `100`. count (boolean) – `true` (default) - Return hits in result. `false` - Do not return hits in result, in order to produce results faster.
Accepts:	application/xml, application/json – ItemSearchDocument
Produces:	application/xml, application/json – SearchResultDocument

View change sets

GET /document/(name)/changes

Retrieves all change sets that have been applied to the document.

Query Parameters:	change (string) – Retrieve a single change set. first (integer) – Return change sets from that number in the list of sorted change sets. Default is `1`. number (integer) – Return at most that number of change sets. Default is all change sets.
Response Headers:	Link – Contains URLs to the previous, next, first and last pages.
Produces:	application/xml, application/json – MetadataChangeSetDocument
Role:	_document_read

Example

NONE

GET /document/editor/changes

HTML/XML

<?xml version="1.0" ?>
<MetadataChangeSetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <changeSet>
        <id>VX-20381</id>
        <metadata>
            <revision>VX-20380</revision>
            <timespan end="+INF" start="-INF">
                <field change="VX-20381" timestamp="2014-11-18T10:27:31.192+01:00" user="admin" uuid="7d1032a5-2ced-42ce-a553-1fbbaf2faeef">
                    <name>editor_name</name>
                    <value change="VX-20381" timestamp="2014-11-18T10:27:31.192+01:00" user="admin" uuid="c0426f6f-f1f0-4729-aaef-43a7f3b5bbfa">alice</value>
                </field>
            </timespan>
        </metadata>
    </changeSet>
    <changeSet>
        <id>VX-20382</id>
        <metadata>
            <revision>VX-20381</revision>
            <timespan end="+INF" start="-INF">
                <field change="VX-20382" timestamp="2014-11-18T10:27:31.229+01:00" user="admin" uuid="7d1032a5-2ced-42ce-a553-1fbbaf2faeef">
                    <name>editor_name</name>
                    <value change="VX-20382" timestamp="2014-11-18T10:27:31.229+01:00" user="admin" uuid="281d6f83-a624-4fa0-81fd-debe0e8bdf68">Bob</value>
                </field>
            </timespan>
        </metadata>
    </changeSet>
</MetadataChangeSetDocument>

Delete a document

DELETE /document/(name)

Removes the metadata document with the specified name.

Role:

_document_write