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

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.date.year,
      dateTimeExpression.dateTimeInterval.start.date.month,
      dateTimeExpression.dateTimeInterval.start.date.day,
      dateTimeExpression.dateTimeInterval.start.time.hour,
      dateTimeExpression.dateTimeInterval.start.time.minute,
      dateTimeExpression.dateTimeInterval.start.time.second);
    whenEnd = dates.ZonedDateTime.of(
      dateTimeExpression.dateTimeInterval.end.date.year,
      dateTimeExpression.dateTimeInterval.end.date.month,
      dateTimeExpression.dateTimeInterval.end.date.day,
      dateTimeExpression.dateTimeInterval.end.time.hour,
      dateTimeExpression.dateTimeInterval.end.time.minute,
      dateTimeExpression.dateTimeInterval.end.time.second);
  }

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

  // code continues...
}

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 times for specific durations. The capsule could implement a duration model with a role-of the Period concept:

// MyDuration.model.bxb
structure (MyDuration) {
  role-of (viv.time.Period)
}

You might want this duration to be initialized to a default of one hour. You can create an InitializeDuration action model that outputs your duration model, initialized with JavaScript code. The InitializeDuration action is very simply

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

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 can be used as a goal in the default-init block of the timer's creation action:

// CreateTimer.model.bxb
action (CreateTimer) {
  type (Search)
  collect {
    input (duration) {
      type (MyDuration)
      min (Required) max (One)
      default-init {
        intent {
          goal {
            InitializeDuration
          }
        }
      }
    }
  }
  output (Timer)
}

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.

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. 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.