OneSpan Sign Developer: Archive, Trash and Delete
In OneSpan Sign, Archive, Trash, and Delete are all transaction actions that allow you to manage the lifecycle of your transaction after it’s either completed or no longer needed. If you would like to restrict access to completed transactions or simply want to delete a transaction, this blog will clarify the concepts and behavior of these three transaction actions, help you understand how they are designed, and explain how to programmatically apply them.
ARCHIVE
In OneSpan Sign, there are the following package statuses:
DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
Notice that only “ARCHIVED” is a status of package while the other two topics “TRASHED” and “DELETED” are not.
The Archive action moves the selected transactions from your Inbox to the Archived folder containing all your archived transactions. This action is available only for “COMPLETED” transactions in your Inbox.
The Restore action is used to change the selected transactions to their previous state. This action is available only for transactions in the Archived or Trashed folder. For example, the Restore action will change a package status from “ARCHIVED” to “COMPLETED”.
In REST:
HTTP Request PUT /api/packages/{packageId} HTTP Headers Authorization: Basic api_key Accept: application/json Content-Type: application/json Request Payload { "status": "ARCHIVED"/"COMPLETED" }
In Java SDK:
eslClient.getPackageService().archive(packageId); //archive action eslClient.getPackageService().markComplete(packageId); //restore archive
In .Net SDK:
eslClient.PackageService.Archive(packageId); //archive action eslClient.PackageService.MarkComplete(packageId); //restore archive
In Apex SDK
ESignLiveSDK sdk = new ESignLiveSDK(); sdk.setStatus("packageID", ESignLiveAPIObjects.PackageStatus.ARCHIVED); //archive action sdk.setStatus("packageID", ESignLiveAPIObjects.PackageStatus.COMPLETED); //restore archive
Once a package is archived, your signer won’t have access to the package. When they click the download link in their email, they will see “Access Denied” as the below picture shows.
While as a Sender, you can still retrieve metadata, download the documents/evidence summary, call REST/SDK functions as you can with any other “COMPLETED” package.
TRASH
The Trash action is used to move a selected transaction from your Inbox/Drafts/Archived Folder to the Trash Folder.
As we mentioned above, ”TRASHED” is not a package status, so how can we represent a package as trashed? There’s a separate attribute named “trashed” in the package JSON.
If this property is set to “true”, the package is “TRASHED”, and you can only find it in your Trash Folder. Since trashing a package doesn’t change its status, if you set the property back to false, the package will be recovered while maintaining the proper status.
In REST:
HTTP Request PUT /api/packages/{packageId} HTTP Headers Authorization: Basic api_key Accept: application/json Content-Type: application/json Request Payload { "trashed": true/false }
In Java SDK:
eslClient.getPackageService().trash(packageId); //trash action eslClient.getPackageService().restore(packageId); //restore trash
In .Net SDK:
eslClient.PackageService.Trash(packageId); //trash action eslClient.PackageService.Restore(packageId); //restore trash
In Apex SDK:
ESignLiveSDK sdk = new ESignLiveSDK(); String packageId = '2APPpsAcqVk8QbJKABFqWvHy-kQ='; ESignLiveAPIObjects.Package_x pack = sdk.getPackage(packageId); pack.trashed = true; //trash action //pack.trashed = false; //restore trash sdk.updatePackage(pack, packageId);
TRASHing a package will put it in the TRASH folder for 2 weeks, after which it will be deleted, permanently.
DELETE
A “DELETE” request is accomplished by calling the same REST api as retrieving package metadata. Once a package is deleted, only the packageID is retained with a status of DELETED in OneSpan Sign. Everything else is removed and cannot be reinstated.
In REST:
HTTP Request DELETE /api/packages/{packageId} HTTP Headers Authorization: Basic api_key Accept: application/json Content-Type: application/json
In Java SDK:
eslClient.getPackageService().deletePackage(packageId); //delete action
In .Net SDK:
eslClient.PackageService.DeletePackage(packageId); //delete action
In Apex SDK:
ESignLiveSDK sdk = new ESignLiveSDK(); sdk.deletePackage('packageId'); //delete action
The Delete action differs from the Trash action because, there is no way to restore a package after it has been deleted. When trying to get access to the transaction again, you will always see below picture, which tells you that the package is no longer accessible. With Trash Action, you still have the chance to restore your package within 2 weeks.
Through today’s blog, we’ve reviewed three Transaction Actions: Archive, Trash and Delete. You now have a clearer understanding of how they are designed and learn how to use or restore them in both REST and SDK methods.
If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!