UC Add Item

Motivation

Items are the central entity in the Vidispine data model and can consist of several different representations of a media asset within the VidiCore system.

There are several ways of importing media into VidiCore. Which one that is used depends on where the media is located, the order of operations, and what automation that is required.

On a high level, the different ways of importing are:

Regular import

This import uses a URI pointing outside of VidiCore storages to reference the source media. VidiCore will make a copy of the source material (and sidecar files given by the user) to a VidiCore storage.

The job type for this type of import is PLACEHOLDER_IMPORT.

Raw import

Here, the caller supplies the material in the REST API call as data in the request body. This is useful when the data is stored as a file at the caller’s point, for example when the end user is uploading information in a web browser. It is also useful when the information resides in a location which VidiCore cannot reach, for example behind a firewall.

VidiCore supports partial upload, so the caller can split the input in multiple parts in order to better handle network problems or in order to parallelize uploads.

The job type for this type of import is RAW_IMPORT. Note that the job is not created until all parts of the file has been uploaded.

File import

This import is used where the file is already located on a storage which is supervised by VidiCore. In this type of import, no copying takes place. Instead, a new item is created, and the file is associated with the file.

The job type for this type of import is RAW_IMPORT.

Auto-import

This is a special case of file import, where no explicit call has to be done for every file. The user sets up rules for how files are imported, and if any sidecar files are processed as well.

The job type for this type of import is AUTO_IMPORT.

Placeholder import

A placeholder import is an import where the placeholder item and a placeholder shape are created before any file is imported. When creating the placeholder shape, the caller gives item metadata and information about the components. The creation of the placeholder item is a synchronous operation, and the item id is immediately returned.

Using the item id, the caller can populate the placeholder shape with files, either by posting the URI or the raw content to the components of the shape. The placeholder import is the import method that gives the highest flexibility.

Example

Regular import

Example of a regular import from an uri using a simple metadata document:

Request:

POST /import?uri=http://example.com/video.avi

Body:

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
      <timespan end="+INF" start="-INF">
         <field>
            <name>title</name>
            <value>This is an imported item!</value>
         </field>
      </timespan>
</MetadataDocument>

File import

Example of an import from a storage:

POST /storage/VX-1/file/VX-3/import

Body:

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
      <timespan end="+INF" start="-INF">
         <field>
            <name>title</name>
            <value>This is an imported item!</value>
         </field>
      </timespan>
</MetadataDocument>

Placeholder import

To do a placeholder import we start by creating a placeholder which returns the item id for the empty placeholder.

POST /import/placeholder?container=1

Body:

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
      <timespan end="+INF" start="-INF">
         <field>
            <name>title</name>
            <value>This is an imported item!</value>
         </field>
      </timespan>
</MetadataDocument>

Response:

VX-1134

Then we can attach media to our item using an uri:

POST /import/placeholder/VX-1134/container?tag=__mp4&uri=http://example.com/video.avi

Resources

https://apidoc.vidispine.com/latest/ref/item/import.html#imports

How to

https://apidoc.vidispine.com/latest/ref/item/import.html#imports

https://apidoc.vidispine.com/latest/ref/storage/file.html#importing-a-file-from-a-storage