Exports

An item export is the process of copying a file from storage to a location accessible by the system.

Create export jobs

Start an export job for a single item

POST /item/(item-id)/export

Creates a new export job that will copy a file to a remote location.

A shape tag can be specified to decide which shape that will be exported.

If the URI ends with a “/” the URI is assumed to describe a folder and the file will retain its existing filename. Otherwise it is assumed that the URI describes a file and that filename will be used.

Query Parameters:
 
  • uri (string) – A URI to the destination of the file.
  • locationName (string) – The name of an export location.
  • metadata (boolean) –
    • true - Metadata will also be exported to side-car XML file.
    • false (default) - No metadata is exported.
  • projection (string) – Defines the projection to use when exporting the metadata.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • useOriginalFilename (boolean) – If set to true, the file(s) will be exported with their original filename if available. Default is false.
  • useOriginalComponentFilename (boolean) – If set to true, the file(s) will be exported with their original component filename if available.
  • tag (string) – Finds a shape with the specified tag and uses that for export. If not specified, the system will attempt to use the original shape.
  • start (string) – Defines a start time code for the media.
  • end (string) – Defines an end time code for the media.
  • template (string) – export template to use.
  • allowMissing (boolean) –
    • true (default) - Job will be started and the missing files will be ignored.
    • false - Job will fail if there are missing files and the files could not be generated by transcoding. A shape tag should be specified.
  • track (string) – Comma-separated list of item track ids. Can include wildcards, e.g. A*. Can also contain component ids. Default is *, all tracks/components.
  • version (string) –
    • essence-version-id - Return shapes for a specified version.
    • all - Return shapes for all versions.
    • latest (default) - Return shapes for the latest version.
    • latest-per-shapetag - Return shapes with the highest essence version number per shape tag.
Produces:
Role:

_export

Note

FTP active mode

For FTP exports, active mode can be forced by adding ?passive=false to the FTP URL. To set the client side ports used in active mode, set the configuration property ftpActiveModePortRange, the value should be a range, e.g. 42100-42200. To set the client IP used in active mode, set the configuration property ftpActiveModeIp.

Note

XMP rewrite

By using the jobmetadata query parameter with rewriteXMP=false (remember to URL encode the =), any XMP metadata in the source file will not be updated with the XMP metadata of the item.

Example

Create a new export job that transfers the file of a shape with the tag flv.

POST /item/VX-250/export?tag=flv&uri=file:/home/user/video/myvideo.flv
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <jobId>VX-1293</jobId>
   <user>admin</user>
   <started>2010-05-07T14:05:51.826+02:00</started>
   <status>READY</status>
   <type>EXPORT</type>
   <priority>MEDIUM</priority>
</JobDocument>

Start an export job for a single item as an IMF package

POST /item/(item-id)/export/imp

Creates a new export job that will create an IMF package as a remote location. URI must end with an “/” to denote a folder.

Query Parameters:
 
  • uri (string) – A URI to the destination of the file.
  • locationName (string) – The name of an export location.
  • metadata (boolean) –
    • true - Metadata will also be exported to side-car XML file.
    • false (default) - No metadata is exported.
  • projection (string) – Defines the projection to use when exporting the metadata.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • useOriginalFilename (boolean) – If set to true, the file(s) will be exported with their original filename if available. Default is false.
  • useOriginalComponentFilename (boolean) – If set to true, the file(s) will be exported with their original component filename if available.
  • tag (string) – Finds a shape with the specified tag and uses that for export. If not specified, the system will attempt to use the original shape.
  • start (string) – Defines a start Time codes for the media.
  • end (string) – Defines an end Time codes for the media.
  • template (string) – Export template to use (see Export Templates).
  • allowMissing (boolean) –
    • true (default) - Job will be started and the missing files will be ignored.
    • false - Job will fail if there are missing files and the files could not be generated by transcoding. A shape tag should be specified.
  • track (string) –

    Comma-separated list of item track ids to include as physical files. Can include wildcards, e.g. A*. Can also contain component ids. Default is *, all tracks/components.

    Since Vidispine 5.0, can also be of syntax: shape: {shape-id}:{track}, cpl: {CPL UUID}:{track}, tag: {shape-tag}:{track}, or component: {component-id}. (The component: syntax means the same as with no prefix.)

  • cplTrack (string) – Comma-separated list of item track ids to include in the CPL. The same format as the track parameter. Default is the same as the track parameter.
  • version (string) –
    • essence-version-id - Return shapes for a specified version.
    • all - Return shapes for all versions.
    • latest (default) - Return shapes for the latest version.
    • latest-per-shapetag - Return shapes with the highest essence version number per shape tag.
Produces:
Role:

_export

Start an export job for a single shape

POST /item/(item-id)/shape/(shape-id)/export

Creates a new export job that will copy a file from the specified shape to a remote location.

If the URI ends with a “/” the URI is assumed to describe a folder and the file will retain its existing filename. Otherwise it is assumed that the URI describes a file and that filename will be used.

Query Parameters:
 
  • uri (string) – A URI to the destination of the file.
  • locationName (string) – The name of an export location.
  • metadata (boolean) –
    • true - Metadata will also be exported to side-car XML file.
    • false (default) - No metadata is exported.
  • projection (string) – Defines the projection to use when exporting the metadata.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • useOriginalFilename (boolean) – If set to true, the file(s) will be exported with their original filename if available. Default is false.
  • useOriginalComponentFilename (boolean) – If set to true, the file(s) will be exported with their original component filename if available.
  • start (string) – Defines a start time code for the media.
  • end (string) – Defines an end time code for the media.
  • allowMissing (boolean) –
    • true (default) - Job will be started and the missing files will be ignored.
    • false - Job won’t be started if there are missing files.
  • track (string) – Comma-separated list of item track ids. Can include wildcards, e.g. A*. Can also contain component ids. Default is *, all tracks/components.
Produces:
Role:

_export

Start an export job for a collection or a library

POST /collection/(collection-id)/export
POST /library/(library-id)/export

Creates a new export job that will copy all matching files in the collection/library to a remote location.

A shape tag can be specified to decide which shapes that will be exported. The files will retain their original names and the URI should therefore point to the folder where the files should be placed.

Query Parameters:
 
  • uri (string) – A URI to the destination of the file.
  • locationName (string) – The name of an export location.
  • metadata (boolean) –
    • true - Metadata will also be exported to side-car XML file.
    • false (default) - No metadata is exported.
  • projection (string) – Defines the projection to use when exporting the metadata.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • useOriginalFilename (boolean) – If set to true, the file(s) will be exported with their original filename if available. Default is false.
  • useOriginalComponentFilename (boolean) – If set to true, the file(s) will be exported with their original component filename if available.
  • tag (string) – Finds a shape with the specified tag and uses that for export. If not specified, the system will attempt to use the original shape.
  • all (boolean) –
    • true (default) - Fail the job if not all files from the selected shapes could be exported.
    • false - Don’t export lost or unavailable files.
  • template (string) – export template to use.
  • track (string) – Comma-separated list of item track ids. Can include wildcards, e.g. A*. Can also contain component ids. Default is *, all tracks/components.
  • version (string) –
    • essence-version-id - Return shapes for a specified version.
    • all - Return shapes for all versions.
    • latest (default) - Return shapes for the latest version.
    • latest-per-shapetag - Return shapes with the highest essence version number per shape tag.
Produces:
Role:

_export

Example

Create a new export job that transfers files in a certain collection that has shapes with the tag flv.

POST /collection/VX-10/export?tag=flv&uri=file:/home/user/video/
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <jobId>VX-1334</jobId>
  <user>admin</user>
  <started>2010-05-24T14:53:12.732+02:00</started>
  <status>READY</status>
  <type>EXPORT</type>
  <priority>MEDIUM</priority>
</JobDocument>

Start an export job of an shape to an IMF package

POST /item/(item-id)/shape/(shape-id)/export/imp

Creates a new export job that will create an IMF package as a remote location. URI must end with an “/” to denote a folder.

Query Parameters:
 
  • uri (string) – A URI to the destination of the file.
  • locationName (string) – The name of an export location.
  • metadata (boolean) –
    • true - Metadata will also be exported to side-car XML file.
    • false (default) - No metadata is exported.
  • projection (string) – Defines the projection to use when exporting the metadata.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • useOriginalFilename (boolean) – If set to true, the file(s) will be exported with their original filename if available. Default is false.
  • useOriginalComponentFilename (boolean) – If set to true, the file(s) will be exported with their original component filename if available.
  • start (string) – Defines a start Time codes for the media.
  • end (string) – Defines an end Time codes for the media.
  • allowMissing (boolean) –
    • true (default) - Job will be started and the missing files will be ignored.
    • false - Job won’t be started if there are missing files.
  • track (string) – Comma-separated list of item track ids. Can include wildcards, e.g. A*. Can also contain component ids. Default is *, all tracks/components.
  • cplTrack (string) – Comma-separated list of item track ids to include in the CPL. Can include wildcards, e.g. A*. Can also contain component ids. Default is the same as the track parameter.
Produces:
Role:

_export