UC Attach New File To Existing Item

Motivation

A possible scenario for this would be an external transcoder driven by a VidiFlow module where an existing shape of an item is used as source material and the destination file is going to be attached to the same item as additional shape.

Workflow

• Item with itemId and existing shape is present in VidiCore.

• Create the file object via POST /API/storage/<storageId>/file?path=<relativePathOfFileOnStorage>&state=TO_APPEAR&createOnly=true.

  • this is to create the file entity manually and will return the file ID of the newly created file;

  • createOnly=true acts as a safeguard not to create the same physical file twice; if the API call returns an error the import process should stop. Of course, such error scenarios should be avoided at an earlier stage of the ingest workflow for a better user experience.

• Start writing the file to the storage.

  • It is important to create the file object before starting to write; otherwise the above API would fail as the file object may have already been created by VidiCore.

  • If it is not possible to create the file object properly creating the file (e.g. for some video servers) then an appropriate solution needs to be defined.
    A possible solution would be to define an VidiCore storage with a method type not equal NONE and build agents to access the videos.

  • When you are 100% sure that the physical file exists on the storage change the state of file object to OPEN via PUT /API/storage/file/<fileId>/state/CLOSED.

Other applications may rely on the existence of a physical file if the file state is OPEN. Keep it on TO_APPEAR if you cannot determine for sure if the file exists.

• If the file is suitable for processing while still being written, attach the file as a new shape to the existing item via POST /API/item/<itemId>/shape?fileId=<fileId>&tag=<shapeTag>

  • VidiCore will start an import job on the item and will return its job ID.

  • The import job will extract technical metadata from the file, create the appropriate components on the shape, and will attach the technical metadata to the shape.

For MXF files you can assume that they can be processed while being written, esp. if the MXF files have a ClosedComplete header. Files in an mp4 container usually are not suitable for processing while being written.

• When file is copied completely, update the shape with the final technical file data via
  POST /API/item/<itemId>/shape/<shapeId>/update

  • VidiCore will start an shape update job on the shape and will return its job ID.

  • The update job will extract technical metadata from the file and update the technical metadata of the shape.

• When file is copied completely, change the state of file object to CLOSED via
  PUT /API/storage/file/<fileId>/state/CLOSED.

  • This is not mandatory as VidiCore will detect the closed file itself if the browse flag is set to true on the storage, but it will speed up the ingest process and thus should always be done.

• If your file cannot be processed while being written then trigger the shape import job now: POST /API/item/<itemId>/shape?fileId=<fileId>&tag=<shapeTag>

  • VidiCore will start an import job on the item and will return its job ID.

  • The import job will extract technical metadata from the file, create the appropriate components on the shape, and will attach the technical metadata to the shape.

• If you’ve started this shape import job while the file still was being written, we recommend to run a shape deduction job on the newly created shape: POST /API/item/<itemId>/shape/<shapeId>/update

  • VidiCore will start a shape deduction job on the shape and will return its job ID.

  • The shape deduction job will extract technical metadata from the file, update the appropriate components on the shape, and will update the technical metadata on the shape.