How time zones work in Sapho

Last update:

Audience: Developers building Sapho micro apps

If you are building micro apps for a company with operations in a country that has multiple time zones (such as the United States) or for a multinational corporation, it is important to understand how to work with time zones in Sapho.

Every micro app has pages with components on them. You can find these in the Pages tab within your micro app. Any data component that is used on a page with the intention to display or set temporal values and is based on a DB column of TIMESTAMP or DATETIME type is able to support either server or client time zone.

What is Server Time Zone?

The Server Time Zone is the time zone of the application server (e.g. Tomcat). Please note that Sapho assumes the time zone of the database server is the same as the time zone of the application server.

What is Client Time Zone?

The Client Time Zone is the time zone of the end user device. A client can be a computer (if the user accesses Sapho micro apps in a desktop browser) or a smartphone (if the user is using the Sapho App).

How to offset time zone differences for temporal values in a micro app?

Here’s how to change the time zone for Date-Time Values:

  1. Click the pencil icon to edit your micro app
  2. Go to the Settings tab in the left side menu
    1.png
  3. Under Time Zone for Date-Time Values select Client Time Zone. You will need to re-publish your micro app after changing this option.

This setting affects the following data components available in the Sapho Builder: Text Input, Text Area, Text Field, Select, Radio Button, Multiselect, Checklist, Table, List, Chart, and Date/Time.

(Please note that date and time data types differ for each database vendor. The column types used in the examples below are based on the date and time data types available in the MySQL database.)

How do time zone settings work for components based on TIMESTAMP columns?

Scenario 1

  • Application server is in time zone A (UTC-8:00)
  • Client is in time zone B (UTC-6:00)
  • Time Zone for Date-Time Value is set to Server Time Zone

The Sapho Server is being run in-house at a company whose headquarters are in Los Angeles (i.e. the application server is in UTC-8:00). However, company’s employees use Sapho micro apps from multiple locations around the country as well as overseas (i.e. each client has a different time zone).

Let’s assume that a sales manager based in the New York office of this company wants to use their Customer Engagements micro app to schedule a call. To add an extra layer to the example, let’s say that the manager will not handle the call, but will assign it to a sales representative based in Chicago, where the sales lead has its main offices (i.e. the client’s time zone will be UTC-6:00).

  • The sales manager schedules a call from the Add Engagment page in his micro app on 2017-03-24 at 13:00:00 and clicks the Add button. The time is based on the time zone in New York. (UTC-5:00).
  • Sapho Server will store the entered value in the database as 2017-03-24 13:00:00.
  • The detail page for this new record will show the Start field as 2017-03-24 13:00:00 (the time the manager has entered).
  • The sales representative in Chicago gets a card in their Sapho Feed that they were assigned a call by the manager in New York. When they tap the card to view the detail page, they see the Start set to 2017-03-24 13:00:00. However, this time is incorrect since the sales representative is in a different time zone.

To offset time zone differences, the developer that created the micro app should have set the Time Zone for Date-Time Value to Client Time Zone.

Scenario 2

  • Application server is in time zone A (UTC-8:00)
  • Client is in time zone B (UTC-6:00)
  • Time Zone for Date-Time Value is set to Client Time Zone

We’ll use the same example of the sales manager in New York using the Customer Engagements micro app to schedule a call.

  • On the Add Engagement page, the sales manager schedules a call for 2017-03-24 at 13:00:00. When the manager schedules the call, they want to set the time based on their client time zone, i.e. UTC-5:00.
  • Sapho Server will store this value in the database in Server Time Zone, i.e. 2017-03-24 10:00:00 (UTC-8:00).
  • After the manager clicks the Add button, the detail page for the saved record will show the Start field set correctly to 2017-03-24 13:00:00. In other words, the temporal value is displayed in the micro app based on Client Time Zone (UTC-5:00) even though it it is stored in the database in Server Time Zone.
  • When the sales representative in Chicago opens the detail page for the same call, they will see that they have been assigned a call on 2017-03-24 at 12:00:00. Notice that this start time is different from what the manager scheduled or is able to see (UTC-5:00); but it is correct because the sales representative is in a different time zone (UTC-6:00).

Do time zone settings affect components based on DATETIME columns?

Yes, they do. This happens, because any DATETIME column from a database is treated in Sapho like a TIMESTAMP column.

2.png

If the Start field from the previous scenarios got its values from a DATETIME column, it would be similarly affected by incorrect time zone settings.

Do time zone settings affect components based on DATE columns?

No, they don’t. Values for DATE columns are always displayed and stored regardless of the time zone of the client or server.

For instance, suppose that the HR department is using a New Hires micro app. The micro app has a list of employees that will join the company soon and each employee has a page with more details about them. Let’s say that a candidate accepts a job offer and the HR manager needs to add a new record in the micro app. While doing this, the manager enters 2017-03-30 for the Start Date input. Sapho Server will store the same value as entered (i.e. 2017-03-30) and later on, any end user who opens the new employee’s detail page will see the same date regardless of their time zone.

Do time zone settings affect components based on TIME columns?

No, they don’t. Values for TIME columns are always displayed and stored regardless of the time zone of the client or server.

For example, a Zendesk Analytics micro app has weekly updates on key metrics about customer interactions. One of the metrics is the Average Response Time of a customer support specialist to a ticket submitted by a customer. This field pulls data from a TIME column. No matter in what timezone the update will be received and read, the detail page in the Sapho micro app will display the same time.