Solution overview - OfficeDev/microsoft-teams-apps-company-communicator GitHub Wiki
Solution Overview
Refer the following image for high level architecture.
The Company Communicator app has the following main components:
- App Service: The app service implements the message compose experience in the team tab, and the messaging endpoint for the bot.
- Service Bus: The individual messages sent by the bot to the recipients are enqueued on a service bus queue, to be processed by an Azure Function. This queue decouples the message composition experience from the process that delivers the message to recipients.
- Azure Function: The Azure Functions picks up the messages from the queues, prepares the recipients and delivers them.
- Azure Key vault: The Azure Key vault stores the secrets, certificates and connection strings. For more information about the data stored, please check this.
- Author Bot Registration: The Author Bot registration is used for author's app. The application is separated from the User application so that different teams policies can be applied.
- User Bot Registration: The User Bot registration is used for user's app, which is installed by users to receive messages send by Company Communicator application.
- Graph App Registration: The Graph application registration is used for Microsoft Graph api's. The recommended approach is to have a different application registered for managing Microsoft Graph API permissions.
- Microsoft Graph API: The app leverages Microsoft graph api's to Search Groups, Get Group Transitive Members, Get Users and proactively install the User application for a user.
App Service
The app service implements two main components, the tab for composing messages and viewing their status, and the messaging endpoint for the bot.
Messages tab
The messages tab is the interface by which message authors create the messages to be sent, specify the intended recipients, and initiate the send. After sending, the tab reports the status of the message delivery, as counts of deliveries that were successful or failed.
The tab is implemented as a React application, using UI components from Stardust UI and Office UI Fabric React. The message compose UX is in a task module, with a message preview implemented using the Adaptive Cards SDK.
The tab's front-end gets its data from web APIs implemented by the same app service that's hosting it. These APIs are protected by AAD token authentication, which checks that the user attempting to access the site is in the list of valid senders.
User Bot endpoint
The app service exposes a bot messaging endpoint, which receives activities from Bot Framework when a user installs the User application.
conversationUpdate: When the app is installed in team, or personally by users, the bot is notified via a conversationUpdate activity. The bot uses these messages to keep track of the users and teams that have installed the app:
- The list of teams is used to populate the team picker in the compose UX.
- The bot tracks the Teams user ids (
29:xxx) of the users that install the app, so that it can broadcast messages to them. Proactive messaging in Teams requires the bot to know this unique ID, which otherwise cannot be derived from their AAD ID or UPN.
messageReaction: When the user reacts to a message sent by the bot, Teams sends the bot a messageReaction event. We don't use this information in the initial version, we plan to do so in the future.
Author Bot endpoint
The app service exposes a bot messaging endpoint, which receives activities from Bot Framework when an author takes any action on messages sent by the Author bot.
conversationUpdate: When the app is installed in team, the bot is notified via a conversationUpdate activity. The bot uses these messages to keep track of the authors that have installed the app.
fileConsent: When the author accepts/declines the file consent card sent by the bot, Team sends the bot a fileConsentAccept or fileConsentDecline event. On author's consent file is uploaded to the author's OneDrive.
Azure Function
Company Communicator uses five Azure Functions:
Prepare To Send function
This is a durable function and is executed for every message in the "prepare-to-send" Service Bus queue. The function does following:
- Stores the message.
- Syncs the recipients.
Note: Send to everyone workflow syncs all the users in the tenant. The code filters out Guest users and users who do not have a valid Teams license. You may change the behavior if desired. Refer - SyncAllUsersActivity.cs.
- Proactively Installs the User app for recipients who do not have the app.
Note: Applicable if proactive app installation is enabled and external App Id is configured.
- Sends a data aggregation trigger message to Data Queue.
- Sends a dedicated message for every recipient to Send Message Queue.
It also manages the state of the notification. (if its syncing recipients/ installing app).
Send function
This function is executed for every message in the "send" Service Bus queue. The message contains the delivery information for each recipient- message Id and recipient details. The function does following:
- Checks if the conversationId is set for the recipient. If not, marks it as failed and exit.
- Reads the message to be sent.
- Sends the message to the recipient.
- Stores the send status in an Azure table.
Data aggregation function
An instance of this function runs every 20 secs, while the app is actively delivering messages. For each message that's currently in the sending state, the data aggregation function checks the delivery records created by the Send function, and updates the success/failure count.
Export function
This is a durable function and is executed for every message in the "export" Service Bus queue. The function does following:
- Reads all the recipients for the message.
- Creates and stages the zip file in Azure Blob Storage.
- Sends the File Consent Card to user to upload the file to User's One Drive.
Clean Up function
This is a time trigger function and runs as per the scheduled time. It deletes the staged files and file consent card for which there is no response from user within a set period of time.
Microsoft Graph API
Delegated Permissions
App service requires the following Delegated permission:
| Sr. No. | Use Case | API | Delegated permissions | API version |
|---|---|---|---|---|
| 1. | Search Groups | GET https://graph.microsoft.com/v1.0/groups?$filter=condition |
GroupMember.Read.All | v1.0 |
| 2. | Get App Catalog Id | GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=distributionMethod eq 'organization' | AppCatalog.Read.All | v1.0 |
App Permissions
Azure functions require the following App Permissions for different use cases:
| Sr. No. | Use Case | API | Application permissions | API version |
|---|---|---|---|---|
| 1. | Get All Users | GET https://graph.microsoft.com/v1.0/users/delta | User.Read.All | v1.0 |
| 2. | Get User | GET https://graph.microsoft.com/v1.0/users/user-id |
User.Read.All | v1.0 |
| 3. | Get Group Transitive Members | GET https://graph.microsoft.com/v1.0/groups/group-id/transitiveMembers |
GroupMember.Read.All | v1.0 |
| 4. | Get Teams App Installation Id | GET https://graph.microsoft.com/v1.0/users/user-id/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq 'teamsAppId' |
TeamsAppInstallation.ReadWriteForUser.All | v1.0 |
| 5. | Get Chat Id | GET https://graph.microsoft.com/v1.0/users/user-id/teamwork/installedApps/teamsAppInstallationId/chat |
TeamsAppInstallation.ReadWriteForUser.All | v1.0 |
| 6. | Install app for user | POST https://graph.microsoft.com/v1.0/user-id/teamwork/installedApps |
TeamsAppInstallation.ReadWriteForUser.All | v1.0 |