Post

2 followers Follow
1
Avatar

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

}

Ophir Kenig Answered

Please sign in to leave a comment.

6 comments

0
Avatar

If I enter a start date, will it go in as midnight PST, midnight GMT or the working day start time, GMT adjusted?

Similarly, will an end date have a non-midnight GMT timestamp ?

RHB 0 votes
Comment actions Permalink
0
Avatar

Hi, the timestamp is taken from the time zone settings of the user the API works with. The concept is similar to working with the API of SFDC.

Yaron Perlman 0 votes
Comment actions Permalink
0
Avatar

yes, but when I punch in a date, for a start date, what time does the day start. midnight or the working day start time, e.g. 9:00am, and similarly for the end date, what is time associated with it? In the database, knowing that it is stored as GMT.

RHB 0 votes
Comment actions Permalink
0
Avatar

It depends on the user you are using to access the API. 

Yaron Perlman 0 votes
Comment actions Permalink
0
Avatar

so is it always the user's workday starting time, converted and stored as GMT?

RHB 0 votes
Comment actions Permalink
0
Avatar

Work items start/due date times are according to the Organizational Calendar times (or the Project Calendar if you use one), in the organizational timezone. For example:

  • You have a work item with a start date of Aug 29
  • The organizational time zone is PST (UTC-8)
  • The organizational calendar's working hours are 9:00am - 4:00pm 

With these the start time of the work item would be Aug 29 5:00pm (UTC).

Note: The start/due dates only depend on the organizational time zone (so they are uniform for the organization). They do not depend on the identity or time zone of the manager/resources of the work item.

Ophir Kenig 0 votes
Comment actions Permalink