article by Frank Nimphius, August 2020
Oracle Digital Assistant lives in the cloud where it uses universal time (UTC) for all date operations. Dependent on where you live in this world, the timezone offset of your local time compared to UTC varies. For Germany, where I am based in, the timezone offset is 2 hours that Germany is ahead of UTC (or 7200000 ms).
UTC is a common date and time reference used in many applications and software products. However, the user local time is often needed, for example if there are deadlines like opening hours to enforce and check. This article explains how you can obtain the local time in Oracle Digital Assistant using the Oracle Web SDK.
Oracle Digital Assistant chatbots (digital assistants) communicate with users through a conversation channel that is connected to a messenger on the user device. Because Oracle Digital Assistant does not have direct access to the user device, it cannot query the user local time. This means that the local time information needs to be passed by the messenger as part of an initial message sent to the digital assistant. 3rd party messengers like Facebook send the timezoneOffset information that then becomes accessible in Oracle Digital Assistant through the ${profile.timezoneOffset} expression in BotML.
The image below shows what gets printed when you run the Oracle Web channel (Oracle Web SDK) and print the Oracle Digital Assistant cloud tie, the timezoneOffset and the calculated local time. As you can see, the timezoneOffset is not available and thus the local time calculated in the sample is the same as the UTC time.
With the (really) simple solution explained in this article, the display can be changed correctly to what is shown in the image below. Notice the time offset to be -7200000, which is the timezone difference between Germany and UTC in ms from the perspective of the UTC time (which is important to know).
To determine the local time in Oracle Digital Assistant, you need to do the following
- Use JavaScript to determine the client local time offset and pass it to Oracle Digital Assistant
- Access the timezone offset in BotML using ${profile.timezoneOffset}
- Compute the local time from the UTC time in Oracle Digital Assistant and the timezone offset passed from the web messenger
Determining the client timezone offset
When you download the Oracle Web SDK as part of the Oracle Native Client SDKs (for OCI Native environments) from the Internet (https://www.oracle.com/downloads/cloud/amce-downloads.html), then you download a sample with it. The sample is a index.html page and two JavaScript files of which one is the SDK itself. The other file is the "settings.js" file and holds all of the configurations and customizations. The sample is a great way to get started and allows you to explore the Web SDK functionality.
As part of the Oracle product documentation, you can access the Web SDK developer guide at https://docs.oracle.com/en/cloud/paas/digital-assistant/sdk-js/index.html. One configuration parameter you can set on the messenger client is initUserProfile, which can be used to pass the timezoneOffset information.
To read the timezoneOffset from the user browser client and to pass it to Oracle Digital Assistant, you use the following setting
initUserProfile: {profile: {timezoneOffset: (new Date()).getTimezoneOffset()*60*1000}}
Note that it is important to name the timezone offset parameter you pass "timezoneOffset" so that it aligns with the name of the same parameter passed by 3rd party messengers. This way your bot will also work with those 3rd party messengers when it come to accessing the timezone information.
Accessing the timezoneOffset in BotML
As mentioned, you access the timezoneOffset through an expression: ${profile.timezoneOffset}.
However, its recommended that you ensure the profile variable has a value, so that the following expression should be used instead of the short expression in the image above: ${profile.timezoneOffset?has_content?then(profile.timezoneOffset?number,0)}
Determining the local time
To determine the local time, you first need to obtain the UTC time in Oracle Digital Assistant. This can be achieved using Apache FreeMarker as shown below
The ${.now?string.full} expression reads the UTC date and time information and prints it with all its details. In a second step, I used a System.MatchEntities component to save the value in a TIME entity type variable
With this, the UTC date is available in the datetime variable of my sample. With this information and the timezoneOffset profile variable you are now good to compute the local time. The expression you use for this is: ${(datetime.value.date?number-profile.timezoneOffset?has_content?then(profile.timezoneOffset?number,0))?number_to_datetime}
Notice that in the expression you subtract the timezone from UTC. Remember that I said that the timezoneOffset is defined from the UTC perspective. So, Germany is 2 hours ahead of UTC, which from the perspective of UTC means that UTC is 2hrs from German local time. Subtracting a negative number (which -7200000 is) you actually adding 7200000 ms).
Related Content
TechExchange Quick-Tip: Understanding the profile.timezoneOffset variable in Oracle Intelligent Bots
TechExchange: Oracle Digital Assistant Web SDK customization and programming examples
Reference for Oracle Digital Assistant Native Client SDK for Web
Oracle Web channel product documentation
TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube
