Add large file
Add large file
OVERVIEW
"Add file" API can timeout in case of uploading a large file, in order to address this limitation and upload a large file use this "Add large file" API. The use of this feature is a three step process.
The process comprises of generating a "progress key" for a site to which the document is being uploaded, this can be obtained using the sites API. Once the "progress key" is obtained it can be used in the "Add file" API request. One the upload has started the server will return a message indicating that the upload is now in progress.
Please note that you only need to use this API method in case of large file upload otherwise use Add file API method
Step 1 :
Purpose
The following API endpoint provides a document progress key which can then be used to track the upload of the document.
Request URL
GET /sites/{siteid}/documentprogresskey/
A sample request URL will look like the following
https://domain.com/instancename/api/1/sites/2/documentprogresskey
Response
The response will be a string in a format similar to the below text
rsxSEFlmFB_1423555822871
Step 2 :
Purpose
This second call is an extension to the Add file API, and requires the progress key to be sent over. In addition this call supports an additional "notification" parameter to control how the email notification is going to behave on addition of the new document.
Note: For large files, the upload is going to take a long time and a server timeout will happen, however, the client can ignore this time out error and can use the Step 3 to monitor the status of the upload.
| Resource(API) EndPoint | Query Params | Form Params | HTTP Method | Request XML |
Response XML |
Response Code |
|---|---|---|---|---|---|---|
| /files/content |
parentfolderid={parentfolderid} sourceclient={sourceclient} (optional) progressiveoperkey={documentprogresskey} (optional) |
filename={filename}
|
POST | Response XML | Response Code | |
| file | Make sure that the parameter name is called file and the value for it is the file to be uploaded | |||||
| notification | Optional parameter called "notification" which is used for email "notification" preference. 1 = Respect user preference 2 = Force email notification 3 = Suppress all notifications (Default if this parameter is not supplied) |
Sample request URL :https://domain.com/instancename
Below are some optional parameters that can be used to manage a two way sync with an external DMS system like worksite. These parameters are stored with the document itself and can be referenced in get file API call.
| Parameter Name | Value | Description |
|---|---|---|
| dmsparentfolderid | string | ID of the parent folder of the document as available in the external DMS system |
| dmsdatabasename | string | The name of the database from where the document was obtained. This is to store the exact location of the document in the external DMS system |
| dmsdocid | string | The document id of the document in the external DMS system |
| dmsversion | string | the version of the document in the external DMS system |
| dmseditdate | string | The date when the document was edited in the DMS system. The format for date is yyyy-MM-dd HH:mm:ss |
Assumptions :
Optional form data parameter called "notification" which is used for "notification" preference.
1 = Respect user preference
2 = Force email notification
3 = Suppress all notifications
This notification form data parameter is optional and when not provided defaults to "Suppress all notifications".
<file>
<fileid>1547</fileid>
<status>INPROGRESS</status>
<documentKey>rsxSEFlmFB_1423555822871</documentKey>
</file>
Response Code
| Code | Meaning |
|---|---|
| 201 | document uploaded successfully |
| 401 | Unauthorized |
| 403 | Validation failed/ Forbidden |
| 405 | Method not allowed (calling api with wrong method) |
| 500 | Internal error occured while uploading document |
Step 3 :
Purpose
API call in Step 2 does not wait for the file upload to complete, but sends a immediate response with the document key to track the document upload progress. The document key returned in the previous step should then be used in this API call to find out the status of the uploaded document. Once the document upload is complete this API call will return the document id of the uploaded document.
Request URL
POST /sites/{siteid}/documentstatus/{documentkey}
| Resource(API) EndPoint | Query Params | Form Params | HTTP Method |
|---|---|---|---|
| /sites/{siteid}/documentstatus/{documentkey} | POST |
Please note that sourceclient parameter is to be repeated in this step in order for the system to register the uploaded file as a sourceclient activity.
Sample request URL : https://domain.com/instancename/api/1/sites/2/documentstatus/rsxSEFlmFB_1423555822871
<documentID>55</documentID>
<status>INPROGRESS</status>
<documentKey>rsxSEFlmFB_1423555822871</documentKey>
</ProgressiveDocResponse>
Or in case of file uploading done below response will come.
<ProgressiveDocResponse>
<documentID>55</documentID>
<status>Done</status>
</ProgressiveDocResponse>
More documentation is needed for the
Shawn Rupert there are multiple factors that determine if Add file or Add large file is to be used. The key criteria are how you are displaying the interface on your end. If the file is large enough that the user cannot wait on the screen for the upload to complete then you should use Add large file API.
The documentation is missing the 'file' parameter, thanks for raising it, we will update our documentation accordingly.
I tested this in Postman. Postman did not immediately return the status response but continued to upload the file as the Add file API would do. Get upload status returns a 405.
Isn't form parameter "file" also required in step 2?
I know there are a lot of factors related to uploading a file, but in general can you give a rough estimate as to how large a file can be before it is considered as a large file?
Thank you
Your review has been submitted.
Comments
5 Comments