Totara Microsoft Teams plugin data flows

Basic Totara bot information flow

This is a basic information flow for the Totara Microsoft Teams plugin that handles a request from Azure, then sends the response to Azure, which then sends it to the Microsoft Teams end user:

Basic Totara bot main components

There are seven main components of a basic Totara bot:

Authoriser: Authenticates the token before dispatching the activity to the bot
Router: Finds the best-matched dispatcher (dispatchers send different responses for different activities) based on the query from the Bot service
Notification: Stores notification subscription (notification triggered by send_user_message_adhoc_task)
Client: CURL client to send the response
Resolver: URL resolver to resolve the V3 rest API
Logger: Logs any errors, warnings, debug messages, etc.
Storage: Stores bot settings and user settings

How does the Totara bot process messages from the Azure Bot service internally?

The Totara Bot processes messages from the Azure Bot service as follows:

Activity is a query sent by the Azure Bot service
The router is the component to find the best-matched dispatcher
The dispatcher is the component that sends the response

Query example:

{
   "text":"signin ",
   "textFormat":"plain",
   "attachments":[
      {
         "contentType":"text/html",
         "content":"<p><span>signin&nbsp;</span></p>"
      }
   ],
   "type":"message",
   "timestamp":"2024-04-06T23:46:21.7309891Z",
   "localTimestamp":"2024-04-07T12:46:21.7309891+13:00",
   "id":"1712447181691",
   "channelId":"msteams",
   "serviceUrl":"https://smba.trafficmanager.net/au/",
   "from":{
      "id":"29:1CriY0RW7ReZuaXLrMVqVxuJbytEXHUTOL4k1vA1J0kRpW4l9yn4yqAcg3CJFAjBtcw1FW6BgHpJdFPVhewJC0A",
      "name":"Gary",
      "aadObjectId":"a250e1fa-eaea-442f-9e88-0ce8d0b8ce61"
   },
   "conversation":{
      "conversationType":"personal",
      "tenantId":"25f77c55-1f63-491c-93d0-938de2281cfc",
      "id":"a:1FZl9SBKp3sB3aab-Y8tH5y3cIVYvf_Pu29BfuusGWA9mHFQiIlt_WFjOnefLj1k7nI5JcUE2raVhjWXuINFQi7oJTjcxpxzuAHzPIFuebmraapUoVJFxwkqy9aT9-CcN"
   },
   "recipient":{
      "id":"28:3fb72b93-5441-4050-a3fa-fdf631db7ce8",
      "name":"garyngrokbot"
   },
   "entities":[
      {
         "locale":"en-GB",
         "country":"GB",
         "platform":"Web",
         "timezone":"Pacific/Auckland",
         "type":"clientInfo"
      }
   ],
   "channelData":{
      "tenant":{
         "id":"25f77c55-1f63-491c-93d0-938de2281cfc"
      }
   },
   "locale":"en-GB",
   "localTimezone":"Pacific/Auckland"
}

HTTP header example:

{
    "X-Ms-Tenant-Id" : 25f77c55-1f63-491c-93d0-938de2281cfc,
    "X-Ms-Conversation-Id" : a:1FZl9SBKp3sB3aab-Y8tH5y3cIVYvf_Pu29BfuusGWA9mHFQiIlt_WFjOnefLj1k7nI5JcUE2raVhjWXuINFQi7oJTjcxpxzuAHzPIFuebmraapUoVJFxwkqy9aT9-CcN,
    "X-Forwarded-Proto" : https,
    "X-Forwarded-Host" : your-site-host,
    "X-Forwarded-For" : 52.114.15.98,
    "Ms-Cv": +QCSRdYDcEWdKyF/8aGi7w.1.1.1.305069239.1.1,
    "HTTP_AUTHORIZATION" : Bearer Token,
    "HTTP_USER_AGENT" : Microsoft-SkypeBotApi (Microsoft-BotFramework/3.0),
}

Totara Teams bot example response:

hTTP Header
{
  “Authorization” : Bearer token (that is the same token value sent by Bot service)
}

{
  “type”: “message”,
  “text”: “Great, You're all set up to receive notifications.”,
  "Conversation":{ 
    "Id":"a":1FZl9SBKp3sB3aab-Y8tH5y3cIVYvf_Pu29BfuusGWA9mHFQiIlt_WFjOnefLj1k7nI5JcUE2raVhjWXuINFQi7oJTjcxpxzuAHzPIFuebmraapUoVJFxwkqy9aT9-CcN
   },
 "From":{
    "id":"28":3fb72b93-5441-4050-a3fa-fdf631db7ce8
   },
 "Recipient":{ 
   "id":"”29":1CriY0RW7ReZuaXLrMVqVxuJbytEXHUTOL4k1vA1J0kRpW4l9yn4yqAcg3CJFAjBtcw1FW6BgHpJdFPVhewJC0A“
   }
}

Basic SSO Bot workflow

Here we have outlined the basic SSO Bot workflow:

The end user sends a sign-in message for the first time to the Microsoft Teams client.
The Microsoft Teams client sends the request to the Bot service.
The Bot service looks for the token from the Bot framework token service.
If no token is found, a response is provided to the Bot service.
The Bot service sends the query and token from HTTP header to the Totara Bot.
Totara Bot sends a response containing sign-in card to Bot service.
The Bot service responses with sign-in card to the Microsoft Teams client.
The Microsoft Teams client shows the sign-in card to the end user.
End user requests sign-in.
The Microsoft Teams client forwards the end user to the Totara bot.
The Totara bot requests authentication with callback containing client_id, return URL, etc. to Azure.
Azure validates authentication and sends a response with a token to Totara OAuth 2.0 server.
Totara OAuth 2.0 sends the request to get Azure user information.
Azure validates the requests and responds to Azure user information on the Totara OAuth 2.0 server.

Non-SSO bot workflow (OAuth)

When SSO is not being used, the workflow is as follows:

Internal processing dataflow

The Totara Bot authenticates the token from the HTTP header first sent by the Azure Bot service and stores bot_settings, treats the query from the Bot service as the activity, gets the dispatcher by the router, and the dispatcher will send the response to the Azure Bot service according to the activity.

If the user has not been verified, the end user needs to sign in to the system, which will invoke the signup_verify activity (server/totara/msteams/classes/my/dispatcher/signin_verify.php) that stores the current user information into the totara_msteams_user table and totara_msteams_user_settings table.

Teams tabs

The dataflow for tabs in the Microsoft Teams plugin is as follows: