OneSpan Sign Developer: Specify Expiry Date

Setting up the expiry date is an important feature for your e-signing experience, because it limits the amount of time your signer has to complete the transaction and helps you manage the lifecycle of your transactions. After a transaction expires, it will return to the “drafts folder” and recipients will lose their access to the Signing Ceremony. 

In the upcoming 11.29 version, one of the most notable updates regarding this feature is the time-based expiry setting. This allows you to define the number of days until a transaction expires rather than specifying a date. So first, we’ll walk you through the current product implementation before we cover the changes coming in the next update. 

Specify Expiry Date

Before version 11.29, specifying a date value was the only available approach to configuring the expiry. This date is formatted in GMT time in the OneSpan Sign system. Therefore if your date is in your local time zone, convert it to GMT before setting it. 

Let’s say we have a transaction, and we want it to expire at “2019-08-23T00:00:00 EDT”. Here we will demonstrate how to set the expiry using both the SDK and API methods below.

SDK function:

We will address the requirement in two steps. First, converting the date to GMT time requires different actions depending on the programming language being used. Second, call an SDK function to configure the date when transaction is created.

Java 

// step1: convert to GMT time
// local date, expire at 2019-07-23T00:00:00 EDT
TimeZone localTimeZone = TimeZone.getTimeZone("EDT");
Calendar localCalender = new GregorianCalendar(2019, 8 - 1, 23, 0, 0, 0); 
Date gmtDate = new Date(localCalender.getTimeInMillis() - localTimeZone.getRawOffset());
// step2: create package with expiry date
DocumentPackage pkg = PackageBuilder
		.newPackageNamed("Create a package with Expiry Date - " + System.currentTimeMillis())
		.expiresAt(gmtDate)
		.build();

.NET 

//step1: convert local time to GMT
// local date, expire at 2019-08-23T00:00:00 EDT
DateTime easternTime = new DateTime(2019, 08, 23, 00, 00, 00);
string easternZoneId = "Eastern Standard Time";
TimeZoneInfo easternZone = TimeZoneInfo.FindSystemTimeZoneById(easternZoneId);
DateTime gmtTime = TimeZoneInfo.ConvertTimeToUtc(easternTime, easternZone);
// step2: create package with expiry date
DocumentPackage pkg = PackageBuilder
        .NewPackageNamed("Create a package with Expiry Date - " + DateTime.Now)
        .ExpiresOn(gmtTime)
        .Build();

You can download the complete sample code for Java and .NET SDK.

REST method:

In JSON level, the expiry is represented as “due” attribute right under the transaction level. We will use below package creation API Call to demonstrate you how to configure it via REST.

HTTP Request

POST /api/packages

HTTP Headers

Authorization: Basic api_key
Accept: application/json
Content-Type: multipart/form-data

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="testDocumentExtraction.pdf"
Content-Type: application/pdf

%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
  "status": "DRAFT",
  "due": "2019-08-23T04:00:00Z",
  "type": "PACKAGE",
  "name": "Example Package"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--

Response Payload

{
    "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

After Transaction Expired

Although setting up the expiry is easy, there are some behaviors that occur once a transaction expires that may interest you. We’ve listed a few that you may have observed below:

•    All signers will lose access to the Signing Ceremony immediately and see the below error page in their screen:

•    The OneSpan Sign system will update the package status to “EXPIRED” hourly, so it’s possible that your transaction will still appear to be in “SENT” status. However, signers will be blocked from the transaction immediately.

•    Once your transaction status is changed, recipients will receive a notification email. To cancel or customize this message, contact our support team. 

•    If a transaction expires and you wish to extend access, you must set the expiry date to a future date and resend the transaction.

Features Paired with Expiry Setting     

Here, we’ve listed features that may interest you when developing with expiry date.

EMAIL.EXPIRE.WARNING

If there are signers who have not yet signed a document, this email template will be sent to signers five days before the transaction’s expiry date. Refer to the Email Template Documentation Page for all available parameters in the template.

EMAIL.REMIND.SIGNER

This Reminder Email is a more general email template used to encourage your recipients to add their signatures to the document. Check our “Setting up a Reminder Schedule” guide for more information.

Callback Notification

If a transaction expires, your integrated application needs to be aware of this and react accordingly. The solution is to set up a callback listener and fire the “PACKAGE_EXPIRE” notification. OneSpan Sign will hit your callback URL carrying the relevant information once the event is triggered.

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!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today