Which collections support uploading?

To determine the upload location (which is the request URL of the upload request), you must first find a collection that supports upload.

Assets can only be uploaded to archives. Furthermore, assets can only be uploaded to certain locations within archives:

• If the archive has a custom input folder, then assets can only be uploaded to the root URL of the archive. It is not possible to upload to a specific sub folder or to create a new sub folder during upload.
• If the archive does not have a custom input folder, then assets can only be uploaded to physical folders. A physical folder is any sub folder that represents an actual folder on disk. For example, the root of an archive or the root of a union member is NOT a physical folder.

It is recommended to use the upload destination list API to discover possible upload locations and/r to check the properties of a particular collection to see if it is a valid upload location. For more information, see ingestion.

Update Response and Status Polling

Once the file transfer has finished, the API returns a response with status code 202 Accepted. At this time, the upload is not finished. The server has to do further processing, such as applying metadata, doing consistency and security checks, copying the file to its storage location, and generating renditions. It is not guaranteed that all of these operations will be completed successfully. Clients should not attempt to make any API requests that rely on the existence of the uploaded assets before the upload has finished successfully.

When an upload has finished, and assuming no further changes have been made, the following guarantees are made:

• An API request to the asset returns a valid result.
• The asset is contained in the asset list of the collection containing it as long as the asset list is requested with the default sorting order and no search query on the collection.
• The asset is contained in the asset list of the collection containing it if the asset list is requested with a search query matching the asset.
• Quick renditions, previews, and thumbnails of the asset are available via the API.

The following are NOT guaranteed:

• Video renditions are NOT NECESSARILY available. A client can check the status of video renditions of an asset by requesting its API representation.
• The asset is NOT NECESSARILY returned in search results that should match it. Search indexing may be delayed.
• The asset is NOT NECESSARILY contained in the asset list of the collection containing it if the asset list is requested with a non-default sorting order.

An upload webhook, if configured, fires once an upload has finished successfully.

The Location header of the response is a URL that can be used for polling the status of the upload.

202 Accepted
Content-Type: application/vnd.fotoware.upload-response+json
Location: http://FOTOWEB_HOSTNAME/fotoweb/me/background-tasks/0735ca40-3a93-11e9-ae8d-34e12de8a773

with a request body:

{
  "href": "/fotoweb/me/background-tasks/0735ca40-3a93-11e9-ae8d-34e12de8a773"
}

where

The Location header, as well as the href attribute is the URL of the background task, which is used in the poll requests described below. The Location header contains an absolute URL, whereas the href attribute contains a relative URL.

GET /fotoweb/me/background-tasks/0735ca40-3a93-11e9-ae8d-34e12de8a773
Accept: application/vnd.fotoware.upload-status+json

200 OK
Content-Type: application/vnd.fotoware.upload-status.json

{
  "job": {
    "status": "pending" | "inProgress" | "done" | "failed",
    "result": [
        {
          "href": "/fotoweb/archives/5000-Wirefeed/Incoming/image.jpg",
          "done": true | false,
          "originalFilename": "image.jpg",
          "errorCode": "..." | null,
          "errorMessage": "..." | null,
          "asset": {...} | null,
        },
        {...},
        ...
    ] | null,
    "updates": {
      "frequency": 100,
      "href": "/fotoweb/me/background-tasks/0735ca40-3a93-11e9-ae8d-34e12de8a773",
      "type": "replace"
    }
  },
  "task": {
    "status": "pending" | "inProgress" | "done" | "failed",
    "created": "2019-02-27T13:24:36.708Z",
    "modified": "2019-02-27T13:24:36.708Z",
    "href": "/fotoweb/me/background-tasks/0735ca40-3a93-11e9-ae8d-34e12de8a773",
    "type": "upload",
  }
}

404 Not Found

403 Forbidden

Error handling

If the job.status attribute of an upload task result is done, then upload of ALL files has succeeded. The location of each file can be checked in the result attribute.

If the job.status attribute of an upload task result is failed, then upload of ONE OR MORE files has failed, but some files may have been uploaded successfully. The status of each file can be checked in the result attribute. If the errorCode attribute in an entry in result is null, then that file was uploaded successfully. Otherwise, errorCode and errorMessage contain further information about the error. Clients may retry to upload these files. The server guarantees that they were not transferred to their final storage (or have been deleted again).

If a poll request fails with a status code above 500, then clients should repeat polling with the same frequency. It is at the discretion of the client to stop polling or increase the interval in this case.

If a poll request fails with a status code of or above 400 and below 500, then clients should stop polling. Such errors are either unexpected or due to bugs in the client or server. An error message should be shown to the user, and the status of the upload is unknown.

User interface considerations

As long as an upload task is pending, the upload should be shown as in progress.

Progress bars are easy to calculate during file transfer (the initial upload request), but during polling/post-processing, it is hard to know the current status, so a progress bar should show either 100% or something close to it (which is also the maximum of the file transfer process), such as 99%.

It is not possible to abort/cancel post-processing. If the client simply stops polling, the status of the upload will be unknown.

It is OK to first complete all upload requests and poll the status of all uploads at the end. This makes most sense for a modal dialog (but it shows the status to the user only when all uploads have finished). A user interface that shows the status in real time and remains responsive all the time (background upload) should poll all the time.

Preserving the modification date/time of uploaded assets

When uploading assets via the API it may be desirable to preserve the original modification time of the assets being uploaded. To accomplish this, get the file modification date from the file to upload (e.g., using the file system API on your platform), then send it in the upload request using the "mt" attribute, as shown here:

{
  "fields": [... (patch instructions for metadata fields) ...],
  "attributes": [
    {"key": "mt", "value": "2018-01-02T11:22:33Z"}
  ]
}

where

Applying metadata during upload

Metadata can be applied to assets during upload. This ensures strong metadata consistency in FotoWeb archives. If a client uploaded assets and applied metadata later in a separate request, then these assets might be without metadata, without consistent metadata, or without required metadata fields for a short period after the upload. Applying metadata during upload ensures that all assets in the FotoWeb systems always have fully consistent metadata.

Metadata can be applied to each asset in an upload request. This is done by adding a metadata part to the request body for each asset to which metadata shall be applied:

--WUG7zDvyA3hVq16Q
Content-Disposition: name="Metadata" filename="image.jpg.metadata.json"
 
{
  "fields": [
    {"id": 5, "value": "Roadrunner"},
    {"id": 80, "value": "Wyle E. Coyote", "action": "add"},
    {"id": 25, "action": "erase"},
    {"id": 25, "action": "add", "value": ["chicken", "food"]}
  ]
}

 where the Content-Disposition header parameter must be set as follows:

For example, when applying metadata to an asset where filename is set to "image.jpg" in the "FileData" part, then the "Metadata" part must begin as follows:

--WUG7zDvyA3hVq16Q
Content-Disposition: name="Metadata" filename="image.jpg.metadata.json"

// If the field is a non-bag field:
"value": "foo"           // Replaces existing value with "foo"
"value": ["foo"]         // Replaces existing value with "foo"
"value": []              // valid, but does nothing
"value": ["foo", "bar"]  // INVALID, because at most one value may be given


// If the field is a bag field:
"value": "foo"           // Adds "foo" to existing values
"value": ["foo"]         // Adds "foo" to existing values
"value": ["foo", "bar"]  // Adds "foo" and "bar" to existing values
"value": []              // valid, but does nothing

{
  "fields": [
    {"id": 500, "value": "V1"},
    {"id": 501, "action": "erase"},
    {"id": 502, "action": "append", "value": "V3"},
    {"id": 503, "action": "prepend", "value": "V4"}
  ]
}

{
  "fields": [
    {"id": 25, "action": "erase"},
    {"id": 25, "action": "add", "value": ["food", "chicken"]},
    {"id": 80, "action": "add", "value": "Wyle E. Coyote"}
  ]
}

A special case: Metadata in PDF files

When uploading PDF files to Fotoware, any metadata added to the PDF during upload will be committed to storage as an XMP sidecar that accompanies the PDF. This has the practical implication that when subsequently downloading the asset from a Fotoware user interface, a zip file will be delivered with the PDF file and the sidecar included. However, when downloading assets using the API, for which there is no UI, only the PDF file will be delivered, and any added metadata will not be included in the downloaded file since it has not been embedded. 

To successfully embed metadata into the PDF so that it can be downloaded completely via the API, there are two options:

• Apply the metadata to the PDF post-upload. This will ensure that any sidecar information is embedded in the actual PDF
• Execute a metadata patch operation on any field in the PDF post-upload. This will trigger the reindexing of the asset and embed any sidecar information into the PDF.

Metadata fields that are automatically set

When uploading assets to FotoWeb, FotoWeb sets certain fields automatically. This is described here.

Full example

The following is an example of a complete upload request with metadata:

POST /fotoweb/archives/5000-Wirefeed/Incoming/
Accept: application/vnd.fotoware.upload-response+json
Content-Type: multipart/form-data; boundary=WUG7zDvyA3hVq16Q
authentication headers
 
--WUG7zDvyA3hVq16Q
Content-Disposition: form-data; name="Filedata"; filename="image.jpg"
Content-Type: image/jpeg
 
binary image data
--WUG7zDvyA3hVq16Q
Content-Disposition: name="Metadata" filename="image.jpg.metadata.json"
 
{
  "fields": [
    {"id": 5, "value": "Roadrunner"},
    {"id": 80, "value": "Wyle E. Coyote", "action": "add"},
    {"id": 25, "action": "erase"},
    {"id": 25, "action": "add", "value": ["chicken", "food"]}
  ]
}
--WUG7zDvyA3hVq16Q