< Back to Blog

What every developer should know about time


With daylight savings time ending today, I thought this was a good time for a post. How to handle time is one of those tricky issues where it is all too easy to get it wrong. So let's dive in. (Note: We learned these lessons when implementing the scheduling system in Windward Reports.)

First off, using UTC (also known as Greenwich Mean Time) is many times not the correct solution. Yet many programmers think if they store everything that way, then they have it covered. (This mistake is why several years ago when Congress changed the start of DST in the U.S. you had to run a hotfix on Outlook for it to adjust reoccurring events.)

So let's start with the key question – what do we mean by time? When a user says they want something to run at 7:00 am, what do they mean? In most cases they mean 7:00 am where they are located – but not always. In some cases, to accurately compare say web server statistics, they want each "day" to end at the same time, unadjusted for DST. At the other end, someone who takes medicine at certain times of the day and has that set in their calendar, will want that to always be on local time so a 3:00pm event is not 3:00am when they have travelled half way around the world.

So we have three main use cases here (there are some others, but they can generally be handled by the following):

  1. The same absolute (for lack of a better word) time.
  2. The time in a given time zone, shifting when DST goes on/off (including double DST which occurs in some regions).
  3. The local time.

The first is trivial to handle – you set it as UTC. By doing this every day of the year will have 24 hours. (Interesting note, UTC only matches the time in Greenwich during standard time. When it is DST there, Greenwich and UTC are not identical.)

The second requires storing a time and a time zone. However, the time zone is the geographical zone, not the present offset (offset is the difference with UTC). In other words, you store "Mountain Time," not "Mountain Standard Time" or "Mountain Daylight Savings Time." So 7:00 am in "Mountain Time" will be 7:00 am in Colorado regardless of the time of year.

The third is similar to the second in that it has a time zone called "Local Time." However, it requires knowing what time zone it is in in order to determine when it occurs.

Outlook now has a means to handle this. And you can now set the time zone for each event.

When I have business trips I use this including my flight times departing in one zone and arriving in another. Outlook displays everything in the local timezone and adjusts when that changes. The iPhone on the other hand has no idea this is going on and has everything off when I'm on a trip that is in another timezone (and when you live in Colorado, almost every trip is to another timezone).

Putting it to use

Ok, so how do you handle this? It's actually pretty simple. Every time needs to be stored one of two ways:

  1. As UTC. Generally when stored as UTC, you will still set/display it in local time.
  2. As a datetime plus a geographical timezone (which can be "local time").

Now the trick is knowing which to use. Here are some general rules. You will need to figure this out for additional use cases, but most do fall in to these categories.

  1. When something happened – UTC. This is a singular event and regardless of how the user wants it displayed, when it occurred is unchangeable.
  2. When the user selects a timezone of UTC – UTC.
  3. An event in the future where the user wants it to occur in a timezone – datetime plus a timezone. Now it might be safe to use UTC if it will occur in the next several months (changing timezones generally have that much warning - although sometimes it's just 8 days), but at some point out you need to do this, so you should do it for all cases. In this case you display what you stored.
  4. For a scheduled event, when it will next happen – UTC. This is a performance requirement where you want to be able to get all "next events" where their runtime is before now. Much faster to search against dates than recalculate each one. However, this does need to recalculate all scheduled events regularly in case the rules have changed for an event that runs every quarter.
  5. For events that are on "local time" the recalculation should occur anytime the user's timezone changes. And if an event is skipped in the change, it needs to occur immediately.

.NET DateTime

Diving in to .NET, this means we need to be able to get two things which the standard library does not provide:

  1. Create a DateTime in any timezone (DateTime only supports your local timezone and UTC).
  2. For a given Date, Time, and geographical timezone, get the UTC time. This needs to adjust based on the DST rules for that zone on that date.

Fortunately there's a solution to this. We have open sourced out extensions to the DateTime timezone functionality. This uses registry settings in Windows to perform all calculations for each zone and therefore should remain up to date.

Browser pain

The one thing we have not figured out is how to know a user's location if they are using a browser to hit our web application. For most countries the locale can be used to determine the timezone – but not for the U.S. (6 zones), Canada, or Russia (11 zones). So you have to ask a user to set their timezone – and to change it when they travel. If anyone knows of a solution to this, please let me know.

Update: I received the following from Justin Bonnar (thank you):

  <input id="timezone_offset" type="hidden" name="timezone_offset" value="">
  <script type="text/javascript"></script>
 document.getElementById('timezone_offset').value = new Date().getTimezoneOffset();

Using that plus the suggestion of the geo location for the IP address mentioned below will get you close. But it's not 100%. The time offset does not tell you if you for example if you are in Arizona (they & Hawaii do not observer daylight savings time) vs Pacific/Mountain (depending on DST) time zone. You also depend on javascript being on although that is true for 99% of the users out there today.

The geo location based on IP address is also iffy. I was at a hotel in D.C. when I got a report of our demo download form having a problem. We pre-populate the form with city, state, & country based on the geo of the IP address. It said I was in Cleveland, OH. So again, usually right but not always.

My take is we can use the offset, and for cases where there are multiple timezones with that offset (on that given day), follow up with the geo of the IP address. But I sure wish the powers that be would add a tz= to the header info sent with an HTML request.

Did I miss anything?

If I missed an interesting use case, please let me know. Comments as always are very welcome.

What every developer should know series:

  • What every developer should know series
  • If you've just discovered us, we're excited. Know more about Windward and get your 14-day free trial and start creating documents in quick time with our low/no code solutions.

    Tags Start & End

    Tags Can Start & End Anywhere

    Appendix B

    .NET code for multi-page image output

    Appendix A

    Java code for multi-page image output

    Data Bin Search

    The Data Bin can now be searched to find a table, column, node or other piece of data without scrolling through it all.

    Shrink to Fit

    This will shrink the contents of a cell until it fits the defined cell size.

    Time Zone Conversion

    A new Windward macro has been added to help with converting dates and times from UTC time to the local time zone.

    Image Output Format

    New image output formats added.

    PostScript Output Format

    PostScript, commonly used with printers and printing companies, has been added as an additional output format.

    New and Improved Datasets (Designer, Java Engine, .NET Engine)

    Datasets have been re-written from scratch to be more powerful and easier to use.

    Stored Procedure Wizard (Designer)

    This works for all tag types that are connected to a SQL-based data source (Microsoft SQL Server, Oracle, MySQL, or DB2).

    Boolean Conditional Wizard (Designer)

    Before, conditional statements could only be written manually. Now they can also be built using our intuitive Wizard interface.

    Reorganized Ribbon

    The ribbon menus have been re-organized and consolidated to improve the report design workflow.

    XPath 2.0 as Data Source

    Adds various capabilities such as inequalities,descending sort, joins, and other functions.

    SQL Select Debugger

    SQL Select  Debugger

    • The look and feel was improved
    • Stored Procedure Wizard
    • Improved Exceptions pane

    Tag Editor/Tag Selector

    Added a Query tab as a field for typing or pasting in a select statement

    • Color Coding of Keywords
    • TypeAhead
    • Evaluate is now "Preview"

    Rename a Datasource

    All tags using that Data source will be automatically updated with that name.

    Connecting to a Data Source

    New single interface to replace 2 separate dialog boxes

    Tag Tree

    Displays of all the tags in the template, structured as they are placed in the template. This provides a simple & intuitive way to see the structure of your template. Also provides the capability to go to any tag and/or see the properties of any tag.

    Added Javelin into the RESTful Engine

    Support for Google Application Engine Integration

    The ability to integrate the Windward Engine into Google’s cloud computing platform for developing and hosting web applications dubbed Google Applications Engine (GAE).

    Additional Refinement for HTML Output

    • Improved indentation for ordered and unordered lists
    • Better handling of template header and footer images
    • Better handling for background images and colors

    Redesigned PDF Output Support

    This new  integration will allow for processing of complex scripts and bi-directional  text such as Arabic.  Your PDF output  will be much tighter and more closely match your template, and we’ll be able  to respond rapidly to PDF requests and fixes.

    PowerPoint Support

    Includes support for new ForEach and slide break handling, table header row repeat across slide breaks, and native Microsoft support for charts and images.

    Tags are Color Coded

    Tags are color coded in the template by type, making it easy to visually identify them.

    Increased Performance

    Version 13’s core code has been reworked and optimized to offer a reduced memory footprint, faster PDF generation and full documentation of supported features and limitations in the specifications for DOCX, XLSX and PPTX.

    Advanced Image Properties

    Documents can include advanced Word image properties such as shadows, borders, and styles.

    Improved HTML Output

    Windward has updated HTML output to reflect changing HTML standards.

    Version 13 New Data Sources

    Windward now works with a slew of new datasources: MongoDB, JSON, Cassandra, OData, Salesforce.com

    Generate Code

    The Generate Code tool in the designer allows you to open an existing template and, with a click of a button, automatically create a window with the code needed to run your current template with all data sources and variables. Simply copy this code and paste into your application's code in the appropriate place. You now have Windward integrated into your application.

    You only need to do this once. You do not do this for each template. Instead, where it has explicit files for the template and output, change that to parameters you pass to this code. Same for the parameters passed to Windward. This example uses explicit values to show you what to substitute in where.

    Pivot Tables Adjusted in Output

    Any pivot tables in an XLSX template are carried over to the XLSX output. The ranges in the pivot ranges are adjusted to match the generated output. So your final XLSX will have pivot tables set as expected in the generated file.

    This makes creating an XLSX workbook with pivot tables trivial.

    Imported Template Can be Set to Match the Parent Styles

    In an imported sub-template, if its properties for a style (ex. Normal) differ from the parent template's properties for the style, the use in the sub-template can be set to either use the properties in the sub-template, or the properties in the parent.

    You set to retain when you don't want the child template's styling to change when imported. You set to use the parent when you want the styling of the imported template to match the styling in the parent.

    Any explicit styling is always retained. This only impacts styling set by styles.

    Tags can be Placed in Text Boxes

    Tags can be placed in text boxes. Including linked text boxes. This gives you the ability to set the text in a textbox from your data.

    Tags can be Placed in Shapes & Smart Art

    Tags can be placed in shapes & smart art. This gives you the ability to set the text in a shape from your data.

    HTML Output Supports Embedded Images

    When generating HTML output, the engine can either write bitmaps as distinct files the generate HTML references, or it can embed the images in the HTML providing a single file for the output.

    Footnotes & Endnotes can Have Tags

    You can place tags in pretty much any part of a template, including in footnotes & endnotes.

    Document Locking Supported in DOCX & XLSX

    Any parts of a DOCX or XLSX (PowerPoint does not support this) file that are locked in the template, will be locked the same in the output.

    Specify Font Substitution

    If a font used in the template does not exist on the server generating a report, the font to substitute can be specified.
    In addition, if a glyph to be rendered does not exist in the font specified, you can specify the replacement font. This can be set distinctly for European, Bi-Directional, and Far East fonts.

    Process Multiple Datasources Simultaneously

    If you need this - it's essential. And if you don't need it, it's irrelevant.

    Windward enables you to build a document by applying multiple datasources to the template simultaneously. When Windward is merging the data into a template, it processes the template by handling each tag in order, and each tag pulls from different datasources. (As opposed to processing all of one datasource, then processing the next.)

    This allows the select tag to use data from another datasource in its select. For example, if you are pulling customer information from one data source, you can then pull data from the sales datasource using the customer ID of the customer presently processing to pull the sales information for that customer. If you're interested in patching together your data from multiple datasources, read this post on our blog.

    David Thielen

    President/CEO at Windward Studios

    From his early years as a Senior Developer at Microsoft, to legendary designer of the popular Enemy Nations strategy game, to reporting and document generation guru, Dave has never lost his passion for building superb software and teams.

    Written by:_
    David Thielen
    President/CEO at Windward Studios
    Windward © 2021 All Rights Reserved.


    Got questions about reporting and document generation? We've got answers—let's connect!
    Send a note
    messaging, phone, or email contact optionsclose out button