Date and Time Handling

In Agent all datetime values are transmitted to and from the web browser as UTC. This document is here to guide you on all the fun situations you might run into related to time conversions to and from Clarify database time.

Server Needs

Clarify unfortunately does Not store date and time values in UTC. Most Clarify installations store dates in the Database server's local time zone. You can determine which timezone your Clarify database is configured using this SQL.

SELECT * FROM table_time_zone WHERE is_default = 1

The default time zone has to match the timezone of the database server

UTC Expected

Agent configures all Clarify sessions to set their timezone to a UTC offset of zero. Thus, all date times received from the user need to be in UTC.

Sending Dates

Before you send a date to the server you need to convert it to UTC. Luckily when using our Date Picker this happens automatically.

Non-Required Dates

Even if you are using the Date Picker you might have a date that is not required. When this happens a blank value rather than a valid date is going to be submitted. To correct for this non-required date times need to be compensated for.

Note As I am writing this we are reworking how this will work and this section will be updated to reflect the new mechanism. Which is hopefully no mechanism.

When a date time that is not required it has no value. There is a special value that needs to be sent 01-01-1753 and it of course needs to be converted to utc. Currently we have a helper function in momentHelper that detects a blank value.

function getValidDate(value) {
  var date = moment(value);
  if (date.isValid()) return date.utc();

  return moment(new Date('1/1/1753')).utc();
}

// usage

var startDate = momentHelper.getValidDate(this.model.get('datepickerProperty');

Note that when using the dateFor template helper and DatePicker behavior, this check is done for you automatically so there is no need for post-processing the date unless you also need to add a time to it.

Shift into Manual

When handling dates yourself, as mentioned repeatedly, you need to convert to UTC before posting them to the server. The best way to do this is with momentHelper.

var shipDate = momentHelper.moment($('#shipDate').utc()

// saving your model
this.model.save({ 'shipDate' : shipDate });

Dovetail SDK Additional Fields

This tip is a special case when interacting with endpoints using Doveatil SDK APIs and you need to add additional fields of different data types.

Sometimes it is useful to set additional fields for a Dovetail SDK invocation. There is a mechanism often used to simultaneously update additional fields on the database table which the API modifies. If you are only setting fields with one kind of type you should use the appropriate data type parameter. When you need to mix different types, say a date and a string, you'll need to do the following.

In this example the subcase is being updated and additionally the required_date field and the description field are being updated. The problem is they are two different data types and due to a legacy limitation you can only give one object type for all additional fields. The common denominator here is string as the data access layer will simply coerce the string into the correct datatype. We just need to ensure that the string is in the correct format for a date.

var toolkit = _session.CreateSupportToolkit();

var updateSubcaseSetup = new UpdateSubcaseSetup(request.Id)
{
	Severity = request.Severity,
	Priority = request.Priority
};

updateSubcaseSetup.AdditionalFields.Append("required_date", AdditionalFieldType.String, request.DueDate.ToString("s"));
updateSubcaseSetup.AdditionalFields.Append("description", AdditionalFieldType.String, request.Description);

Notice how the the additional field was set with a sortable string rather than a Date. This ensures that the string will be coerced into a date with all the values we need.

Receiving dates

On the client when you receive a date it will be in UTC but the client doesn't think in UTC they think in their timezone. We use momentHelper to localize the date for the user. We provide a variety of output mechanisms using the Momentization behavior. You simply need to wrap your date in a span with the desired date class and enlist the Momentization behavior and voilà localized dates in your views.

Dates in Forms

It is easy to put a DatePicker on your form using the dateFor form helper.