Timezones usage in the API

As a SAAS solution serving thousands of organizations around the globe, many of them operating in several time zones, Clarizen  is always aware of the time zone of particular time information in the system.

To make a deterministic use of time values all times returned by the Clarizen API are returned in UTC time zone.

If your API implementation needs to display the time in a different time zone, you need to adjust the returned value accordingly.

If the API implementation is not aware of the time zone, or it needs to show time values using the organization time zone or a user time zone (if set), they can be easily retrieved.

The following .NET sample demonstrates calculating a time value using the organizational and the current user timezone (The organization ID and current user ID are returned by the Login message result, or as the result of a GetSessionInfoMessage. if you need a different user time zone, retrieve their ID first).

One more note: Time zones in Clarizen do not consider Daylight Saving (DST).

var retrieveOrg = new RetrieveMessage

{

   Id = new EntityId

   {

      TypeName = "Organization",

      Value = loginRresult.OrganizationId

   },

   Fields = new string[] { "Timezone.Offset", "Timezone.name" }

};

var retrieveUser = new RetrieveMessage

{

   Id = new EntityId

   {

      TypeName = "User",

      Value = loginRresult.UserId

   },

   Fields = new string[] { "Timezone.Offset", "Timezone.name" }

};

var datetime = new DateTime(2013, 5, 27, 8, 0, 0);

var results = service.Execute(new BaseMessage[] { retrieveOrg, retrieveUser });

RetrieveResult OrgResult = (RetrieveResult) results[0];

RetrieveResult UserResult = (RetrieveResult) results[1];

var orgTimeZone = (OrgResult.Entity as GenericEntity).Values[0].Value as GenericEntity;

var userTimeZone = (UserResult.Entity as GenericEntity).Values[0].Value as GenericEntity;

var orgTimezoneName = orgTimeZone.Values[1].Value;

var orgOffset = (int) orgTimeZone.Values[0].Value;

string resultText = "Api sample time is " + datetime.ToString() +

   "\r\nOrg TimeZone " + orgTimezoneName +

   "\r\nOrg Offset = " + orgOffset.ToString() +

   "\r\nTime in organizational timezone is " + datetime.AddMinutes(-orgOffset).ToString();

if (userTimeZone != null)

{

   var userTimezoneName = userTimeZone.Values[1].Value;

   var userOffset = (int)userTimeZone.Values[0].Value;

   resultText += "\r\nUser TimeZone " + userTimezoneName +

          "\r\nUser Offset = " + userOffset.ToString() +

          "\r\nTime in user timezone is " + datetime.AddMinutes(-userOffset).ToString();

}