File Upload/Retrieval Process

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.

Digital assets and attachments will use different endpoints for uploading. Digital assets will use /api/chunk/upload and /api/chunk/complete. Attachments will use /api/chunk/upload/attachment and /api/chunk/complete/attachment. 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 and /api/chunk/upload/attachment 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 or api/chunk/complete/attachment, 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.

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.

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:
  • If uploading a digital asset
    • 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.
  • If uploading an attachment
    • Call GET api/chunk/upload/attachment?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/attachment 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

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 or digital assets or POST api/chunk/complete/attachment for attachments, 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.

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
}

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"
}

You’ll need the attachmentID, the versionID, and a way to call into the API (the link is calculated — not stored in the DB)

Call GET https://{domain}/api/attachments/{attachmentId}/versions/{versionId} — the response body will include an attribute called ‘downloadUri’. In order to retrieve the file, you may use the url in a browser where you have an active MO session (you need to be authenticated in order to access the file), or you may perform a GET request on the file, passing in your authorization token in a header as if calling any other endpoint.