Dealing With Date and Time With Corticon.js

In this blog we will explore the complexity of dealing with date/time in general and in particular with Serverless functions (Lambda or Azure functions).

We will talk about the Universal Time Coordinate (UTC) and we will also look at how to pass date/time values in a Corticon.js decision service JSON payload.

This post is intended for users doing integration of decision services with other systems; it’s not intended for rules author.

Issues Dealing With Date/Time

There are quite a few issues with dealing with dates times and distributed systems in general (distributed clients as well as distributed decision services):

• We cannot make any assumptions of where a decision service runs. Indeed, it could be deployed to a data center on East Coast of the U.S. or in Europe or in Asia, etc.
• The client requests could be coming from different time zones as well.
• When implementing composite applications, the various services invoked could be running in different time zones and as well be using different date formats. A simple example composite application would be an event in AWS Cloud or Azure triggers the execution of few REST calls, the data from these calls is composed into a payload and passed to a set of decision services.

Here is a quick diagram showing the complexity of dealing with distributed clients as well as distributed decision services.

This scenario could be for example, a rental car service where the dates exchanged are the date of the reservation and the date/time when the vehicle is available.

Client 1 is on the East Coast of the U.S. and makes a request for reserving a car. The request can be served by Server 1, which is in the same time zone but is running in the cloud where the servers are set to UTC time anyway. As part of fulfilling the request, Server 1 makes a request to a REST service for computing a premium based on where the vehicle will be driven and to a second service to adjust premium based on the risk adjusted for the season. This REST services are running in different time zone than the client and Server 1 as well.

Client 2 is in Bermuda at UTC – 3, but its request is routed to a data-center on the West Coast of the U.S. at UTC – 7.

We can also imagine the scenario where Client 1, flies to a different city and is now at UTC – 5. The date/time computations still need to occur properly.

We quickly see how complex the situation gets and that we cannot make any assumptions of where a decision service runs, even between two successive requests.

Standardizing on UTC as a universal time coordinate starts to make sense if we don’t want to pull hair trying to make complex systems work 😊.

UTC

UTC stands for Universal Time Coordinate. Corticon.js decision services will convert all date/time to UTC time reference automatically and will do all its computations and output in UTC mode. There are many reasons to take this approach:

1. To establish a common reference no matter where various instances of the engine is running which is good for communications between services
2. To keep things simpler (think about troubleshooting and debugging)
3. To make things more maintainable and easier to test

For some good reads on why use UTC see: The Worst Server Setup Mistake You Can Make and Always Use UTC Dates And Times, among others.

As a side note, there are similarity between UTC and GMT but technically these are different. See UTC – The World's Time Standard for more background data and differences between UTC and GMT.

Format in JSON Payload

UTC lets us agree on a specific time coordinate, but it does not specify the format to represent the date/time in a request or response.

JSON does not standardize how to represent dates and times. The most common formats we have seen used in services, in particular REST services, are ISO 8601 and as a number (number of milliseconds since epoch). Thus, in order to make your life easier, we decided to support these two formats right out of the box.

In the JSON payload the date/time data can be specified as either:

1. An ISO 8601 date format as a string. We get into that format in more detail in this related blog post. You can check https://en.wikipedia.org/wiki/ISO_8601 for a reference.
2. A long value, representing the time since epoch in ms (Timestamp in milliseconds). It can be passed either as a string or as a number. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTime) This format is not easily readable, you can use this tool, for example: https://www.epochconverter.com/to get at a local time representation.

For example, here is how you could pass the date/time (UTC) “Thursday, July 30, 2020 6:00:00 PM” in the decision service JSON payload:

1. 2020-07-30T18:00:00.000Z
   This represents the date/time as ISO 8601 directly to the UTC reference (that is with no time zone specified).
2. 2020-07-30T14:00:00.000-04
   This represents the same date/time as ISO 8601 with a time zone (notice instead of 18 hour it is 14). We do accept this format as input but won’t return the results in this notation.
3. 1596132000000
   The same date/time as the number of ms since epoch
4. “1596132000000”
   Same as previous one but as a string. We support this as a convenience and to avoid confusions.

So, to summarize, here are a couple of things to keep in mind:

1. The Corticon.js engine does all its computation using UTC as the time reference.
2. The Corticon.js engine will always return DateTime to UTC and formatted as ISO 8601 no matter what the input format you used (for input options see next section where we talk about time-zones).

Dealing With Time-Zones

Here are key parameters to consider when thinking about TZ:

• Identical Serverless functions could be running in different data center with different TZ
• Azure or Lambda are configured to run in UTC anyway
• Two client UIs could be running in different TZ
• Mobile users, using the same application may travel to a different place. They expect the application to continue working correctly.
• Even more tricky, the output from a decision service could be used as input to another API (REST, Serverless or others) that reside in different TZ.

At the end of the day, decision services are one part of a bigger picture and the integrator has to deal with TZ no matter what. We are not really adding a new problem here. We are defining simple rules by which dates and times will work correctly.

Now that you understand the issues dealing with date, we recommend you work with UTC dates and only adjust to the local user time zone just before displaying them.

To make your life a little easier, we offer two options:

1. Convert all date/time to UTC before writing to the payload (for example, 2020-07-30T18:00:00.000Z)..
2. Pass the date/time with a TZ offset (for example, 2020-07-30T14:00:00.000-04), Corticon.js will recognize the TZ and construct the UTC date/time appropriately.

Independently of the option chosen, the date/times in the result JSON will be returned in UTC. You are left with the task of converting to the local time zone of the various devices where the date/time is rendered. Of course, this is assuming the result is directly used in a user interface, if you are chaining a decision service to another, you likely won’t need to do any conversion.

In conclusion, dealing with date/times is tricky. We tried to make the life of an integrator easier by:

1. Standardizing to UTC decision service computations and output. This simplifies things a great deal and avoid lots of headaches troubleshooting issues.
2. Still allowing you to pass the date/time as input in either UTC or with a time zone offset.
3. Offering two different standardized formats for date/time representation in the JSON data. This should provide flexibility when meshing decision services with other services.

Hopefully, you find this useful for integrating your decision services into your applications and as importantly, for debugging and maintaining it.

Feel free to leave a question below for any additional questions you may have.

We discuss the ISO 8601 date/time format in this related blog post, "Understanding ISO 8601 Date and Time Format."

Learn more about Corticon.js