Bixby Developer Center

Many Bixby capsules need to not only work with date and time values, but need to be able to handle complicated requests from users. For example, "3:00 pm next Tuesday"; "4 weeks from now"; "in 3 hours"; "starting Saturday afternoon and ending Wednesday morning". To handle dates and times, Bixby provides the viv.time library capsule. This offers a set of concepts and actions that allow natural language date-time expressions to be converted to fully resolved objects, and provides a special abstract structure concept for training.

Date and Time Concepts

The viv.time capsule include the following major concepts. (There are many other concepts used internally in viv.time, and some of the models below have private fields used for processing, but the ones below are the ones your capsule is most likely to interact with.)

Date

A precise date: for example, March 23, 2018. It can optionally include a "fuzzy" period (for example, ±3 days), which your function can use if appropriate. (For example, a search for airline flights might specify a departure date, but also include flights on the day before and the day after.)

Time

A precise point in time during a day, without a date specified. It can optionally include a "fuzzy" period (for example, ±3 minutes), which your function can use if appropriate.

1. A TimeZoneId is a string in the "Area/Location" format defined by the IANA Time Zone Database, such as "America/Los_Angeles" or "Asia/Seoul".
2. A NamedTime field which allows users to use "fuzzy" descriptions like "mid-afternoon" and "happy hour". The conversion to a more precise time specification is handled by the library.

DetachedTime

A DetachedTime is similar to a Time concept, but does not require a time zone to be set.

Note that DetachedTime does not have the role of Time, so the concepts cannot be used interchangeably.

DateTime

A structure containing both a required date and time, as well as the Unix time expressed in milliseconds.

1. The calculatedFromNow field indicates whether a Date, DateTime, or any Interval type is calculated from now by using a DateTimeExpression such as "in the next 3 hours" or "tomorrow".

Period

A structure representing a span of time, for example, 3 years 5 months 2 days and 7 hours. This is frequently used as a structure within other structures, such as the fuzzyFactor for Date and Time concepts.

1. The periodNights field is useful for travel searches such as "I want to stay for three nights". It equates to one day longer than the number of nights: a period of three nights is a period of four days.

DateInterval

An interval with a start Date field and an end Date field: for example, March 23, 2018 to March 26, 2018.

TimeInterval

An interval with a start Time field and an end Time field, with no date specified: for example, 10:00 am to 11:00 am.

DateTimeInterval

An interval with a start DateTime field and an end DateTime field. This is the most complete representation of an interval from one millisecond instant to another instant, complete with time zone.

DurationPeriod

This is a transient variant of Period, and should be used by actions as the input type for a duration.

DateTimeExpression

A convenience structure containing the four major viv.time input types. This is an abstraction designed for natural language input; read Training below for more details.

Action Modeling

The Space Resorts Sample Capsule uses DateTimeExpression to handle utterances with start and end dates. These utterances might have either a specific date, a range of specific dates, or a description of a date or dates such as "next weekend". The ConstructDateIntervalFromDateTimeExpression action takes a DateTimeExpression and returns a DateInterval.

action (ConstructDateIntervalFromDateTimeExpression) {
  type (Constructor)
  collect {
    input (dateTimeExpression) {
      type (time.DateTimeExpression)
      min (Required)
      default-select {
        with-rule {
          select-first
        }
      }
    }
  }
  output (DateInterval)
}

View on GitHub

Handling Dates and Times in JavaScript

The other side of handling dates and times is using them in your JavaScript implementations. The concepts from viv.time will be passed to your functions as JavaScript objects, and can be manipulated easily.

Depending on your capsule's design, you might need to perform other date and time functions, particularly when working with external APIs. Tasks such as converting to JSON or parsing dates are provided in Bixby's JavaScript API. Bixby's dates class can create ZonedDateTime objects, which have a variety of methods that include date/time addition and subtraction, comparisons, conditional tests, and formatting functions.

The JavaScript implementation for the ConstructDateIntervalFromDateTimeExpression action above examines the properties in the DateTimeExpression and either returns the DateInterval component or converts the DateTimeInterval component into a DateInterval:

var console = require('console')
module.exports.function = function (dateTimeExpression) {
  console.log("dateTimeExpression:", dateTimeExpression)
  if (dateTimeExpression.dateInterval) {
    return {
      start: dateTimeExpression.dateInterval.start,
      end: dateTimeExpression.dateInterval.end
    }
  }
  if (dateTimeExpression.dateTimeInterval) {
    return {
      start: dateTimeExpression.dateTimeInterval.start.date,
      end: dateTimeExpression.dateTimeInterval.end.date
    }
  }
  if (dateTimeExpression.date) {
    //using same date for both start and end. This is not a valid case,should throw checkedError
    return {
      start: dateTimeExpression.date,
      end: dateTimeExpression.date
    }
  }
  return null //TODO handle error cases
}

View on GitHub

Initializing Date & Time Concepts

Your capsule might need to initialize date and time concepts to specific values. A way to do this is to use default-init to initialize a concept in an action.

Suppose your capsule allows users to set ranges of dates. The Space Resorts capsule handles this for booking by implementing a DateInterval model with a role-of the DateInterval concept:

structure (DateInterval) {
  role-of (time.DateInterval)
}

View on GitHub

This is initialized in the CreateItem action by setting a default-init with a goal of GetDateInterval, which ensures the user is prompted to select the start and end dates of the reservation.

    input (dateInterval) {
      type (DateInterval)
      min (Required)
      default-init {

        intent { // Prompt for the interval
          goal: GetDateInterval
        }
      }
    }

View on GitHub

The GetDateInterval action, in turn, has an intent with a goal of DateInterval:

action (GetDateInterval) {
  description (Prompt user to enter a date interval)
  type (Constructor)
  collect {
    computed-input (dateInterval) {
      type (DateInterval)
      min (Required)
      compute {
        intent {
          goal { @prompt-behavior(AlwaysElicitation) DateInterval }
        }
      }
    }
  }
  output (DateInterval) {
    evaluate { $expr(dateInterval) }
  }
}

View on GitHub

In another scenario, JavaScript might be used, for example, to perform an InitializeDuration action that outputs a Duration model with a role-of Period set to one hour.

action (InitializeDuration) {
  type (Search)
  output (Duration)
}

The JavaScript code simply returns the proper values for the duration:

function initializeDuration() {
  return {
    periodHours: 1,
    periodMinutes: 0,
    periodSeconds: 0
  }
}

module.exports = {
  initializeDuration: initializeDuration
}

Now, the InitializeDuration action could be used as a goal in a default-init block.

Similar initialization goal actions can be created for other viv.time concepts. These are particularly useful when initializing Bixby Views components like duration and date pickers.

Training

While it's possible to train your capsule using any of the viv.time concepts as utterance annotations, it's usually best to use viv.time.DateTimeExpression rather than Date, DateTime, or either of the interval types.

Because "this weekend" in the above example is annotated as a DateTimeExpression, this could match utterances such as "March 8th", "four weeks from now", "tomorrow at 8pm", or "Christmas morning". This gives your capsule tremendous flexibility in understanding user requests involving dates and times with very little work on your part. Bixby will simply provide the proper DateTime concept to your action.

Here's the aligned NL for a few utterances that invoke a hypothetical FindEarthquakes action:

show earthquakes[g:viv.earthquake.Earthquake] around
(San Francisco)[v:viv.geo.LocalityName]
(on October 17, 1989)[v:viv.time.DateTimeExpression]

show earthquakes[g:viv.earthquake.Earthquake] of at least
(5.0)[v:viv.earthquake.Magnitude:5.0] magnitude around
(San Francisco)[v:viv.geo.LocalityName]
(last month)[v:viv.time.DateTimeExpression]

find earthquakes[g:viv.earthquake.Earthquake] in
(Puerto Rico)[v:viv.geo.CountryDivisionName:'Puerto Rico']
(yesterday afternoon)[v:viv.time.DateTimeExpression]

The first of these queries would resolve to a Date, and fill in the date field of the returned DateTimeExpression. The second would resolve to a DateInterval; the third would resolve to a DateTimeInterval. When you train on DateTimeExpression, only one of the four fields will be set at a time, based on the value derived from the user's utterance. Your JavaScript action implementation must test for values in each field of DateTimeExpression and take appropriate action. The example implementation above for findEarthquakes demonstrates this.

Bixby Views Components

Bixby Views provide input components that include interactive components for selecting dates, times, and durations.

• The date picker returns a viv.time.Date concept.

• The time picker returns a viv.time.Time concept.

• The calendar returns either a viv.time.Date or a viv.time.DateInterval concept.

• The duration picker returns a viv.time.Period concept.

The components are customizable, letting you select the initial values and the range of allowed values. They require you to import viv.time into your capsule.

For details and examples of how to use the view components, read the linked entries in the Reference Guides.