Mattermost integration designed

[jordanh]

Issue - Enhancement

Mattermost is a collaboration platform similar to Slack popular in the regulated market. We're contractually obligated to build a Mattermost integration for the DoD by 2021 Jan 01.

The first step to developing this integration will be to design it.

Related: #3538

Acceptance Criteria (optional)

Users can:

• CRUD Mattermost integration on their team

• Notifications designed, mirroring today's Slack integration (at a minimum)

• Set of implementation issues created

• Estimated effort: 13 points (see CONTRIBUTING.md)

[github-actions]

Stale issue

[mattkrick]

still a thing we are contractually obligated to do 🙃

[enriquesanchez]

A Mattermost integration was one of the top most requested integrations from the Parabol User Feedback Survey 🔒.

[jordanh]

I've been doing some research in this area. Here's a design proposal.

Mattermost Integration Proposal

Overview

Mattermost is a real-time message and collaboration service similar to Slack.

Where Mattermost differs is it is open-source. It has become popular with institutions where private-hosted or single-tenant software is preferred to multitenant SaaS. As @enriquesanchez noted above, adding a Mattermost integration was the most popularly requested integration. In fact after parsing these same data, @avivapinchas found that Mattermost scored as the most-requested integration among the over 300 survey respondents.

Adding integrations to Mattermost

Like Slack, Mattermost has a marketplace. However, unlike Slack many of these integrations need to be written as source-level plugins loaded on the user's system. For services which only require authenticated notifications be sent (like ours), Mattermost provides additional mechanisms for authenticated incoming messages: OAuth 2.0, personal access tokens, and incoming webhooks. Each of these facilities may be disabled by administrators, and only incoming webhooks are enabled by default.

To support a new generation of interactive, serverless integrations Mattermost is also developing a system they call Mattermost Apps. It is currently in developer preview.

Message format

Mattermost offers similar (and in many ways, superior) formatting options to Slack. Achieving functional and design parity with our current notification messages will not be an issue.

Options

1. source plugin – we can create a source-level plugin à la this GitLab plugin
   • Pros: marketplace listing and marketing reach, paves road for future interactive functionality, understood by their users
   • Cons: another repo/architecture to support, longer to develop
2. oauth 2.0 – we could adapt our Slack design for Mattermost, and use a very similar Oauth 2.0 facility
   • Pros: straightforward patterns to follow, direct adaptation
   • Cons: would need new pattern for specifying which oauth facility to authenticate against (self hosting!); not all Mattermost installations enable the oauth 2.0 service—not everybody could use our integration
3. personal access tokens ("PAT") – each user could add a personal access token to enable the integration
   - Pros: by manually adding a PAT we could still support a direct adaptation of the Slack design (i.e. we can get channel listings, send public and direct messages)
   - Cons: PATs are disabled by default, not every user could use our integration
4. incoming webhooks – incoming webhooks post messages to a single channel, they are enabled by default
   - Pros: simplest to implement, we can send all team notifications with ease
   - Cons: too simple? Our Mattermost integration would only be a subset of what our Slack integration supports today
5. Mattermost Apps – we can create a plugin that is as easy to install as /apps install http http://prbl.app/integrations/mattermost/manifest.json
   - Pros: paves the way for an interactive plugin service in the future, no 3rd-party repo or service to maintain
   - Cons: API is very much still in flux, users must install "apps" plugin first, requires Mattermost oauth 2.0 enabled, would require design to get started, and likely some sort of team access token to authenticate requests from Mattermost→Parabol

Proposed direction

I propose we take approach #4: incoming webhooks. The two driving factors are:

• Speed of development and time to market
• Nearly every Mattermost can use it, out of the box, without making a request of their Mattermost administrator

Should we find a broad and welcoming audience, I propose we consider evaluating option #2 and/or #5 as possible future enhancements. We may find supporting multiple levels of integration advantageous to our users: all could at least use webhooks, while users on permissive enough systems could use the interactive capabilities provide via approach #5.

Adding integration, configuration, and removal:

I propose the configuration panel looks like:

Configuration is team-wide. All users share a single webhook configuration per team.

Removal is simply:

Note: there is no token refreshment as there are no tokens to refresh.

Notification types

Notifications should resemble what we emit today for Slack:

Start meeting

End meeting

Stage timer start

If the Mattermost integration is added, but not Slack, the in-meeting panel looks like:

Stage timer stop

Key differences from slack integration today

• We do without the SlackNotification table, per-user configurations, and the ability to send some messages as private/direct messages and some as team public
• We do without the ability for notifications to be sent to multiple channels (i.e. we do not provide an affordance to add multiple webhooks per team)

EDITS:

• 2021-Oct-20: stage timer panel design added

[enriquesanchez]

From a design stand point this looks good to me 👍. I like that we're reusing most of the design we already have in place for the Slack integration.

The table/button hack is very clever! 😃

The only suggestion I have is to add a small explanation on how the required webhook can be obtained. I'm not sure this would be obvious to everyone and it wouldn't hurt to point folks in the right direction.