...
The bulk file download via the web client is a new feature that will allow users to select files, review/refine the file selection, and then download all of the files as a single zip file. The workflow consists of five basic phases: file selection, selection review, download, download order review, download history. While a typical workflow flow might involve the user moving through the all of the phase in order, the user is free to move between phases at will.
...
- Clear the list
- Download the list (transition to download phase)
Download
The user's goal for this phase will be proceed with the actual file download. This phase is similar to the checkout phase of the an online shopping experience. In this phase the user will provide a name for their zip file and will be presented with the sub-set of files that will actually be included in the download (unavailable files will be excluded). When the user chooses to proceed with the download, the download order will be started (see Figure 1).
...
If any errors occur during this transaction all changes will be rolled back, restoring their download list to its starting state. The user will be blocked from making changes to their download list during the execution of the download transaction. Upon success, the user will be transition transitioned to the download order review phase to review the newly created download order and ultimately download the file.
Download Order Review
The user's goal for the download review phase is to review their latest an existing download order and actually download the a resulting file. This phase is similar to the review of an existing order from an online shopping experience. Figure 1. shows two start points, the first involves the creation of a new download order from the user's download list, and the second starts from an existing download order. In either case the user will be able to select an existing download orders to start the actual bulk file download job and ultimately download the file. Download orders are immutable and stateless. The user will be free to re-download any of their previous download orders from this phase.
Download History
The user's goal for the download history phase is to review previous download orders. This phase is similar to reviewing previous order from an online shopping experience. In this phase the user will be able see a listing of all of their previous orders in reverse chronological order. When the user wishes to download a previous order they will transition back to the download order review phase.
Limitations
Managing file selection across a paginated list of results creates an awkward user experience. Therefore, the entire download list must be presented to the user without pagination (scrollbars are allowed). This means there must be a limit on the number of files allowed in the download list. The download list must be small enough to be fetched as a single web-service request. A download list will have a limit of 100 files.
...
To support adding all of the files in a folder (non-recursive) (use case 1a) we will need to return the total number of files in a folder and the total size of all files in the folder from POST/entity/children. The proposal is to add a 'partMask' (similar to QueryBundleRequest) with 0x01=count and 0x02=totalFileSizeMB..
REST APIs
| DownloadList |
|---|
| List<FileHandleAssociation> filesToDownload |
| Date updatedOn |
| DownloadOrder |
|---|
| String orderId |
| List<FileHandleAssociation> files |
| Date createdOn |
| String createdBy |
| String zipFileName |
| Long totalSizeMB |
| DownloadOrderSummary |
|---|
| String orderId |
| Date createdOn |
| String zipFileName |
| Long numberOfFiles |
| Long totalSizeMB |
<<Interface>> AddRequest |
|---|
| AddFolderRequest implements AddRequest |
|---|
| String parentId |
| AddQueryRequest implements AddRequest |
|---|
| Query query |
| DownloadOrderRequest |
|---|
| LIst<FileHandleAssociation> subSet |
| String zipFileName |
| Phase | Description | Response | Path | Request |
|---|---|---|---|---|
| File Selection | Start an asynchronous job to add all of the files from either a folder or a view query to the user's DownloadList | AsyncJobId | POST /download/list/<userid>/add/async/start | AddRequest |
| File Selection | Get the results of an asynchronous job to add files to a user's download list. | DownloadList | GET /download/list/<userid>/add/async/get/<jobid> | |
| File Selection | Add a single file to a user's download list. | DownloadList | POST /download/list/<userid>/add | FileHandleAssociation |
| Selection Review | Get a user's download list. | DownloadList | GET /download/list/<userid> | |
| Selection Review | Remove a list of file from a user's download list | POST /download/list/<userid>/remove | List<FileHandleAssociation> | |
| Selection Review | Clear a user's download list | DELETE /download/list/<userid> | ||
| Download | Create a DownloadOrder from the user's current download list. | DownloadOrder | PUT /download/list/<userid>/order | DownloadOrderRequest |
| Download Order Review | Get a DownloadOrder given its ID. | DownloadOrder | GET /download/order/<orderId> | |
| Download Order Review | Start an asynchronous job to download a download order. | AsyncJobId | POST /download/order/<orderId>/async/start | |
| Download Review | Get the results of an asynchronous job to download a download order. | BulkFileDownloadResponse | POST /download/order/<orderId>/async/get/<jobId> | |
| Download History | Get a user's previous download order history in reverse chronological order. | Paginated<DownloadOrderSummary> | GET /download/order/<userId>/history |
Review Notes
- Do not use file size to restrict the addition of a file to the list. Allow the user's download list to be larger than the size limit. Instead block the download of a list if over the size limit.
- Download order should include a sub-list so use can choose to download a sub-set of the their list. This is part of allowing user's download list to be over the max file size.