RESTAPI:Transfer Status
With this endpoint, a sender of a transfer is able to request information about the transfer's status. This status includes information about its file downloads, the processing status of the transfer itself and possible errors regarding files or sending of email notifications. After triggering the finalization of a transfer session, this endpoint can also be used as a polling endpoint to determine when file processing has ended and if the transfer files are available for download or if problems with files led to the non-availability of the transfer.
Requesting the status of a transfer as its sender
GET https://<your-url>/api/users/<sender email-address>/transfers/<tracking-id>
General transfer information
The endpoints returns an object with two fields. The first field transfer contains mostly the same general transfer information as the Transfer Session State endpoint including the used configuration, the files, the recipients, and the expiration date.
Status: Recipient Downloads
The performed downloads of recipients can be found in the respective RecipientStatus objects inside the subfield recipients of the status field.
Each recipient contains a list of FileDownload objects for each transfer file.
| Field name | Description |
|---|---|
| id | The file id of this file. |
| downloads | A list of performed downloads for this file by the recipient in the upper hierarchy. |
As files can be downloaded or viewed in the Web App Content Viewer multiple times, a list of all retrieval actions with their respective timestamp are returned.
| Field name | Description |
|---|---|
| downloadDate | The date of the download. ISO 8601 with 'T' separator and numeric timezone. |
| retrievalMethod | The method how the file was retrieved: Downloaded or viewed in Content Viewer. |
Status: Transfer's lifecycle
When a transfer session is finalized, it receives the state processing. After the processing completes, a transfer will go into the state active, when at least one file was processed correctly, or into the state failed, when all files have been removed during processing (when configured), e.g. when a virus was found or if the File Type Filter does not allow this type of file.
As long as a transfer has the state active, it is available for download by recipients. In the following time the state can change depending on various conditions:
- The transfer has been revoked by the sender. The transfer is set to deleted_by_revocation.
- When the download security of transfers is set to "delete" when too many wrong passwords were entered, the transfer files are deleted from the Cryptshare server and the state is set to deleted_by_security.
- Administrators are able to delete a transfer via the Cryptshare administration interface, e.g. on the sender's behalf when they sent the transfer to the wrong person and the sender is not able to revoke the transfer themselves. The transfer is set to deleted_by_admin.
- When the expiration date is reached and the next execution of the Cleanup Task has been performed, a transfer is set to deleted_by_expiration.
| State name | Description |
|---|---|
| Active | The transfer is available to be downloaded by the recipients.
When the expiration date was reached, but the Cleanup Task did not run yet, the transfer will keep this state. |
| Deleted_by_expiration | The transfer is not available anymore, due to reaching the expiration date and after being processed by the Cleanup Task. |
| Deleted_by_revocation | The transfer is not available anymore, due to revocation by the sender. |
| Deleted_by_admin | The transfer is not available anymore, due to deletion by the Cryptshare server administrator via the Transfer Log. |
| Deleted_by_security | The transfer is not available anymore, due to too many failed password entry attempts by recipients. |
| Processing | The transfer is not available yet. The finalization of this transfer-session was triggered, but is not finished yet. |
| Failed | The transfer is not available, due all files have been removed during finalization. |
| Unknown | Transfers that were sent with Cryptshare version 5.7.0 and older have this state. |
Status: Transfer Polling after finalizing a transfer session and recipients' download links and possible errors
In the second field status the state of the transfer can be seen in its subfield state. As soon as the finalization of the transfer session was triggered, the state of the transfer is set to processing. By polling this endpoint, the state should change after some time to either active or failed. The length of the processing depends on the size of the transfer files and the configured file-processing steps by the Cryptshare Server administrator.
The download links for recipients can be found in the respective RecipientStatus objects inside the subfield recipients of the status field. If the Cryptshare server should not handle the notification of recipients, these links should be sent to recipients manually, in order to notify them that a transfer is available for them.
All recipients are listed with the following fields:
| Field name | Description |
|---|---|
| The email address of this recipient | |
| downloadUrl | The download url for this recipient.
When using a password mode other than "no password", it contains a URL with only the recipient's transfer id. When password mode "no password" was used, a password is added to the URL. In case a verification token was used for executing this request than the one for finalizing the transfer, the URL will be set to null, since the password cannot be decrypted anymore for Transfer Status purposes. |
| id | The transfer id of this recipient. |
| notificationFailed | If the sending of a notification email failed (when configured in the Transfer Session) |
| fileDownloads | For each transfer file a list of performed downloads. |
Handling possible errors
During transfer processing errors might have occurred. These range from not being able to send notification emails to either the sender or the recipient,
In order to quickly check for any errors, the status' field warnings can be checked. If it is set to false, no errors occurred. If this property is set to true, there might be one or more problems.
- TransferStatus -> Status status -> Boolean emlCreationFailed. When the creation of the confidential message failed.
- TransferStatus -> Status status -> SenderStatus sender -> Boolean notificationFailed: When the sending of the upload summary to the sender failed.
- TransferStatus -> Status status -> List<RecipientStatus> recipients -> Boolean notificationFailed: When the sending of recipient notifications has failed to the respective recipient.
- TransferStatus -> Status status -> List<FileStatus> files -> Boolean removed & String removalCause: When a file has been removed from the transfer and the reason for the removal. This removalCause can be localized by the Accept-Language header.