Managing Transactions

To download the full code sample see our Code Share site.

This topic describes how to retrieve, update, archive, and delete a transaction.

Retrieving Transactions

To retrieve a transaction, you will first need to create a PackageId object using the ID returned to you during the creation of the transaction. Then, retrieve the transaction using this PackageId in the OneSpan Sign client. The following code will do this:

// Create a PackageId instance using the specified ID
PackageId packageId = new PackageId("package_id_here");

// Retrieve the document package using the ESL client
DocumentPackage retrievedPkg = eslClient.getPackage(packageId);

You can also retrieve a list of transactions. The following code will do this:

// Retrieve a page of document packages with status SENT
Page<DocumentPackage> resultPage = eslClient
    .getPackageService()
    .getPackages(
        new PackageStatusConverter(PackageStatus.SENT).toAPIPackageStatus(),
        new PageRequest(1, 10)
    );

The code example above will return the first ten transactions that are in a SENT status. You can, however, query other statuses, such as DRAFT, COMPLETED, DECLINED, EXPIRED, and ARCHIVED.

SMS Notification Limits

To prevent any misuse and excessive sending of SMS notifications, there is a limit of 50 SMS notifications per transaction. Once the limit of 50 SMS notifications is reached for a particular transaction, a message will be displayed in the user interface, and the customer will no longer be able to send any more SMS for that transaction.

For Java and .NET integrators an alert about 'SMS notification limit reached' can be obtained during a package retrieval. The following code will do this:

// Retrieve the document package with alerts extension
DocumentPackage packageWithAlerts = eslClient.getPackageWithExtensions(
    packageId,
    DocumentPackageRequestExtension.ALERTS
);

// Extract the list of system alerts from the package
List<SystemAlert> alerts = packageWithAlerts.getAlerts();
``

Updating a Transaction

To update a transaction, the transaction must be in a DRAFT status.

To update an existing transaction, create a transaction object with only the updates you want to make to the transaction. Then, call the UpdatePackage function with the PackageId of the existing transaction. The following code will do this:

// Build a new document package with updated properties
DocumentPackage packageToUpdate = PackageBuilder
    .newPackageNamed(NEW_PACKAGE_NAME)
    .describedAs(NEW_DESCRIPTION)
    .withEmailMessage(NEW_EMAIL_MESSAGE)
    .expiresAt(LocalDateTime.now().toDate())
    .withLanguage(Locale.FRENCH)
    .withVisibility(NEW_VISIBILITY)
    .withNotarized(NEW_NOTARIZED)
    .autocomplete(false)
    .withSettings(settingsToUpdate)
    .build();
// Update the package using the ESL client
eslClient.updatePackage(packageId, packageToUpdate);

Deleting Transactions

If you want to permanently remove a transaction from your account, call the deletePackage function using the PackageId of the transaction you wish to delete.

Deleting a transaction cannot be undone.

The following code will do this:

// Delete the document package using its package ID
eslClient.getPackageService().deletePackage(packageId);
``

If you do not want to permanently delete this transaction, you can instead move it to your Trash folder. This way it will not be deleted and can be retrieved at a later date. The following code will do this:

// Move the document package to the trash using its package ID
eslClient.getPackageService().trash(packageId);

Archiving Transactions

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.

To do this, call on the OneSpan Sign client with the PackageId of the transaction you wish to archive. The following code will do this:

// Archive the document package using its package ID
eslClient.getPackageService().archive(new PackageId("packageId"));

To download the full code sample see our Code Share site.

This topic describes how to retrieve, update, archive, and delete a transaction.

Retrieving Transactions

To retrieve a transaction, you will first need to create a PackageId object using the ID returned to you during the creation of the transaction. Then, retrieve the transaction using this PackageId in the OneSpan Sign client. The following code will do this:

// Create a PackageId instance using the specified ID
PackageId packageId = new PackageId("package_id_here");

// Retrieve the document package using the ESL client
DocumentPackage retrievedPkg = eslClient.GetPackage(packageId);

You can also retrieve a list of transactions. The following code will do this:

// Retrieve a page of document packages with status SENT
Page<DocumentPackage> packages = eslClient.PackageService.GetPackages(
    DocumentPackageStatus.SENT,
    new PageRequest(1, 10)
);

The code example above will return the first ten transactions that are in a SENT status. You can, however, query other statuses, such as DRAFT, COMPLETED, DECLINED, EXPIRED, and ARCHIVED.

SMS Notification Limits

To prevent any misuse and excessive sending of SMS notifications, there is a limit of 50 SMS notifications per transaction. Once the limit of 50 SMS notifications is reached for a particular transaction, a message will be displayed in the user interface, and the customer will no longer be able to send any more SMS for that transaction.

For Java and .NET integrators an alert about 'SMS notification limit reached' can be obtained during a package retrieval. The following code will do this:

// Retrieve the document package with the specified extensions
DocumentPackage packageWithAlerts = ossClient.GetPackageWithExtensions(id, extensions);

// Access the list of system alerts from the package
IList<SystemAlert> alerts = packageWithAlerts.Alerts;
``

Updating a Transaction

To update an existing transaction, create a transaction object with only the updates you want to make to the transaction. Then, call the UpdatePackage function with the PackageId of the existing transaction. The following code will do this:

// Build a new document package with updated properties
DocumentPackage packageToUpdate = PackageBuilder
    .NewPackageNamed(NEW_PACKAGE_NAME)
    .WithEmailMessage(NEW_EMAIL_MESSAGE)
    .ExpiresOn(NEW_EXPIRY_DATE)
    .WithLanguage(NEW_LANGUAGE)
    .WithVisibility(NEW_VISIBILITY)
    .WithNotarized(NEW_NOTARIZED)
    .WithoutAutomaticCompletion()
    .WithSettings(settingsToUpdate)
    .Build();

// Update the package using the ESL client
eslClient.UpdatePackage(packageId, packageToUpdate);

Deleting Transactions

If you want to permanently remove a transaction from your account, call the deletePackage function using the PackageId of the transaction you wish to delete.

Deleting a transaction cannot be undone.

The following code will do this:

// Delete the document package using its package ID
eslClient.PackageService.DeletePackage(packageId);

If you do not want to permanently delete this transaction, you can instead move it to your Trash folder. This way it will not be deleted and can be retrieved at a later date. The following code will do this:

// Move the document package to the trash using its package ID
eslClient.PackageService.Trash(packageId);

Archiving Transactions

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.

To do this, call on the OneSpan Sign client with the PackageId of the transaction you wish to archive. The following code will do this:

// Archive the document package using its package ID
eslClient.PackageService.Archive(new PackageId("packageId"));

To download the full code sample see our Code Share site.

This topic describes how to retrieve, update, archive, and delete a transaction.

Retrieving Transactions

To retrieve a transaction, you will first need to create a PackageId object using the ID returned to you during the creation of the transaction. Then, retrieve the transaction using this PackageId in the OneSpan Sign client. The following code will do this:

 //retrieve a package   ESignLiveSDK sdk = new ESignLiveSDK();   ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId); 

You can also retrieve a list of transactions. The following code will do this:

 public List<ESignLiveAPIObjects.Package_x> getPackages(Map<String,String> queryParameters) 

You can pass a map of query parameters in order to narrow your search like this:

 List<ESignLiveAPIObjects.Package_x> pkgs = getPackages(new Map<String,String>{'from'=>'0','to'=>'9','status'=>'SENT'}); 

The code example above will return the first ten transactions that are in a SENT status. You can, however, query other statuses, such as DRAFT, COMPLETED, DECLINED, EXPIRED, and ARCHIVED.

Updating a Transaction

To update an existing transaction, create a transaction object with only the updates you want to make to the transaction. Then, call the updatePackage() function with the PackageId of the existing transaction and the updates Package_x object. The following code will do this:

// Option 1: Retrieve and update an existing package
ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);

// Option 2: Create a new package object and update its name
ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();
pkg.name = 'changed package name';

// Update the package using the SDK
sdk.updatePackage(pkg, packageId);

Deleting Transactions

If you want to permanently remove a transaction from your account, call the deletePackage () function using the PackageId of the transaction you wish to delete.

Deleting a transaction cannot be undone.

The following code will do this:

// Delete the document package using its package ID
sdk.deletePackage(packageId);

If you do not want to permanently delete this transaction, you can instead move it to your Trash folder. This way it will not be deleted and can be retrieved at a later date. The following code will do this:

// Retrieve the package using its ID
ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);

// Mark the package as trashed
pkg.trashed = true;

// Update the package to apply the change
sdk.updatePackage(pkg, packageId);

Archiving Transactions

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.

To do this, call the setStatus() function with the PackageId of the transaction you wish to archive. The following code will do this:

// Archive the document package (only possible if the package is completed)
sdk.setStatus(packageId, ESignLiveAPIObjects.PackageStatus.ARCHIVED);

// Restore the archived package by setting its status back to COMPLETED
sdk.setStatus(packageId, ESignLiveAPIObjects.PackageStatus.COMPLETED);