From 65789225123030c41110f037163fe4d2210a20dd Mon Sep 17 00:00:00 2001 From: George Goldberg Date: Tue, 22 Nov 2016 17:50:55 +0000 Subject: [PATCH 1/5] Update the Slack import docs with latest features. This updates the Slack import docs, in particular to note the fact that Bot messages, and file attachments can now be imported. PLT-4280. --- source/administration/migrating.rst | 68 ++++++++++++++++++++++++++- source/help/settings/team-settings.md | 26 +--------- 2 files changed, 69 insertions(+), 25 deletions(-) diff --git a/source/administration/migrating.rst b/source/administration/migrating.rst index f3378b69851..69bd8d96d0c 100644 --- a/source/administration/migrating.rst +++ b/source/administration/migrating.rst @@ -26,4 +26,70 @@ The following instructions migrate Mattermost from one server to another by back Migrating from Slack ==================== -You can import channels and users from Slack into Mattermost from Team Settings > Import. Please review our documentation on `Slack Import `_ for more details. +.. note:: As a proprietary SaaS service, Slack is able to change its export format quickly and without notice. If you encounter issues not mentioned in the documentation below, please alert the product team by `filing an issue `_. + +The Slack Import feature in Mattermost is in "Beta" and focus is on supporting migration of teams of less than 100 registered users. + +This feature can be accessed through the `Mattermost Web App `_ or using the `CLI `_. + +.. warning:: **It is highly recommended that you test Slack import before applying it to an instance intended for production.** + + If you use Docker, you can spin up a test instance in one line (``docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform``). If you don't use Docker, there are `step-by-step instructions `_ to install Mattermost in preview mode in less than 5 minutes. + +Supported Features +++++++++++++++++++ + +The following key features are supported out of the box when importing from Slack: + +* User accounts with and email address set. + +* Public channels and text messages posted in them by users. + +* Channel topic and purpose. + +* Automatically adding imported users to their channels. + +Messages with file attachments are imported as a message containing a link to Slack's servers by default. The file attachments themselves can be imported to Mattermost by using the `Slack Advanced Exporter `_ tool to add them to your archive before importing it. + +Bot and Integration messages are imported by default, but if you would like them to display with the appropriate username when imported, you should ensure that `Enable Integrations to Override Usernames `_ is set **before** doing the import. + +.. note:: Slack user accounts with the same email address as existing accounts on your Mattermost server will be merged into those accounts on import. + +Limitations ++++++++++++ + +The following limitations are present when importing from Slack: + +* The Markdown subset used by Slack's Posts 2.0 feature announced on September 28, 2015 is not yet supported. + +* Direct Message and Private Group history. Slack does not include these messages when generating the export archive. + +Migrating from Slack using the Mattermost Web App ++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. note:: For larger imports, particularly those where you have used the `slack-advanced-exporter tool` to add Slack post attachments to the archive, it is recommended to import the Slack data using the `CLI `_. + +1. Generate a Slack "Export" file from **Slack > Team Settings > Import/Export Data > Export > Start Export**. + +2. In Mattermost go to **Team Settings > Import > Import from Slack**. *Team Administrator* or *System Administrator* role is required to access this menu option. + +3. Click **Select file** to upload Slack export file and click **Import**. + + +Migrating from Slack using the Mattermost CLI ++++++++++++++++++++++++++++++++++++++++++++++ + +1. Generate a Slack "Export" file from **Slack > Team Settings > Import/Export Data > Export > Start Export**. + +2. Run the following Mattermost CLI command, with the name of a team you have already created: + + ``$ platform -slack_import -team_name="your-team" -import_archive /path/to/your-slack-export.zip`` + +Using the Imported Team ++++++++++++++++++++++++ + +* During the import process, the emails and usernames from Slack are used to create new Mattermost accounts. + +* Slack users can activate their new Mattermost accounts by using Mattermost's Password Reset screen with their email addresses from Slack to set new passwords for their Mattermost accounts. + +* Once logged in, the Mattermost users will have access to previous Slack messages in the public channels imported from Slack. diff --git a/source/help/settings/team-settings.md b/source/help/settings/team-settings.md index cfd8fff8bb9..7cdaf8fcc5a 100644 --- a/source/help/settings/team-settings.md +++ b/source/help/settings/team-settings.md @@ -27,29 +27,7 @@ The **Invite Code** is used as part of the URL in the team invitation link retri ### Import -#### Import from Slack (Beta) +#### Import from Slack (Beta) -*Note: As a proprietary SaaS service, Slack is able to change its export format quickly and without notice. If you encounter issues not mentioned in the documentation below, please alert the product team by [filing an issue](https://github.com/mattermost/platform/issues).* +You can import channels and users from Slack into Mattermost from **Team Settings > Import**. Please review our documentation on [Slack Import](https://docs.mattermost.com/administration/migrating.html?highlight=slack#migrating-from-slack) for more details. -The Slack Import feature in Mattermost is in "Beta" and focus is on supporting migration of teams of less than 100 registered users. To use: - -1. Generate a Slack "Export" file from **Slack > Team Settings > Import/Export Data > Export > Start Export**. - -2. In Mattermost go to **Team Settings > Import > Import from Slack**. _Team Administrator_ or _System Administrator_ role is required to access this menu option. - -3. Click **Select file** to upload Slack export file and click **Import**. - -4. Emails and usernames from Slack are used to create new Mattermost accounts. - -5. Slack users can activate their new Mattermost accounts by using Mattermost's Password Reset screen with their email addresses from Slack to set new passwords for their Mattermost accounts. - -6. Once logged in, the Mattermost users will have access to previous Slack messages in the public channels imported from Slack. - -**It is highly recommended that you test Slack import before applying it to an instance intended for production.** If you use Docker, you can spin up a test instance in one line (`docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform`). If you don't use Docker, there are [step-by-step instructions](http://docs.mattermost.com/install/docker-local-machine.html) to install Mattermost in preview mode in less than 5 minutes. - -#### Limitations - -- Newly added markdown support in Slack's Posts 2.0 feature announced on September 28, 2015 is not yet supported. -- Slack does not export files or images your team has stored in Slack's database. Mattermost will provide links to the location of your assets in Slack's web UI. However, you can use [this tool](https://github.com/grundleborg/slack-advanced-exporter) to include files in the Slack export, and import them into Mattermost. -- Slack does not export any content from private groups or direct messages that your team has stored in Slack's database. -- In Beta, Slack accounts with usernames or email addresses identical to existing Mattermost accounts will be merged. No pre-check or roll-back is currently offered. From 58e5a247a5ffbb48a713c6212e2655af2a09fb0b Mon Sep 17 00:00:00 2001 From: George Goldberg Date: Thu, 24 Nov 2016 19:07:33 +0000 Subject: [PATCH 2/5] Address review comments. --- source/administration/migrating.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/administration/migrating.rst b/source/administration/migrating.rst index 69bd8d96d0c..d6f74d1a466 100644 --- a/source/administration/migrating.rst +++ b/source/administration/migrating.rst @@ -28,7 +28,7 @@ Migrating from Slack .. note:: As a proprietary SaaS service, Slack is able to change its export format quickly and without notice. If you encounter issues not mentioned in the documentation below, please alert the product team by `filing an issue `_. -The Slack Import feature in Mattermost is in "Beta" and focus is on supporting migration of teams of less than 100 registered users. +The Slack Import feature in Mattermost is in "Beta" and focused on supporting migration of teams of less than 100 registered users. This feature can be accessed through the `Mattermost Web App `_ or using the `CLI `_. @@ -41,9 +41,9 @@ Supported Features The following key features are supported out of the box when importing from Slack: -* User accounts with and email address set. +* User accounts with an email address set. -* Public channels and text messages posted in them by users. +* Public channels and the text messages posted in them by users. * Channel topic and purpose. @@ -62,7 +62,7 @@ The following limitations are present when importing from Slack: * The Markdown subset used by Slack's Posts 2.0 feature announced on September 28, 2015 is not yet supported. -* Direct Message and Private Group history. Slack does not include these messages when generating the export archive. +* Direct Message and Private Groups cannot be imported. Slack does not include these messages when generating the export archive. Migrating from Slack using the Mattermost Web App +++++++++++++++++++++++++++++++++++++++++++++++++ From 187f4b07795cecf564df9f9214d2813741071d4d Mon Sep 17 00:00:00 2001 From: George Goldberg Date: Fri, 2 Dec 2016 16:56:04 +0000 Subject: [PATCH 3/5] Fix more review comments. --- source/administration/migrating.rst | 28 ++++++++++++++++----------- source/help/settings/team-settings.md | 2 +- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/source/administration/migrating.rst b/source/administration/migrating.rst index d6f74d1a466..5e26fb00b5b 100644 --- a/source/administration/migrating.rst +++ b/source/administration/migrating.rst @@ -26,32 +26,38 @@ The following instructions migrate Mattermost from one server to another by back Migrating from Slack ==================== -.. note:: As a proprietary SaaS service, Slack is able to change its export format quickly and without notice. If you encounter issues not mentioned in the documentation below, please alert the product team by `filing an issue `_. +.. note:: As a proprietary SaaS service, Slack is able to change its export format quickly and without notice. If you encounter issues not mentioned in the documentation below, please alert the product team by `filing an issue `_. The Slack Import feature in Mattermost is in "Beta" and focused on supporting migration of teams of less than 100 registered users. -This feature can be accessed through the `Mattermost Web App `_ or using the `CLI `_. +This feature can be accessed through the `Mattermost Web App `_ or using the `CLI `_. .. warning:: **It is highly recommended that you test Slack import before applying it to an instance intended for production.** - If you use Docker, you can spin up a test instance in one line (``docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform``). If you don't use Docker, there are `step-by-step instructions `_ to install Mattermost in preview mode in less than 5 minutes. + If you use Docker, you can spin up a test instance in one line: + + .. code:: bash + + docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform + + If you don't use Docker, there are `step-by-step instructions `_ to install Mattermost in preview mode in less than 5 minutes. Supported Features ++++++++++++++++++ -The following key features are supported out of the box when importing from Slack: +The following key features are supported when importing from Slack: -* User accounts with an email address set. +* User accounts with an email address set -* Public channels and the text messages posted in them by users. +* Public channels and the text messages posted in them -* Channel topic and purpose. +* Channel topic and purpose -* Automatically adding imported users to their channels. +* Imported users added automatically to their channels Messages with file attachments are imported as a message containing a link to Slack's servers by default. The file attachments themselves can be imported to Mattermost by using the `Slack Advanced Exporter `_ tool to add them to your archive before importing it. -Bot and Integration messages are imported by default, but if you would like them to display with the appropriate username when imported, you should ensure that `Enable Integrations to Override Usernames `_ is set **before** doing the import. +Bot and Integration messages are imported by default, but if you would like them to display with the appropriate username when imported, you should ensure that `Enable Integrations to Override Usernames `_ is set in **System Console > Integrations > Custom Integrations** *before* doing the import. .. note:: Slack user accounts with the same email address as existing accounts on your Mattermost server will be merged into those accounts on import. @@ -71,7 +77,7 @@ Migrating from Slack using the Mattermost Web App 1. Generate a Slack "Export" file from **Slack > Team Settings > Import/Export Data > Export > Start Export**. -2. In Mattermost go to **Team Settings > Import > Import from Slack**. *Team Administrator* or *System Administrator* role is required to access this menu option. +2. In Mattermost go to **Team Settings > Import > Import from Slack**. "Team Admin" or "System Admin" role is required to access this menu option. 3. Click **Select file** to upload Slack export file and click **Import**. @@ -92,4 +98,4 @@ Using the Imported Team * Slack users can activate their new Mattermost accounts by using Mattermost's Password Reset screen with their email addresses from Slack to set new passwords for their Mattermost accounts. -* Once logged in, the Mattermost users will have access to previous Slack messages in the public channels imported from Slack. +* Once logged in, Mattermost users will have access to previous Slack messages in the public channels imported from Slack. diff --git a/source/help/settings/team-settings.md b/source/help/settings/team-settings.md index 7cdaf8fcc5a..520a148ba68 100644 --- a/source/help/settings/team-settings.md +++ b/source/help/settings/team-settings.md @@ -29,5 +29,5 @@ The **Invite Code** is used as part of the URL in the team invitation link retri #### Import from Slack (Beta) -You can import channels and users from Slack into Mattermost from **Team Settings > Import**. Please review our documentation on [Slack Import](https://docs.mattermost.com/administration/migrating.html?highlight=slack#migrating-from-slack) for more details. +You can import channels and users from Slack into Mattermost from **Team Settings > Import**. Please review our documentation on [Slack Import](https://docs.mattermost.com/administration/migrating.html#migrating-from-slack) for more details. From ab0a7dab7edd4c7843cd0276c4e6620efbb97164 Mon Sep 17 00:00:00 2001 From: George Goldberg Date: Fri, 2 Dec 2016 16:58:07 +0000 Subject: [PATCH 4/5] Fix some URLs. --- source/administration/migrating.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/administration/migrating.rst b/source/administration/migrating.rst index 5e26fb00b5b..47c13f046d0 100644 --- a/source/administration/migrating.rst +++ b/source/administration/migrating.rst @@ -40,7 +40,7 @@ This feature can be accessed through the `Mattermost Web App `_ to install Mattermost in preview mode in less than 5 minutes. + If you don't use Docker, there are `step-by-step instructions `_ to install Mattermost in preview mode in less than 5 minutes. Supported Features ++++++++++++++++++ @@ -73,7 +73,7 @@ The following limitations are present when importing from Slack: Migrating from Slack using the Mattermost Web App +++++++++++++++++++++++++++++++++++++++++++++++++ -.. note:: For larger imports, particularly those where you have used the `slack-advanced-exporter tool` to add Slack post attachments to the archive, it is recommended to import the Slack data using the `CLI `_. +.. note:: For larger imports, particularly those where you have used the `slack-advanced-exporter tool` to add Slack post attachments to the archive, it is recommended to import the Slack data using the `CLI `_. 1. Generate a Slack "Export" file from **Slack > Team Settings > Import/Export Data > Export > Start Export**. From 42e94102a6db0249d6a85c0f7df5491421620937 Mon Sep 17 00:00:00 2001 From: Jason Blais Date: Fri, 2 Dec 2016 17:41:49 -0500 Subject: [PATCH 5/5] Update migrating.rst --- source/administration/migrating.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration/migrating.rst b/source/administration/migrating.rst index 47c13f046d0..036ef73e761 100644 --- a/source/administration/migrating.rst +++ b/source/administration/migrating.rst @@ -77,7 +77,7 @@ Migrating from Slack using the Mattermost Web App 1. Generate a Slack "Export" file from **Slack > Team Settings > Import/Export Data > Export > Start Export**. -2. In Mattermost go to **Team Settings > Import > Import from Slack**. "Team Admin" or "System Admin" role is required to access this menu option. +2. In Mattermost go to **Team Settings > Import > Import from Slack**. Team Admin or System Admin role is required to access this menu option. 3. Click **Select file** to upload Slack export file and click **Import**.