Using Microsoft Teams (with BotFramework)
Configurating st2chatops with Microsoft Teams is much more involved than configuring other chat providers.
Note
Caveats
There are multiple hubot adapters for Microsoft Teams and/or BotFramework. Only two of them (that we found) are production quality, and only the BotFramework-Hubot project is the officially supported option.
Microsoft BotFramework’s “push model” requires bots to have an open port open to the internet. This is a limitation of Teams/BotFramework. (source)
The BotFramework bot does not receive all messages in a channel. Users MUST explicitly at-mention the bot user to send any messages to the bot.
Users can alternatively direct message the bot user itself (without at-mentioning it) in the bot user’s “room”. This isn’t really considered ChatOps though. And it is impossible to disable this “feature” from within Teams itself. However, all StackStorm alias executions are logged as normal, although StackStorm’s RBAC does not work in st2chatops.
The Orky project is meant to run within Azure and send events via a websocket. We have investigated this method but we were unable to get it working in development.
Setup BotFramework
Note the internet accessible hostname and port for your st2chatops (hubot) server.
Register a bot within BotFramework.
Note your Microsoft App ID and password, you will need these later.
Configure the “Messaging endpoint” option to your st2chatops server, and append
/api/messages
to it.
https://<hostname>:<port>/api/messagesWarning
Ensure that URI path of the messaging endpoint matches the
BOTBUILDER_ENDPOINT
setting in your/opt/stackstorm/chatops/st2chatops.env
configuration file.
Create the bot application manifest zip file
The application manifest is a zip folder of a few files:
coloricon.png
- a 96px by 96px png icon of your botoutlineicon.png
- a 20px by 20px png icon of your botmanifest.json
- a JSON file that describes your bot
Below is an example of a manifest.json
file. You should copy these contents and
modify them to match your organization. Use the Microsoft App ID you got from the
previous steps to fill in BOTH the id
and botId
values. However, you will NOT
use the Microsoft App password in this file. All information included in this file
will be specific to your deployment of StackStorm.
{
"manifestVersion": "1.0",
"version": "1.0",
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee",
"packageName": "company.division.stackstorm.chatops",
"developer": {
"name": "Company",
"websiteUrl": "https://example.com/Organization/Project",
"privacyUrl": "https://example.com/Organization/Project/blob/master/privacy.md",
"termsOfUseUrl": "https://example.com/Organization/Project/blob/master/terms.md"
},
"name": {
"short": "StackStorm (bot)",
"full": "StackStorm automation platform"
},
"description": {
"short": "You can use StackStorm with ChatOps",
"full": "You can use StackStorm to implement ChatOps within your organization!"
},
"icons": {
"outline": "outlineicon.png",
"color": "coloricon.png"
},
"accentColor": "#FFFFED",
"bots": [
{
"botId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee",
"isNotificationOnly": false,
"scopes": [
"team",
"personal"
],
"commandLists":[
{
"scopes":[
"team",
"personal"
],
"commands":[]
}
]
}
]
}
If you know what ChatOps commands StackStorm will support, you can specify them in the
commandLists
array. This will allow Teams to display better help information, but
it is not possible to dynamically update this information when new aliases are added
to st2chatops, or when aliases are changed. Due to this limitation, it is probably best
to make this the basic st2chatops/hubot help command (which is !help
by default).
Here is a snippet of commandLists
from the Orky project:
"commandLists":[
{
"scopes":[
"team",
"personal"
],
"commands":[
{
"title":"add ",
"description":"Adds a bot with the given name."
},
{
"title":"remove ",
"description":"Removes a bot with the given name."
},
{
"title":"enable ",
"description":"Enables a bot."
},
{
"title":"disable ",
"description":"Disables a bot."
},
{
"title":"copy ",
"description":"Copies a bot and returns the copy key."
},
{
"title":"paste ",
"description":"Pastes a bot referenced by the copied key."
},
{
"title":"rename ",
"description":"Renames a bot."
},
{
"title":"status",
"description":"Shows the status of your bots."
},
{
"title":"tell ",
"description":"Tells a bot to execute a command."
}
]
}
]
Warning
Make sure that id
and botId
are the same values!
Zip all of those files into the root of a zip file:
$ zip manifest.zip manifest.json outlineicon.png coloricon.png
Warning
Make sure that the files themselves are located at the root of the zip file and not in a directory in the zip file root!
The Orky project has a complete example manifest.json file you can take a look at for more information.
Sideload the application manifest into Microsoft Teams
Note
You will need to sideload the application manifest into all teams that use ChatOps.
You will need to have administrator privileges in your Microsoft Teams tenant to sideload application manifests. If you do not see the “Upload a custom app” option then you do not have the correct permissions to sideload a bot application.
Go to the “Teams” tab on the left column, and click a team you wish to sideload to.
Click the three horizontal dots next to the team name in the channel list.
Select “Manage team”, and go to the “Apps” tab in the main pane.
At the bottom right of the main pane, click the “Upload a custom app” link.
Upload the application manifest file you created previously.
Please see the official documentation for more information on how to sideload an app package to Microsoft Teams.
Configure st2chatops.env
Modify your st2chatops configuration file at /opt/stackstorm/chatops/st2chatops.env
.
Uncomment the lines for HUBOT_ADAPTER=botframework
, but do NOT change this value.
Also uncomment the lines for BOTBUILDER_APP_ID
and BOTBUILDER_APP_PASSWORD
, and
change their values to the Microsoft App ID and password from the previous steps.
Warning
Ensure that the BOTBUILDER_APP_ID
is the same as the id
and botId
in your
manifest file.
If you did not configure the /api/messages
endpoint in your BotFramework configuration,
set the BOTBUILDER_ENDPOINT
to the URI path you used. Set the rest of the options for
Microsoft Teams/BotFramework in st2chatops.env
.
Warning
If you do not set HUBOT_OFFICE365_TENANT_FILTER
, then ALL Office365 tenants will be
able to communicate with your hubot instance if they sideload your application manifest.
Troubleshooting
Troubleshooting the Microsoft Teams adapter is nearly impossible to do directly. You can use the test client in the configuration webpage of your BotFramework bot to test the connection from BotFramework to your bot. If your st2chatops logs show messages received from the web test client in BotFramework, then the issue is between Microsoft Teams and BotFramework. Double check the values in your application manifest, and remove and re-upload your manifest (if you changed it). You can also message your bot directly from within Microsoft Teams, in its own room.
Here are a few links that may help you troubleshoot:
ngrok.com - tunnels an HTTP/HTTPS
ngrok.io
URL to your local machine, useful for debugging what requests are coming from BotFrameworkA complete example of manifest.json for your bot application manifest JSON file to include the in your bot application manifest zip file.
Official Microsoft documentation for uploading an app package to Teams
Documentation for Orky - you will NOT use Orky itself, but it does have instructions for configuring a BotFramework bot and creating a bot application manifest
Finally, the Orky project is very interesting to us, but as of this writing, the plugin is difficult to configure, some of the code is broken, and it is exceptionally difficult to debug.