diff --git a/source/administration/migrating.rst b/source/administration/migrating.rst index f3378b69851..036ef73e761 100644 --- a/source/administration/migrating.rst +++ b/source/administration/migrating.rst @@ -26,4 +26,76 @@ 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 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 `_. + +.. 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: + + .. 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 when importing from Slack: + +* User accounts with an email address set + +* Public channels and the text messages posted in them + +* Channel topic and purpose + +* 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 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. + +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 Groups cannot be imported. 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 Admin or System Admin 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, 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..520a148ba68 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#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.