Considerations when configuring time zones

When configuring time zones in Experience Cloud, remember that every time the platform is accessed or data is modified, a time zone is used. This includes data imports, data exports, and reports (including filters).

The following image shows the main areas to consider when configuring time zones:

The table below lists the relevant areas:

Understanding company requirements

Before configuring time zones be sure that you understand your company's requirements. Some typical questions to ask include:

• Who will be looking at the data? Where in the world are these people located?

• Do users need to see time in a local time zone, or does the company always use a global corporate time zone?

• Can the company provide time zones for all records in the Feed and Org files?

Companies must provide time zones in their Feed and Org files. Reports use the local time of each unit. Ensure that your company contacts understand that while reports show data per the correct time zones, there is no clear way to display the time zones themselves. Also note that there is no way to toggle between different time zones.

When implementing time zones, there are three possible options:

No matter which approach is chosen there are three things that need to be taken into account:

Time zone configuration objects

To make time zone configuration easier, Experience Cloud solutions include several time zone configuration objects, including a Time zone unit group containing a child item for every time zone. Use these child items when mapping units through your Org Auto Importer.

Experience Cloud also includes several time-shift K-fields, which calculate fields with Date/Time data type based on the Timezone Unit group of the records displayed in reports, as shown in the following image.

The first 5 K-fields are meant to replace Event fields with Date/Time data type in record-level reports:

• Local Creation Date.
• Local Response Date.
• Local Alert Closed Date.
• Local Invitation Date.
• Local Expiration Date.

The next 3 K-fields are meant to replace Event fields with Date/Time data type in Health Check reports:

• Local SSO Attempt Date.
• Local Export Start Date.
• Local Export End Date.

Lastly, the Local Timezone K-field ensures that there is a default time zone available for reports if one of the other time zone K-fields is configured incorrectly (such as when the code specifies an invalid time zone). For example, you might edit your Responses reports to use the Local Response Date K-field instead of Response date (e_responsedate). To configure these K-fields, specify a default time zone in the following line:

var DEFAULT_TIMEZONE = 'America/Los_Angeles';

Configuring time zones

If your company needs to use one or more time zone other than Pacific time, complete the following steps to configure time zones in your Experience Cloud solution:

1. On the Company > Units > Groups Admin screen, ensure that the root group (usually All Company Units) has a value for the TimeZone property. This becomes the company time zone, and can be used to set relative time zones, as described in User time zones for relative time periods.
2. When importing Org data, ensure that your Auto Importer maps a time zone to the Timezones field for every unit. Available values for this field include all of the child items of the Timezones Unit group you verified in the previous step.

   For more information about working with Auto Importer, see Importing.

3. On the Reporting > Fields > K-Fields screen, specify a default time zone in the following line for each of the listed K-fields:

   var DEFAULT_TIMEZONE = 'America/Los_Angeles';

   • Local Creation Date.

   • Local Response Date.

   • Local Alert Closed Date.
   • Local Invitation Date.
   • Local Expiration Date.

   • Local SSO Attempt Date.

   • Local Export Start Date.

   • Local Export End Date.

   For more information about configuring K-fields, see K-fields.

4. Update your standard report modules, record-level custom reports, and Health Check custom module to use the time-shift K-fields in place of standard Event fields with Date/Time data type.

   For more information about working with standard report modules, see Standard Report Modules. For more information about working with custom modules, see Custom Module. For more information bout Health Check, see Health Check.

5. On the Reporting > Report Helpers > Fields > Backfill screen, run a backfill to ensure that in-memory data is updated to reflect the changes you made to time zones.

   For more information, see Backfill.

   Important: Any time you make changes to time zone objects, you must follow those changes with a backfill.
6. By default, Experience Cloud displays dates in the US format. If you want to display dates in a different format, see Displaying dates in non-US formats.

Imports

When importing data through Auto Importer, if your data includes a field with Date/Time data type, be sure to also specify the time zone. Ask your company representative to provide this in the feed file. Most corporate IT systems can provide that data. If you do not provide a time zone, Experience Cloud assumes Pacific time for the source data.

Upon importing Date/Time data type fields, Experience Cloud converts and stores it in Pacific time. All of the Date/Time values still reflect the source data accurately, but are time-shifted to a single timezone. Because of that shift, the other configurations explained in this topic are necessary.

Org hierarchy

To determine which surveys should be associated with a specific date, Experience Cloud uses the time zone of each unit, which is set by the TimeZone property of the parent Unit group.

For example, consider a retail store in London, which is represented in Experience Cloud as a unit. The store is part of the UK unit group, where the TimeZone has been set to Europe/London. A user who has filtered report data down to this store for the 8th of December 2017 sees surveys that were completed on that day, London time. The user might be in a different time zone, but for reporting only the unit time zone matters.

The easiest way to configure this is to use the child items of the Timezones unit group, mapping units to the correct Timezone unit group in the Org Auto Importer.

User time zones for relative time periods

The example in the previous section is clear when the report Time period is fixed, such as a specific date. However, many time periods in Experience Cloud are relative (such as Today, Last Week, Previous Six Months, and so on). Relative time periods mean different things to users in different time zones.

For example, consider the hour of 6 a.m. London time on the 8th of December. While that point in time is Today for a user in London, it is the 7th of December for a user in San Francisco.

When a user picks a relative time period in a report, Experience Cloud must choose a time zone for determining the dates to which the relative timeperiod corresponds. By default, Experience Cloud does this by obtaining the user's time zone from one of the following sources, in order of preference:

1. The Time Zone of the user's role. Set this property in the following scenarios:
   • Your users reside in different time zones, but you want all users in a role to see the same time zone in reports. For example, you might want all users across the United States to see the same numbers in reports.
   • Your users sign in through Single sign-on (SSO), which makes the browser source described below unavailable, and you want to use multiple, role-based time zones instead of the single, company-wide time zone.
   

   For more information about configuring roles, see Roles.

2. User preference set as part of self-service.
3. The user's browser.
   Note: This source is available only when users sign in manually with a username and password. Experience Cloud cannot retrieve the user's time zone when signing in through SSO.
4. The Time Zone property value for a unit group, starting at the highest-level group and working downward to child groups until a value is found. For more information about configuring unit groups, see Unit groups.

Using K-fields to display time zones in reports

As noted earlier, Experience Cloud stores all dates in Pacific time, and for report filtering uses the unit time zone to determine which surveys should be displayed for a selected time period. For this to work, the platform expects the reporting date to be in Pacific time (such as with the e_responsedate field). This causes the reporting application to processes date filters and display dates differently, as highlighted in the following image:

While you can use time-shift K-fields in Medallia Alchemy Experience Reporting modules, it is not necessary because these modules automatically adjust the displayed time of E-fields according to your Experience Cloud time zone. For more information about the modules included in Medallia Alchemy Experience Reporting, see Reporting.

Legacy report modules, however, must use time-shift K-fields to calculate time zones for each field with Date/Time data type used in reporting, based on the time zones used in unit data fields.

There are two possible options: the K-field can either have a hard coded time zone, or it can pull in the time zone from a unit data field. If there is more than one time zone, store this on the unit level; otherwise, it would be necessary to write one k-field for every time zone.

K-field syntax for hardcoded time zone (available in K-field library):

(function() {
	
	// The first timezone is the desired output, while the second timezone is current (typically 'US/Pacific').
	// Find the full list of timezones here: http://joda-time.sourceforge.net/timezones.html
	return date(e_responsedate).withZone(org.joda.time.DateTimeZone.forID('Europe/Moscow')).withZoneRetainFields(org.joda.time.DateTimeZone.forID('US/Pacific'));
	
})();

K-field syntax for getting time zone from unit data field (available in K-field library):

(function() {
	
	//Set timezone to the value of the unit data field holding the timezone
	var timezone = getUnitDatafield(e_unitid,'timezone');
	
	//Check if timezone is missing and set a default timezone if it is missing.
	!!timezone ? timezone : timezone = "Etc/GMT";
	
	//Check if timezone is invalid and set a default timezone if it is invalid.
	!!org.joda.time.DateTimeZone.getAvailableIDs().contains(timezone) ? timezone : timezone = "Etc/GMT";
	
	// The first timezone is the desired output, while the second timezone is current (typically 'US/Pacific').
	// Find the full list of timezones here: http://joda-time.sourceforge.net/timezones.html
	return date(e_responsedate).withZone(org.joda.time.DateTimeZone.forID(timezone)).withZoneRetainFields(org.joda.time.DateTimeZone.forID('US/Pacific'));
	
})();

For more information about these K-fields, see Time zone configuration objects.

Health Check reports

By default, Health Check custom reports always assume Pacific time because no units are associated with the data. However, you can work around this default behavior by adding a time-field attribute to the optionbox-filter element in your report. For example:

<analytics-report> 
	<axis axis="Columns Dropdown"> 
		<optionbox-filter plugins="UNIT,TIMEPERIOD,COLUMNS" time-field="k_packages_bp_timezone_create_datetime"/>  
		<columns-dropdown-split/> 
	</axis>  
	<axis axis="Key Health Metrics"> 
		<field-not-null field="e_packages_bp_abtesting_general_variant_alt"/>  
		<aggregate operation="AVERAGE"/>  
		<format decimals="1"/>  
		<heading-blank text="i18n:bp_click_through_rate" css-class="row-em background-blue nowrap"/>  
		<split field="e_packages_bp_abtesting_general_variant_alt" min-sample-size="1"> 
			<aggregate-field field="r_packages_clickthrough_rate"/> 
		</split>  
		<heading-blank text="i18n:bp_abandonment_rate" css-class="row-em background-blue nowrap"/>  
		<split field="e_packages_bp_abtesting_general_variant_alt" min-sample-size="1"> 
			<aggregate-field field="r_packages_abandonment_rate"/> 
		</split>  
		<heading-blank text="i18n:bp_response_rate" css-class="row-em background-blue nowrap"/>  
		<split field="e_packages_bp_abtesting_general_variant_alt" min-sample-size="1"> 
			<aggregate-field field="r_packages_response_rate"/> 
		</split>  
		<heading-blank text="i18n:bp_comment_rate" css-class="row-em background-blue nowrap"/>  
		<split field="e_packages_bp_abtesting_general_variant_alt" min-sample-size="1"> 
			<aggregate-field field="r_packages_bp_abtesting_comment_rate"/> 
		</split>  
		<heading-blank text="i18n:bp_time_to_complete_minutes" css-class="row-em background-blue nowrap"/>  
		<split field="e_packages_bp_abtesting_general_variant_alt" min-sample-size="1"> 
			<aggregate-field field="r_packages_survey_time_to_complete"/> 
		</split> 
	</axis> 
</analytics-report>

Displaying dates in non-US formats

Experience Cloud reports show dates in the format of the user’s reporting language. By default, this is American English. For example:

To show dates in other formats (such as UK English), configure languages and locales in the Experience Cloud Setup environment. For detailed information about configuring languages and locales, see Localization.

Turn on the UseForReporting property, and be sure to activate the locale. Turn off the UseForSurveys property if you will not use the locale for surveys.

Configuring a locale enables Experience Cloud to display most dates correctly. Some areas (such as custom time periods and email template dates) are not affected by locales. You can work around exceptions by manually setting the format you want on the Reporting > Localization > Translations screen. For example, you might update the MM/dd/yy format to dd/MM/yy, as shown in the following image. For detailed information about localizing your Experience Cloud solution, see Localization.

Exports

When filtering data to include in the export, Experience Cloud uses Pacific by default. To work around this, such as when you need to filter by a relative time period, use a time-shifted K-field associated with a time period to ensure that exports contain the correct time.