help: Update import-data-from-slack.

templates/zerver/help/import-data-from-slack.md

@@ -1,64 +1,75 @@
-# Import data from Slack
+# Import data from Slack (beta)
 
-{!follow-steps.md!} import data from Slack to Zulip. We support
+Zulip supports importing data from Slack, including users, channels,
-importing data from Slack, including users, channels, messages,
+messages, attachments, avatars, custom emoji, and emoji reactions.
-attachments, avatars, custom emoji, and emoji reactions.
 
 !!! warn ""
-    **Note:** You need administrative rights to the Slack workspace to export data from Slack.
+    These instructions require shell access to the Zulip server. If you'd like
+    to import a Slack organization into the hosted zulipchat.com service,
+    contact support@zulipchat.com.
 
-{!go-to-the.md!} [Slack's export page](https://my.slack.com/services/export) to get your
+1. [Export your Slack data](https://my.slack.com/services/export). You will
-team's zipped data file.
+   receive a zip file `slack_data.zip`.
 
-2. Generate a Slack API legacy token using Slack's
+    !!! warn ""
-[token generator](https://api.slack.com/custom-integrations/legacy-tokens)
+        **Note:** Only Slack owners and admins can export data from Slack.
-to import all of the necessary data. We use this as current Slack exports don't
+        See Slack's
-include user's email data, however, we still get that data from Slack's older
+        [guide to data exports](https://get.slack.help/hc/en-us/articles/201658943-Export-data-and-message-history)
-method of legacy tokens.
+        for more information.
-**Note:** Once Slack starts including user emails in the exports,
-this extra step of using legacy tokens to get user data would no longer be
-necessary.
 
-3. Convert the zip file to Zulip export format using the command
+2. [Generate a Slack API token](https://api.slack.com/custom-integrations/legacy-tokens).
-`./manage.py convert_slack_data <zip_file> <organization_name> --token
-<token> --output <output_dir>`.  This would generate a data file
-`output_dir` in Zulip's standard data import format.
 
-4. Import the converted data into a Zulip using the command
+### Import into a new Zulip instance
-`./manage.py import --import-into-nonempty <output_dir>`
 
-!!! tip ""
+Log in to your Zulip server as the `zulip` user. Run the following
-    These instructions require shell access to the Zulip server.
+commands, replacing `<token>` with the value generated above:
-    If you'd like to import a Slack organization into the hosted
-    zulipchat.com service, contact support@zulipchat.com.
 
-## Slack data elements that are not directly translated
+```
+cd ~/zulip
+./manage.py convert_slack_data slack_data.zip '' --token <token> --output converted_slack_data
+./manage.py import --destroy-rebuild-database converted_slack_data
+```
 
-- Slack's data exports only include public channels and messages to
+!!! warn ""
-public channels unless you pay for their Plus plan or contact Slack
+    **Warning:** This will destroy all existing data in your Zulip instance.
-support.  See
+
-[Slack documentation](https://get.slack.help/hc/en-us/articles/204897248-Guide-to-Slack-import-and-export-tools)
+### Import into an existing Zulip instance
+
+Log in to your Zulip server as the `zulip` user. Run the following
+commands, replacing `<token>` with the value generated above, and
+`<subdomain>` with the subdomain of the URL you'd like for your imported
+Zulip organization.
+
+```
+cd ~/zulip
+./manage.py convert_slack_data slack_data.zip <subdomain> --token <token> --output converted_slack_data
+./manage.py import --import-into-nonempty converted_slack_data
+```
+
+## Caveats
+
+- 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.
-- The Slack->Zulip converter does not yet support private channels and
+
-  private messages.  We expect to address this in a future revision.
+- (Slack Plus import) Private channels and direct messages are currently
-- Message edit history.  Slack only exports the latest revision of edited messages.
+  not imported. We expect to address this in a future revision.
-- Permission hierarchy. They are mapped as follows
+
-    * Slack's **Primary Owner**, **Workspace Owner**, and **Workspace
+- (Slack Plus import) Message edit history is currently not imported.
-      Admin** users are mapped to Zulip organization administrators.
+
-    * Slack's **Member**, **Multi-Channel Guest**, and
+- Slack doesn't export user settings or organization settings, so
-      **Single-Channel Guest** users are mapped to regular Zulip users.
+  you'll need to configure these manually.
-    * Slack's **Channel Creators** have no special permission in Zulip.
+
-- Zulip's "default streams" work slightly differently from Slack's
+- User phone numbers and custom user profile fields are not currently
-  "Default channels" -- new users are automatically subscribed, but
+  imported. We expect to address this in a future revision.
-  users can still unsusbcribe from them.
+
-- Slack's phone number and skype username fields are not transferred
+- Permission hierarchy:
-  to Zulip.  We expect in a future version to convert these to custom
+    Slack's `Primary owner`, `owner`, and `admin` are mapped to Zulip's `Organization admin`.
-  profile fields.
+    Slack's `Member`, `restricted`, and `ultra restricted` are mapped to regular Zulip users.
-- Zulip doesn't have an analog of Slack's "pinned attachments" feature.
+    `Channel creators` have no special permissions in Zulip.
-- Simultaneous bold and italic formatting of a word. This is not yet supported
+
-  by Zulip's backend markdown.
+- The "joined #channel_name" messages are not imported.
-- Slack's "joined #channel_name" notifications are intentionally not
+
-  transferred because they are spammy.
+- The import tool does not support simultaneous bold and italic
-- Slack's data export tools don't contain details about
+  formatting of a word; we expect to address this in a future revision.
-  organization-level settings, so you'll need to configure the Zulip
-  organization settings manually.