Date types

Experience Cloud accepts different types of time and date objects. Primarily, it stores and handles dates as Joda Time type, but other types can also be used:

The format a date is stored in can be verified by looking at the importer script used to import the data, or alternatively, the script that populates the field. The table below shows the types that result from common ways to create dates:

If the script that originated the variable is not available, use the functions below to figure out its type. Use the k-field editor.

Use the following operations to transform date objects from one type to another:

Additionally, use the following operation to transform strings into date objects:

Date and time operations

Use the following expressions in JavaScript code, for example, when defining K-fields or Importers. They assume that a date field called mydate exists and can be referenced. Some expressions also reference a second date called mydate2.

date(myDate).getYear()

Generally, these operations must be placed in the context of a function, like shown in the example below:

(function() {
	return mydate.getYear();
})();

Chain operations together by placing a . in between them. Each operation in a chain is evaluated over the result of the previous operation. For example, in the following expression, the plusHours() operation acts upon mydate and adds two hours to it. The isBeforeNow() operation works on the previous result and evaluates if the new date is before the present date, returning True or False.

return mydate.plusHours(2).isBeforeNow();

Date formatting operations

The formatDate() operation takes a date and returns it in any notation format, below are a few examples:

Date manipulation operations

Time manipulation operations

Tips and considerations

Most often, you should rely on the operations and expressions listed above to define K-fields or Importers. However, some cases might merit a different strategy.

In certain contexts, some Date fields are returned as an array of long integers. For example, see the fields used in the action (particularly e_bp_annual_survey_start_date and e_bp_annual_survey_end_date) in the Omni Exporter event below:

{
  "changedEntities" : [ {
    "q_bp_portal_survey_firstname_txt" : null,
    "q_bp_portal_survey_program_alt" : null,
    "q_bp_portal_survey_email_txt" : null,
    "q_bp_portal_survey_language_alt" : null,
    "a_surveyid" : 336042,
    "e_bp_portal_survey_start_date" : [2021,12,2],
    "e_bp_portal_survey_end_date" : [2021,12,27]
  } ]
}

In this case, Date is internally represented as an array with 3 elements: [yyyy, MM, dd] in the JSON structure. To process this array with a string format, use the following approach:

  var fieldToDate = function (field) {
    if (!isArray(field)) {
      return null;
    }
  
    return formatDate(
      new Date(
        field[0],
        field[1] - 1,
        field[2]
      ),
      'yyyy-MM-dd'
    );
  };

The function formatDate() returns a JavaScript Date object, where the initial position in the array represents the year, the second position represents the month, and the third position represents the day of the month.

Common errors

Illegal instant due to timezone offset transition

This usually indicates that a org.joda.time.DateTime operation was used to update an object to a date that does not exist. This is usually because the date falls on a daylight savings time transition.

Change the script to avoid this. For example, use the withMillis() operation to set the date of a org.joda.time.DateTime object while accounting for time shifts. The getMillis() method can be used to get the Unix timestamp of an object, also avoiding this problem. Check the org.joda.time.DateTime documentation for details.

TypeError: Cannot find function [X] in object [Time]

This indicates that an invalid method was used on an object. For example, getHours() will not work on an org.joda.time.DateTime object because that method does not exist for that object type. Reference the object's documentation and use the correct method.

Dates in conditions

When working with import conditions that refer to a period of time, express the time in days months and years as follows:

So, for example, a condition could refer to the field e_record_creationdate, use the operator Date in last interval and have the value 35d.