summaryrefslogtreecommitdiffstats
path: root/doc/integrations
diff options
context:
space:
mode:
authorChristopher Speller <crspeller@gmail.com>2016-02-18 09:25:10 -0500
committerChristopher Speller <crspeller@gmail.com>2016-02-18 09:25:10 -0500
commita7fae6e62fbddc5565b10995f0eaeaca0af6c818 (patch)
treed34a4bfbf53e52d48cefbd699fbcac1e8032c879 /doc/integrations
parent8b9ff64881aae5694f616612f994991b2a3d7c59 (diff)
downloadchat-a7fae6e62fbddc5565b10995f0eaeaca0af6c818.tar.gz
chat-a7fae6e62fbddc5565b10995f0eaeaca0af6c818.tar.bz2
chat-a7fae6e62fbddc5565b10995f0eaeaca0af6c818.zip
Moving tests to /tests and removing /doc folder. Docs are now in seperate repository
Diffstat (limited to 'doc/integrations')
-rw-r--r--doc/integrations/Single-Sign-On/GitHub-Enterprise.md20
-rw-r--r--doc/integrations/Single-Sign-On/GitHub.md24
-rw-r--r--doc/integrations/Single-Sign-On/Gitlab.md23
-rw-r--r--doc/integrations/services/Gitlab-Integration-Service-for-Mattermost.md9
-rw-r--r--doc/integrations/webhooks/Incoming-Webhooks.md107
-rw-r--r--doc/integrations/webhooks/Outgoing-Webhooks.md118
6 files changed, 0 insertions, 301 deletions
diff --git a/doc/integrations/Single-Sign-On/GitHub-Enterprise.md b/doc/integrations/Single-Sign-On/GitHub-Enterprise.md
deleted file mode 100644
index 6f6633846..000000000
--- a/doc/integrations/Single-Sign-On/GitHub-Enterprise.md
+++ /dev/null
@@ -1,20 +0,0 @@
-## Configuring GitHub Enterprise Single-Sign-On (unofficial)
-
-Note: Because the authentication interface of GitHub Enterprise is similar to that of GitLab, the GitLab SSO feature can be used to unofficially also support GitHub Enterprise SSO.
-
-Follow these steps to configure Mattermost to use Github Enterprise as a single-sign-on (SSO) service for team creation, account creation and sign-in using the GitLab SSO interface.
-
-1. Login to your GitHub Enterprise account and go to the Applications section in Profile Settings.
-2. Add a new application called "Mattermost" with the following as Authorization callback URL:
- * `<your-mattermost-url>` (example: http://localhost:8065)
-
-3. Submit the application and copy the given _Id_ and _Secret_ into the appropriate _GitLabSettings_ fields in config/config.json
-
-4. Also in config/config.json, set _Enable_ to `true` for the _gitlab_ section, leave _Scope_ blank and use the following for the endpoints:
- * _AuthEndpoint_: `https://<your-github-enterprise-url>/oauth/authorize` (example https://github.com/oauth/authorize)
- * _TokenEndpoint_: `https://<your-github-enterprise-url>/oauth/access_token`
- * _UserApiEndpoint_: `https://<your-github-enterprise-url>/api/v3/user`
-
-5. (Optional) If you would like to force all users to sign-up with GitHub Enterprise only, in the _ServiceSettings_ section of config/config.json set _DisableEmailSignUp_ to `true`.
-
-6. Restart your Mattermost server to see the changes take effect.
diff --git a/doc/integrations/Single-Sign-On/GitHub.md b/doc/integrations/Single-Sign-On/GitHub.md
deleted file mode 100644
index 56e2d1c72..000000000
--- a/doc/integrations/Single-Sign-On/GitHub.md
+++ /dev/null
@@ -1,24 +0,0 @@
-## Configuring GitHub Single-Sign-On (unofficial)
-
-Note: Because the authentication interface of GitHub is similar to that of GitLab, the GitLab SSO feature can be used to unofficially also support GitHub SSO.
-
-Follow these steps to configure Mattermost to use Github as a single-sign-on (SSO) service for team creation, account creation and sign-in using the GitLab SSO interface.
-
-1. Login to your GitHub account and go to the Applications section in Profile Settings.
-2. Add a new application called "Mattermost" with the following as Authorization callback URL:
- * `<your-mattermost-url>` (example: http://localhost:8065)
-
-3. Submit the application and copy the given _Id_ and _Secret_ into the appropriate _GitLabSettings_ fields in config/config.json
-
-4. Also in config/config.json, set _Enable_ to `true` for the _gitlab_ section, leave _Scope_ blank and use the following for the endpoints:
- * _AuthEndpoint_: `https://github.com/login/oauth/authorize`
- * _TokenEndpoint_: `https://github.com/login/oauth/access_token`
- * _UserApiEndpoint_: `https://api.github.com/user`
-
-6. (Optional) If you would like to force all users to sign-up with GitHub only,
-in the _ServiceSettings_ section of config/config.json set _DisableEmailSignUp_
-to `true`.
-
-6. Restart your Mattermost server to see the changes take effect.
-
-7. Tell the users to set their public email for GitHub at the [Public profile page](https://github.com/settings/profile). Mattermost uses the email to create account.
diff --git a/doc/integrations/Single-Sign-On/Gitlab.md b/doc/integrations/Single-Sign-On/Gitlab.md
deleted file mode 100644
index f0acc0e66..000000000
--- a/doc/integrations/Single-Sign-On/Gitlab.md
+++ /dev/null
@@ -1,23 +0,0 @@
-## Configuring GitLab Single-Sign-On
-
-Follow these steps to configure Mattermost to use GitLab as a single-sign-on (SSO) service for team creation, account creation and sign-in.
-
-1. Login to your GitLab account and go to the Applications section either in Profile Settings or Admin Area.
-2. Add a new application called "Mattermost" with the following as Redirect URIs:
- * `<your-mattermost-url>/login/gitlab/complete` (example: http://localhost:8065/login/gitlab/complete)
- * `<your-mattermost-url>/signup/gitlab/complete`
-
- (Note: If your GitLab instance is set up to use SSL, your URIs must begin with https://. Otherwise, use http://).
-
-3. Submit the application and copy the given _Id_ and _Secret_ into the appropriate _GitLabSettings_ fields in config/config.json
-
-4. Also in config/config.json, set _Enable_ to `true` for the _gitlab_ section, leave _Scope_ blank and use the following for the endpoints:
- * _AuthEndpoint_: `https://<your-gitlab-url>/oauth/authorize` (example https://example.com/oauth/authorize)
- * _TokenEndpoint_: `https://<your-gitlab-url>/oauth/token`
- * _UserApiEndpoint_: `https://<your-gitlab-url>/api/v3/user`
-
- Note: Make sure your `HTTPS` or `HTTP` prefix for endpoint URLs matches your server configuration.
-
-5. (Optional) If you would like to force all users to sign-up with GitLab only, in the _ServiceSettings_ section of config/config.json set _DisableEmailSignUp_ to `true`.
-
-6. Restart your Mattermost server to see the changes take effect.
diff --git a/doc/integrations/services/Gitlab-Integration-Service-for-Mattermost.md b/doc/integrations/services/Gitlab-Integration-Service-for-Mattermost.md
deleted file mode 100644
index 2ce56bb72..000000000
--- a/doc/integrations/services/Gitlab-Integration-Service-for-Mattermost.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# [GitLab Integration Service for Mattermost](https://github.com/mattermost/mattermost-integration-gitlab)
-
-This [open source integration service](https://github.com/mattermost/mattermost-integration-gitlab) let you configure real-time notifications on GitLab issues, merge requests and comments to be delivered to selected Mattermost channels.
-
-The service can be installed on any Linux-based web server and instructions for **Heroku** and **Ubuntu 14.04** are included. Please see [Mattermost incoming webhooks documentation](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Incoming-Webhooks.md) for details on formatting options within the service.
-
-The Mattermost community is invited to fork, extend and repurpose this service for other applications. If you'd like your integration featured on http://mattermost.org/webhooks, please mail info@mattermost.org or tweet to us at @mattermosthq.
-
-![webhooks](https://gitlab.com/gitlab-org/omnibus-gitlab/uploads/677b0aa055693c4dcabad0ee580c61b8/730_gitlab_feature_request.png)
diff --git a/doc/integrations/webhooks/Incoming-Webhooks.md b/doc/integrations/webhooks/Incoming-Webhooks.md
deleted file mode 100644
index 7373892ad..000000000
--- a/doc/integrations/webhooks/Incoming-Webhooks.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# Incoming Webhooks
-
-Incoming webhooks allow external applications, written in the programming language of your choice--to post messages into Mattermost channels, private groups and direct messages by sending a specifically formatted JSON payload via HTTP POST request to a secret Mattermost URL generated specifically for each application.
-
-A couple key points:
-
-- **Mattermost incoming webhooks are Slack-compatible.** If you've used Slack's incoming webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's proprietary JSON payload format into markdown to render in Mattermost messages
-- **Mattermost incoming webhooks support full markdown.** A rich range of formatting unavailable in Slack is made possible through [markdown support](../../usage/Markdown.md) in Mattermost, including headings, formatted fonts, tables, inline images and other options supported by [Mattermost Markdown]
-
-_Example:_
-
-Suppose you wanted to create a notification of the status of a daily build, with a table of total tests run and total tests failed by component category, with links to failed tests by category. You could create the following JSON payload to post to a Mattermost channel using webhooks:
-
-```
-payload={"text": "
----
-##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0
-| Component | Tests Run | Tests Failed |
-|:-----------|:------------|:-----------------------------------------------|
-| Server | 948 | :white_check_mark: 0 |
-| Web Client | 123 | :warning: [2 (see details)](http://linktologs) |
-| iOS Client | 78 | :warning: [3 (see details)](http://linktologs) |
----
-"}
-```
-Which would render in a Mattermost message as follows:
-
----
-##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0
-| Component | Tests Run | Tests Failed |
-|:-----------|:------------|:-----------------------------------------------|
-| Server | 948 | :white_check_mark: 0 |
-| Web Client | 123 | :warning: [2 (see details)](http://linktologs) |
-| iOS Client | 78 | :warning: [3 (see details)](http://linktologs) |
----
-
-### Enabling Incoming Webhooks
-Incoming webhooks should be enabled on your Mattermost instance by default, but if they are not you'll need to get your system administrator to enable them. If you are the system administrator you can enable them by doing the following:
-
-1. Login to your Mattermost team account that has the system administrator role
-1. Enable incoming webhooks from **System Console -> Service Settings**
-1. (Optional) Configure the **Enable Overriding of Usernames from Webhooks** option to allow external applications to post messages under any name. If not enabled, the username of the creator of the webhook URL is used to post messages
-2. (Optional) Configure the **Enable Overriding of Icon from Webhooks** option to allow external applciations to change the icon of the account posting messages. If not enabled, the icon of the creator of the webhook URL is used to post messages
-
-### Setting Up Existing Integrations
-If you've already found or built an integration and are just looking to hook it up, then you should just need to follow the specific instructions of that integration. If the integration is using Mattermost incoming webhooks, then at some point in the instructions it will ask for a webhook URL. You can get this URL by following the first step in the next section _Creating Integrations using Incoming Webhooks_.
-
-### Creating Integrations using Incoming Webhooks
-You can create a webhook integration to post into Mattermost channels and private groups using these steps:
-
-**Note: Incoming webhooks must be enabled. Only your Mattermost system administrator can enable incoming webhooks if they are currently disabled.**
-
-2. Create a Mattermost Incoming Webhook URL
- 1. Login to your Mattermost team site and go to **Account Settings -> Integrations**
- 2. Next to **Incoming Webhooks** click **Edit**
- 3. Select the channel or private group to receive webhook payloads, then click **Add** to create the webhook
- 4. To see your new webhook in action, try a curl command from your terminal or command-line to send a JSON string as the `payload` parameter in a HTTP POST request
- 1. Example:
- ```
-curl -i -X POST -d 'payload={"text": "Hello, this is some text."}' http://yourmattermost.com/hooks/xxx-generatedkey-xxx
-```
-
-3. Build your integration in the programming language of your choice
- 1. Most integrations will be used to translate some sort of output from another system to an appropriately formatted input that will be passed into the Mattermost webhook URL. For example, an integration could take events generated by [GitLab outgoing webhooks](http://doc.gitlab.com/ee/web_hooks/web_hooks.html) and parse them into a JSON body to post into Mattermost
- 1. To get the message posted into Mattermost, your integration will need to create an HTTP POST request that will submit to the incoming webhook URL you created before. The body of the request must have a `payload` that contains a JSON object that specifies a `text` parameter. For example, `payload={"text": "Hello, this is some text."}` is a valid body for a request
- 2. Set up your integration running on Heroku, an AWS server or a server of your own to start sending real time updates to Mattermost channels and private groups
-
-Additional Notes:
-
-1. For the HTTP request body, if `Content-Type` is specified as `application/json` in the headers of the HTTP request then the body of the request can be direct JSON. For example, ```{"text": "Hello, this is some text."}```
-
-2. You can override the channel specified in the webhook definition by specifying a `channel` parameter in your payload. For example, you might have a single webhook created for _Town Square_, but you can use ```payload={"channel": "off-topic", "text": "Hello, this is some text."}``` to send a message to the _Off-Topic_ channel using the same webhook URL. If an `@` symbol followed by a username is specified, then the message will be sent to that user's direct message channel
-
-1. In addition, with **Enable Overriding of Usernames from Webhooks** turned on, you can also override the username the message posts as by providing a `username` parameter in your JSON payload. For example, you might want your message looking like it came from a robot so you can use ```payload={"username": "robot", "text": "Hello, this is some text."}``` to change the username of the post to robot. Note, to combat any malicious users from trying to use this to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) a `BOT` indicator appears next to posts coming from webhooks
-
-2. With **Enable Overriding of Icon from Webhooks** turned on, you can similarly change the icon the message posts with by providing a link to an image in the `icon_url` parameter of your payload. For example, ```payload={"icon_url": "http://somewebsite.com/somecoolimage.jpg", "text": "Hello, this is some text."}``` will post using whatever image is located at `http://somewebsite.com/somecoolimage.jpg` as the icon for the post
-
-3. Also, as mentioned previously, [markdown](../../usage/Markdown.md) can be used to create richly formatted payloads, for example: ```payload={"text": "# A Header\nThe _text_ below **the** header."}``` creates a messages with a header, a carriage return and bold text for "the"
-
-4. Just like regular posts, the text will be limited to 4000 characters at maximum
-
-### Slack Compatibility
-
-Mattermost makes it easy to take integrations written for Slack's proprietary JSON payload format and repurpose them to become Mattermost integrations. For example:
-
-#### Connecting Mattermost to GitLab using Slack UI
-
-GitLab is the leading open-source alternative to GitHub and offers built-in integrations with Slack. Rather than having to change code to support Mattermost, users can add Mattermost webhooks directly into the interface for Slack.
-
-1. In GitLab, go to **Settings** > **Services** and select **Slack**.
-2. Paste in the incoming webhook URL provided by Mattermost from under **Account Settings** > **Integration** > **Incoming Webhooks**.
-3. Optionally set the **Username** you'd like displayed when the notification is made. Leave the **Channel** field blank
-4. Click **Save** then test the settings to confirm posts will be made to Mattermost
-
-#### Translating Slack's proprietary data format to Mattermost
-
-The following describes the automatic translations Mattermost performance to process data coming from Slack:
-
-1. Payloads designed for Slack using `<>` to note the need to hyperlink a URL, such as ```payload={"text": "<http://www.mattermost.com/>"}```, are translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack
-2. Similiarly, payloads designed for Slack using `|` within a `<>` to define linked text, such as ```payload={"text": "Click <http://www.mattermost.com/|here> for a link."}```, are also translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack
-3. Like Slack, by overriding the channel name with a `@username`, such as `payload={"text": "Hi", channel: "@jim"}`, you can send the message to a user through your direct message chat
-4. Channel names can be prepended with a `#`, like they are in Slack incoming webhooks, and the message will still be sent to the correct channel
-
-To see samples and community contributions, please visit <http://mattermost.org/webhooks>.
-
-#### Known Issues
-- Mattermost does not yet support Slack's feature of using _icon_emoji_ to override the message icon.
diff --git a/doc/integrations/webhooks/Outgoing-Webhooks.md b/doc/integrations/webhooks/Outgoing-Webhooks.md
deleted file mode 100644
index 5fbbb9d87..000000000
--- a/doc/integrations/webhooks/Outgoing-Webhooks.md
+++ /dev/null
@@ -1,118 +0,0 @@
-# Outgoing Webhooks
-
-Outgoing webhooks allow external applications, written in the programming language of your choice--to receive HTTP POST requests whenever a user posts to a certain channel, with a trigger word at the beginning of the message, or a combination of both. If the external application responds appropriately to the HTTP request, as response post can be made in the channel where the original post occurred.
-
-A couple key points:
-
-- **Mattermost outgoing webhooks are Slack-compatible.** If you've used Slack's outgoing webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's proprietary JSON payload format into markdown to render in Mattermost messages
-- **Mattermost outgoing webhooks support full markdown.** When an integration responds with a message to post, it will have access to a rich range of formatting unavailable in Slack that is made possible through [markdown support](../../usage/Markdown.md) in Mattermost. This includes headings, formatted fonts, tables, inline images and other options supported by [Mattermost Markdown]
-
-_Example:_
-
-Suppose you had an external application that recieved a post event whenever a message starting with `#build`. If a user posted the message `#build Let's see the status`, then the external application would receive an HTTP POST with data about that message. The application could then respond with a table of total tests run and total tests failed by component category, with links to failed tests by category. An example response might be:
-```
-{"text": "
----
-##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0
-| Component | Tests Run | Tests Failed |
-|:-----------|:------------|:-----------------------------------------------|
-| Server | 948 | :white_check_mark: 0 |
-| Web Client | 123 | :warning: [2 (see details)](http://linktologs) |
-| iOS Client | 78 | :warning: [3 (see details)](http://linktologs) |
----
-"}
-```
-Which would render in a Mattermost message as follows:
-
----
-##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0
-| Component | Tests Run | Tests Failed |
-|:-----------|:------------|:-----------------------------------------------|
-| Server | 948 | :white_check_mark: 0 |
-| Web Client | 123 | :warning: [2 (see details)](http://linktologs) |
-| iOS Client | 78 | :warning: [3 (see details)](http://linktologs) |
----
-
-### Enabling Outgoing Webhooks
-Outgoing webhooks are off by default, and can be enabled by the system administrator. If you are the system administrator you can enable them by doing the following:
-
-1. Login to your Mattermost team account that has the system administrator role.
-1. Enable outgoing webhooks from **System Console -> Service Settings**.
-1. (Optional) Configure the **Enable Overriding of Usernames from Webhooks** option to allow external applications to post messages under any name. If not enabled, the username of the creator of the webhook URL is used to post messages.
-2. (Optional) Configure the **Enable Overriding of Icon from Webhooks** option to allow external applciations to change the icon of the account posting messages. If not enabled, the icon of the creator of the webhook URL is used to post messages.
-
-### Set Up an Outgoing Webhook
-Once outgoing webhooks are enabled, you will be able to set one up through the Mattermost UI. You will need to know the following
-
-1. The channel (if not all of them) you want to listen to post events from
-2. The trigger words (if any) that will trigger a post event if they are the **first word** of the post
-3. The URL you want Mattermost to report the events to
-
-Once you have those, you can follow these steps to set up your webhook:
-
-1. Login to your Mattermost team site and go to **Account Settings -> Integrations**
-2. Next to **Outgoing Webhooks** click **Edit**
-3. Under **Add a new outgoing webhook** select your options
- 1. Select a channel from the **Channel** dropdown to only report events from a certain channel (optional if Trigger Words selected)
- 2. Enter comma separated words into **Trigger Words** to only report events from posts that start with one of those words (optional if **Channel** selected)
- 3. Enter new line separated URLs that the post events will be sent too
-4. Click **Add** to add your webhook to the system
-5. Your new outgoing webhook will be displayed below with a **Token** that any external application that wants to listen to the webhook should ask for in it's instructions
-
-### Creating Integrations using Outgoing Webhooks
-
-If you'd like to build your own integration that uses outgoing webhooks, you can follow these general guidelines:
-
-1. In the programming language of your choice, write your integration to perform what you had in mind
- 1. Your integration should have a function for receiving HTTP POSTs from Mattermost that look like this example:
- ```
- Content-Length: 244
- User-Agent: Go 1.1 package http
- Host: localhost:5000
- Accept: application/json
- Content-Type: application/x-www-form-urlencoded
-
- channel_id=hawos4dqtby53pd64o4a4cmeoo&
- channel_name=town-square&
- team_domain=someteam&
- team_id=kwoknj9nwpypzgzy78wkw516qe&
- text=some text here&
- timestamp=1445532266&
- token=zmigewsanbbsdf59xnmduzypjc&
- trigger_word=some&
- user_id=rnina9994bde8mua79zqcg5hmo&
- user_name=somename
- ```
- 2. Your integration must have a configurable **MATTERMOST_TOKEN** variable that is the Token given to you when you set up the outgoing webhook in Mattermost as decribed in the previous section _Set Up an Outgoing Webhook_. This configurable **MATTERMOST_TOKEN** must match the token in the request body so your application can be sure the request came from Mattermost
- 3. If you want your integration to post a message back to the same channel, it can respond to the HTTP POST request from Mattermost with a JSON response body similar to this example:
- ```
- {
- "text": "This is some response text."
- }
- ```
-3. Set up your integration running on Heroku, an AWS server or a server of your own to start getting real time post events from Mattermost channels
-
-Additional Notes:
-
-1. With **Enable Overriding of Usernames from Webhooks** turned on, you can also override the username the message posts as by providing a `username` parameter in your JSON payload. For example, you might want your message looking like it came from a robot so you can use the JSON response ```{"username": "robot", "text": "Hello, this is some text."}``` to change the username of the post to robot. Note, to combat any malicious users from trying to use this to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) a `BOT` indicator appears next to posts coming from webhooks
-
-2. With **Enable Overriding of Icon from Webhooks** turned on, you can similarly change the icon the message posts with by providing a link to an image in the `icon_url` parameter of your JSON response. For example, ```{"icon_url": "http://somewebsite.com/somecoolimage.jpg", "text": "Hello, this is some text."}``` will post using whatever image is located at `http://somewebsite.com/somecoolimage.jpg` as the icon for the post
-
-3. Also, as mentioned previously, [markdown](../../usage/Markdown.md) can be used to create richly formatted payloads, for example: ```payload={"text": "# A Header\nThe _text_ below **the** header."}``` creates a messages with a header, a carriage return and bold text for "the"
-
-4. Just like regular posts, the text will be limited to 4000 characters at maximum
-
-### Slack Compatibility
-
-As mentioned above, Mattermost makes it easy to take integrations written for Slack's proprietary JSON payload format and repurpose them to become Mattermost integrations. The following automatic translations are supported:
-
-1. The HTTP POST request body is formatted the same as Slack's, which means your Slack integration's receiving function should not need to change at all to be compatible with Mattermost
-2. JSON responses designed for Slack using `<>` to note the need to hyperlink a URL, such as ```{"text": "<http://www.mattermost.com/>"}```, are translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack
-3. Similiarly, responses designed for Slack using `|` within a `<>` to define linked text, such as ```{"text": "Click <http://www.mattermost.com/|here> for a link."}```, are also translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack
-
-To see samples and community contributions, please visit <http://mattermost.org/webhooks>.
-
-#### Known Issues in v1.1
-
-- Overriding of usernames does not yet apply to notifications
-- Cannot supply `icon_emoji` to override the message icon