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!