OneSpan Sign Release 11.21: Time Zone Support

Recently, we deployed version 11.21 of OneSpan Sign to the preview and sandbox environment. One of the new features added in this version is customizable time zones for transaction owners at the Account/Sender and Transaction levels. You can find the deployment dates for all our environments on our Trust Center page.

In this blog, we’ll focus on how to configure Time Zone in Account, Sender and Transaction levels via the Web UI, REST API, and SDKs. 

What to Expect with Time Zone Support

Time Zone Support allows Senders and Integrators to configure a transaction with a specific time zone. Visible time components like signature timestamp and date fields will format and show the time according to time zone configured at package level. It creates less confusion for signers that need to sign a contract by a certain date.

The timestamp will include the time zone name. (EST instead of GMT -5:00 as the above picture shows).

Note:

Below are the date formats used for the signature and date fields:

{
 "signatureFormat": "e-Signed by $signer_name; \n on $date;",
 "signatureDateFormat":"yyyy-MM-dd HH:mm:ss z
} 

And this is for my date field:

{
 "aws.document.autofield.date.format" : "yyyy-MM-dd HH:mm:ss z"
}

You can have these formats updated per your requirement by contacting our support team.

There are three levels on which you can configure the Time Zone: Account, Sender, and Transaction. A zone specified at the Transaction level supersedes zones specified at the other levels, and a zone specified at the Sender level overwrites the Account level time zone setting. We will discuss how to set these three levels in the section below.

Account Time Zone Configuration

Specifying time zone at the Account level changes the default Time Zone for newly invited Senders in your account. You can have this configured by contacting our Technical Support.

Note:

• Newly invited Senders will inherit the Account level time zone.
• But all existing accounts and its senders’ time zone will be set as system default (GMT 0:00)
• Setting the Time Zone at the Account level won’t directly change the existing Senders’ time zone. Therefore, you may want to follow the next section.

Sender Time Zone Configuration

Sender Time Zone is a more granular setting than Account Level, which provides you with more flexibility when you have multiple senders. This comes in handy when your senders are under different local time zones. All new transactions moving forward will inherit the Sender Level Time Zone Configuration as default and all existing packages will be set as system default (GMT 0:00).

In Web UI

On the Personal Information page, a new Time Zone field has been added, and you can specify the time zone through the drop-down list containing all time zones.
 

Note:

• Timezone Support currently only shows up in New Sender UI. Classic Sender UI does not include Timezone Support.

REST method

Below API is used to update a sender. 

HTTP Request
POST /api/account/senders/{senderId}
HTTP Headers
Accept: application/json
Content-Type: application/json
Authorization: Basic api_key
Request Payload
{
	"timezoneId": "America/Toronto"
}

Note:

• “timezoneId” is an attribute under your Sender JSON
• Time Zone id and label mapping table will be at the end of this blog

SDK method

Java SDK:

eslClient.getAccountService().updateSender(SenderInfoBuilder.newSenderInfo("[email protected]")																	 
                                                            .withTimezoneId("America/Toronto").build(), "18EZDL44xgsX");

.Net SDK:

eslClient.AccountService.UpdateSender(SenderInfoBuilder.NewSenderInfo("[email protected]")																	 
                                                       .WithTimezoneId("America/Toronto").Build(), "18EZDL44xgsX");

Package Time Zone Configuration

Package Time Zone will default to the Sender Level setting, but you can still set a specific Time Zone for each package. And same to package, templates can also be given a time zone value and packages created from templates will inherit this setting.

In Web UI

A new Time Zone field has been added to the Advanced Options Tab on both the “Create New Transaction” page and Package Edition page.

REST method

Below API call is an example for package creation.

HTTP Request
POST /api/packages
HTTP Headers
Authorization: Basic api_key
Accept: application/json
Content-Type: application/json
Request Payload
{
  "name": "test time zone",
  "description": "",
  "autocomplete": true,
  "type": "PACKAGE",
  "due": null,
  "language": "en",
  "timezoneId": "America/Toronto"
}

Like Time Zone at Sender Level, this “timezoneId” attribute stores at the Package JSON:

Java SDK:

DocumentPackage pkg = PackageBuilder.newPackageNamed("Test Time Zone")
            	.withSigner(SignerBuilder.newSignerWithEmail("[email protected]" )
            			......
            			)
            	.withDocument(DocumentBuilder.newDocumentWithName("document 1")
            			......
            			)
            	.withTimezoneId("America/Toronto")
            	.build();
		
		PackageId packageId = eslClient.createPackageOneStep(pkg);

.Net SDK:

DocumentPackage pkg = PackageBuilder.NewPackageNamed("Test Time Zone")
            	.WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]" )
            			......
            			)
            	.WithDocument(DocumentBuilder.NewDocumentWithName("document 1")
            			......
            			)
            	.WithTimezoneId("America/Toronto")
            	.Build();
		
		PackageId packageId = eslClient.CreatePackageOneStep(pkg);

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!