Enterprise People Bot template for Composer
APPLIES TO: Composer v2.x
Note
Language Understanding (LUIS) will be retired on 1 October 2025. Beginning 1 April 2023, you won't be able to create new LUIS resources. A newer version of language understanding is now available as part of Azure AI Language.
Conversational language understanding (CLU), a feature of Azure AI Language, is the updated version of LUIS. For more information about question-and-answer support in Composer, see Natural language processing.
The bot helps to discover who a colleague is in an organization and the realm of their interconnectivity with other colleagues (peers, frequent collaborators, their manager).
Conversational experience
The following are the applicable core scenarios:
Showcase
- "Who is.."
- "Who is the manager of"
- "Who are frequent collaborators of...", and much more!
Tip
Learn more about the design principles used in the Enterprise Assistant Bot which includes the Enterprise People Bot as a skill.
Developer experience
The Enterprise People Bot template highlights the recommended best practices for conversational experiences:
- Adaptive Dialogs
- Language Understanding with LUIS
- Language Generation and Adaptive Cards
- Custom actions for Microsoft Graph
Adaptive Dialogs
Adaptive Dialogs enable more flexibility and sophistication in dialog flows. Learn more about Adaptive Dialogs. In this section, we will discuss the overall design of the adaptive dialogs in the Enterprise People Bot, and some key concepts in the design.
Each intent handled in the Enterprise People bot implements the following design pattern:
Authenticate with Microsoft Entra ID
Get Person object from Microsoft Graph API
Get additional information for Person from Graph API
Return card with relevant details
The Enterprise People Bot contains the following dialogs:
Dialog | Description |
---|---|
Authentication | Signs the user into Microsoft Entra ID |
FindPersonDialog | Flow for searching for a user by their name or email |
GetCollaboratorsDialog | Flow for getting the frequent collaborators of a user |
GetDirectReportsDialog | Flow for getting a user's direct report |
GetManagerDialog | Flow for getting a user's manager |
GetPeersDialog | Flow for getting a user's peers who share same manager |
GetProfileDialog | Flow for getting a user's profile |
ListDialog | Flow for displaying, navigating and choosing from a list |
ResolveUserDialog | Flow for getting a user's profile from a list of users |
UnknownIntentDialog | Handles if the intent is unknown to the LU recognizer |
UserListDialog | Flow for handling displaying a list of users (include getting photos, profile) |
Each dialog follows these patterns:
The ResolveUserDialog is called to attempt to identify the user to look up.
Once the user has been identified, additional user data is retrieved from Microsoft Graph API.
Reusable flows have been factored out into separate dialogs so that the logic is consistent throughout. Some examples in this project are Authentication, ResolveUserDialog, ListDialog, GetProfileDialog.
Language Understanding (LUIS)
LUIS provides the ability to recognize intents and extract entities from user utterances. Learn more about language understanding.
The language model included in this project recognizes the following intents:
Intent | Example Utterances |
---|---|
GetManager | Find the manager of John Who is the manager of Janet? What is the name of Jake's manager? |
GetDirectReport | Who reports to Hayden? Please show me who Amy manages? Tell me the reports of Mary |
GetPeers | Show me Harry's team Who are Kevin's colleagues? Who are Lauren's peers? |
GetProfile | Tell me more about Megan Who is Jackson? I want to know who Morgan is |
GetCollaborators | Who collaborates with me most? |
Language generation with Adaptive Cards
Language Generation is the tool for writing bot responses in Composer. The Enterprise People Bot uses many LG templates and techniques. 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.
- Profile.lg contains the Adaptive Card templates for the user profile card.
- UserList.lg contains the Adaptive Card templates for the user list card.
Adaptive Cards
The Enterprise People Bot uses Adaptive Cards to display profile information about a person and render lists of people.
The following screenshot shows the two types of cards we render in the Enterprise People Bot:
Each card is composed of Adaptive Card Containers that the user can select to trigger further actions. For example, in the profile card, the user can trigger the following actions by selecting the appropriate icon:
- Email the person
- Message the person via Teams
- Call the person via Teams
Additionally, they can select actions which trigger other intents in the bot:
- Get the manager of the person
- Get frequent collaborators of the person
- Get peers of the person (colleagues share same manager)
- Get direct reports of the person ("team")
Custom actions for Microsoft Graph
The Enterprise People Bot uses the Microsoft Graph API to answer questions about the people in an organization. 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, and a more friendly experience in Composer. Learn more about custom actions.
Here is what the custom Get Direct Reports action looks like in Composer:
Data usage and storage
The Enterprise People Bot requires access to users' Microsoft Graph data. The following tables outline what data is accessed, where it's 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 | N/A |
Dialog | N/A |
Turn | User access token User profile - Phone number - Job title - Name - Office Location - Display name - ID (Graph use only) User photo |
Due to the potentially sensitive data stored by the bot 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.
Application Insights (Recommended)
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 People Bot template in Bot Framework Composer, follow the steps in