From b8dd409d71de12e0e8903c8236ce04c75472a977 Mon Sep 17 00:00:00 2001 From: Alya Abbott Date: Mon, 14 Oct 2024 11:31:51 -0700 Subject: [PATCH] help: Update exports documentation. Document in-app exports with user consent. --- api_docs/changelog.md | 9 ++- docs/overview/changelog.md | 5 +- help/export-your-organization.md | 89 ++++++++------------- help/include/not-human-export-format.md | 2 +- web/templates/settings/account_settings.hbs | 2 +- zerver/openapi/zulip.yaml | 24 +++--- 6 files changed, 54 insertions(+), 77 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 706e595b49..828d11f93c 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -79,11 +79,12 @@ format used by the Zulip server that they are interacting with. * [`GET /export/realm`](/api/get-realm-exports), [`GET /events`](/api/get-events): Added `export_type` field to the dictionaries in `exports` array. It indicates whether - the export is of public data or full data with user consent. + the export is of public data or full data with user consent + (standard export). * [`POST /export/realm`](/api/get-realm-exports): Added `export_type` parameter to add support for admins to decide whether to create a - public data export or a full data export with member consent. + public or a standard data export. **Feature level 303** @@ -185,8 +186,8 @@ format used by the Zulip server that they are interacting with. **Feature level 295** * [`GET /export/realm/consents`](/api/get-realm-export-consents): Added - a new endpoint to fetch the consents of users for their [private data - exports](/help/export-your-organization#full-export-with-member-consent). + a new endpoint to fetch the [consents of users](/help/export-your-organization#configure-whether-administrators-can-export-your-private-data) + for their private data exports. * `/api/v1/tus` is an endpoint implementing the [`tus` protocol](https://tus.io/protocols/resumable-upload) for resumable uploads. Clients which send authenticated credentials (either via browser-based diff --git a/docs/overview/changelog.md b/docs/overview/changelog.md index f5ae15ec8a..7d4d8ed404 100644 --- a/docs/overview/changelog.md +++ b/docs/overview/changelog.md @@ -1405,9 +1405,8 @@ _Released 2022-07-21_ _Released 2022-07-11_ - CVE-2022-31134: Exclude private file uploads from [exports of public - data](https://zulip.com/help/export-your-organization#export-of-public-data). We - would like to thank Antoine Benoist for bringing this issue to our - attention. + data](https://zulip.com/help/export-your-organization#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server). + We would like to thank Antoine Benoist for bringing this issue to our attention. - Upgraded python requirements. - Improved documentation for load balancers to mention CIDR address ranges. diff --git a/help/export-your-organization.md b/help/export-your-organization.md index c36c25e582..846aff5b70 100644 --- a/help/export-your-organization.md +++ b/help/export-your-organization.md @@ -2,24 +2,28 @@ !!! warn "" - These instructions are specific to the hosted Zulip Cloud service. - If you're running your own server, you may be looking for our + If you're self-hosting Zulip, you may want to check out the documentation on [server export and import][export-and-import] or [server backups][production-backups]. -Zulip has high quality export tools that can be used to migrate from the hosted -Zulip Cloud service to your own servers. Two types of data exports are available -to all Zulip Cloud organizations: +Zulip has high quality export tools that can be used to migrate between the +hosted Zulip Cloud service and your own servers. Two types of data exports are +available for all Zulip organizations: -* [**Export of public data**](#export-of-public-data): Complete data for your - organization *other than* [private channel](/help/channel-permissions) messages - and [direct messages](/help/direct-messages). +* [**Export of public + data**](#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server): + Complete data for your organization *other than* [private + channel](/help/channel-permissions) messages and [direct + messages](/help/direct-messages). This export includes user settings and + channel subscriptions. -* [**Full export with member consent**](#full-export-with-member-consent): +* [**Standard + export**](#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server): Everything in the export of public data, plus all the [private channel](/help/channel-permissions) messages and [direct - messages](/help/direct-messages) of members who opt in to have their data - exported. + messages](/help/direct-messages) that members who have + [allowed](#configure-whether-administrators-can-export-your-private-data) + administrators to export their private data can access. Two additional types of data exports are available to **corporate** [Zulip Cloud Standard][plans] and [Zulip Cloud Plus][plans] customers: @@ -33,7 +37,7 @@ Standard][plans] and [Zulip Cloud Plus][plans] customers: of messages matching some combination of criteria (e.g., sender, recipient, message keyword, or timestamp). -## Export of public data +## Export for migrating to Zulip Cloud or a self-hosted server {!admin-only.md!} @@ -43,12 +47,17 @@ Standard][plans] and [Zulip Cloud Plus][plans] customers: {settings_tab|data-exports-admin} -1. Click **Start export of public data**. +1. Click **Start export**. -1. After a few minutes, you'll be able to download the export as a `.tar.gz` -file from that page. +1. Select the desired **Export type**. -1. Import the tarball using [Zulip's logical data import tool][import-only]. +1. Click **Start export** to begin the export process. After a few minutes, + you'll be able to download the exported data from the list of + data exports. + +1. Use [Zulip's logical data import tool][import-only] to import your data into + a self-hosted server. For Zulip Cloud imports, contact + [support@zulip.com](mailto:support@zulip.com). !!! warn "" @@ -57,44 +66,6 @@ file from that page. {end_tabs} -## Full export with member consent - -{!owner-only.md!} - -{!not-human-export-format.md!} - -In addition to your organization's public data, this export includes all the -messages received by any user in the organization who consents to the data -export. In particular, it includes any [private -channel](/help/channel-permissions) messages and [direct -messages](/help/direct-messages) where *at least one of the recipients* has -given consent. - -Users who do not provide consent will have their settings and channel -subscriptions exported, but will have no personalized message history. - -{start_tabs} - -1. Email [support@zulip.com](mailto:support@zulip.com) with your - organization's `zulipchat.com` URL, asking for a **full export with - member consent**. Please send the email from the same address - that you use to sign in to Zulip, so that Zulip Support can verify - that you are an owner of the organization. - -1. You will receive an email with instructions on how to collect member consent. - Follow the instructions, and notify - [support@zulip.com](mailto:support@zulip.com) when the process has been - completed. - -1. You will receive an archive in the `.tar.gz` format containing all public - information for your organization, plus [private - channel](/help/channel-permissions) messages and [direct - messages](/help/direct-messages) for users who gave consent. - -1. Import the tarball using [Zulip's logical data import tool][import-only]. - -{end_tabs} - ## Full export without member consent {!owner-only.md!} @@ -158,6 +129,16 @@ importing the export into a new Zulip organization. {end_tabs} +## Configure whether administrators can export your private data + +{start_tabs} + +{settings_tab|account-and-privacy} + +1. Under **Privacy**, toggle **Let administrators export my private data**. + +{end_tabs} + ## Related articles * [Change organization URL](/help/change-organization-url) diff --git a/help/include/not-human-export-format.md b/help/include/not-human-export-format.md index 971286ea0a..c8ff518304 100644 --- a/help/include/not-human-export-format.md +++ b/help/include/not-human-export-format.md @@ -1,4 +1,4 @@ !!! warn "" - The format of this export is designed for importing into a self-hosted + This export is formatted for importing into Zulip Cloud or a self-hosted installation of Zulip. It is not designed to be human-readable. diff --git a/web/templates/settings/account_settings.hbs b/web/templates/settings/account_settings.hbs index 05887aaa4f..32fdb1ff3c 100644 --- a/web/templates/settings/account_settings.hbs +++ b/web/templates/settings/account_settings.hbs @@ -98,7 +98,7 @@ setting_name="allow_private_data_export" is_checked=settings_object.allow_private_data_export label=settings_label.allow_private_data_export - help_link="/help/export-your-organization#full-export-with-member-consent" + help_link="/help/export-your-organization#export-your-organization" }}
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index b6d71af67a..a589ba2083 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -13119,16 +13119,15 @@ paths: tags: ["server_and_organizations"] x-requires-administrator: true description: | - Fetch all [public data exports][public-data-export] and - [full data exports with member consent][full-data-export] of the organization. + Fetch all the public and standard [data exports][export-data] + of the organization. **Changes**: Prior to Zulip 10.0 (feature level 304), only public data exports could be fetched using this endpoint. New in Zulip 2.1. - [public-data-export]: /help/export-your-organization#export-of-public-data - [full-data-export]: /help/export-your-organization#full-export-with-member-consent + [export-data]: /help/export-your-organization#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server responses: "200": description: Success. @@ -13173,8 +13172,7 @@ paths: tags: ["server_and_organizations"] x-requires-administrator: true description: | - Create a [public data export][public-data-export] or a - [full data export with member consent][full-data-export] of the organization. + Create a public or a standard [data export][export-data] of the organization. !!! warn "" @@ -13187,8 +13185,7 @@ paths: New in Zulip 2.1. - [public-data-export]: /help/export-your-organization#export-of-public-data - [full-data-export]: /help/export-your-organization#full-export-with-member-consent + [export-data]: /help/export-your-organization#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server [data-export]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#data-export [backups]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#backups requestBody: @@ -13200,10 +13197,10 @@ paths: properties: export_type: description: | - Whether to create a public export or a full export with member consent. + Whether to create a public or a standard data export. - 1 = Public data export. - - 2 = Full data export with member consent. + - 2 = Standard data export. If not specified, defaults to 1. @@ -13258,7 +13255,7 @@ paths: tags: ["server_and_organizations"] x-requires-administrator: true description: | - Fetches which users have [consented](/help/export-your-organization#full-export-with-member-consent) + Fetches which users have [consented](/help/export-your-organization#configure-whether-administrators-can-export-your-private-data) for their private data to be exported by organization administrators. **Changes**: New in Zulip 10.0 (feature level 295). @@ -22159,11 +22156,10 @@ components: export_type: type: integer description: | - Whether the data export is a public data export or a - full data export with member consent. + Whether the data export is a public or a standard data export. - 1 = Public data export. - - 2 = Full data export with member consent. + - 2 = Standard data export. **Changes**: New in Zulip 10.0 (feature level 304). Previously, the export type was not included in these objects because only