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 Models

The viv.time capsule provides the following concepts:

• Date: A specific date: for example, March 23, 2018. This structure concept contains fully-resolved month, day, and year integer fields. It may 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.)

• DateTime: A specific time on a specific day: for example, 8:23 AM on March 23, 2018. In addition to month, day, and year, DateTime includes fully-resolved hour, minute, second, millisecond, and timezone fields. All fields are integer except for timezone, which is a string. May optionally include a "fuzzy" period (for example, +/- 1 hour).

• DateInterval: An interval with a start Date field and/or an end Date field: for example, March 23, 2018 to March 26, 2018. DateInterval must include either start or end, but one field might be omitted. Handling an open range is the responsibility of your capsule.

• DateTimeInterval: An interval with a start DateTime field and/or an end DateTime field: for example, 9:00 AM March 23, 2018 to 5:00 PM March 24, 2018. DateTimeInterval must include either start or end, but one field might be omitted. Handling an open range is the responsibility of your capsule.

• DurationPeriod: A duration of time: for example, "2 weeks and 3 days". A DurationPeriod will include integer fields for years, months, weeks, days, nights, hours, minutes, seconds, and milliseconds.

• DateTimeExpression: A structure concept that contains fields for date, dateTime, dateInterval, and dateTimeInterval. This is an abstraction designed for training.

This example supposes an earthquake search capsule, which can accept queries searching for quakes that occurred on a given date or during specified intervals, with or without times. The FindEarthquakes action could be modeled like this:

action (earthquake.FindEarthquakes) {
  description (Action to find an earthquake based on when it occurred [required], where, the magnitude and/or classfication.)

  input (dateTimeExpression) {
    type (time.DateTimeExpression)
  }

  input (where) {
    type (geo.SearchRegion)
  }
  input (minMagnitude) {
   type (earthquake.Magnitude)
  }
  input (classification) {
    type (earthquake.Classification)
  }

  output (earthquake.Earthquake)
}

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 FindEarthquakes action above could be coded like this:

module.exports = function findEarthquakes(
  where, dateTimeExpression, minMagnitude, classification
) {
  var whenStart;
  var whenEnd;

  if (dateTimeExpression.date) {
    whenStart = dates.ZonedDateTime.fromDate(dateTimeExpression.date);
    whenEnd = whenStart.withHour(23).withMinute(59).withSecond(59);
  }
  else if (dateTimeExpression.dateInterval) {
    whenStart = dates.ZonedDateTime.of(
      dateTimeExpression.dateInterval.start.year,
      dateTimeExpression.dateInterval.start.month,
      dateTimeExpression.dateInterval.start.day);
    whenEnd = dates.ZonedDateTime.of(
      dateTimeExpression.dateInterval.end.year,
      dateTimeExpression.dateInterval.end.month,
      dateTimeExpression.dateInterval.end.day,
      23, 59, 59);
  }
  else if (dateTimeExpression.dateTimeInterval) {
    whenStart = dates.ZonedDateTime.of(
      dateTimeExpression.dateTimeInterval.start.year,
      dateTimeExpression.dateTimeInterval.start.month,
      dateTimeExpression.dateTimeInterval.start.day,
      dateTimeExpression.dateTimeInterval.start.hour,
      dateTimeExpression.dateTimeInterval.start.minute,
      dateTimeExpression.dateTimeInterval.start.second);
    whenEnd = dates.ZonedDateTime.of(
      dateTimeExpression.dateTimeInterval.end.year,
      dateTimeExpression.dateTimeInterval.end.month,
      dateTimeExpression.dateTimeInterval.end.day,
      dateTimeExpression.dateTimeInterval.end.hour,
      dateTimeExpression.dateTimeInterval.end.minute,
      dateTimeExpression.dateTimeInterval.end.second);
  }

  var start = whenStart.toIsoString();
  var end = whenEnd.toIsoString();

  // code continues...
}

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. This abstract type contains four fields for the other types, only one of which will be set at a time. When your capsule is trained on DateTimeExpression, Bixby will fill in the appropriate field based on the utterance. Then, your JavaScript action implementation can test for values in each field and take appropriate action. (The example implementation above for findEarthquakes demonstrates this.)

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.

Aligned natural language queries that could be used for the FindEarthquakes action might include:

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.

Bixby Views Components

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

• 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 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 either picker, read the date picker and time picker entries in the Developer Center's References.