Working with dates and times
This section contains information that is important to consider when working with dates and times.
iCore System time zone
In iCore Integration Suite, all dates and times are stored as UTC (Coordinated Universal Time). Dates and times that are not specified in UTC are internally converted to UTC before they are stored. For the conversion to work correctly, the software needs to know what time zone the iCore system is currently using, and therefore the concept of an "iCore System time zone" is introduced. In most cases, the iCore System time zone is the same as that of the computer/server on which the iCore system has been running.
Example:
A non-clustered iCore System that has been running on a server in Sweden is upgraded. The following iCore System time zone is selected from the list of available time zones: (UTC+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna.
Setting the System time zone
The iCore System time zone is set when a new system is created, or when an existing system (of a version earlier than iCIS v4.2.xx) is upgraded. It can also be set in the System settings in the Administrator tool.
.NET struct System.DateTime
The System.DateTime.Kind property indicates whether the time represented by the instance is based on local time, Coordinated Universal Time (UTC), or neither.
DateTime in iCIS
When DateTime instances are used in iCIS, its Kind is interpreted as shown in the table below.
| System.Datetime.Kind | Interpretation in iCIS | Remarks |
|---|---|---|
| Unspecified | System time | |
| Utc | UTC time | |
| Local | Local time of the machine on which the code is currently running. | Not recommended. This option will be interpreted as the time zone of the local computer and not the system, which may not be the correct interpretation of what the user wants since it is not certain what machine may execute the component containing the code. |
Date and time as input to iCIS
A date and time value can be given as input to iCIS at both design time and runtime. In both cases, it is important to understand whether this value represents a date and time in the iCore System time zone, or in UTC.
Design time
At design time, dates and times can be given as input to iCIS in different scenarios, for example during the configuration of a Timer, or when configuring time validity in an Adapterflow. In these cases, it is possible to specify explicitly if the given date and time should be interpreted as UTC, by setting the 'Is UTC' property to True (checkbox). If this check box is left unchecked, the date and time value will be interpreted to be in the iCore System time zone.
When you are working with Workflows, note the following:
- To set a datetime in UTC, use a VB expression which specifies DateTime.Kind to 'Utc'.
- When you use the datetime picker to select a date and time, the DateTime.Kind will be set to 'Local'. Make sure to update DateTime.Kind to 'Utc' or 'Unspecified' (if you want to use the iCore System time zone) in the VB expression.
Runtime
Dates and times can also be given as input during runtime, for example during the execution of a filter (as a filter parameter value), or a Script execution. In cases where the date and time is represented by a DateTime instance, iCIS will use the value of the Kind property (described above) to determine the time zone.
In cases where the date and time is represented as a string, for example in Script functions or in Adapterflows, it can look like this:
"2019-01-01 12:00:00". If this date and time is intended to be in UTC, it can be specified by adding a 'Z' suffix: "2019-01-01 12:00:00Z". A string without the 'Z' suffix will be interpreted to be in system time zone.Examples
The following strings represent a date and time that iCIS will interpret to be in the iCore System time zone, and therefore converted to UTC before they are stored:
- "2019-01-01 12:00:00"
- "2019-01-01T12:00:00"
The following strings represent a date and time that iCIS will interpret to be in UTC, and therefore store as is (without conversion):
- "2019-01-01 12:00:00Z"
- "2019-01-01T12:00:00Z"
Important considerations
When working with DateTime instances in iCIS, there are a few properties and methods that should be avoided:
- DateTimeKind.Local – It can never be guaranteed that this time is correct since the time zone of the local computer may differ from that of the iCore system.
- DateTime.Now – Returns a DateTime instance with its Kind set to DateTimeKind.Local.
- DateTime.Today – Returns a DateTime instance with its Kind set to DateTimeKind.Local.
- DateTime.ToLocalTime() – Returns a DateTime instance with its Kind set to DateTimeKind.Local. If Kind is set to DateTimeKind.Unspecified, conversion will probably be incorrect.
- DateTime.ToUniversalTime() – If Kind is set to DateTimeKind.Local, it uses the local time zone of the computer on which it is run at conversion, not the iCore system time zone.
- DateTimeStyles.AssumeLocal – If this enum value is used during parsing of date and time strings to DateTime instances, it will interpret a string with no UTC denotation to be in the local computer's time zone.
If a DateTime instance with Kind set to DateTimeKind.Local must be passed to iCIS, it should be converted first, either to system time or UTC time. There are two extension methods made available in iCore public API for this conversion:
- public static DateTime ToUtc (this DateTime dateTime, ISystem system)
- public static DateTime ToSystemTime (this DateTime dateTime, ISystem system)
note
The extension methods become available by including the namespace iCore.Public.Entities.
Example code
DateTime d = new DateTime(2019, 1, 1, 12, 0, 0, DateTimeKind.Utc) //Instantiates a DateTime with Kind set to DateTimeKind.Utc
DateTime d = DateTime.UtcNow //Returns an instance of DateTime representing the current time in UTC.
DateTime d = DateTime.UtcNow.ToSystemTime(SystemContext) //Returns an instance of DateTime representing the current time in UTC, converted to the iCore System time zone.
DateTime d = DateTime.Parse("2019-01-01 12:00:00Z", CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal) //Date and time represented as a string being parsed to an instance of DateTime with Kind set to DateTimeKind.Utc.
DateTime d = DateTime.Parse("2019-01-01 12:00:00", CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal) //Date and time represented as a string being parsed to an instance of DateTime with Kind set to DateTimeKind.Unspecified.
Remark about DateTimeStyles
The DateTimeStyles enum value AdjustToUniversal can be confusing since it will make the parsing return a DateTime instance with DateTimeKind.Utc only when the string denotes a UTC time. If the input string does not denote a UTC time, no conversion occurs and the resulting Kind property is Unspecified.