diff --git a/docs/source/chatops/aliases.rst b/docs/source/chatops/aliases.rst index e65aaba1f..c49609c2d 100644 --- a/docs/source/chatops/aliases.rst +++ b/docs/source/chatops/aliases.rst @@ -318,8 +318,8 @@ follow as an attachment. ``{~}`` at the end of the string will display the whole message in plaintext. -Passing Attachment API parameters (Slack-only) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Passing Attachment API parameters (Slack, Mattermost, and Rocketchat only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Slack formats ChatOps output as attachments, and you can configure the API parameters in the ``result.extra.slack`` field. @@ -366,8 +366,68 @@ dynamically: color: "{{execution.parameters.color}}" [...] -Support for other chat providers is coming soon, and of course you are always welcome to -contribute! See the example below for hacking on ``extra``. +Mattermost and Rocketchat also support the Slack attachments API. However, you will need +to use the ``mattermost`` and ``rocketchat`` keys of ``extra``: + +.. code-block:: yaml + + [...] + formats: + - "say {{ phrase }} in {{ color }}" + result: + extra: + mattermost: + color: "{{execution.parameters.color}}" + [...] + +.. code-block:: yaml + + formats: + - "say {{ phrase }} in {{ color }}" + result: + extra: + rocketchat: + color: "{{execution.parameters.color}}" + [...] + +.. _specifying-multiple-extra-keys-for-different-providers: + +Specifying Multiple ``extra`` Keys For Different Providers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +And you absolutely can specify more than one chat provider in a single alias by using +more than one key in ``extra``. This can be useful if you might switch chat providers +in the future, or if you are trying to prototype an alias to (for instance) compare and +contrast chat providers (although we can tell you that, right now, Slack definitely has +the best integration with st2chatops). + +.. code-block:: yaml + + [...] + formats: + - "say {{ phrase }} in {{ color }}" + result: + extra: + slack: + image_url: "http://i.imgur.com/Gb9kAYK.jpg" + fields: + - title: Kitten headcount + value: Eight. + short: true + - title: Number of boxes + value: A bunch. + short: true + color: "#00AA00" + mattermost: + color: "{{execution.parameters.color}}" + rocketchat: + color: "{{execution.parameters.color}}" + [...] + +Other chat providers also support ``extra``. See the :ref:`example below ` for +hacking on ``extra``. You may also need to dig into the +`source code `_ for +individual adapters to see how to use ``extra`` for your chat provider. Testing and extending alias parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -379,6 +439,8 @@ on ``hubot-stackstorm`` without having to modify StackStorm source code. For example, you might want to introduce an ``audit`` parameter that would make Hubot log executions of certain aliases into a separate file. You would define it in your aliases like this: +.. _extra-hacking: + .. code-block:: yaml --- diff --git a/docs/source/chatops/chatops.rst b/docs/source/chatops/chatops.rst index b85f86886..d460d5463 100644 --- a/docs/source/chatops/chatops.rst +++ b/docs/source/chatops/chatops.rst @@ -45,9 +45,50 @@ about what ChatOps means to us, and how it provides real-world value to you. .. _chatops-configuration: +Officially Supported Chat Providers +=================================== + +We officially provide support for the following chat providers with hubot: + +* `Slack `_ +* Microsoft Teams (via `BotFramework `_) +* `Mattermost version 5 `_ +* `Rocket.Chat `_ +* `Cisco Spark `_ + +Since +`HipChat is being discontinued `_, +official support for the `HipChat adapter `_ will end when +HipChat reaches end-of-life (as of this writing, this is planned for June 30th, 2020), and it will be +completely removed **without any deprecation period** from the st2chatops project once HipChat itself +is terminated. Administrators of local HipChat servers should **already** be actively migrating to +other chat providers. + +For help migrating between chat providers, please see the section on +:ref:`specifying multiple extra keys for different providers ` +for some ideas on how to ease the transition between HipChat and another chat provider. + +Officially Unsupported Chat Providers +===================================== + +We do not provide support for the following adapters, but they are still bundled in the +st2chatops package, can be configured in ``st2chatops.env``, and still work (as far as we +know). + +* `Flowdock `_ +* `XMPP `_ +* `IRC `_ + Configuration ============= +.. note:: Microsoft Teams + + Configuring st2chatops with Microsoft Teams is a more involved process. Please see + :doc:`our documentation ` specifically for that chat provider. + All other chat providers can be configured in ``st2chatops.env`` with the instructions + below. + Package-based Install ~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/chatops/index.rst b/docs/source/chatops/index.rst index 2ef85ca74..346215e5c 100644 --- a/docs/source/chatops/index.rst +++ b/docs/source/chatops/index.rst @@ -50,6 +50,7 @@ Interested in learning more? Here are some things to get you started on your voy :maxdepth: 1 chatops + Configuration for Microsoft Teams Action Aliases notifications Pack Deployment diff --git a/docs/source/chatops/msteams.rst b/docs/source/chatops/msteams.rst new file mode 100644 index 000000000..9829598b5 --- /dev/null +++ b/docs/source/chatops/msteams.rst @@ -0,0 +1,261 @@ +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 +~~~~~~~~~~~~~~~~~~ + +1. Note the internet accessible hostname and port for your st2chatops (hubot) server. +2. Register a bot within `BotFramework `_. +3. Note your Microsoft App ID and password, you will need these later. +4. Configure the "Messaging endpoint" option to your st2chatops server, and append + ``/api/messages`` to it. + + .. code-block:: none + + https://:/api/messages + + .. warning:: + + 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 bot +* ``outlineicon.png`` - a 20px by 20px png icon of your bot +* ``manifest.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. + +.. code-block:: json + + { + "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: + +.. code-block:: none + + "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: + +.. code-block:: bash + + $ 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. + +1. Go to the "Teams" tab on the left column, and click a team you wish to sideload to. +2. Click the three horizontal dots next to the team name in the channel list. +3. Select "Manage team", and go to the "Apps" tab in the main pane. +4. At the bottom right of the main pane, click the "Upload a custom app" link. +5. 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. + +Restart st2chatops +~~~~~~~~~~~~~~~~~~ + +Restart st2chatops with the ``st2ctl`` command: + +.. code-block:: bash + + st2ctl restart-component st2chatops + +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 BotFramework +* `Documentation for the BotFramework-Hubot adapter `_ +* `Hubot issue with configuration steps `_ +* A 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.