Enterprise Calendar Bot template for Composer

APPLIES TO: Composer v2.x

The Enterprise Calendar Bot helps to manage user's schedule by displaying, creating, and rescheduling calendar events.

Conversational experience

The following are the applicable core scenarios:

Enterprise calendar bot feature diagram

Showcase

  • "Set up a meeting with Anna for tomorrow at 9 AM"
  • "When do I have breaks today"
  • "What is scheduled for tomorrow”, and much more!

Tip

Learn more about the design principles used in the Enterprise Assistant Bot which includes the Enterprise Calendar Bot as a skill.

Developer experience

The Enterprise Calendar Bot template highlights the recommended best practices for complex conversational experiences. The bot demonstrates this through the following features:

  • Adaptive Dialogs with Interruptions
  • Language Understanding with LUIS
  • Language Generation and Adaptive Cards
  • Custom actions for Microsoft Graph

Adaptive dialogs with interruptions

Adaptive Dialogs enable more flexibility and sophistication in dialog flows. Learn more about Adaptive Dialogs. The Enterprise Calendar Bot uses these features to build flows that can be interrupted by configuring different rules that allow prompt responses to be evaluated against the full stack of language recognizers to find the best flow for the user's utterance. Each intent handled in the Enterprise Calendar Bot implements the following design pattern:

  1. Recognize intent at Root Dialog level
  2. Emit SetOptions custom event
    1. Extract all entities and save them in bot state
    2. Authenticate user
    3. Get user profile from Microsoft Graph
  3. Begin the child dialog and pass in entities as dialog options
  4. Execute dialog logic in OnBeginDialog trigger of child dialog
  5. For any activities received by during the execution of the child dialog, recognize intent and evaluate interruption rules

Calendar dialog flow diagram

The Enterprise Calendar Bot contains the following dialogs:

Dialog Description
Authentication Signs in user and gets basic user information
CancelEvent Flow for canceling existing calendar item
CreateEvent Flow for creating a new calendar item
GetContacts Flow for looking up contacts
GetEvents Flow for looking up events
List Flow for displaying, navigating, and choosing from a list
ResolveDateTime Flow for recognizing and disambiguating datetimes from the user's utterance
RespondToEvent Flow for accepting and declining event invitations
ShowEvents Flow for displaying calendar events
UpdateEvent Flow for updating calendar events

Each dialog follows these patterns:

  • Each dialog contains a series of OnEvent trigger steps that are called from the OnBeginDialog trigger. This makes the flow easier to follow and allows the steps to be executed in a different order without duplication.

    Enterprise Calendar EmitEvent actions

  • OnIntent triggers have been added for each dialog where interruptions are allowed. Each Input action uses the allowInterruptions property to configure the rules that should apply to that specific prompt.

    Enterprise Calendar OnIntent triggers

    Enterprise Calendar allowInterruptions property

  • Reusable flows have been factored out into separate dialogs so that the logic is consistent throughout. Some examples in this project are GetEventsDialog, GetContactsDialog ListDialog, and ResolveDateTimeDialog.

Language Understanding (LUIS)

LUIS provides the ability to recognize intents and extract entities from user utterances. In this project, each dialog that includes language understanding has its own LUIS model containing the specific intents that should be recognized in the context of that dialog flow. If the dialog is configured to allow interruptions, but does not recognize an intent, the utterance may be evaluated against the other recognizers in the dialog stack. Learn more about language understanding.

The language model included in this project recognizes the following intents:

Intent Example Utterances
CancelEvent Cancel my meeting
I want to cancel the meeting this afternoon
Cancel my meeting with Thomas tomorrow
CreateEvent Schedule a meeting
Book a meeting with Sharon tomorrow
New meeting on Wednesday with Diego and Alex titled Project Sync
GetAvailabilityBreaks When am I free today?
When do I have breaks on Friday?
Am I free tomorrow?
When do I start on Wednesday?
When does my day start?
GetAvailabilityLast When am I done on Friday?
When is my last meeting?
When am I done for the day?
GetEventAttendees Who is attending the next meeting?
Who is coming to my meeting tomorrow morning?
Will Megan be at my next event?
GetEventDateTime When are my meetings with Chris?
What time is my next meeting?
When am I meeting with Rebecca this week?
GetEventLocation Where is my meeting with Michael?
Where is the next meeting?
What room is my meeting in today?
GetEvents What is on my schedule today?
What meetings do I have tomorrow?
What is up next?
RespondAccept Accept the meeting on February 4th
I want to accept the next meeting
Accept the invite from Monica
RespondDecline Decline the meeting at 1pm
Decline the invite from Frances
Tell George I can't make the meeting tomorrow
ResponseTentativelyAccept Tentatively accept the meeting with next week with Ryan
Mark me as tentative for the meeting this afternoon
Tell Louis I'm tentative today
SetAttendeesAdd Add Donovan to the Project Review tomorrow
Forward the Project Review to Martin
Invite attendees to my meeting on Friday
SetAttendeesRemove Remove attendees from a meeting
Remove Ron from the meeting tomorrow at 10am
Uninvite Tara to the Project Review today
SetDateTime Change the date of my meeting
Update my meeting to start at noon on Saturday
Change my hair appointment to Wednesday at 1pm
SetDescription Add a description to my meeting
Add content to the meeting with John
Set the description for the session tomorrow
SetDuration Change my meeting with Scott to 1 hour
Extend the Design Sync to 2 hours
Set the event to last 1 hour and 30 minutes
SetLocation Change the location of my next meeting
Set the location of the meeting with Harry
Update the location of the meeting tomorrow afternoon
SetOnlineMeetingAdd Add a Microsoft Teams link
Make my next meeting a Teams meeting
Add a conference call to the meeting tomorrow afternoon
SetOnlineMeetingRemove Remove the conference call from the meeting with Elaine
Don't include a Teams link in the next meeting
Remove Microsoft Teams from the meeting
SetTitle Update the title of my next meeting
Set the subject of the meeting with Erin to Team Lunch
Change the title of the session tomorrow morning
UpdateEvent Update my meeting with Brian and Nicole
Modify the Budget Review on Tuesday
Edit my meeting on Friday

Language generation with Adaptive Cards

Language generation is the tool for writing bot responses in Composer. The Enterprise Calendar Bot uses a variety of LG templates including Adaptive Cards. To enable the easy reuse of assets and cards, the templates are broken down into the following files which are imported throughout the project:

  • Actions.lg – contains all the actions used in cards throughout the project. This helps keep all the actions consistent.
  • Icons.lg – contains all the icons used throughout the project. This simplifies any card templates and makes updating the icons simpler.
  • Functions.lg – contains any common functions used throughout the project.
  • Cards.lg – contains standard Adaptive Card templates and structure. This reduces the time required to create cards and ensures consistency in layout.

Custom actions for Microsoft Graph

The Enterprise Calendar Bot uses the Microsoft Graph API to access and manage the user's calendar. To simplify the visual flows in Composer, the Microsoft Graph API calls are made in code and exposed as custom actions in Composer. This enables the reuse of the Microsoft Graph actions in multiple dialogs and projects, as well as a more friendly experience in Composer. Learn more about custom actions.

Here is what the custom Create Event action looks like in Composer:

Create Event custom action screenshot

Data usage and storage

The Enterprise Calendar Bot requires access to users' Microsoft Graph data. The following tables outline what data is accessed, where it is stored, and the default data retention policy for each service. We recommend reviewing this information and adjusting the default configuration of your services to meet your organization's compliance standards.

Storage locations

This section outlines the different data stores used in a typical bot lifecycle, their purpose, and our recommendations for configuring them.

Azure Cosmos DB (Required)

Cosmos DB is the default and recommended provider for storing Bot State. Bot State is split into 4 different scopes with different default lifetimes over the course of a conversation. The default scopes are as follows:

  • Conversation State: For storing values that should persist over the lifetime of a conversation with a user on a given channel. In a channel with persistent conversations such as Microsoft Teams or Facebook Messenger, this could be stored indefinitely.
  • User State: For storing values that should persist over the lifetime of a user on a given channel. In a channel with persistent conversations such as Microsoft Teams or Facebook Messenger, this could be stored indefinitely.
  • Dialog State: For storing values that should persist for the duration of a dialog. If a dialog is left in a waiting state in a channel with persistent conversations such as Microsoft Teams or Facebook Messenger, this could be stored indefinitely.
  • Turn State: For storing values that persist only for the current turn. A turn indicates the time between the user's response. Every time a new activity from a user is received, Turn State is reset. Turn State properties are never written to a persistent storage location.
Scope MS Graph Data stored by Enterprise People Bot
Conversation N/A
User Working hours
Time zone
Dialog Events
Attendees (email and display name only)
Contacts (email and display name only)
People (email and display name only)
Turn User access token
User profile

Due to the potentially sensitive data stored by the skills in Bot State, we recommend the following configuration for your Cosmos DB resource:

  • Configure a default Time to Live (TTL) for your Cosmos DB container. This value should be adjusted according to your organization's standards. Learn more.

If you have Application Insights provisioned and configured in your Project Settings, each incoming and outgoing activity will be logged including varying properties depending on your settings. You can configure your telemetry settings in your Project Settings in Composer by toggling the following properties:

"runtimeSettings": {
    "telemetry": {
      "logActivities": true,
      "logPersonalInformation": false
    }
}

The logActivities property controls whether activity will be logged in Application Insights, and the logPersonalInformation property controls whether the logged activities will include the Activity.Text, Activity.Speak. and Activity.From.Name properties. By default, any telemetry stored in Application Insights will follow the default retention duration. You may want to change this behavior depending on your organization's standards. Learn more.

Azure Blob Storage (Optional)

If you have transcript storage configured in your Project Settings, each incoming and outgoing activity will be logged in Azure Blob Storage. This is useful for analysis of your bot's conversations but should be evaluated against your organization's compliance standards. You can configure transcript storage in your Project Settings in Composer by toggling the following property:

 "runtimeSettings": {
    "features": {
      "traceTranscript": false
    }
}

Note

When emitting trace events in your dialogs, they may be written to Application Insights and Azure Blob Storage depending on your project configuration. Trace events are only sent when communicating with your bot via the Bot Framework Emulator.

Next steps

To get started using the Enterprise Calendar Bot template in Bot Framework Composer, follow the steps in