by Frank Nimphius, April 2018

Update: Oracle Intelligent Bots has been rebranded Oracle Digital Assistant to better describe its capabilities beyond a standard chatbot. To learn more, visit cloud.oracle.com/digital-assistant

Oracle Intelligent Bots profiles user profile information that includes firstName, lastName, locale and timezoneOffset information. From all of these, the timezoneOffset option appears to be the least understood.

profile.timezoneOffset 1-0-1

The timezoneOffset variable is passed from the messenger to the bot. You can access the profile.timezoneOffset from anywhere in the dialog flow using the  ${profile.timezoneOffset} expression. The result string presents the time offset the bot user has compared to the Coordinated Universal Time (UTC).

Using UTC as a reference you can always compute the time for a specific location to match the user time. For example, if your business is in the US but you need to consider the local user time for a transaction, then this can be calculated based on the knowledge you have about the timezoneOffset. 

To print the user time offset, you can use a dialog flow state similar to this:

  printTimeZoneOffset:
    component: "System.Output"
    properties:
      keepTurn: true
      text: "${profile.timezoneOffset}"

I, for example, am based in Germany and therefore for me, as the bot user, the messenger client independent offset is printed as 7200000. The time offset is in milliseconds, which means that apparently in Germany I am 2 hours ahead of UTC time. 

So how do you compute this in Bot ML? The trick is to know that the timezone difference is returned as a string and that it needs to be coerced into a number to be able to compute the offset in hours. 

computeOffsetInHours:
  component: "System.Output"
    properties:
      text: "${profile.timezoneOffset?number / 3600000}"

Notice the ?number expression, which is an Apache FreeMarker Expression.

Accessing time offset information from a custom component

Great, you can access the profile.timezoneOffset from BotML. But what this information is needed in a custom component?

Well one option is to create a custom component input parameter that the bot designer provides the offset information to. The other option is to access the profile variable directly from the custom component using the custom component SDK.

var timeOffset = conversation.variable("profile.timezoneOffset");

UTC vs. GMT

The Coordinated Universal Time provides time information equivalent to Greenwich Mean Time (GMT). In fact UTC is the same time then GMT. While no country or timezone officially uses UTC, some countries for for GMT. Neither UTC nor GMT change for daylight saving, which means the time information stay consistent over a year. Countries that use GMT instead switch to another timezone, like the UK that switches to BST (British Summer Time) when it comes to daylight saving. 

Oracle Intelligent Bots DATE entity

The Oracle Intelligent Bots DATE entity does return date information in UTC milliseconds. At current, DATE does not consider the user timezoneOffset. So asking the bot to book a table for tomorrow, the extracted information is the date of tomorrow with the current time in UTC. To print the date and time for the user time zone, you need to add the time zone offset to the time information as shown below.

computeBookingDateTime:
  component: "System.Output"
  properties:
    text: "${(iResult.value.entityMatches['DATE'][0].date?long + profile.timezoneOffset?number)?number_to_datetime}"
  transitions: {}

Notice the "iResult.value.entityMatches['DATE'][0].date" expression " that reads the extracted DATE information from the NLP result variable. After calculating the user time, you use the Apache FreeMarker "?number_to_datetime" expression to format the output to the ISO date format. The printed output in my case was:

Apr 14, 2018 1:37:35 PM

Note: Have a look at the Apache FreeMarker Manual for how to change the printed date to other formats

A known problem

As the time of writing, the integrated tester returns the timezoneOffset incorrectly as a difference (prefixed with "-" ) for countries that are ahead of UTC. Facebook Messenger and other messengers that add this offset information do it correctly though. So don't be confused when using the tester. 

Author