Mattermost Playbooks allows your team to create and run playbooks from within Mattermost. For configuration and administration information visit our documentation.
In your mattermost-server
configuration (config/config.json
), set the following values:
ServiceSettings.EnableLocalMode: true
PluginSettings.EnableUploads: true
and restart the server. Once done, the relevant make
commands should be able to install builds. Those commands are:
make deploy
- builds and installs the plugin a single time
make watch
- continuously builds and installs when files change
which are run from the repo root.
This repository is licensed under the Apache 2.0 License, except for the server/enterprise directory which is licensed under the Mattermost Source Available License. See Mattermost Source Available License to learn more.
Although a valid Mattermost Enterprise license is required to access all features if using this plugin in production, the Mattermost Source Available License allows you to compile and test this plugin in development and testing environments without a Mattermost Enterprise license. As such, we welcome community contributions to this plugin.
If you're running Mattermost Starter and don't already have a valid license, you can obtain a trial license from System Console > Edition and License. If you're running the Team Edition of Mattermost, including when you run the server directly from source, you may instead configure your server to enable both testing (ServiceSettings.EnableTesting
) and developer mode (ServiceSettings.EnableDeveloper
). These settings are not recommended in production environments. See Contributing to learn more about how to set up your development environment.
When you've submitted a PR that requires a documentation update, please visit the documentation here, select Edit in the top-right corner of the page, and add your update. You can read more about the process in the docs repo README file.
If you're uncertain whether your PR requires documentation, or you'd like some editorial feedback prior to submitting the docs PR, you can add the Docs/Needed
label to your PR in this repo, and tag @justinegeffen.
To quickly test Mattermost Playbooks, use the following test commands to create playbook runs populated with random data:
-
/playbook test create-playbooks [total playbooks]
- Provide a number of total playbooks that will be created. The command creates one or more playbooks based on the given parameter.- An example command looks like:
/playbook test create-playbooks 5
- An example command looks like:
-
/playbook test create-playbook-run [playbook ID] [timestamp] [playbook run name]
- Provide the ID of an existing playbook to which the current user has access, a timestamp, and a playbook run name. The command creates an ongoing playbook run with the creation date set to the specified timestamp.- An example command looks like:
/playbook test create-playbook-run 6utgh6qg7p8ndeef9edc583cpc 2020-11-23 PR-Testing
- An example command looks like:
-
/playbook test bulk-data [ongoing] [ended] [days] [seed]
- Provide a number of ongoing and ended playbook runs, a number of days, and an optional random seed. The command creates the given number of ongoing and ended playbook runs, with creation dates randomly betweenn
days ago and the day when the command was issued. The seed may be used to reproduce the same outcome on multiple invocations. Names are generated randomly.- An example command looks like:
/playbook test bulk-data 10 3 342 2
- An example command looks like:
When running E2E tests, the local mattermost-server
configuration may be unexpectedly modified if either on_prem_default_config.json
or cloud_default_default_config.json
(depending on the server edition) has conflicting values for the same keys. This can be avoided by setting CYPRESS_developerMode=true
when calling Cypress scripts. For example: CYPRESS_developerMode=true npm run cypress:open
.
This plugin contains both a server and web app portion. Read our documentation about the Developer Workflow and Developer Setup for more information about developing and extending plugins.
For more information about contributing to Mattermost, and the different ways you can contribute, see https://www.mattermost.org/contribute-to-mattermost.
Logging should use the logrus package (not pluginAPI.Log
, mlog
, or log
). The standard logger is automatically wired into the pluginAPI and proxied through the server:
logger := logrus.WithField("playbook_run_id", playbookRunID)
err := findUserForPlaybookRunAndTeam(playbookRunID, userID, teamID)
if err != nil {
logrus.WithError(err).WithFields(logrus.Fields{
"user_id": userID,
"team_id": teamID,
}).Warn("Failed to find user for playbook run and team")
}
A few guidelines when logging:
- Use the appropriate level:
- Error: an error log should require some human action to fix something upon receipt
- Warn: a warning log might require investigation if it occurs in bulk, but does not require human action
- Info: a information log provides context that will typically be logged by default
- Debug: a debug log provides context that will typically be logged only on demand
- Write static log messages (
Failed to find user for playbook run and team
) instead of interpolating parameters into the log message itself (Failed to find user %s for playbook run %s and team %s
) - Use snake case when naming fields. Try to name these fields consistently with other usage.
- Pass errors using
WithError
. - Use
WithFields
when passing more than one field that is not anerr
. - Common fields can be set once instead of being passed for every log
For more information, join the discussion in the Developers: Playbooks
channel.