Yardi Store Developer eXchange

From time to time we are contacted by developers who are confused about the handling of Date values by the Store 4 platform. To help clarify this, I’d like to present these three things that every developer MUST be aware of when writing code for the Store 4 web services:

All Date values have times associated with them.

The most important thing to remember is that Date values are not just arbitrary; they represent a specific moment in time. So when you see the value “1-1-2011”, you need to be aware that it actually represents “1-1-2011 12:00:00 AM”.

All Date values have time zones associated with them.

Following the same pattern, all Date values contain time zone information–whether you see it or not. Most software platforms consider Date values to be in local time by default, so that’s most likely a safe assumption for any client. XML, as a universal data format, is an example of this: If you look at any Date parameters in XML, you can plainly see the time zone information there. When an XML Date parameter reaches the Store 4 servers, it is translated into local server time before being processed.

This is done for 2 reasons:

1. The server is like any other platform in that it prefers to work in local time.
2. As stated above, the Date value represents a specific moment in time. Midnight in New York is the same moment in time as 10:00 PM the previous day Utah; so converting the value to local time is really the more accurate approach.

But here’s the real kicker that causes the most confusion:

Store uses Mountain time for all date values.

The Store client and server treat all dates as if they were in Mountain time, regardless of the client’s actual location. This includes daylight savings time as well. So when a site in New York records a transaction at 1:00 PM Eastern time, Store actually saves it as 11:00 AM Mountain time in the database. The same thing happens with a site in California: A transaction at 1:00 PM Pacific time is recorded as 2:00 PM Mountain time.

We definitely want to find a more robust solution for this in the future. It’s obviously not an approach that will work well on a global scale; but for the time being we’re only in the U.S. market and it makes reporting much easier for the users if they don’t have to consider time zones.

The downside to this is that special consideration must be taken by our web service clients. We handle all the time zone conversions in our own client, but any custom clients must do the same. So let’s walk through an example to see how the whole process works.

Let’s suppose a client in New York wants to pull down its list of transactions for a single day–January 1st, 2011. The client would create a request message using these Start and End dates:

• StartDate = 1-1-2011
• EndDate = 1-2-2011

Now, different client technologies may encode the date in slightly different formats in XML. It’s important to find out how your particular technology serializes dates, so you can adjust accordingly. But when the message is sent to Store, it will probably look something like this:

• <StartDate>2011-01-01T00:00:00-05:00</StartDate>
• <EndDate>2011-01-02T00:00:00-05:00</EndDate>

Note the time and time zone information that was automatically included with the values. The server will take these values and convert them to its own local time (MST), so the values will then be:

• StartDate = 12-31-2011 10:00:00 PM
• EndDate = 1-1-2011 10:00:00 PM

Now when the query executes on the server using these values, you can see that it will be off by two hours, and the data returned may be inaccurate. To counteract this, the client needs to shift its date values by its own local offset from MST. So, since New York is 2 hours ahead of MST, they should add 2 hours to all of its date values before sending them to Store–that way they’ll be converted to the correct time in MST, and the query will return the desired results. By the same token, any date values returned from the web services will probably be automatically converted to the client’s local time (EST in this case), so they should remove 2 hours from each date value coming back to make sure they are used consistently.