Overview

When creating new or adding versions to Attachments or renditions to Digital Assets in Aprimo, you will need to first upload a file using the file upload routes provided, then use the file’s unique identifier and name when creating new digital asset or attachment versions.

To upload a new file, you have an option to break the file into chunks when uploading. This allows you to resume file uploads if a transfer fails, but is not necessary. We do recommend using chunking if dealing with larger files, as the maximum HTTP Request Length allows on the /api/chunk/upload call is 25MB (including the file content and additional parameters). The steps required to upload are as follows:

  1. Split the file into chunks (optional).
  2. Upload the file chunks (or full file) to the server.
  3. Once all file content is uploaded, call the POST api/chunk/complete, which will compiles the chunks together on the server. This call still must be made even if the full file content was uploaded in a single chunk.
  4. Use a unique identifier and filename to create the digital asset rendition or the attachment version.

Splitting the file into chunks

Step one is to optionally split the file into equal size chunks (except the last chunk, which may be smaller).

The appropriate chunk size can be determined by you, and you may even use an adaptive chunk size based on the bandwidth of users uploading.

Uploading file chunks

The below parameters are used across the file chunk upload routes.

  • resumableFilename – The name of the file being uploaded in chunks.
  • resumableChunkNumber – The chunk number, starting at 1, indicating the order of the chunks you are uploading.
  • resumableIdentifier – A guid generated by you to uniquely identify the upload. For example, “c46d9d54-4335-4d77-acca-67ed4d3142ff”. Guids can sometimes be represented by surround them with curly braces, like {c4669d54-4335-4d77-acca-67ed4d3142ff}, however, do not use curly braces when passing a GUID to these routes.
  • fileĀ – The file chunk contents.

To upload the file chunks, take the following steps, with resumeableChunkNumber starting with 1.

  • Generate a new GUID for the resumableIdentifier.
  • For each chunk:
    • Call GET api/chunk/upload?resumableFilename={yourFilename}&resumableChunkNumber={chunkNumber}&resumableIdentifier={resumableIdentifier} to ensure the chunk has not been uploaded already.
      • This call will return a 200 OK Status if the chunk already exists.
      • If the chunk does not exist, it will return a 404.
    • Call POST api/chunk/upload with a multi-part form data body containing the resumableChunkNumber, resumableFilename, and resumableIdentifier parameters in the body along with a file parameter containing the chunk contents.
      • A 200 OK will indicate that the chunk was uploaded successfully.
    • Increment the chunkNumber by 1.

Note, below is a POSTMAN screenshot showing how to make the POST api/chunk/upload call.

The two headers under the headers tab are:

  • X-Access-Token: {yourAccessToken}
  • Content-Type: application/x-www-form-urlencoded

Combining file chunks

Once all of your file chunks are uploaded, you need to make one more API call to tell the Aprimo servers to combine the file.

Call the POST api/chunk/complete route, and in the POST body, pass in as JSON:

{
	FileId: "yourGeneratedGuid",
	FileName: "yourFilename"
}

Ensure the FileName parameter matches the resumableFileName parameter used in the earlier calls, and the FileId parameter matches theĀ resumableIdentifier parameter used in earlier calls.

The uploaded file chunks/completed file is only guaranteed to be available for 8 hours to be associated to an attachment version or digital asset version. Upon association to an attachment version or digital asset rendition, the file is committed into the Aprimo internal file store and will be permanently available as part of that attachment version or digital asset rendition.

Creating new attachment versions or digital asset renditions

When creating a new attachment version or digital asset rendition, provide both the FileId and FileName parameters to associate an uploaded file to the record.

For example, here is a sample JSON body to create a new attachment version onto attachment ID 1101.

{
    "isDefaultVersion": true,
    "attachmentId": 1101,
    "FileId": "c4669d54-4335-4d77-acca-67ed4d3142ff",
    "FileName": "SampleFileChunk.txt",
    "versionComments": "Original Version",
    "versionType": 3
}

Creating new attachment versions of internet files

When creating a new attachment version of an internet file, provide the FileId and FileName and Extension parameters to associate an internet file to the record. The route for this call is /api/attachments/1101/versions

For example, here is a sample JSON body to create a new attachment version of an internet file onto attachment ID 1101. The route for this call is /api/attachments/1101/versions.

{
    "isDefaultVersion": true,
    "attachmentId": 1101,
    "filename": "http://www.espn.com",
    "downloadUri": "http://www.espn.com",
    "thumbnailStatus": 3,
    "versionType": 1,
    "annotationFileType": 0,
    "versionComments": "New Internet File version via API",
    "sendNotification": 0,
    "versionUrl": "http://www.espn.com",
    "fileID" : "0c62463e-6730-45d0-8701-e2ad273b52b7"
}