mirror of https://github.com/zulip/zulip.git
help center: Rewrite Import from Slack documentation.
This commit is contained in:
Alya Abbott
Tim Abbott
parent
ae33873902
commit
ff82c69480
|
|
@ -1,149 +1,314 @@
|
|||
# Import from Slack
|
||||
|
||||
Starting with Zulip 1.8, Zulip supports importing data from Slack,
|
||||
including users, channels, messages, attachments, avatars, custom
|
||||
emoji, and emoji reactions.
|
||||
You can import your Slack organization into Zulip. It's a great way to preserve
|
||||
your organization's history when you migrate from Slack to Zulip, and to make
|
||||
the transition easy for the members of your organization.
|
||||
|
||||
This tool has been used to import Slack workspaces with 10,000 members
|
||||
and millions of messages. If you're planning on doing an import much
|
||||
larger than that, or run into performance issues when importing,
|
||||
[contact us](/help/contact-support) for help.
|
||||
The import will include your organization's:
|
||||
|
||||
**Note:** You can only import a Slack workspace as a new Zulip
|
||||
organization. In particular, you cannot use this tool to import from Slack
|
||||
into an existing Zulip organization.
|
||||
* **Name** and **Logo**
|
||||
* **Message history**, including attachments and emoji reactions
|
||||
* **Users**, including names, emails, roles, avatars, time zones, and custom profile fields
|
||||
* **Channels**, including all user subscriptions
|
||||
* **Custom emoji**
|
||||
|
||||
## Import from Slack
|
||||
|
||||
First, export your data from Slack.
|
||||
|
||||
!!! warn ""
|
||||
|
||||
**Note:** Only Slack owners and admins can export data from Slack.
|
||||
See Slack's
|
||||
[guide to data exports](https://get.slack.help/hc/en-us/articles/201658943-Export-data-and-message-history)
|
||||
for more information.
|
||||
|
||||
#### Get a Slack API token.
|
||||
|
||||
It will be a long string starting with `xoxb-`. It is required to
|
||||
fetch data that Slack doesn't include in their data exports, like
|
||||
email addresses.
|
||||
## Import process overview
|
||||
|
||||
To import your Slack organization into Zulip, you will need to take the
|
||||
following steps, which are described in more detail below:
|
||||
|
||||
{start_tabs}
|
||||
|
||||
1. [Create a new Slack app](https://api.slack.com/apps).
|
||||
1. [Export your Slack data](/help/import-from-slack#export-your-slack-data).
|
||||
|
||||
2. [Add OAuth scopes](https://api.slack.com/authentication/basics#scopes)
|
||||
to your app. We need the following 'bot token scopes':
|
||||
2. [Import you Slack data into
|
||||
Zulip](/help/import-from-slack#import-your-data-into-zulip).
|
||||
|
||||
3. [Clean up](/help/import-from-slack#clean-up-after-the-slack-export) after the Slack export.
|
||||
|
||||
4. [Get your organization started with Zulip](/help/import-from-slack#get-your-organization-started-with-zulip)!
|
||||
|
||||
{end_tabs}
|
||||
|
||||
## Import your organization from Slack into Zulip
|
||||
|
||||
### Export your Slack data
|
||||
|
||||
Slack's [data export
|
||||
service](https://slack.com/services/export) allows you to
|
||||
export all public channel messages, **including older messages that may no
|
||||
longer be searchable** under your Slack plan.
|
||||
|
||||
Unfortunately, Slack [only
|
||||
allows](https://slack.com/help/articles/201658943-Export-your-workspace-data)
|
||||
workspaces that are on the **Business+** or **Enterprise Grid** plans
|
||||
to export private channels and direct messages. Slack's support has
|
||||
confirmed this policy as of August 2022.
|
||||
|
||||
Owners of **Business+** or **Enterprise Grid** workspaces can [request
|
||||
special
|
||||
access](https://slack.com/help/articles/204897248-Guide-to-Slack-import-and-export-tools#options-by-plan)
|
||||
in order to export private message data.
|
||||
|
||||
{start_tabs}
|
||||
|
||||
1. Make sure that you are an owner or admin of your Slack
|
||||
workspace. If you are one, the Slack web application will display
|
||||
that in your profile, in a banner covering the bottom of your
|
||||
avatar.
|
||||
|
||||
2. [Export your Slack message history](https://my.slack.com/services/export).
|
||||
You should be able to download a `zip` file with your data a few minutes
|
||||
after you start the export process.
|
||||
|
||||
3. You will also need to export your workspace's user data and custom emoji.
|
||||
To do so, start
|
||||
by [creating a new Slack app](https://api.slack.com/apps). Choose the "From
|
||||
scratch" creation option.
|
||||
|
||||
4. [Create a
|
||||
bot user](https://slack.com/help/articles/115005265703-Create-a-bot-for-your-workspace),
|
||||
following the instructions to add the following OAuth scopes to your bot:
|
||||
- `emoji:read`
|
||||
- `users:read`
|
||||
- `users:read.email`
|
||||
- `team:read`
|
||||
|
||||
3. [Install the app](https://api.slack.com/authentication/basics#installing)
|
||||
to your workspace. You will get an API token that you can now use to fetch
|
||||
data from your Slack workspace.
|
||||
5. [Install your new app](https://api.slack.com/authentication/basics#installing)
|
||||
to your Slack workspace.
|
||||
|
||||
6. You will immediately see a **Bot User OAuth Token**, which is a long
|
||||
string of numbers and characters starting with `xoxb-`. Copy this token. You
|
||||
will use it to download user and emoji data from your Slack workspace.
|
||||
|
||||
{end_tabs}
|
||||
|
||||
### Export your Slack data
|
||||
### Import your data into Zulip
|
||||
|
||||
Now, [Export your Slack data](https://my.slack.com/services/export). You will
|
||||
receive a zip file `slack_data.zip`.
|
||||
To start using Zulip, you will need to choose between Zulip Cloud and
|
||||
self-hosting Zulip. For a simple managed solution, with no setup or maintenance
|
||||
overhead, you can [sign up](/new/) for Zulip Cloud with just a few clicks.
|
||||
Alternatively, you can [self-host](/self-hosting/) your Zulip organization. See
|
||||
[here](/help/zulip-cloud-or-self-hosting) to learn more.
|
||||
|
||||
!!! warn ""
|
||||
|
||||
This step will also generate a different token starting with
|
||||
`xoxe-`; you don't need it.
|
||||
**You can only import a Slack workspace as a new Zulip organization.** Slack
|
||||
workspace history cannot be added into an existing Zulip organization.
|
||||
|
||||
### Import into Zulip Cloud
|
||||
{start_tabs}
|
||||
|
||||
Email support@zulip.com with `slack_data.zip`, the Slack API token
|
||||
generated above, and your desired subdomain. Your imported organization will
|
||||
be hosted at `<subdomain>.zulipchat.com`.
|
||||
{tab|zulip-cloud}
|
||||
|
||||
If you've already created a test organization at
|
||||
`<subdomain>.zulipchat.com`, let us know, and we can rename the old
|
||||
organization first.
|
||||
#### Import into a Zulip Cloud organization
|
||||
|
||||
### Import into a self-hosted Zulip server
|
||||
If you plan to use Zulip Cloud, we'll take it from here! Please e-mail
|
||||
[support@zulip.com](mailto:support@zulip.com) with the following information:
|
||||
|
||||
First
|
||||
[install a new Zulip server](https://zulip.readthedocs.io/en/stable/production/install.html),
|
||||
skipping "Step 3: Create a Zulip organization, and log in" (you'll
|
||||
create your Zulip organization via the data import tool instead).
|
||||
1. The subdomain you would like to use for your organization. Your Zulip chat will
|
||||
be hosted at `<subdomain>.zulipchat.com`.
|
||||
|
||||
Copy the `slack_data.zip` file you obtained above onto the Zulip
|
||||
2. The `zip` file containing your Slack message history export.
|
||||
|
||||
3. Your Slack **Bot User OAuth Token**, which will be a long
|
||||
string of numbers and characters starting with `xoxb-`
|
||||
|
||||
!!! warn ""
|
||||
|
||||
If the organization already exists, the import process will overwrite all data
|
||||
that's already there. If needed, we're happy to preserve your data by moving an
|
||||
organization you've already created to a new subdomain prior to running the import process.
|
||||
|
||||
{tab|self-hosting}
|
||||
|
||||
#### Import into a self-hosted Zulip server
|
||||
|
||||
Zulip's Slack import tool is robust, and has been used to import Slack
|
||||
workspaces with 10,000 members and millions of messages. If you're planning on
|
||||
doing an import much larger than that, or run into performance issues when
|
||||
importing, [contact us](/help/contact-support) for help.
|
||||
|
||||
1. Follow steps
|
||||
[1](https://zulip.readthedocs.io/en/stable/production/install.html#step-1-download-the-latest-release)
|
||||
and
|
||||
[2](https://zulip.readthedocs.io/en/stable/production/install.html#step-2-install-zulip)
|
||||
of the guide for [installing a new Zulip
|
||||
server](https://zulip.readthedocs.io/en/stable/production/install.html).
|
||||
|
||||
1. Copy the `zip` file containing your Slack message history export onto your Zulip
|
||||
server, and put it in `/tmp/`.
|
||||
|
||||
Log in to a shell on your Zulip server as the `zulip` user. To import with
|
||||
the most common configuration, run the following commands, replacing
|
||||
`<token>` with the value generated above.
|
||||
1. Log in to a shell on your Zulip server as the `zulip` user.
|
||||
|
||||
```
|
||||
cd /home/zulip/deployments/current
|
||||
./scripts/stop-server
|
||||
./manage.py convert_slack_data /tmp/slack_data.zip --token <token> --output /tmp/converted_slack_data
|
||||
./manage.py import '' /tmp/converted_slack_data
|
||||
./scripts/start-server
|
||||
```
|
||||
1. To import into an organization hosted on the root domain
|
||||
(`EXTERNAL_HOST`) of the Zulip installation, run the following commands, replacing
|
||||
`<token>` with your Slack **Bot User OAuth Token**.
|
||||
|
||||
This could take several minutes to run, depending on how much data
|
||||
you're importing. The server stop/restart is only necessary when
|
||||
importing on a server with minimal RAM, where an OOM kill might
|
||||
otherwise occur.
|
||||
!!! tip ""
|
||||
The import could take several minutes to run, depending on how much data you're importing.
|
||||
|
||||
**Import options**
|
||||
```
|
||||
cd /home/zulip/deployments/current
|
||||
./scripts/stop-server
|
||||
./manage.py convert_slack_data /tmp/slack_data.zip --token <token> --output /tmp/converted_slack_data
|
||||
./manage.py import '' /tmp/converted_slack_data
|
||||
./scripts/start-server
|
||||
```
|
||||
|
||||
The commands above create an imported organization on the root domain
|
||||
(`EXTERNAL_HOST`) of the Zulip installation. You can also import into a
|
||||
custom subdomain, e.g. if you already have an existing organization on the
|
||||
root domain. Replace the last line above with the following, after replacing
|
||||
`<subdomain>` with the desired subdomain.
|
||||
Alternatively, to import into a custom subdomain, run:
|
||||
|
||||
```
|
||||
./manage.py import <subdomain> converted_slack_data
|
||||
```
|
||||
```
|
||||
cd /home/zulip/deployments/current
|
||||
./scripts/stop-server
|
||||
./manage.py convert_slack_data /tmp/slack_data.zip --token <token> --output /tmp/converted_slack_data
|
||||
./manage.py import <subdomain> /tmp/converted_slack_data
|
||||
./scripts/start-server
|
||||
```
|
||||
|
||||
### Remove the Slack app used for export
|
||||
!!! tip ""
|
||||
The server stop/restart commands are only necessary when
|
||||
importing on a server with minimal RAM, where an OOM kill might
|
||||
otherwise occur.
|
||||
|
||||
Once the import is complete, you should delete [the Slack
|
||||
app](https://api.slack.com/apps) (and thus API token) that you created
|
||||
in the earlier step. This will prevent the token from being used to
|
||||
access your Slack instance in the future.
|
||||
1. Follow [step 4](https://zulip.readthedocs.io/en/stable/production/install.html#step-4-configure-and-use)
|
||||
of the guide for [installing a new Zulip
|
||||
server](https://zulip.readthedocs.io/en/stable/production/install.html).
|
||||
|
||||
{!import-login.md!}
|
||||
{end_tabs}
|
||||
|
||||
## Caveats
|
||||
#### Import details
|
||||
|
||||
- Slack doesn't export private channels or direct messages unless you pay
|
||||
for Slack Plus or contact Slack support. See
|
||||
[Slack's documentation](https://get.slack.help/hc/en-us/articles/204897248-Guide-to-Slack-import-and-export-tools)
|
||||
for more details.
|
||||
Whether you are using Zulip Cloud or self-hosting Zulip, here are few notes to keep
|
||||
in mind about the import process:
|
||||
|
||||
- (Slack Plus import) Message edit history is currently not imported.
|
||||
- Slack does not export workspace settings, so you will need to [configure
|
||||
the settings for your Zulip organization](/help/customize-organization-settings).
|
||||
This includes settings like [email
|
||||
visibility](/help/restrict-visibility-of-email-addresses),
|
||||
[message editing permissions](/help/configure-message-editing-and-deletion#configure-message-editing-and-deletion_1),
|
||||
and [how users can join your organization](/help/restrict-account-creation).
|
||||
|
||||
- Slack doesn't export user settings or organization settings, so
|
||||
you'll need to configure these manually.
|
||||
- Slack does not export user settings, so users in your organization may want to
|
||||
[customize their account settings](/help/getting-started-with-zulip).
|
||||
|
||||
- Import of [user roles](/help/roles-and-permissions):
|
||||
- Slack's `Workspace Primary Owner` and `Workspace Owner` users
|
||||
are mapped to Zulip `Organization owner` users.
|
||||
- Slack's `Workspace Admin` users are mapped to Zulip's `Organization
|
||||
administrator` users.
|
||||
- Slack's `Member` users is mapped to Zulip `Member` users.
|
||||
- Slack's `Single Channel Guest` and `Multi Channel Guest` users
|
||||
are mapped to Zulip `Guest` users.
|
||||
- Slack's `Channel creators` have no special permissions in Zulip.
|
||||
- Slack's user roles are mapped to Zulip's [user
|
||||
roles](/help/roles-and-permissions) in the following way:
|
||||
|
||||
- The "joined #channel_name" messages are not imported.
|
||||
| Slack role | Zulip role |
|
||||
|-------------------------|---------------|
|
||||
| Workspace Primary Owner | Owner |
|
||||
| Workspace Owner | Owner |
|
||||
| Workspace Admin | Administrator |
|
||||
| Member | Member |
|
||||
| Single Channel Guest | Guest |
|
||||
| Multi Channel Guest | Guest |
|
||||
| Channel creator | none |
|
||||
|
||||
- Messages in threads are still imported, but they are not explicitly marked as
|
||||
to be in a thread.
|
||||
- Messages in threads are imported, but they are not explicitly marked as
|
||||
being in a thread.
|
||||
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
|
||||
- Message edit history and `@user joined #channel_name` messages are not imported.
|
||||
|
||||
## Clean up after the Slack export
|
||||
|
||||
Once your organization has been successfully imported in to Zulip, you should
|
||||
delete [the Slack app](https://api.slack.com/apps) that you created in order to
|
||||
[export your Slack data](#export-your-slack-data). This will prevent the OAuth
|
||||
token from being used to access your Slack workspace in the future.
|
||||
|
||||
## Get your organization started with Zulip
|
||||
|
||||
Once the import process is completed, you will need to:
|
||||
|
||||
{start_tabs}
|
||||
|
||||
1. [Configure the settings for your organization](/help/customize-organization-settings),
|
||||
which are not exported from Slack. This includes settings like [email
|
||||
visibility](/help/restrict-visibility-of-email-addresses), [message editing
|
||||
permissions](/help/configure-message-editing-and-deletion#configure-message-editing-and-deletion_1),
|
||||
and [how users can join your organization](/help/restrict-account-creation).
|
||||
|
||||
2. All users from your Slack workspace will have accounts in your new Zulip
|
||||
organization. However, you will need to decide how users will log in for the first time (see below).
|
||||
|
||||
3. Share the URL for your new Zulip organization, and (recommended) the [Getting
|
||||
started with Zulip guide](/help/getting-started-with-zulip).
|
||||
|
||||
4. Migrate any [integrations](/integrations), which is easy to do with Zulip's
|
||||
[Slack-compatible incoming webhook](/integrations/doc/slack_incoming).
|
||||
|
||||
{end_tabs}
|
||||
|
||||
|
||||
### Decide how users will log in
|
||||
|
||||
When user accounts are imported from Slack, users initially do not have passwords
|
||||
configured. There are a few options for how users can log in for the first time.
|
||||
|
||||
!!! tip ""
|
||||
For security reasons, Slack passwords are never exported.
|
||||
|
||||
### Allow users to log in with non-password authentication
|
||||
|
||||
When you create your organization, users will immediately be able to log in with
|
||||
[authentication methods](/help/configure-authentication-methods) that do not
|
||||
require a password. Zulip offers a variety of authentication methods, including
|
||||
Google, GitHub, GitLab, Apple, LDAP and [SAML](/help/saml-authentication).
|
||||
|
||||
### Send password reset emails to all users
|
||||
|
||||
You can send password reset emails to all users in your organization, which
|
||||
will allow them to set an initial password.
|
||||
|
||||
If you imported your organization into Zulip Cloud, simply e-mail
|
||||
[support@zulip.com](mailto:support@zulip.com) to request this.
|
||||
|
||||
#### Send password reset emails (self-hosted organization)
|
||||
|
||||
{start_tabs}
|
||||
|
||||
{tab|default-subdomain}
|
||||
|
||||
1. To test the process, start by sending yourself a password reset email by
|
||||
using the following command:
|
||||
|
||||
```
|
||||
./manage.py send_password_reset_email -u username@example.com
|
||||
```
|
||||
|
||||
1. When ready, send password reset emails to all users by
|
||||
using the following command:
|
||||
|
||||
```
|
||||
./manage.py send_password_reset_email -r '' --all-users
|
||||
```
|
||||
|
||||
{tab|custom-subdomain}
|
||||
|
||||
1. To test the process, start by sending yourself a password reset email by
|
||||
using the following command:
|
||||
|
||||
```
|
||||
./manage.py send_password_reset_email -u username@example.com
|
||||
```
|
||||
|
||||
1. When ready, send password reset emails to all users by
|
||||
using the following command:
|
||||
|
||||
```
|
||||
./manage.py send_password_reset_email -r <subdomain> --all-users
|
||||
```
|
||||
|
||||
{end_tabs}
|
||||
|
||||
### Manual password resets
|
||||
|
||||
Alternatively, users can reset their own passwords by following the instructions
|
||||
on your organization's login page.
|
||||
|
||||
## Related articles
|
||||
|
||||
- [Slack-compatible incoming webhook](/integrations/doc/slack_incoming)
|
||||
* [Choosing between Zulip Cloud and self-hosting](/help/zulip-cloud-or-self-hosting)
|
||||
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
|
||||
* [Slack-compatible incoming webhook](/integrations/doc/slack_incoming)
|
||||
* [Getting started with Zulip](/help/getting-started-with-zulip)
|
||||
|
|
|
|||
|
|
@ -77,6 +77,10 @@ TAB_SECTION_LABELS = {
|
|||
"web-public-streams": "Web-public streams",
|
||||
"via-user-profile": "Via the user's profile",
|
||||
"via-organization-settings": "Via organization settings",
|
||||
"default-subdomain": "Default subdomain",
|
||||
"custom-subdomain": "Custom subdomain",
|
||||
"zulip-cloud": "Zulip Cloud",
|
||||
"self-hosting": "Self hosting",
|
||||
}
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue