Hero - Build your bot

DateTime Handler

Being able to handle date and time expressions is crucial for many applications. Think of bots for travel booking or insurance claims for example. Teneo provides a _DateTime Handler_ that can be used to catch date and time expressions from the user input. The DateTime Handler is included in the [Teneo Lexical Resources](/studio/language-understanding/concepts/languages#teneo-lexical-resources).

Many date and time expressions have to be interpreted with respect to an anchor date and time. For example, 'tomorrow' denotes different dates depending on when it has been said. The following table contains some examples returned by the DateTime Handler. _DateTime **expression**_ is what the user said, _DateTime **representation**_[1](#footnotes) reflects what the DateTime library caught, and _DateTime **interpretation**_ is a map containing [Java LocalDates](https://docs.oracle.com/javase/8/docs/api/java/time/LocalDate.html) and [Java LocalTimes](https://docs.oracle.com/javase/8/docs/api/java/time/LocalTime.html) returned by the interpretation script. Note that the assumed anchor date for the interpretations below was June 8th 2021:

| DateTime expression | DateTime representation[1](#footnotes) | DateTime interpretation |
|:----------------- | :----------------- |:----------------- |
| Tomorrow | [ date: [ named_relative: tomorrow ]] | [ date: [ start: [ 2021-06-09 ], type: point ] &nbsp; time: [ start: [ 00:00 ]]] |
| August 19th, 2021 | [ date: [ month: 8, day_of_month: 19, year: 2021 ]] | [ date: [ start: [ 2021-08-19 ], type: point ] &nbsp; time: [ start: [ 00:00 ]]] |
| Monday at 3 o'clock| [ date: [ weekday: mon ], &nbsp; time: [ hour:3, meridiem: ampm ]] | [ date: [ start: [ 2021-06-14 ], type: point ], &nbsp; time: [ start: [ 03:00, 15:00 ], type: point ]] |
| Today, between 15:30 and 16:15 | [ date: [ named_relative: today ], &nbsp; time: [ relation: between, &nbsp; time1: [ hour: 3, meridiem: pm, minute: 30 ], &nbsp; time2: [ hour: 4, meridiem: pm, minute: 15 ]]] | [ date: [ start: [ 2021-06-08 ], type: point ], &nbsp; time: [ start: [ 15:30 ], end: [ 16:15 ], type: range ]]

As you can see from the examples, there are cases where it is not clear which exact time the user meant. In such cases, the interpretation simply contains both alternatives, "03:00" and "15:00", for "3 o'clock". The ambiguity can then be [resolved in the solution](/studio/reference/datetimehandler#disambiguation-strategies), if needed.

### Assign the DateTime library
The DateTime library is assigned as soon as you have assigned the Lexical Resource. Visual instructions of how to do that can be found [here](/getting-started/your-first-solution#assign-teneo-lexical-resources).

## Use the DateTime Handler in your flow
In the following, we will build a simple example flow that makes use of the DateTime Handler to book tables.

We will first set up the basic flow structure:
1. Create a new flow and call it `Book a table`.
2. Name the trigger `I want to book a table`.
3. Paste the following learning examples:
* `I want to book a table`
* `I would like to book a table`
* `I'd like to book a table`
* `Can I book a table`
* `Can I make a reservation for a table`
* `Could I book a table`

4. Click on the Plus icon under the trigger, followed by 'Match' and 'Generate' to automatically generate a match based on the example specification.
5. Name the Output node `When?`. Add the answer `When do you want to book it?` to this node. 
6. Click on the Plus icon under the output node and select 'Continue with' followed by 'Transaction'.
7. Now click on the Plus icon just above the empty output node that was just added and select 'Continue with' and 'Script'.
8. Name the last output node `Booking confirmation`.

This is how your flow should now look:

![1-new flow](//images.ctfassets.net/2vbtnveccz5s/33zOrH9jcPSzHTOFNmp8vF/d98417ab54310f7acb0f868fba12869f/1-new_flow.png?classes=w50)

Next, we will add content to the empty nodes and add conditions to the transitions.

### Catch Date and Time using language objects
Teneo's DateTime library features numerous different language objects that can be used to catch date and time expressions in the user input. Some of these are illustrated in the table below. Depending on which kind of DateTime expressions you are expecting from the user, e.g. only date or only time or only weekdays, you may want to use different language objects. All language objects in the English DateTime library start with the prefix 'DT'. You can thus simply search for `DT*` in Teneo's [search interface](/studio/language-understanding/how-to/find-language-objects#search-interface) (prefixes for languages other than English can be found in the grey box below), to see all language objects that belong to the DateTime library. We recommend starting with the main object, __DT_DATE_TIME.REC__ and then clicking your way through the language objects used there and continuing to do so until you find the level of granularity that you are looking for.

| Language Object Name | Coverage | Examples |
| :-------- | :-------- | :------- |
| %DT_DATE_TIME.REC | Combinations of date and time expressions | _18:30 on August 14th_, _Tomorrow at 5 o'clock_ |
| %DT_DATE.REC | Date expressions | _14.08.2019_, _Monday next week_, _five days from now_ |
| %DT_TIME.REC | Time expressions | _13:40_, _at quarter past eight_, _at 5pm_| 

!!! The DateTime Handler is available in the following languages: 
Chinese, Danish, Dutch, English, French, German, Italian, Japanese, Norwegian, Portuguese, Spanish, and Swedish. 

!!! More info can be found in the [documentation](https://documentation.artificial-solutions.com/latest/#/reference/pre-built-knowledge/date-and-time?id=migration).

In our example, we will use the most general one, __DT_DATE_TIME.REC__:
1. Add the flow variable `dateTimeRepresentation` to your flow and assign it the default value `[:]`. 
2. Click on the Plus icon above the script node and select 'Match' and 'TLML Syntax'.
3. Paste the following into the transition's TLML Syntax field: `%DT_DATE_TIME.REC^{dateTimeRepresentation = lob.datetime}`.
4. Name the User Intent node `Get date and time`.

![2-add var and transition](//videos.ctfassets.net/2vbtnveccz5s/5tmMv0tAgC8JGpgXGO4QR6/77425b6859d977ad39ef8e7a02219ee5/2-add_var_and_transition.mp4)

While it's not fully functional yet, you can now use the output node 'Booking confirmation' to print the intermediate DateTime representation:
1. Set the answer text in the 'Booking confirmation' output node to `Great! I booked a table for ${dateTimeRepresentation}`. 
2. Hit 'Save'.
3. Give it a try in Tryout!

You should now get the following response:
> **User:** I want to book a table 
> **Bot:** When do you want to book it? 
> **User:** Tomorrow, 6:30. 
> **Bot:** Great! I booked a table for [ date: [ named_relative: tomorrow ], time: [ hour: 6, meridiem: ampm, minute: 30 ]]

Note that this is the intermediate DateTime representation that simply reflects what the user said. This representation is not really meant to be printed to the user. We just wanted to show you what happens internally here. For example, you can see that the time expression '6:30' is ambiguous with respect to am/pm. We will show you [below](/studio/reference/datetimehandler#ambiguous-representation) how you can resolve such ambiguities. In order to get an actual date and time, this representation needs to be handed over to the interpreter. In the next section, we will show you how this is done.

### Interpret Date and Time via script call

Go back to the 'Book a table' flow in edit mode. Then:
1. Add a flow variable called `dateTime` and assign it the default value `[:]`.
2. Navigate to the script node.
3. Paste `dateTime = datetime.Handler.interpret(dateTimeRepresentation)` into the script field.
4. In the 'Booking confirmation' node, replace the existing answer with: `Great! I booked a table for ${dateTime.time.start[0]} on ${dateTime.date.start[0]}`. This selects the first time point ('time.start[0]') and the first date point ('date.start[0]') from the date time map that the interpreter returned and prints it to the user in a more readable format.
5. Hit 'Save'.

![3-interpreting with script](//videos.ctfassets.net/2vbtnveccz5s/7agEXEBhd8RAJBKqAzY5wX/6c45c3f8b32691f99fbcc56112063a76/3-interpreting_with_script.mp4)

Now go ahead and give it a try in Tryout! For the dialogue above, you should now get an answer that looks like the following (with the date varying depending on when you speak to the bot):

> **User:** I want to book a table. 
> **Bot:** When do you want to book it? 
> **User:** Tomorrow, 6:30. 
> **Bot:** Great! I booked a table for 6:30 on 2022-10-01. 

!!! Note that the expression 'DateTime.time.start[0]' picks the first available start time that the interpreter script returned. However, as you have seen from the internal representation above, this time expression was ambiguous with respect to am/pm ( 'meridiem : ampm' ). In the following, we illustrate some disambiguation strategies.

## Disambiguation strategies
Many time expressions like "6:30" or "3 o'clock" are ambiguous as to whether they denote 'am' or 'pm'. The DateTimeInterpreter returns both possible times for such expressions: "06:30" and "18:30". However, for many applications it is crucial to correctly disambiguate such time expressions. We will illustrate two disambiguation strategies here that you may use in your solution. One is to disambiguate the representation before sending it to the interpretation script, and the other one is to disambiguate what the interpretation script returned.

### Ambiguous representation
The safest way to disambiguate a time expression is to let the user disambiguate it. The fact that time expressions are ambiguous with respect to 'am'/'pm' is visible from the intermediate DateTime representation. Thus, it can be resolved there before it is handed over to the DateTime interpretation script:
1. Open the 'Book a table' flow in edit mode.
2. Click on the Plus icon below the 'Get date and time' transition and select 'Split path' followed by 'transaction element' and 'Output'.
3. Name this new output node `Resolve ambiguity`.
4. Give it the answer `Do you mean ${dateTimeRepresentation.time.hour} am or pm?`.
5. Draw a transition between 'Resolve ambiguity' and 'Interpret date and time'.

![4-resolve ambiguity](//videos.ctfassets.net/2vbtnveccz5s/4ITzypPkiLeVxttPMZ3Fel/99bd983492d112d7cffa69198e08029f/4-resolve_ambiguity.mp4)

The basic structure is now in place. Time to fill the transitions with content! We will start with the first one. 
1. Click on the Plus icon above 'Resolve ambiguity' and add a 'Match' for 'TLML Syntax'. 
2. Paste the following into the 'TLML Syntax' field: `{dateTimeRepresentation.containsKey('time') && dateTimeRepresentation.time.meridiem=='ampm'}`. This condition is fulfilled if the DateTime expression holds a time and if this times does not hold a specified 'am' or 'pm'. 

Now that we are done with our first transition, it is time for the second one. 
1. Click on the Plus icon under 'Resolve ambiguity' and add a 'Match' for 'TLML Syntax'.
2. Paste in the following. Depending on what the user said, this condition sets the meridiem to 'am' or 'pm'.
`(am)^{dateTimeRepresentation.time.meridiem='am'}
/
(pm)^{dateTimeRepresentation.time.meridiem='pm'}` 
4. Hit 'Save'.

![5-populate transitions](//videos.ctfassets.net/2vbtnveccz5s/GktxOwWVZwF4ogZIhB77W/3d50682da08006b6e1c0f5d95287a7e5/5-populate_transitions.mp4)

That's it! You should now get the following dialogue:

> **User:** I want to book a table. 
> **Bot:** When do you want to book it? 
> **User:** Tomorrow, 6:30. 
> **Bot** Do you mean 6 am or pm? 
> **User:** pm 
> **Bot:** Great! I booked a table for 18:30 on 2021-06-09. 

### Ambiguous interpretation
In the previous section we have shown how the decision about 'am' vs 'pm' can be returned to the user to request clarification. Sometimes however, the context only allows one interpretation and in such cases we should avoid asking the user. Let's say that we still want to book a table. As the restaurant is open from 5pm to 11pm, all table bookings will denote 'pm'. In cases where the DateTime interpreter returns more than one possible time, we will thus always select 'pm'.

This is how we will go about: before returning the DateTime interpreter's answer to the user, we will select the 'pm' time, if applicable. Whenever two times are returned, the second one (at index 1) is always 'pm'. If this is the case, we copy the 'pm' value from index 1 to index 0. This way, we do not have to modify the output node:
1. We start from the 'Book a table' flow that we created [above](/studio/reference/datetimehandler#interpret-date-and-time-via-script-call) (without disambiguation of the representation) in edit mode.
2. Select the script node and paste the following after its current content:
 `if (dateTime.time.start[1]) {
 dateTime.time.start[0] = dateTime.time.start[1]
 }` 
3. Hit 'Save'.

![6-ambiguous interpretation](//videos.ctfassets.net/2vbtnveccz5s/4tKFTDQBvQeq8YbmsWgoVa/a0fef6e128aaa96634e202fd491f5f53/6-ambiguous_interpretation.mp4)

That's it. When talking to your bot, you should now always get the 'pm' interpretation for ambiguous time expressions like 6:30:

> **User:** I want to book a table. 
> **Bot:** When do you want to book it? 
> **User:** Tomorrow, 6:30. 
> **Bot:** Great! I booked a table for 18:30 on 2021-06-09. 

### Ambiguous interpretation direction
For some date and time expressions the interpretation depends on the conversation context. For example, the expression 'on Wednesday' may be interpreted as a date in the past or in the future. The following example dialogue happened on Friday, October 14th 2022:

> **User:** I __arrived__ in Barcelona _on Wednesday_. 
> **Bot:** You mean 2022-10-19, right? 

> **User:** I __will arrive__ in Barcelona _on Wednesday_. 
> **Bot:** You mean 2022-10-19, right? 

By default, the interpretation direction is 'forward', so 'on Wednesday' would be interpreted as the following Wednesday. It is possible to change this interpretation direction to 'back' in order to point to the previous Wednesday instead. We will show you how to edit the default interpretation direction in the next section. Here, we will show you how you can take advantage of the verb tense to make an appropriate decision. One component of the [Teneo Input Processing Chain](/article/build/language-understanding/concepts/annotations) assigns part-of-speech tags to all words of the user input. We will make use of one of these tags, __%$PAST.POS__, which indicates that a verb occurred in past tense in order to set the interpretation direction to 'back'. In the following, we build a small example flow in order to illustrate the functionality: 

1. Create a new flow.
2. Name the flow `Disambiguate Interpretation Direction`.
3. Add a flow variable called `dateTimeRepresentation` and assign it the default value `[:]`. It will store the representation of the DateTime expression uttered by the user.
4. Add a flow variable called `pastTense` and assign it the default value `null`. This one will store whether or not a past tense tag was found in the user input.
5. Add a flow variable called `dateTime` and assign it the default value `null`. It will store the DateTime interpretation.

Now that the variables are created, let us proceed with building the flow structure.

1. Name the trigger `DateTime + Tense`. 
2. Click on the Plus icon beneath the trigger, followed by 'Match' and 'TLML Syntax', and paste the following: `%DT_DATE_TIME.REC^{dateTimeRepresentation=lob.datetime} 
&^ 
(%$PAST.POS^{pastTense = true}):o` 
3. Click on the Plus icon above the output and select 'Continue with' and 'Script'.
4. Name the script node `Call Interpreter`. 
5. Paste the following into the script node. This will call the interpreter with the interpretation direction 'back' if the pastTense variable has been set in the Trigger condition. Otherwise, the interpreter will be called with the default interpretation direction "forward" (which does not need to be explicitly specified). 
`dateTime = pastTense?datetime.Handler.interpret(dateTimeRepresentation, "back"): datetime.Handler.interpret(dateTimeRepresentation)` 
6. Paste `You mean ${DateTime.date.start[0]}, right?` into the Output node and name it `You mean ... right?`.
7. Hit 'Save'.

![7-amb interpretation direction](//videos.ctfassets.net/2vbtnveccz5s/7MDddO85tQZ8j1HkYN1Sqt/5b30d68326977a94805617e5401086f6/7-amb_interpretation_direction.mp4)

## Edit default settings

**Anchor date** By default, the DateTime interpretation script assumes the current day to be the anchor date for relative date expressions like 'tomorrow' or 'Monday next week'. Should it be necessary for you to change this anchor date, you can do so by adding the desired anchor date to the DateTime interpreter call. Say you want "14th of August 2019" to be your anchor date. Then, the [DateTime interpreter call](/studio/reference/datetimehandler#interpret-date-and-time-via-script-call) in the script node of your flow will look like this: `dateTime = datetime.Handler.interpret(dateTimeRepresentation, "2019-08-14")`. Please note that the new anchor date must be passed in [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601) and put into quotes (""). If you want to change the anchor date globally for the whole solution, go to the [global pre-processing script](/article/build/scripting/concepts/scripts#global-scripts_session_pre-processing) and paste `datetime.Handler.setAnchor("2019-08-14")`. Note that you have to [restart the conversation](/article/optimize/refine-your-bot/how-to/how-to-use-try-out#try-out-panel_restart--reload) before changes in the global script will apply.

**Anchor time** You may not only modify the anchor date, but also the anchor time, if necessary. In order to do so, simply add the time to the anchor date by keeping the [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601), like so: `dateTime = datetime.Handler.interpret(dateTimeRepresentation, "2018-11-21T1630")`. The first two digits after the 'T' denote the hour and the last two digits the minutes of the anchor time.

**Interpretation direction** For some expressions, like 'on Monday' or 'in September', the interpretation depends on the context. They may denote a date in the past or in the future. Depending on the domain for which you created your bot, different interpretation directions might be appropriate. For example, in our table booking domain, one can assume that all dates occurring in the conversation denote future events. However, in an insurance claim domain a backwards interpretation direction is more suitable. By default the interpretation direction is set to 'forward', but you can change it to 'back' by adding it to the DateTime interpreter call: `dateTime = datetime.Handler.interpret(dateTimeRepresentation, "back")`.

**Both** You may also change both the anchor date and the interpretation direction at once: `dateTime = datetime.Handler.interpret(dateTimeRepresentation, "2018-11-21T1630", "back")`.

## Advanced Usage
The DateTime Handler covers a wide range of different date and time expressions and it always returns the most plausible interpretation. However, if necessary, you may adapt the DateTime Handler to, for example, recognize named days or adjust the interpretation of existing dates and times. For more information, read [this page](https://documentation.artificial-solutions.com/latest/#/reference/pre-built-knowledge/date-and-time?id=deprecated-methods) on Advanced Usage.

-------------
1. See [DateTime Handler Reference](/studio/reference/datetime-handler-reference) for more details on the language-independent DateTime representation.

Table of Contents