Skip to main content

 

Documentation & User Guides | FotoWare

Ingestion

Explains how to add assets to an archive using the API.

What is Ingestion?

Ingestion is the process of adding assets to a FotoWeb archive. There are several ways to do this:

  • Uploading new assets
  • Copying assets from other archives
  • Moving assets from other archives

All of these operations create new assets with new unique URLs, although in the case of copying or moving, the new assets are identical to previously existing assets. When copying an asset, the original asset stays in place, whereas when moving an asset, the original asset is deleted, and its URL becomes invalid.

Destinations

In order to ingest assets, an application must specify a destination. This is typically a folder in an archive, but it can also be a different kind of collection, such as the user's upload area.

Destination Lists

The full API descriptor provides links to three collection lists in the following attributes:

move_to: "/fotoweb/me/move-to/",
copy_to: "/fotoweb/me/copy-to/",
upload_to: "/fotoweb/me/upload-to/",

Each of these links point to a collection list, which is called a destination list. They contain all possible top-level upload destinations (typically archives and/or the upload area) as sub collections. These can then browsed hierarchically in the usual way to find suitable destinations.

The following example shows a request to get the top level of upload destinations:

GET /fotoweb/me/upload-to/
Accept: application/vnd.fotoware.collectionlist+json

200 OK
Conent-Type: application/vnd.fotoware.collectionlist+json

{
  data: [ ... list of collections ... ],
  paging: null
}

The request to get all sub collections of a collection is the same, except the request URL is replaced by the URL (given in the data attribute) of the collection whose sub collections to get.

What is a Destination?

A suitable destination is a collection which allows assets to be added using a specific operation (move, copy or upload).

Note that not all collections discovered through a destination list are destinations. However, by hierarchically browsing these destination lists, an application can find all destinations for the given operation. The following conditions must be checked, depending on the type of operation, to determine if a collection is a suitable destination:

  • Copy: The permissions in the collection information array contains the "Copy" value
  • Move: The permissions in the collection information array contains the "Move" value

For upload, there are special rules:

  • A collection is an upload destination if and only if thecanUploadToflag is set in the collection information.
  • Assets can be uploaded to new sub folders in a collection if and only if the canCreateFolders flag is set in the collection information.

For all operations, thecanIngestToChildrenflag determines whether there can exist sub collections that are suitable destinations. If this flag is not set, then sub collections do not need to be evaluated recursively to search for destination, because there are none. A user interface for choosing a destination should not display an "expand" button in this case.

Configuring Destinations

This section explains which concrete collections are suitable destinations for ingestion and how to configure it. This is relevant for administrators. API clients can and should simply discover upload destinations as described in the previous sections.

  • An archive itself is a destination only if the archive has a custom ingestion folder
  • A folder in an archive is a destination only if it is a physical folder. A physical folder is one of the following
    • A document folder of a regular index
    • A document folder of a union member
    • A sub folder of another physical folder
  • The user's upload area is a suitable destination only if it is enabled for the request user
  • In addition to the rules above, the request user must have permission to ingest to an archive. The necessary permissions are:
    • CopyTo (copy)
    • MoveTo (move)
    • Upload (upload)

If an archive has a custom ingestion folder, then it is only possible to ingest to the archive itself, not to any folders in it. Therefore, the canIngestToChildren flag is false.

It is not possible to create folders in the upload area. Therefore, canCreateFolders is set to false.

Ingesting Assets

Once a destination has been found, the actual ingestion operation can be performed using the API. For more information, see

Note that, unless stated otherwise, thehrefattribute of a destination's JSON representation specifies the URL that must be used with an ingestion (e.g., upload) request. However, for discovering ingestion destinations and listing sub collections, thedataattribute must be used.

  • Was this article helpful?