To ensure that users are able to easily and consistently work with dates across all TeamDynamix applications, dates submitted through the Web API are handled using Coordinated Universal Time (UTC) standards.
When submitting date and datetime fields through the Web API, values should match ISO 8601 standards. This means that values submitted for date and datetime fields should generally match the following format:
The following table describes what part of the date and time is represented in the above datetime format string.
| Component | Description |
|---|---|
| YYYY | Year |
| MM | Month |
| DD | Day |
| T | Separator between the date and time values provided. |
| hh | Hour |
| mm | Minute |
| ss | Second |
| TZD | Time Offset |
A time value can be offset from the standard UTC value using a Time Offset. This either follows the time value as the character 'Z', indicating
that the time is in UTC, or is set to the UTC time offset in the format ±[hh]:[mm] or ±[hh][mm]. The offset may or may not
include a colon separating the hour and minute segment. A full list of UTC time offsets for each time zone can be found
here.
Times returned from the Web API will always be in UTC, however when submitting new values for a datetime field, you may either use the UTC value or provide a UTC offset.
Although full datetime values are accepted for all date and datetime fields in the Web API, there are instances in which only date values are used.
To ensure that these values are set properly when performing operations through the Web API, any date only fields should be set with a time value of
00:00:00. Additionally, a time zone offset should be used to ensure that the date selected is not offset incorrectly while being saved,
leading to display problems in different time zones.
Date only fields returned from the server will have their time value set relative to the server it is being sent from. Care should be taken to ensure that these values are being treated properly when retrieving data through the Web API.
Custom Attributes that are configured as date and date/time fields can be modified similarly to other standard dates (with some exceptions for date-only fields, detailed below). All above formatting rules and specifications apply when setting custom attribute values through the Web API.
Custom Attributes configured as date only fields can be modified in two ways. While standard date/time formatting as described above will correctly set
these custom attributes, you will still have to deal with time zone offsets as needed to set the values properly. To avoid this, date only custom attributes
support a simpler date only format, which allows for users to omit the time and time-zone offset portion entirely. For example, the value
2024-11-13 will set a custom attribute's value to today's date.
As an example, suppose a user needs to submit the current date and time as a value to a field. The following table displays how one might format the current date and time in a number of acceptable ways that the Web API can recognize.
| Format | Date and Time Value | Date Only Value |
|---|---|---|
| Coordinated Universal Time (UTC) | 2024-11-13T06:43:31Z | 2024-11-13T00:00:00Z |
| Eastern Standard Time (EST) |
2024-11-13T01:43:31-05:00
2024-11-13T01:43:31-0500 |
2024-11-13T00:00:00-05:00
2024-11-13T00:00:00-0500 |
| Eastern Daylight Savings Time (EDT) |
2024-11-13T02:43:31-04:00
2024-11-13T02:43:31-0400 |
2024-11-13T00:00:00-04:00
2024-11-13T00:00:00-0400 |
| Pacific Standard Time (PST) |
2024-11-12T10:43:31-08:00
2024-11-12T10:43:31-0800 |
2024-11-12T00:00:00-08:00
2024-11-12T00:00:00-0800 |