blog

OneSpan Sign Release 11.21: Time Zone Support

Developer
|  December 12, 2018 Duo Liang
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. 12-12-1

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.12-12-2
 

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

12-12-3

SDK method

Java SDK:

eslClient.getAccountService().updateSender(SenderInfoBuilder.newSenderInfo("xx@example.com")																	 
                                                            .withTimezoneId("America/Toronto").build(), "18EZDL44xgsX");

.Net SDK:

eslClient.AccountService.UpdateSender(SenderInfoBuilder.NewSenderInfo("xx@example.com")																	 
                                                       .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.12-12-4

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:12-12-5

Java SDK:

DocumentPackage pkg = PackageBuilder.newPackageNamed("Test Time Zone")
            	.withSigner(SignerBuilder.newSignerWithEmail("signer1@mailinator.com" )
            			......
            			)
            	.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("signer1@mailinator.com" )
            			......
            			)
            	.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!

Appendix: Time Zone ID and Label mapping table ​​​​

ID Label
Etc/GMT+12 (GMT-12:00) GMT-12
Pacific/Samoa (GMT-11:00) Pacific/Samoa
US/Samoa (GMT-11:00) US/Samoa
HST (GMT-10:00) HST
Pacific/Honolulu (GMT-10:00) Pacific/Honolulu
Pacific/Marquesas (GMT-9:30) Pacific/Marquesas
Pacific/Gambier (GMT-9:00) Pacific/Gambier
US/Alaska (GMT-9:00) US/Alaska
America/Los_Angeles (GMT-8:00) America/Los Angeles
America/Tijuana (GMT-8:00) America/Tijuana
Canada/Pacific (GMT-8:00) Canada/Pacific
PST (GMT-8:00) PST
America/Denver (GMT-7:00) America/Denver
Canada/Mountain (GMT-7:00) Canada/Mountain
CST (GMT-6:00) CST
Canada/Central (GMT-6:00) Canada/Central
US/Central (GMT-6:00) US/Central
America/Bogota (GMT-5:00) America/Bogota
America/Toronto (GMT-5:00) America/Toronto
EST (GMT-5:00) EST
US/Eastern (GMT-5:00) US/Eastern
America/Caracas (GMT-4:30) America/Caracas
America/Puerto_Rico (GMT-4:00) America/Puerto Rico
Canada/Atlantic (GMT-4:00) Canada/Atlantic
America/St_Johns (GMT-3:30) America/St Johns
CNT (GMT-3:30) CNT
Canada/Newfoundland (GMT-3:30) Canada/Newfoundland
America/Argentina/Buenos_Aires (GMT-3:00) America/Argentina/Buenos Aires
Brazil/East (GMT-3:00) Brazil/East
Atlantic/South_Georgia (GMT-2:00) Atlantic/South Georgia
Brazil/DeNoronha (GMT-2:00) Brazil/DeNoronha
Atlantic/Azores (GMT-1:00) Atlantic/Azores
Atlantic/Cape_Verde (GMT-1:00) Atlantic/Cape Verde
Africa/Casablanca (GMT 0:00) Africa/Casablanca
GMT (GMT 0:00) GMT
Etc/Greenwich (GMT 0:00) Greenwich
Europe/London (GMT 0:00) Europe/London
Africa/Lagos (GMT+1:00) Africa/Lagos
CET (GMT+1:00) CET
Europe/Paris (GMT+1:00) Europe/Paris
Europe/Zurich (GMT+1:00) Europe/Zurich
ART (GMT+2:00) ART
Africa/Cairo (GMT+2:00) Africa/Cairo
Asia/Istanbul (GMT+2:00) Asia/Istanbul
Europe/Helsinki (GMT+2:00) Europe/Helsinki
Africa/Addis_Ababa (GMT+3:00) Africa/Addis Ababa
Africa/Nairobi (GMT+3:00) Africa/Nairobi
Asia/Tehran (GMT+3:30) Asia/Tehran
Asia/Dubai (GMT+4:00) Asia/Dubai
Europe/Moscow (GMT+4:00) Europe/Moscow
NET (GMT+4:00) NET
Asia/Kabul (GMT+4:30) Asia/Kabul
Asia/Karachi (GMT+5:00) Asia/Karachi
Asia/Kolkata (GMT+5:30) Asia/Kolkata
IST (GMT+5:30) IST
Asia/Katmandu (GMT+5:45) Asia/Katmandu
Asia/Dhaka (GMT+6:00) Asia/Dhaka
Asia/Rangoon (GMT+6:30) Asia/Rangoon
Asia/Bangkok (GMT+7:00) Asia/Bangkok
Asia/Jakarta (GMT+7:00) Asia/Jakarta
VST (GMT+7:00) VST
Asia/Hong_Kong (GMT+8:00) Asia/Hong Kong
Australia/Perth (GMT+8:00) Australia/Perth
CTT (GMT+8:00) CTT
Asia/Seoul (GMT+9:00) Asia/Seoul
Asia/Tokyo (GMT+9:00) Asia/Tokyo
JST (GMT+9:00) JST
ACT (GMT+9:30) ACT
Australia/Adelaide (GMT+9:30) Australia/Adelaide
AET (GMT+10:00) AET
Australia/Brisbane (GMT+10:00) Australia/Brisbane
Australia/LHI (GMT+10:30) Australia/LHI
Australia/Lord_Howe (GMT+10:30) Australia/Lord Howe
Asia/Vladivostok (GMT+11:00) Asia/Vladivostok
SST (GMT+11:00) SST
Pacific/Norfolk (GMT+11:30) Pacific/Norfolk
Antarctica/South_Pole (GMT+12:00) Antarctica/South Pole
NST (GMT+12:00) NST
Pacific/Auckland (GMT+12:00) Pacific/Auckland
NZ-CHAT (GMT+12:45) NZ-CHAT
Pacific/Chatham (GMT+12:45) Pacific/Chatham
MIT (GMT+13:00) MIT
Pacific/Tongatapu (GMT+13:00) Pacific/Tongatapu
Pacific/Kiritimati (GMT+14:00) Pacific/Kiritimati