diff --git a/docs/.gitbook/assets/attach-from-post.png b/assets/attach-from-post.png similarity index 100% rename from docs/.gitbook/assets/attach-from-post.png rename to assets/attach-from-post.png diff --git a/docs/.gitbook/assets/channel-subscriptions-modal.png b/assets/channel-subscriptions-modal.png similarity index 100% rename from docs/.gitbook/assets/channel-subscriptions-modal.png rename to assets/channel-subscriptions-modal.png diff --git a/docs/.gitbook/assets/create-from-post.png b/assets/create-from-post.png similarity index 100% rename from docs/.gitbook/assets/create-from-post.png rename to assets/create-from-post.png diff --git a/docs/.gitbook/assets/jira-commands.png b/assets/jira-commands.png similarity index 100% rename from docs/.gitbook/assets/jira-commands.png rename to assets/jira-commands.png diff --git a/docs/.gitbook/assets/jira-slash-command.png b/assets/jira-slash-command.png similarity index 100% rename from docs/.gitbook/assets/jira-slash-command.png rename to assets/jira-slash-command.png diff --git a/docs/.gitbook/assets/mention-notification.png b/assets/mention-notification.png similarity index 100% rename from docs/.gitbook/assets/mention-notification.png rename to assets/mention-notification.png diff --git a/docs/.gitbook/assets/restrict-jira-users.png b/assets/restrict-jira-users.png similarity index 100% rename from docs/.gitbook/assets/restrict-jira-users.png rename to assets/restrict-jira-users.png diff --git a/docs/.gitbook/assets/restrict-mattermost-users.png b/assets/restrict-mattermost-users.png similarity index 100% rename from docs/.gitbook/assets/restrict-mattermost-users.png rename to assets/restrict-mattermost-users.png diff --git a/docs/.gitbook/assets/ticket-created.png b/assets/ticket-created.png similarity index 100% rename from docs/.gitbook/assets/ticket-created.png rename to assets/ticket-created.png diff --git a/docs/.gitbook/assets/image (7).png b/docs/.gitbook/assets/image (7).png deleted file mode 100644 index e560699c2..000000000 Binary files a/docs/.gitbook/assets/image (7).png and /dev/null differ diff --git a/docs/.gitbook/assets/image-1 (1).png b/docs/.gitbook/assets/image-1 (1).png deleted file mode 100644 index e560699c2..000000000 Binary files a/docs/.gitbook/assets/image-1 (1).png and /dev/null differ diff --git a/docs/.gitbook/assets/image-1.png b/docs/.gitbook/assets/image-1.png deleted file mode 100644 index e560699c2..000000000 Binary files a/docs/.gitbook/assets/image-1.png and /dev/null differ diff --git a/docs/.gitbook/assets/image-2 (1).png b/docs/.gitbook/assets/image-2 (1).png deleted file mode 100644 index 012bd15ea..000000000 Binary files a/docs/.gitbook/assets/image-2 (1).png and /dev/null differ diff --git a/docs/.gitbook/assets/image-2.png b/docs/.gitbook/assets/image-2.png deleted file mode 100644 index 012bd15ea..000000000 Binary files a/docs/.gitbook/assets/image-2.png and /dev/null differ diff --git a/docs/.gitbook/assets/image-3 (1).png b/docs/.gitbook/assets/image-3 (1).png deleted file mode 100644 index db442538a..000000000 Binary files a/docs/.gitbook/assets/image-3 (1).png and /dev/null differ diff --git a/docs/.gitbook/assets/image-3.png b/docs/.gitbook/assets/image-3.png deleted file mode 100644 index db442538a..000000000 Binary files a/docs/.gitbook/assets/image-3.png and /dev/null differ diff --git a/docs/.gitbook/assets/image-4 (1).png b/docs/.gitbook/assets/image-4 (1).png deleted file mode 100644 index d8ff94ddc..000000000 Binary files a/docs/.gitbook/assets/image-4 (1).png and /dev/null differ diff --git a/docs/.gitbook/assets/image-4.png b/docs/.gitbook/assets/image-4.png deleted file mode 100644 index d8ff94ddc..000000000 Binary files a/docs/.gitbook/assets/image-4.png and /dev/null differ diff --git a/docs/.gitbook/assets/image-5 (1).png b/docs/.gitbook/assets/image-5 (1).png deleted file mode 100644 index a35900ca0..000000000 Binary files a/docs/.gitbook/assets/image-5 (1).png and /dev/null differ diff --git a/docs/.gitbook/assets/image-5.png b/docs/.gitbook/assets/image-5.png deleted file mode 100644 index a35900ca0..000000000 Binary files a/docs/.gitbook/assets/image-5.png and /dev/null differ diff --git a/docs/.gitbook/assets/image-6 (1).png b/docs/.gitbook/assets/image-6 (1).png deleted file mode 100644 index c9490327b..000000000 Binary files a/docs/.gitbook/assets/image-6 (1).png and /dev/null differ diff --git a/docs/.gitbook/assets/image-6.png b/docs/.gitbook/assets/image-6.png deleted file mode 100644 index c9490327b..000000000 Binary files a/docs/.gitbook/assets/image-6.png and /dev/null differ diff --git a/docs/.gitbook/assets/image-7 (1).png b/docs/.gitbook/assets/image-7 (1).png deleted file mode 100644 index 7d93eeb7b..000000000 Binary files a/docs/.gitbook/assets/image-7 (1).png and /dev/null differ diff --git a/docs/.gitbook/assets/image-7.png b/docs/.gitbook/assets/image-7.png deleted file mode 100644 index 7d93eeb7b..000000000 Binary files a/docs/.gitbook/assets/image-7.png and /dev/null differ diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index ad71755fd..000000000 --- a/docs/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Mattermost/Jira Integration - -[![Build Status](https://img.shields.io/circleci/project/github/mattermost/mattermost-plugin-jira/master.svg)](https://circleci.com/gh/mattermost/mattermost-plugin-jira) [![Code Coverage](https://img.shields.io/codecov/c/github/mattermost/mattermost-plugin-jira/master.svg)](https://codecov.io/gh/mattermost/mattermost-plugin-jira) - -This plugin supports a two-way integration between Mattermost and Jira. For a stable production release, please download the latest version [in the Releases tab](https://github.com/mattermost/mattermost-plugin-jira/releases) and follow the [installation](https://mattermost.gitbook.io/plugin-jira/setup/installation) and [configuration](https://mattermost.gitbook.io/plugin-jira/setup/configuration) instructions. - -This plugin supports Jira Core and Jira Software products for Server, Data Center, and Cloud platforms. It has been tested with versions 7 and 8. - -**Support for multiple Jira instances is available in Jira plugin v3.0 and later. The feature is configured using [Administrator Slash Commands](https://mattermost.gitbook.io/plugin-jira/administrator-guide/administrator-slash-commands). Note that versions v3.0.0 and v3.0.1 of the plugin require an E20 Enterprise license to use this feature. The feature is now available for Mattermost E20, Professional, and Enterprise licenses.** diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md deleted file mode 100644 index 9ac4d0c76..000000000 --- a/docs/SUMMARY.md +++ /dev/null @@ -1,29 +0,0 @@ -# Table of Contents - -* [Mattermost/Jira Integration](README.md) -* [Feature Summary](feature-summary.md) - -## Setting Up - -* [Installation](setup/installation.md) -* [Configuration](setup/configuration.md) -* [Updating the Plugin](setup/updating-the-plugin.md) - -## Administrator Guide - -* [Administrator Slash Commands](administrator-guide/administrator-slash-commands.md) -* [Notification Management](administrator-guide/notification-management.md) -* [Permissions](administrator-guide/permissions.md) -* [Troubleshooting](administrator-guide/troubleshooting.md) -* [FAQ](administrator-guide/frequently-asked-questions-faq.md) - -## End User Guide - -* [Getting Started](end-user-guide/getting-started.md) -* [Using /jira commands](end-user-guide/using-jira-commands.md) - -## Development - -* [Environment](development/environment.md) -* [Help Wanted!](development/help-wanted.md) -* [Help and Support](development/help-and-support.md) diff --git a/docs/SUMMARY2.md b/docs/SUMMARY2.md deleted file mode 100644 index 021c4ac37..000000000 --- a/docs/SUMMARY2.md +++ /dev/null @@ -1,6 +0,0 @@ -# Table of contents - -* [Mattermost Jira Plugin](README.md) -* [docs](docs/README.md) - * [Mattermost Jira Plugin](docs/docs.md) -* [Test](test.md) diff --git a/docs/administrator-guide/administrator-slash-commands.md b/docs/administrator-guide/administrator-slash-commands.md deleted file mode 100644 index aa15e17a5..000000000 --- a/docs/administrator-guide/administrator-slash-commands.md +++ /dev/null @@ -1,27 +0,0 @@ -# Administrator Slash Commands - -Administrator slash commands are used to perform system-level functions that require administrator access. - -## Install Jira instances - -* `/jira instance install cloud [jiraURL]` - Connect Mattermost to a Jira Cloud instance located at `` -* `/jira instance install server [jiraURL]` - Connect Mattermost to a Jira Server or Data Center instance located at `` - -## Uninstall Jira instances - -* `/jira instance uninstall cloud [jiraURL]` - Disconnect Mattermost from a Jira Cloud instance located at `` -* `/jira instance uninstall server [jiraURL]` - Disconnect Mattermost from a Jira Server or Data Center instance located at `` - -## Manage Channel Subscriptions - -* `/jira subscribe` - Configure the Jira notifications sent to this channel. See the [Notification Management](notification-management#who-can-set-up-notification-subscriptions-for-a-channel) page to see how to configure which users have access to the `subscribe` command. -* `/jira subscribe list` - Display all the the subscription rules set up across all the channels and teams on your Mattermost instance. This command is only available to Mattermost System Admins. - -## Other - -* `/jira instance alias [URL] [alias-name]` - Assign an alias to an instance -* `/jira instance unalias [alias-name]` - Remove an alias from an instance -* `/jira instance list` - List installed Jira instances -* `/jira instance v2 ` - Set the Jira instance to process \"v2\" webhooks and subscriptions (not prefixed with the instance ID) -* `/jira webhook [--instance=]` - Show the Mattermost webhook to receive JQL queries -* `/jira v2revert` - Revert to V2 jira plugin data model diff --git a/docs/administrator-guide/frequently-asked-questions-faq.md b/docs/administrator-guide/frequently-asked-questions-faq.md deleted file mode 100644 index d4d2d3c17..000000000 --- a/docs/administrator-guide/frequently-asked-questions-faq.md +++ /dev/null @@ -1,53 +0,0 @@ -# Frequently Asked Questions \(FAQ\) - -## Why doesn't my Jira plugin post any messages to Mattermost? - -Try the following troubleshooting steps: - -1. Confirm **Site URL** is configured in **System Console > Environment > Web Server**. - * For older Mattermost versions, this setting is located in **System Console > General > Configuration**. -2. Confirm **User** field is set in **System Console > Plugins > Jira**. The plugin needs to be attached to a user account for the webhook to post messages. -3. Confirm the team URL and channel URL you specified in the Jira webhook URL is in lower case. -4. For issue updated events, only status changes when the ticket is reopened, or when resolved/closed, and assignee changes are supported. If you'd like to see support for additional events, [let us know](https://mattermost.uservoice.com/forums/306457-general). -5. If you specified a JQL query in your Jira webhook page, paste the JQL to Jira issue search and make sure it returns results. If it doesn't, the query may be incorrect. Refer to the [Atlassian documentation](https://confluence.atlassian.com/jirasoftwarecloud/advanced-searching-764478330.html) for help. -6. Use a curl command to make a POST request to the webhook URL. If curl command completes with a `200 OK` response, the plugin is configured correctly. For instance, you can run the following command: - - ```text - curl -v --insecure "https:///plugins/jira/webhook?secret=&team=&channel=&user_id=admin&user_key=admin" --data '{"event":"some_jira_event"}' - ``` - - The ``, ``, ``, and `` fields depend on your setup when configuring the Jira plugin. - -The curl command won't result in an actual post in your channel. - -If you're still having trouble with configuration, please to post in our [Troubleshooting forum](https://forum.mattermost.org/t/how-to-use-the-troubleshooting-forum/150) and we'll be happy to help with issues during setup. - -## How do I disable the plugin? - -You can disable the Jira plugin at any time from **System Console > Plugins > Management**. Any webhook requests will stop immediately with an error code in **System Console > Logs**. No posts are created until the plugin is re-enabled. - -Alternatively, if you only experience problems with Jira-related user interactions in Mattermost such as creating issues, disable these features by setting **Allow users to connect their Mattermost accounts to Jira** to **false** in **System Console > Plugins > Jira**. You will then need to restart the plugin in **System Console > Plugins > Plugin Management** to reset the plugin state for all users logged in. This setting does not affect Jira webhook notifications. - -## Why do I get an error `WebHooks can only use standard http and https ports (80 or 443).`? - -Jira only allows webhooks to connect to the standard ports 80 and 443. If you are using a non-standard port, you will need to set up a proxy for the webhook URL, such as: - -```text -https://32zanxm6u6.execute-api.us-east-1.amazonaws.com/dev/proxy?url=https%3A%2F%2F%3A%2Fplugins%2Fjira%2Fwebhook%3Fsecret%%26team%3D%26channel%3D -``` - -The ``, ``, ``, ``, and `` fields depend on your setup from the above steps. - -## How do I handle credential rotation for the Jira webhook? - -Generate a new secret in **System Console > Plugins > Jira**, then paste the new webhook URL in your Jira webhook configuration. - -## What changed in the Jira 2.1 webhook configuration? - -In Jira 2.1 there's a modal window for a "Channel Subscription" to Jira issues. This requires a firehose of events to be sent from Jira to Mattermost, and the Jira plugin then "routes" or "drops" the events to particular channels. The Channel Subscription modal \(which you can access by going to a particular channel, then typing `jira /subscribe`\) provides easy access for Mattermost Channel Admins to set up which notifications they want to receive per channel. - -Earlier versions of the Jira plugin \(2.0\) used a manual webhook configuration that pointed to specific channels and teams. The webhook configuration was `https://SITEURL/plugins/jira/webhook?secret=WEBHOOKSECRET&team=TEAMURL&channel=CHANNELURL`. This method can still be used to set up notifications from Jira to Mattermost channels if the new Channel Subscription modal doesn't support a particular channel subscription yet. - -## How do I manually configure webhooks notifications to be sent to a Mattermost channel? - -If your organization's infrastructure is set up in such a way that your Mattermost instance can't connect to your Jira instance, you won't be able to use the Channel Subscriptions feature. Instead, you need to use the [Legacy Webhooks](admininstrator-guide/notification-management.md#legacy-webhooks) feature supported by the Jira plugin. diff --git a/docs/administrator-guide/notification-management.md b/docs/administrator-guide/notification-management.md deleted file mode 100644 index 7e3e10faa..000000000 --- a/docs/administrator-guide/notification-management.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: Centrally view all notification subscriptions in your system ---- - -# Notification Management - -## What are Notifications? - -Jira notifications are messages sent to a Mattermost channel when a particular event occurs in Jira. They can be subscribed to from a channel via `/jira subscribe` \(managed within Mattermost\). A webhook can be manually set up from Jira to send a message to a particular channel in Mattermost \(managed via Jira\). - -Notifications and webhooks can be used together or you can opt for one of them. - -![This is a channel notification of a new bug that was created in Jira](../.gitbook/assets/ticket-created.png) - -When any webhook event is received from Jira the plugin reviews all the notification subscriptions. If it matches a rule it will post a notification to the channel. If there are no subscription matches, the webhook event is discarded. - -The notifications and metadata shown in a channel are not protected by Jira permissions. Anyone in the channel can see what's posted to the channel. However if they do not have the appropriate permission they won't be able to see further details of the issue if they click through to it. - -## What is a notification subscription? - -Mattermost users can set up rules that define when a particular event with certain criteria are met in Jira that trigger a notification is sent to a particular channel. These subscription rules can specify the `Jira Project`, `Event Type`, `Issue Type`, and can filter out issues with certain values. - -When a user is setting up a notification subscription they'll only see the projects and issue types they have access to within Jira. If they can't see a project in Jira it won't be displayed as an option for that particular user when they are trying to set up a subscription in Mattermost. - -An approximate JQL query is output as well. This is not guaranteed to be valid JQL and is only shown as a reference to what the query may look like if converted to JQL. - -## Who can set up Notification Subscriptions for a channel? - -You can specify who can set up a notification subscription in the plugin configuration. First, set which **Mattermost** user roles are allowed to access the subscription functionality: - -![](../.gitbook/assets/restrict-mattermost-users.png) - -You can also specify a comma-separated list of Jira groups the user needs to be a member of to be able to create/edit subscriptions. The user editing a subscription only needs to be a member of one of the listed groups. If this is left blank there will be no restriction on Jira groups. - -![](../.gitbook/assets/restrict-jira-users.png) - -A user must meet the criteria of both the Mattermost user settings and Jira group settings in order to edit subscriptions. - -## How can I see all the notification subscriptions that are set up in Mattermost? - -While logged in as a System Admin type `/jira subscribe list` in a Mattermost channel. - -## Which notification events are supported? - -The following Jira event notifications are supported: - -- An issue is created -- Certain fields of an issue issue are updated, configurable per subscription -- An issue is reopened or resolved -- An issue is deleted, when not yet resolved -- Comments created, updated, or deleted - -If you’d like to see support for additional events, [let us know](https://mattermost.uservoice.com/forums/306457-general). - -![This is the Channel Subscription modal](../.gitbook/assets/channel-subscriptions-modal.png) - -## Setting up the webhook in Jira - -In order to have Jira post events to your Mattermost instance, you'll need to set up a webhook inside of Jira. Please see the instructions at [configure webhooks on the Jira server](https://mattermost.gitbook.io/plugin-jira/setting-up/configuration#step-2-configure-webhooks-on-the-jira-server). - -## Legacy Webhooks - -If your organization's infrastructure is set up in such a way that your Mattermost instance can't connect to your Jira instance, you won't be able to use the Channel Subscriptions feature. Instead, you'll need to use the Legacy Webhooks feature (the first iteration of the webhooks feature supported by the Jira plugin). - -1. As a Jira System Administrator, go to **Jira Settings > System > WebHooks**. - - For older versions of Jira, select the gear icon in bottom left corner, then go to **Advanced > WebHooks**. -2. Select **Create a WebHook** to create a new webhook. Enter a **Name** for the webhook and add the Jira webhook URL [https://SITEURL/plugins/jira/webhook?secret=WEBHOOKSECRET&team=TEAMURL&channel=CHANNELURL](https://SITEURL/plugins/jira/webhook?secret=WEBHOOKSECRET&team=TEAMURL&channel=CHANNELURL) \(for Jira 2.1\) as the **URL**. - - - Replace `TEAMURL` and `CHANNELURL` with the Mattermost team URL and channel URL where you want to receive the Jira notifications. For example, if your Mattermost channel's full URL is `https://mattermost.example.com/myteam/channels/mychannel`, the `TEAMURL` would be `myteam`, and the `CHANNELURL` would be `mychannel`. - - Replace `SITEURL` with the site URL of your Mattermost instance, and `WEBHOOKSECRET` with the secret generated in Mattermost via **System Console > Plugins > Jira**. - - For instance, if the team URL is `contributors`, channel URL is `town-square`, site URL is `https://community.mattermost.com`, and the generated webhook secret is `MYSECRET`, then the final webhook URL would be: - - ```text - https://community.mattermost.com/plugins/jira/webhook?secret=MYSECRET&team=contributors&channel=town-square - ``` - -3. \(Optional\) Set a description and a custom JQL query to determine which tickets trigger events. For more information on JQL queries, refer to the [Atlassian help documentation](https://confluence.atlassian.com/jirasoftwarecloud/advanced-searching-764478330.html). -4. Finally, set which issue events send messages to Mattermost channels, then select **Save**. The following issue events are supported: - - Issue Created - - Issue Deleted - - Issue Updated, including when an issue is reopened or resolved, or when the assignee is changed. Optionally send notifications for comments, see below. - -By default, the legacy webhook integration publishes notifications for issue create, resolve, unresolve, reopen, and assign events. To post more events, use the following extra `&`-separated parameters: - -- `updated_all=1`: all events -- `updated_comments=1`: all comment events -- `updated_attachment=1`: updated issue attachments -- `updated_description=1`: updated issue description -- `updated_labels=1`: updated issue labels -- `updated_prioity=1`: updated issue priority -- `updated_rank=1`: ranked issue higher or lower -- `updated_sprint=1`: assigned issue to a different sprint -- `updated_status=1`: transitioned issed to a different status, like Done, In Progress -- `updated_summary=1`: renamed issue - -Here's an example of a webhook configured to create a post for comment events: - -```text -https://community.mattermost.com/plugins/jira/webhook?secret=MYSECRET&team=contributors&channel=town-square&updated_comments=1 -``` diff --git a/docs/administrator-guide/permissions.md b/docs/administrator-guide/permissions.md deleted file mode 100644 index 57082d3bf..000000000 --- a/docs/administrator-guide/permissions.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -description: A general note about Jira and Mattermost permissions ---- - -# Permissions - -## Can I restrict users from creating or attaching Mattermost messages to Jira issues? - -Yes, there is a plugin setting to disable that functionality. - -## How does Mattermost know which issues a user can see? - -Mattermost only displays static messages in the channel and does not enforce Jira permissions on viewers in a channel. - -Any messages in a channel can be seen by all users of that channel. Subscriptions to Jira issues should be made carefully to avoid unwittingly exposing sensitive Jira issues in a public channel for example. Exposure is limited to the information posted to the channel. To transition an issue, or re-assign it the user needs to have the appropriate permissions in Jira. - -## Why does each user need to authenticate with Jira? - -The authentication with Jira lets the JiraBot provide personal notifications for each Mattermost/Jira user whenever they are mentioned on an issue, comment on an issue, or have an issue assigned to them. Additionally, the plugin uses their authentication information to perform actions on their behalf. Tasks such as searching, viewing, creating, assigning, and transitioning issues all abide by the permissions granted to the user within Jira. diff --git a/docs/administrator-guide/troubleshooting.md b/docs/administrator-guide/troubleshooting.md deleted file mode 100644 index 29f54ab6c..000000000 --- a/docs/administrator-guide/troubleshooting.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: >- - If you encounter issues, please try out some of these troubleshooting steps - and share the results with your support staff or the community to provide - better diagnoses of problems. ---- - -# Troubleshooting - -If you experience problems with Jira-related user interactions in Mattermost such as creating issues, disable these features by setting **Allow users to connect their Mattermost accounts to Jira** to **false** in **System Console > Plugins > Jira**. This setting does not affect Jira webhook notifications. Then re-enable this plugin in **System Console > Plugins > Plugin Management** to reset the plugin state for all users. - -Sometimes the plugin may crash unexpectedly and you may notice a response in red text below the chat window displaying `slash command with trigger of '/(name)' not found,`. If you check your log file, look for messages that refer to `plugins` and `health check fail`, `ExecuteCommand` etc. - -If you encounter these types of issues you can set `LogSettings.FileLevel` to `DEBUG` in your `config.json` settings. This will enable debug logging and give more verbose error events in the system log. Then try re-enabling the plugin in the system-console. These log results may be requested by others in the forum or by our support team. - -**Note:** If you have a site with high volumes of activity, this setting can cause Log files to expand substantially and may adversely impact the server performance. Keep an eye on your server logs, or only enable it in development environments. - -### Jira/Mattermost user connections - -Connecting an account between Mattermost and Jira is a key part of the installation process and requires the end-user to authenticate with Jira and allow access to their Jira account. All `create`, `view`, `assign`, and `transition` operations are done using the logged-in user's Jira access token. - -* You must be signed into Mattermost on the same browser you are using to sign into Jira during `connect`. -* The domain end users sign into Mattermost with on that browser must match the SiteURL in `config.json`. diff --git a/docs/development/environment.md b/docs/development/environment.md deleted file mode 100644 index 478ff2fef..000000000 --- a/docs/development/environment.md +++ /dev/null @@ -1,39 +0,0 @@ -# Environment - -To contribute to the project see https://www.mattermost.org/contribute-to-mattermost. - -Join the [Jira plugin channel](https://community.mattermost.com/core/channels/jira-plugin) on our community server to discuss any questions. - -Read our documentation about the [Developer Workflow](https://developers.mattermost.com/extend/plugins/developer-workflow/) and [Developer Setup](https://developers.mattermost.com/extend/plugins/developer-setup/) for more information about developing and extending plugins. - -This plugin supports both Jira Server (self-hosted) and Jira Cloud instances. There can be slight differences in behavior between the two systems, so it's best to test with both systems individually when introducing new webhook logic, or adding a new Jira API call. - -To test your changes against a Jira Cloud instance, we recommend starting a 14-day trial, if you don't have a Jira project to test against. More information can be found here: https://www.atlassian.com/software/jira/try. - -If you are contributing to a feature that requires multiple Jira instances to be installed, please enable [ServiceSettings.EnableDeveloper](https://docs.mattermost.com/configure/configuration-settings.html#enable-developer-mode) in your server's config in order to circumvent the Enterprise license requirement. - -### Run a local instance of Jira server - -To test your changes against a local instance of Jira Server, you need [Docker](https://docs.docker.com/install) installed. - -**Pre-requisite** -As per the [sizing recommendations from Jira](https://confluence.atlassian.com/jirakb/jira-server-sizing-guide-975033809.html), it requires atleast a minimum memory of 8GB. Hence it is advised to increase the amount of resources allocated for your Docker to use. Here are the steps on how to do this using Docker Desktop: -- Click on the Settings icon on the Docker Desktop. -- Navigate to Resources section. -- Ensure that the Memory is set to at least to 8GB or more. -- Ensure that the CPUs is set to at least 4 or more. -- Click on Apply and Restart. - -**Setup your local Jira server** -- Run the command `make jira` in the root of the repository to spin up the Jira server. -Note: It can take a few minutes to start up due to Jira Server's startup processes. If the container fails to start with `exit code 137`, you may need to increase the amount of RAM you are allowing docker to use. - -- Once the above command completes, visit the URL http://localhost:8080 to start setting up the Jira Server. -- Select the option "Set it up for me" and click Continue to MyAtlassian. -- Select the option - "Jira Software (Data Center)" from the list of License Types. -- Enter any Organization Name and click on Generate License. -- Click on the "Yes" button on the Confirmation dialog `Please confirm that you wish to install the license key on the following server: localhost`. -- You will then be redirected to setup Administrator account. Enter all the details and click Next. -- Now sit back while the set up completes. It might take a few minutes to complete. - -**Note:** It's important to note that the Jira Server can use localhost, but your MM Site URL cannot be localhost diff --git a/docs/development/help-and-support.md b/docs/development/help-and-support.md deleted file mode 100644 index b0dfee708..000000000 --- a/docs/development/help-and-support.md +++ /dev/null @@ -1,5 +0,0 @@ -# Help and Support - -- For Mattermost customers - Please open a support case. -- For questions, suggestions, and help, visit the [Jira Plugin channel](https://community.mattermost.com/core/channels/jira-plugin) on our Community server. -- To report a bug, please [open an issue](https://github.com/mattermost/mattermost-plugin-jira/issues). diff --git a/docs/development/help-wanted.md b/docs/development/help-wanted.md deleted file mode 100644 index b7691490f..000000000 --- a/docs/development/help-wanted.md +++ /dev/null @@ -1,6 +0,0 @@ -# Help Wanted! - -If you're interested in joining our community of developers who contribute to Mattermost - check out the current set of issues [that are being requested](https://github.com/mattermost/mattermost-plugin-jira/issues?q=is%3Aissue+is%3Aopen+label%3AEnhancement). - -You can also find issues labeled ["Help Wanted"](https://github.com/mattermost/mattermost-plugin-jira/issues?q=is%3Aissue+is%3Aopen+label%3A%22Help+Wanted%22) in the Jira Repository that we have laid out the primary requirements for and could use some coding help from the community. - diff --git a/docs/end-user-guide/getting-started.md b/docs/end-user-guide/getting-started.md deleted file mode 100644 index 68431e97a..000000000 --- a/docs/end-user-guide/getting-started.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: Connect your Jira account with Mattermost to speed up your daily workflow ---- - -# Getting Started - -To get started with the Jira/Mattermost connector is easy. You'll first need to connect your Jira account with your Mattermost account so the system can perform actions such as searching, viewing and creating Jira issues on your behalf. - -1. Go into any channel within Mattermost, and type `/jira connect`. -2. Follow the link that gets presented to you - it will bring you to your Jira server. -3. Select **Allow**. - -You may notice that when you type `/` a menu pops up - these are called **slash commands** and bring the functionality of Jira \(and other integrations\) to your fingertips. - - - -## Authentication issues with Jira Cloud - -If connecting to a Jira cloud instance, you will need to temporarily enable third-party cookies in your browser during the Jira authentication process. -If you are using Google Chrome, this can be done by going to the browser's cookie settings and selecting "Allow all cookies". You can paste `chrome://settings/cookies` into your address bar to access these settings. After your Jira account is connected, feel free to disable the third-party cookies setting in your browser. diff --git a/docs/end-user-guide/using-jira-commands.md b/docs/end-user-guide/using-jira-commands.md deleted file mode 100644 index 413d96e35..000000000 --- a/docs/end-user-guide/using-jira-commands.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -description: Get the most out the Jira/Mattermost integration ---- - -# Using `/jira` commands - -## Managing Jira issues from Mattermost - -### Create Jira issues - -To create a Jira issue from a Mattermost message, hover over the relevant message and select **\(...\) > More Actions > Create Jira Issue**. - -The available commands are listed below. - -**Note:** [setting] can be `notifications` and [value] can be `on` or `off` - -- `/jira help` - Launch the Jira plugin command line help syntax -- `/jira me` - Display information about the current user -- `/jira about` - Display build info -- `/jira instance list` - List installed Jira instances -- `/jira connect [jiraURL]` - Connect your Mattermost account to your Jira account -- `/jira disconnect [jiraURL]` - Disconnect your Mattermost account from your Jira account -- `/jira [issue] assign [issue-key] [assignee]` - Change the assignee of a Jira issue -- `/jira [issue] create [text]` - Create a new Issue with 'text' inserted into the description field -- `/jira [issue] transition [issue-key] [state]` - Change the state of a Jira issue -- `/jira [issue] unassign [issue-key]` - Unassign the Jira issue -- `/jira [issue] view [issue-key]` - View the details of a specific Jira issue -- `/jira instance settings [setting] [value]` - Update your user settings - -Then select the project and issue type, add a summary, and a description. - -![image](https://user-images.githubusercontent.com/13119842/59113188-985a9280-8912-11e9-9def-9a7382b4137e.png) - -Click **Create** to create the issue which includes any file attachments that were part of the Mattermost message. - -![image](https://user-images.githubusercontent.com/13119842/59113219-a4deeb00-8912-11e9-9741-5ddc8a4b51fa.png) - -**Note:** This plugin does not support all Jira fields. If the project you tried to create an issue for has **required fields** not yet supported, you'll be prompted to manually create an issue. Clicking the provided link opens the issue creation screen on the Jira web interface. The information you entered in Mattermost is migrated over so no work is lost. - -The supported Jira fields are: - -- **Project Picker:** Custom fields and the built-in **Project** field. -- **Single-Line Text:** Custom fields, and built-in fields such as **Summary** and **Environment**. -- **Multi-Line Text:** Custom fields, and built-in fields such as **Description**. -- **Single-Choice Issue:** Custom fields, and built-in fields such as **Issue Type** and **Priority**. -- **Assignee:** System field. - -### Attach Messages to Jira issues - -Keep all information in one place by attaching parts of Mattermost conversations in Jira issues as comments. To attach a message, hover over the relevant message and select **\(...\) > More Actions > Attach to Jira Issue**. - -![You can attach a message to an existing Jira ticket](../.gitbook/assets/attach-from-post.png) - -Then, on the resulting dialog, select the issue you want to attach it to. You may search for issues containing specific text or just the issue number. - -![image](https://user-images.githubusercontent.com/13119842/59113267-b627f780-8912-11e9-90ec-417d430de7e6.png) - -Click **Attach** and the message is attached to the selected Jira issue as a comment with a permalink to the conversation thread as well so you can maintain context of the comment. - -### Transition Jira issues - -Transition issues without the need to switch to your Jira project. To transition an issue, use the `/jira transition ` command. - -For instance, `/jira transition EXT-20 done` transitions the issue key **EXT-20** to **Done**. - -![image](https://user-images.githubusercontent.com/13119842/59113377-dfe11e80-8912-11e9-8971-f869fa123366.png) - -**Note:** - -- States and issue transitions are based on your Jira project workflow configuration. If an invalid state is entered, an ephemeral message is returned mentioning that the state couldn't be found. -- Partial matches work. For example, typing `/jira transition EXT-20 in` will transition to `In Progress`. However, if there are states of `In Review`, `In Progress`, the plugin bot will ask you to be more specific and display the partial matches. - -### Assign Jira issues - -Assign issues to other Jira users without the need to switch to your Jira project. To assign an issue, use the `/jira assign` command. For instance, `/jira assign EXT-20 john` transitions the issue key **EXT-20** to **John**. - -**Note:** - -- Partial Matches work with Usernames and Firstname/Lastname diff --git a/docs/feature-summary.md b/docs/feature-summary.md deleted file mode 100644 index 8c3ca97e7..000000000 --- a/docs/feature-summary.md +++ /dev/null @@ -1,44 +0,0 @@ -# Feature Summary - -## Jira to Mattermost Notifications - -### Channel Subscriptions - -Notify your team of the latest updates by sending notifications from your Jira projects to Mattermost channels. You can specify which events trigger a notification - and you can filter out certain types of notifications to keep down the noise. - -![image](https://user-images.githubusercontent.com/13119842/59113100-6cd7a800-8912-11e9-9e23-3639c0eb9c4d.png) - -### Personal Notifications: JiraBot - -Each user in Mattermost is connected with their own personal Jira account and notifications for issues where someone is mentioned or assigned an issue is mentioned in your own personal Jira notification bot to help everyone stay on top of their assigned issues. - -![A personal JiraBot helps keep you on top of your relevant Jira activities](.gitbook/assets/ticket-created.png) - -## Manage Jira issues in Mattermost - -### Create Jira issues - -- Create Jira issues from scratch or based off of a Mattermost message easily. -- Without leaving Mattermost's UI, quickly select the project, issue type and enter other fields to create the issue. - -![image](https://user-images.githubusercontent.com/13119842/59113188-985a9280-8912-11e9-9def-9a7382b4137e.png) - -### Attach Messages to Jira Issues - -Keep all information in one place by attaching parts of Mattermost conversations in Jira issues as comments. Then, on the resulting dialog, select the Jira issue you want to attach it to. You may search for issues containing specific text. - -![image](https://user-images.githubusercontent.com/13119842/59113267-b627f780-8912-11e9-90ec-417d430de7e6.png) - -### Transition Jira issues - -Transition issues without the need to switch to your Jira project. To transition an issue, use the `/jira transition ` command. - -For instance, `/jira transition EXT-20 done` transitions the issue key **EXT-20** to **Done**. - -![image](https://user-images.githubusercontent.com/13119842/59113377-dfe11e80-8912-11e9-8971-f869fa123366.png) - -### Assign Jira issues - -Assign issues to other Jira users without the need to switch to your Jira project. To assign an issue, use the `/jira assign` command. - -For instance, `/jira assign EXT-20 john` transitions the issue key **EXT-20** to **John**. diff --git a/docs/help-and-support.md b/docs/help-and-support.md deleted file mode 100644 index b0dfee708..000000000 --- a/docs/help-and-support.md +++ /dev/null @@ -1,5 +0,0 @@ -# Help and Support - -- For Mattermost customers - Please open a support case. -- For questions, suggestions, and help, visit the [Jira Plugin channel](https://community.mattermost.com/core/channels/jira-plugin) on our Community server. -- To report a bug, please [open an issue](https://github.com/mattermost/mattermost-plugin-jira/issues). diff --git a/docs/setup/configuration.md b/docs/setup/configuration.md deleted file mode 100644 index cdf7055a9..000000000 --- a/docs/setup/configuration.md +++ /dev/null @@ -1,65 +0,0 @@ -# Configuration - -### Step 1: Configure the plugin in Mattermost - -1. Go to **Plugins Marketplace > Jira**. - 1. Click **Configure**. - 2. Generate a **Secret** for `Webhook Secret`. - 3. Optionally change settings for **Notifications permissions** and **Issue Creation** capabilities. - 4. Click **Save**. -2. At the top of the page set **Enable Plugin** to **True**. -3. Choose **Save** to enable the Jira plugin. - -Once you have the plugin configured, you may continue the process by typing `/jira setup` in any channel. This will prompt a direct message from Jira bot, which will guide you through the next setup steps as described below. - -### Step 2: Install the plugin as an application in Jira - -To allow users to [create and manage Jira issues across Mattermost channels](../end-user-guide/using-jira-commands.md), install the plugin as an application in your Jira instance. For Jira Server or Data Center instances, post `/jira instance install server ` to a Mattermost channel as a Mattermost System Admin, and follow the steps posted to the channel. For Jira Cloud, post `/jira instance install cloud `. - -### Step 3: Configure webhooks on the Jira server - -As of Jira 2.1, you need to configure a single webhook for all possible event triggers that you would like to be pushed into Mattermost. This is called a firehose; the plugin gets sent a stream of events from the Jira server via the webhook configured below. The plugin's Channel Subscription feature processes the firehose of data and then routes the events to channels based on your subscriptions. - -Use the `/jira webhook` command to get your webhook URL to copy into Jira. - -To control Mattermost channel subscriptions, use the `/jira subscribe` command in the channel in which you want to receive subscriptions. Then select the project and event triggers that will post to the channel. To manage all channel subscriptions as an administrator see [Notification Management](../administrator-guide/notification-management.md). - - -1. To get the appropriate webhook URL, post `/jira webhook ` to a Mattermost channel as a Mattermost System Admin. -2. As a Jira System Administrator, go to **Jira Settings > System > WebHooks**. - * For older versions of Jira, click the gear icon in bottom left corner, then go to **Advanced > WebHooks**. -3. Click **Create a WebHook** to create a new webhook. -4. Enter a **Name** for the webhook and add the Jira webhook URL retrieved above as the **URL**. -5. Finally, set which issue events send messages to Mattermost channels and select all of the following: - * Worklog - * created - * updated - * deleted - * Comment - * created - * updated - * deleted - * Issue - * created - * updated - * deleted - * Issue link - * created - * deleted - * Attachment - * created - * deleted - -6. Choose **Save**. - -Previously configured webhooks that point to specific channels are still supported and will continue to work. - -For granular control of how issues are sent to certain channels in your Mattermost instance, you can use the Jira plugin's Channel Subscriptions feature in the Mattermost interface. The webhook JQL used on Jira's side should be made broad enough to make full use out of the feature. - -You can create multiple webhooks in Jira to point to the same endpoint on your Mattermost instance. This is useful when you only want issues from certain projects, or issues that fit a specific JQL criteria to be sent to your Mattermost instance. Larger organizations may want to filter the webhooks by project to minimize load on their Jira server, if they only need specific projects used for the webhook feature. - -### Step 4: Install the plugin as an application in Jira - -To control Mattermost channel subscriptions, use the command `/jira subscribe` in the channel in which you want to receive subscriptions. Then select the project and event triggers that will post to the channel. To manage all channel subscriptions as an administrator see [Notification Management](../admininstrator-guide/notification-management.md). - -If you encounter any issues during the installation process, see our [Frequently Asked Questions](../administrator-guide/frequently-asked-questions-faq.md) for troubleshooting help, or open an issue in the [Mattermost Forum](http://forum.mattermost.org). diff --git a/docs/setup/installation.md b/docs/setup/installation.md deleted file mode 100644 index e50c9e74f..000000000 --- a/docs/setup/installation.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: Get started by installing the Jira plugin from the Marketplace ---- - -# Installation - -### Requirements - -* For Jira 2.1 Mattermost Server v5.14+ is required \(certain plugin APIs became available\) -* For Jira 2.0 Mattermost Server v5.12+ is required - -### Marketplace Installation - -1. Go to **Main Menu > Plugin Marketplace** in Mattermost. -2. Search for "Jira" or manually find the plugin from the list and click **Install**. -3. After the plugin has downloaded and been installed, click the **Configure** button. - -### Manual Installation - -If your server doesn't have access to the internet, you can download the latest [plugin binary release](https://github.com/mattermost/mattermost-plugin-jira/releases) and upload it to your server via **System Console > Plugin Management**. The releases on this page are the same used by the Marketplace. diff --git a/docs/setup/updating-the-plugin.md b/docs/setup/updating-the-plugin.md deleted file mode 100644 index 946b07909..000000000 --- a/docs/setup/updating-the-plugin.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Getting the latest features and fixes ---- - -# Updating the Plugin - -When a new version of the plugin is released to the **Plugin Marketplace**, the system prompts you to update your current version of the Jira plugin to the newest one. There may be a warning shown if there is a major version change that **may** affect the installation. Generally, updates are seamless and don't interrupt the user experience in Mattermost. diff --git a/readme.md b/readme.md index d6d91296c..bbf268113 100644 --- a/readme.md +++ b/readme.md @@ -1,4 +1,4 @@ -# Mattermost/Jira Plugin +# Mattermost Jira Plugin [![Build Status](https://img.shields.io/circleci/project/github/mattermost/mattermost-plugin-jira/master)](https://circleci.com/gh/mattermost/mattermost-plugin-jira) [![Code Coverage](https://img.shields.io/codecov/c/github/mattermost/mattermost-plugin-jira/master)](https://codecov.io/gh/mattermost/mattermost-plugin-jira) @@ -90,7 +90,7 @@ If your server doesn't have access to the internet, you can download the latest #### Step 2: Install the plugin as an application in Jira -To allow users to [create and manage Jira issues across Mattermost channels](../end-user-guide/using-jira-commands.md), install the plugin as an application in your Jira instance. For Jira Server or Data Center instances, post `/jira instance install server ` to a Mattermost channel as a Mattermost system admin, and follow the steps posted to the channel. For Jira Cloud, post `/jira instance install cloud `. +To allow users to create and manage Jira issues across Mattermost channels, install the plugin as an application in your Jira instance. For Jira Server or Data Center instances, post `/jira instance install server ` to a Mattermost channel as a Mattermost system admin, and follow the steps posted to the channel. For Jira Cloud, post `/jira instance install cloud `. #### Step 3: Configure webhooks on the Jira server @@ -98,7 +98,7 @@ As of Jira 2.1, you need to configure a single webhook for all possible event tr Use the `/jira webhook` command to get your webhook URL to copy into Jira. -To control Mattermost channel subscriptions, use the `/jira subscribe` command in the channel in which you want to receive subscriptions. Then select the project and event triggers that will post to the channel. To manage all channel subscriptions as an administrator see [Notification Management](../administrator-guide/notification-management.md). +To control Mattermost channel subscriptions, use the `/jira subscribe` command in the channel in which you want to receive subscriptions. Then select the project and event triggers that will post to the channel. To manage all channel subscriptions as an administrator see the Notification Management section. 1. To get the appropriate webhook URL, post `/jira webhook ` to a Mattermost channel as a Mattermost System Admin. 2. As a Jira System Administrator, go to **Jira Settings > System > WebHooks**. @@ -199,13 +199,11 @@ The following Jira event notifications are supported: * An issue is deleted, when not yet resolved * Comments created, updated, or deleted -If you’d like to see support for additional events, [let us know](https://mattermost.uservoice.com/forums/306457-general). - ![This is the Channel Subscription modal](https://github.com/mattermost/mattermost-plugin-jira/assets/74422101/4dab17fa-5d49-48eb-91b1-cb9596780787) #### Setting up the webhook in Jira -In order to have Jira post events to your Mattermost instance, you'll need to set up a webhook inside of Jira. Please see the instructions at [configure webhooks on the Jira server](https://mattermost.gitbook.io/plugin-jira/setting-up/configuration#step-2-configure-webhooks-on-the-jira-server). +In order to have Jira post events to your Mattermost instance, you'll need to set up a webhook inside of Jira. See the configure webhooks on the Jira server section for details. #### Legacy webhooks @@ -357,11 +355,11 @@ Try the following troubleshooting steps: 2. If you specified a JQL query in your Jira webhook setup, paste the JQL to Jira issue search and make sure it returns results. If it doesn't, the query may be incorrect. Refer to the [Atlassian documentation](https://confluence.atlassian.com/jirasoftwarecloud/advanced-searching-764478330.html) for help. Note that you don't need to include a JQL query when setting up the webhook. -If you're using [Legacy Webhooks](https://mattermost.gitbook.io/plugin-jira/administrator-guide/notification-management#legacy-webhooks): +If you're using legacy webhooks: 1. Confirm the team URL and channel URL you specified in the Jira webhook URL match up with the path shown in your browser when visiting the channel. -2. Only events described in the Legacy Webhook [docs](https://mattermost.gitbook.io/plugin-jira/administrator-guide/notification-management#legacy-webhooks) are supported. +2. Only events described in the Legacy Webhook documentation are supported. 3. Use a curl command to make a POST request to the webhook URL. If curl command completes with a `200 OK` response, the plugin is configured correctly. For instance, you can run the following command: @@ -371,7 +369,7 @@ If you're using [Legacy Webhooks](https://mattermost.gitbook.io/plugin-jira/admi The ``, ``, ``, and `` fields depend on your setup when configuring the Jira plugin. The curl command won't result in an actual post in your channel. -If you're still having trouble with configuration, please to post in our [Troubleshooting forum](https://forum.mattermost.org/t/how-to-use-the-troubleshooting-forum/150) and we'll be happy to help with issues during setup. +If you're still having trouble with configuration, please to post in our [Troubleshooting forum](https://forum.mattermost.com/t/how-to-use-the-troubleshooting-forum/150) and we'll be happy to help with issues during setup. #### How do I disable the plugin? @@ -391,7 +389,7 @@ Generate a new secret in **System Console > Plugins > Jira**, then paste the new In Jira 2.1 there's a modal window for a "Channel Subscription" to Jira issues. This requires a firehose of events to be sent from Jira to Mattermost, and the Jira plugin then "routes" or "drops" the events to particular channels. The Channel Subscription modal \(which you can access by going to a particular channel, then typing `jira /subscribe`\) provides easy access for Mattermost Channel Admins to set up which notifications they want to receive per channel. -If your organization's infrastructure is set up in such a way that your Mattermost instance can't connect to your Jira instance, the Channel Subscriptions feature won't be accessible. Instead, you will need to use the [Legacy Webhooks](admininstrator-guide/notification-management.md#legacy-webhooks) feature supported by the Jira plugin, which allows a Jira webhook to post to a specific channel. +If your organization's infrastructure is set up in such a way that your Mattermost instance can't connect to your Jira instance, the Channel Subscriptions feature won't be accessible. Instead, you will need to use the Legacy Webhooks feature supported by the Jira plugin, which allows a Jira webhook to post to a specific channel. ## License @@ -399,7 +397,7 @@ This repository is licensed under the Apache 2.0 License, except for the [server ## Development -Read our [development docs](https://mattermost.gitbook.io/plugin-jira/development/environment) for this project, as well as the [Developer Workflow](https://developers.mattermost.com/extend/plugins/developer-workflow/) and [Developer Setup](https://developers.mattermost.com/extend/plugins/developer-setup/) documentation for more information about developing and extending plugins. +Read the [Developer Workflow](https://developers.mattermost.com/extend/plugins/developer-workflow/) and [Developer Setup](https://developers.mattermost.com/extend/plugins/developer-setup/) documentation for more information about developing and extending plugins. ### Environment @@ -423,4 +421,4 @@ You can also find issues labeled ["Help Wanted"](https://github.com/mattermost/m - For Mattermost customers - Please open a support case. - For questions, suggestions, and help, visit the [Jira Plugin channel](https://community.mattermost.com/core/channels/jira-plugin) on our Community server. -- To report a bug, please [open an issue](https://github.com/mattermost/mattermost-plugin-jira/issues). +- To report a bug, please [open an issue](https://github.com/mattermost/mattermost-plugin-jira/issues). \ No newline at end of file