Bixby Developer Center

Businesses often need to define the set of hours in which they're open each day. The viv.openHours capsule provides a set of concepts for defining those hours, and actions that allow users to query businesses defined in your capsule based on those hours.

This reference lists out several of the models available in this library capsule. Some sections contain tables listing information about those concepts or actions.

Models

Types are always in the viv.* namespace, and in the viv.openHours.* namespace unless another namespace is specified (for example, viv.geo.*). All properties have a cardinality of min (Optional), max (One) unless otherwise specified.

HoursInformation

This is the primary structure concept in viv.OpenHours, holding all the opening hours information for a place.

1. This is automatically calculated for you based on the current time and date and the information in WeekOpenHours.
2. See viv.time for details.
3. If this flag is set to true, none of the hours defined will apply. All actions involving hours for a business that isClosedPermanently will indicate the business is not open.

WeekOpenHours

This contains all the open hours for a business; it has seven properties for the seven days of the week. Each property is assigned a role-of DayOpenHours. All of these properties have a cardinality of min (Required) max (One).

DayOpenHours

This structure is generally not accessed directly, but is instead accessed through the properties of WeekOpenHours as an instance of MondayOpenHours, TuesdayOpenHours, etc.

1. See viv.time for details.
2. When accessed through MondayOpenHours, TuesdayOpenHours, etc., this enum will be set to to one of Mondays, Tuesdays, Wednesdays, etc., via bind.

IntervalOpen

This is an enum that will resolve to either the symbol Weekends or Weekdays. It can be used for training purposes, for utterances such as "Is Sprouts open on weekends?"

OpenHoursJudgementQuestion

This is designed for training yes or no questions about whether a business is open at a specific time, such as "Is Safeway open right now?"

OpenHoursConstraint

This is a goal for a training entry similar to OpenHoursJudgementQuestion, but rather than a "Yes" or "No" answer, use it to train open hours search constraints, such as "Find Thai restaurants open right now."

OpenHoursWHQuestion

This is designed for training questions whose answers are specific open hours, such as "When does Safeway open tomorrow?"

Usage

Opening hours should be added as a property of your business structure, typically containing the HoursInformation concept. If your business requires an extra API call to fetch hours, use lazy-source to fetch it asynchronously when the property is referenced:

structure (Business) {
  ...
  property (hoursInformation) {
    type (openHours.HoursInformation)
    lazy-source (business.GetHoursInformation)
  }
}

Training

Open hours can be accessed as property projections. You should train both on hoursInformation and on its properties, such as todayOpenHours. Here are some good training examples, represented as Aligned NL:

[g:.hoursInformation] What are the opening hours of
(Sprouts)[v:BusinessName]?

[g:hoursInformation.week.sundays] What are the Sunday hours
for the (library)[v:BusinessCategory:Library] in
(Dublin)[v:geo.LocalityName] (CA)[v:geo.ISOSubdivisionCode]?

[g:hoursInformation.todayOpenHours] What are today's hours for
(First Third Bank)[v:BusinessCategory:Bank]?

Finding Businesses by Open Hours

You can add an input to your FindBusiness action (for example, whatever action in your capsule finds businesses based on search inputs) to accept an open hours constraint:

action (FindBusiness) {
  type (Search)
  ...
  input (openHoursConstraint) {
    type (openHours.OpenHoursConstraint)
    min (Optional) max (One)
  }
  output (Business)
}

Then, train within your capsule:

[g:Business] Find a (bank)[v:BusinessCategory:Bank]
{[g:openHours.OpenHoursConstraint] (open)[v:openHours.OpenHoursDescriptor:OpenAt]
on (weekends)[v:openHours.IntervalOpen:Weekends]}

Answering Open Hours Questions

You cannot set training goals of OpenHoursJudgement and OpenHoursWHAnswer directly, because goals for training must belong to your capsule. To use them, define primitive concepts in your capsule that have a role-of the appropriate concept:

primitive (OpenHoursJudgement) {
  role-of (openHours.OpenHoursJudgement)
  type (Enum)
  symbol (Yes)
  symbol (No)
  symbol (Unknwon)
}

primitive (OpenHoursWHAnswer) {
  role-of (openHours.OpenHoursWHAnswer)
}

Then, you can train with those goals:

[g:OpenHoursJudgement] Can you tell me if
(Walgreens)[v:BusinessName] is {[g:OpenHoursJudgementQuestion]
(open)[v:openHours.OpenHoursDescriptor:OpenAt] (right now)[v:time.DateTime]}?

[g:OpenHoursWHAnswer] What time does (Walgreens)[v:BusinessName]
{[g:openHours.OpenHoursWHQuestion] (open)[v:openHours.OpenHoursDescriptor:OpenAt]
on (April 2nd)[v:time.Date]}?