Configuring an Expiry Date

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

Setting the expiry date of a transaction allows you to limit the amount of time your signer has to complete the transaction. After a transaction expires, it will return to the drafts folder and the status will be changed to EXPIRED. Consequently, recipients will lose their access to the Signer Experience. A task often paired with setting an expiry date is setting up a Reminder Schedule.

If you would like to extend the expiry date of a transaction, including those transactions whose expiry date has already past, simply set the expiry date to a future date and resend the transaction.

Specifying the expiry date

The expiry date is a transaction level property that takes a Date value. Date values in OneSpan Sign are formatted using GMT time. If your date value uses another time zone, you must convert it to GMT before using the value in your DocumentPackage object.

For example, if you want the package to expire at "2019-08-23T00:00:00 EDT", use the following code:

// 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());	

Once you set your GMT date, include it when building your DocumentPackage object. The following code will do this:

// step2: create package with expiry date
DocumentPackage pkg = PackageBuilder
.newPackageNamed("Create a package with Expiry Date - " + System.currentTimeMillis())
.expiresAt(gmtDate)
.build();		

Time-based Expiry

Another way to set an expiry date is to use a time interval. This feature makes it easier for senders to specify a expiry date, especially when the work flow depends on templates.

The following transaction level settings determine the time interval to be used when setting an expiry time.

• defaultTimeBasedExpiry

• remainingDays

To set a time-based expiry, use the following code:

DocumentPackage pkg = PackageBuilder
		.newPackageNamed("Create a package with Expiry Date - " + System.currentTimeMillis())
		.withSettings(DocumentPackageSettingsBuilder.newDocumentPackageSettings()
				.withDefaultTimeBasedExpiry()
				.withRemainingDays(15)
				)
		.build();
PackageId createPackage = eslClient.createPackage(pkg);

• Both defaultTimeBasedExpiry and remainingDays must be set to use a time-based expiry.

• When using time-based expiry, the date is automatically calculated by adding the interval days to the transaction creation date.

• With the time-based expiry already set for your transaction, if you still want to specify the exact date, don’t forget to disable the day-based expiry by setting .withoutDefaultTimeBasedExpiry() at the same time that you update the transaction. This will help avoid any potential confusion.

Default Interval Days

Setting the default number of days before a transaction expires can be done at the following levels:

• Account Level: As time-based expiry is a transaction setting, the default values for this configuration can be pre-set by contacting our Support Team . Once this is done all newly created transactions will inherit these values and automatically calculated the “due” attribute based on the creation date and the interval days.

• Template Level: Setting a default number of days before expiry is very useful when working with templates. If you as using a template, it doesn’t make sense for that template to carry a fixed expiry date that would then be recycled in future uses of the template. By setting a default number of interval days, all expiry dates are dynamically calculated. When you create transactions from an existing template, they then inherit a default time interval rather than a fixed date for their expiry.

Transaction Expiration

Once your transaction expires, note the following:

• All signers will lose access to the Signer Experience immediately.

• The transaction status change to EXPIRED occurs hourly, meaning that it's possible that your transaction will still appears SENT status for a short period of time.

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

Refer to "Create a Callback Event Notification Listener" guide to see how to notify your application of the transaction expiry event.

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

Setting the expiry date of a transaction allows you to limit the amount of time your signer has to complete the transaction. After a transaction expires, it will return to the drafts folder and the status will be changed to EXPIRED. Consequently, recipients will lose their access to the Signer Experience. A task often paired with setting an expiry date is setting up a Reminder Schedule.

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

Specifying the expiry date

The expiry date is a transaction level property that takes a Date value. Date values in OneSpan Sign are formatted using GMT time. If your date value uses another time zone, you must convert it to GMT before using the value in your DocumentPackage object.

For example, if you want the package to expire at "2019-08-23T00:00:00 EDT", use the following code:

//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);

Once you set your GMT date, include it when building your DocumentPackage object. The following code will do this:

// step2: create package with expiry date
DocumentPackage pkg = PackageBuilder
        .NewPackageNamed("Create a package with Expiry Date - " + DateTime.Now)
        <strong>.ExpiresOn(gmtTime)</strong>
        .Build();

Time-based Expiry

Another way to set an expiry date is to use a time interval. This feature makes it easier for senders to specify a expiry date, especially when the work flow depends on templates.

The following transaction level settings determine the time interval to be used when setting an expiry time.

• defaultTimeBasedExpiry

• remainingDays

To set a time-based expiry, use the following code:

DocumentPackage pkg = PackageBuilder.NewPackageNamed("Create a package with Expiry Date - "  + System.DateTime.Now)
        .WithSettings(DocumentPackageSettingsBuilder.NewDocumentPackageSettings()
                                        <strong>.WithDefaultTimeBasedExpiry()</strong>
                                        <strong>.WithRemainingDays(15)</strong>
        )
        .Build();

PackageId pkgId = eslClient.CreatePackageOneStep(pkg);

• Both defaultTimeBasedExpiry and remainingDays must be set to use a time-based expiry.

• When using time-based expiry, the date is automatically calculated by adding the interval days to the transaction creation date.

• With the time-based expiry already set for your transaction, if you still want to specify the exact date, don’t forget to disable the day-based expiry by setting .withoutDefaultTimeBasedExpiry() at the same time that you update the transaction. This will help avoid any potential confusion.

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

Setting the expiry date of a transaction allows you to limit the amount of time your signer has to complete the transaction. After a transaction expires, it will return to the drafts folder and the status will be changed to EXPIRED. Consequently, recipients will lose their access to the Signer Experience. A task often paired with setting an expiry date is setting up a Reminder Schedule.

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

Specifying the expiry date

The expiry date is a transaction level property formatted in the following way: {yyyy}-{MM}-{dd}T{HH}:{mm}:{ss}Z. Date values in OneSpan Sign are formatted using GMT time. If your date value uses another time zone, you must convert it to GMT before using the value in your package creation JSON.

For example, if you want the package to expire at "2019-08-23T00:00:00 EDT", use the following code:

HTTP Request

POST /api/packages 

HTTP Headers

Authorization: Basic api_key
Accept: application/json
Content-Type: application/json 

Request Payload

 {
  "status": "DRAFT",
  "due": "2019-08-23T04:00:00Z",
  "type": "PACKAGE",
  "name": "Example Package"
}

Response Payload

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

Time-based Expiry

Another way to set an expiry date is to use a time interval. This feature makes it easier for senders to specify a expiry date, especially when the work flow depends on templates.

The following transaction level settings determine the time interval to be used when setting an expiry time.

• defaultTimeBasedExpiry

• remainingDays

To set a time-based expiry, use the following code:

HTTP Request

POST /api/packages 

HTTP Headers

Authorization: Basic api_key
Accept: application/json
Content-Type: application/json 

Request Payload

 {
  "status": "DRAFT",
  "description": "A test transaction for Time-based Expiry feature.",
  "language": "en",
  "timezoneId": "GMT",
  "settings": {
    "ceremony": {
      "defaultTimeBasedExpiry": true,
      "remainingDays": 15
    }
  },
  "type": "PACKAGE",
  "name": "Test Time based Expiry"
}

Response Payload

{
    "id": "4tz2ekfB7VcO2cFy6Hx1tkmtyo0="
}

• Both defaultTimeBasedExpiry and remainingDays must be set to use a time-based expiry.

• When using time-based expiry, the date is automatically calculated by adding the interval days to the transaction creation date.

• With the time-based expiry already set for your transaction, if you still want to specify the exact date, don’t forget to disable the day-based expiry by setting .withoutDefaultTimeBasedExpiry() at the same time that you update the transaction. This will help avoid any potential confusion.