Migrate from Slack
Slack’s data control policies may change at any time. Also, Slack may choose to change its export capabilities, and/or charge fees to customers for exporting data stored in Slack. Support for negotiating export of customer IP from Slack Enterprise can be requested by contacting Mattermost sales team.
Migrating from Slack to Mattermost involves the following steps:
1. Prepare your Mattermost server
During the import process, we advise to create a new team for importing the Slack workspace data. If merging multiple Slack workspaces into a single team is the desired end-result, we recommend completing the import to separate teams, validating the results, then using mmctl to move channels between teams.
Also, system administrator roles will be overwritten if the usernames match and the user isn’t an admin on the Slack workspace.
Make sure you are running on a supported version of Mattermost to benefit from the most up-to-date functionality and fixes.
2. Generate a Slack import
Slack offers two ways to export your data from their product.
Regular export - Contains only public channel posts. This does not include private channels, DMs, or group conversations. This can be generated from Slack > Administration > Workspace settings > Import/Export Data > Export > Start Export.
Corporate export - Contains all posts. This includes public channels, private channels, DMs and group messages. You must request this export type from Slack directly.
You will receive a zip file containing the following contents:
Direct messages (
dms.json) (Corporate export)
Private channels (
groups.json) (Corporate export)
Group direct messages (
mpims.json) (Corporate export)
App activity logs (
Folders containing posts for every public channel
Folders containing posts for every private channel (Corporate exports)
Refer to the Slack help article for additioanl details on zip file contents.
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 following documentation, please let the Mattermost Product Team know by filing an issue.
3. Download file attachments and email addresses
When you download your Slack export zip file, some data will be missing from the zip file:
Uploaded attachment contents
We need to create a Slack app in order to gather these contents. Follow these steps to create a Slack app:
Go to https://api.slack.com/apps.
Select Create New App.
Select From scratch.
Name the app Slack Advanced Exporter and select the workspace. You’ll have to do this for every workspace. Then select Create App.
Select OAuth & Permissions on the left-hand side of the screen. Then scroll down to Scopes.
Under Bot Token Scopes type in and select the following scopes:
Scroll up and select Install to Workspace.
Grant the app permissions when prompted.
Copy the Bot User OAuth Token and save it somewhere convenient.
We’ll now use Bot User OAuth Token with the
slack-advanced-exporter tool to download emails and attachments. Download the latest release of
slack-advanced-exporter for your OS and architecture here and extract the executable from the download.
Once you have the program downloaded locally, run the commands below to fetch the emails, and then fetch file attachments. Replace
<SLACK TOKEN> with the Slack token you generated earlier and
<SLACK EXPORT FILE> with the path to your export file.
./slack-advanced-exporter --input-archive <SLACK EXPORT FILE> --output-archive export-with-emails.zip fetch-emails --api-token <SLACK TOKEN>
./slack-advanced-exporter --input-archive export-with-emails.zip --output-archive export-with-emails-and-attachments.zip fetch-attachments --api-token <SLACK TOKEN>
The first command collects all of the user emails and creates the file
export-with-emails.zip. The second command fetches attachments and creates the file
export-with-emails-and-attachments.zip, which we will use going forward.
The second command can take a long time if you have a large number of file uploads. If it’s interrupted, delete the file generated (if any), and start again.
export-with-emails-and-attachments.zip now contains all the information necessary to be imported into Mattermost.
It’s preferable to fetch e-mails first to avoid copying large attachments around. Make sure you choose different file names at each stage, as the tool does not support in-place modifications.
Avoid unzipping and rezipping the Slack export. Doing so can modify the directory structure of the archive which could cause issues with the import process.
4. Convert Slack import to Mattermost’s bulk export format
Now that you have a Slack export file with emails and attachments, let’s convert this information into Mattermost’s bulk import format using the import preparation tool
mmetl. Download the latest release of
mmetl for your OS and architecture. Run
mmetl help to learn more about using the tool.
Next, run the following command to create a Mattermost bulk import file. Replace
<TEAM-NAME> with the name of your team in Mattermost. Note that the name needs to be one word like “my-team”.
./mmetl transform slack --team <TEAM-NAME> --file export-with-emails-and-attachments.zip --output mattermost_import.jsonl
The tool outputs a .jsonl file containing all of your users, channels, and posts. It also creates a
data folder that contains all of your attachments. Users’ default authentication method will be configured as email/password. See the section below for instructions on migrating the auth method to another choice.
It doesn’t matter what you name the
.jsonl file. You can name it what you want with the –output flag as shown above. It just needs to be a
5. Import data into Mattermost
We have two options to run the import process:
Uploading the export through Mattermost’s API, via command line
mmctlfrom the server or from another computer. This option is required for Mattermost Cloud deployments.
SSH into the Mattermost server’s host, upload the export file to this server’s file system somehow, and use the
mattermostcommand to process the export file.
For the first option, the server will save the import in its file store before running the import (e.g. AWS S3 if you are using that as your file store), so there will be time spent uploading/downloading the file in this case. Depending on system/environment specs, a 5GB import should be fine over
mmctl import. Imports greater than 10GB should use the
mattermost binary for import.
The migration is idempotent, meaning that you can run multiple imports that contain the same posts, and there will not be duplicated created posts in Mattermost. Each post is imported with the correct user/author and
created_at value from your Slack instance. Threads are kept in tact with the import.
Option 1: Upload export via
Ensure you have the Mattermost command line tool
mmctl installed. This allows you to perform different tasks that communicate to Mattermost’s API. You’ll also want to configure authentication for the tool.
To prepare our files to be uploaded to the server, we need to put both the
.jsonl file and
data folder together into a zip file.
zip -r mattermost-bulk-import.zip data mattermost_import.jsonl
Then we can upload the zip file to our Mattermost server:
mmctl import upload ./mattermost-bulk-import.zip
Run this command to list the available imports:
mmctl import list available
Run this command to process the import. Replace
<IMPORT FILE NAME> with the name you got from the
mmctl import list available command:
mmctl import process <IMPORT FILE NAME>
Finally, run this command to view the status of the import process job. If the job status shows as
pending, then wait before running the command again. The
--json flag is required to view the possible error message. Replace
<JOB ID> with the id you got from the
mmctl import list process command:
mmctl import job show <JOB ID> --json
Option 2: Use the
mattermost command to run the export
First get the
.jsonl file and
data folder onto your server using something like
scp. Then you’ll use the
mattermost binary to process the bulk import data:
mattermost import bulk ./mattermost_import.jsonl --import-path ./data --apply
If you choose the
mmctl option above, you can use the
mmctl import job show command to view any relevant errors that may have occurred. If you run into problems which the error message does not help to resolve, please try the second option of using the
mattermost bulk import command. The
mmctl import process does not give you any additional debugging information, even in the Mattermost server logs.
Note that if you are part of the user group being imported from Slack, your Mattermost profile must have a matching username and email to the corresponding
user line of the
jsonl file. You can manually edit the file to ensure it matches your Mattermost user.
mm-emoji - Designed to smoothly transition emojis from a Slack instance to Mattermost.
mm-importjs - Breaks up large import files into smaller ones, as well as automatically remove null characters in post content when importing data to Mattermost.
slack-migrate-pinned-posts - Migrates pinned posts from Slack to Mattermost.
Use the imported team
During the import process, the emails and usernames from Slack are used to create new Mattermost accounts. If emails are not present in the Slack export archive, then placeholder values will be generated and the system admin will need to update these manually. We recommend administrators search the final import
userlines for with
@example.comin the email property to address and resolve the missing information prior to import.
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.
Instructions on how to migrate user authenticatation to LDAP or SAML can be found here.