diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 5f13e419332c7c8ab02d68d935bcf7d45126fd07..fd74988e668ca7d79889911f1f0cdfc7cf056b50 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -62,3 +62,4 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ - [Issues API](../../../api/issues.md) - [Configure an external issue tracker](../../../integration/external-issue-tracker.md) - [Tasks](../../tasks.md) +- [External participants](../service_desk/external_participants.md) diff --git a/doc/user/project/service_desk/external_participants.md b/doc/user/project/service_desk/external_participants.md new file mode 100644 index 0000000000000000000000000000000000000000..82da367cee7a4e5d5f808684b92c5af289de92cc --- /dev/null +++ b/doc/user/project/service_desk/external_participants.md @@ -0,0 +1,159 @@ +--- +stage: Service Management +group: Respond +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# External participants + +DETAILS: +**Tier:** Free, Premium, Ultimate +**Offering:** GitLab.com, Self-managed + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3758) in GitLab 17.0 [with a flag](../../../administration/feature_flags.md) named `issue_email_participants`. Disabled by default. + +FLAG: +The availability of this feature is controlled by a feature flag. +For more information, see the history. +This feature is available for testing, but not ready for production use. + +External participants are users without a GitLab account that can interact with an issue or Service Desk ticket only by email. +They get notified of public comments on an issue or ticket by [Service Desk emails](configure.md#customize-emails-sent-to-the-requester). + +The maximum number of external participants on an issue or ticket is 10. + +## Service Desk tickets + +GitLab adds the external author of a Service Desk ticket as an external participant. +That usually is the email address from the `From` header of the initial email that created the ticket. + +### Add external participants from the `Cc` header + +By default GitLab only adds the sender of the email that creates the Service Desk ticket as an external participant. + +You can configure GitLab to also add all email addresses from the `Cc` header to the Service Desk ticket. +This works for the initial email and all replies to the [`thank_you` email](configure.md#customize-emails-sent-to-the-requester). + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +To enable the setting for the project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Select **Add external participants from the `Cc` header**. +1. Select **Save changes**. + +## As an external participant + +An external participant receives a notification for each public comment on the issue or ticket +using [Service Desk emails](configure.md#customize-emails-sent-to-the-requester). + +### Replying to notification emails + +An external participant can [reply to the received notification email](../../../administration/reply_by_email.md#you-reply-to-the-notification-email). +It creates a new comment on the issue or ticket and displays the email address of the external participant +instead of a GitLab username. The email address is followed by `(external participant)`. + + + +### Unsubscribing from notification emails + +External participants can use the unsubscribe link in the default Service Desk email template to +unsubscribe from the issue or ticket. + +If you [customize your `thank_you` and `new_note` email templates](configure.md#customize-emails-sent-to-the-requester), +you can use the `%{UNSUBSCRIBE_URL}` placeholder to add the unsubscribe link to the templates. + +Your GitLab instance must be reachable (for example, from the public internet) for the external participant to successfully unsubscribe. +If that's not the case, consider removing the unsubscribe link from your template. + +## As a GitLab user + +To see the email address of an external participant you must have at least the Reporter role for the project. + +The external participant's email address is obfuscated if both these conditions are true: + +- You are not a member of the project or have the Guest role. +- The issue or ticket is public ([non-confidential](../issues/confidential_issues.md#confidential-issues)). + +The external participant's email address is then obfuscated in: + +- The author field of a Service Desk ticket. +- All [system notes](../system_notes.md) that mention an external participant. +- The [REST](../../../api/notes.md) and [GraphQL](../../../api/graphql/index.md) APIs. +- The warning message below the comment editor. + +For example: + + + +### Notifications sent to external participants + +External participants get notifications for all public comments on an issue. +For private communication, use [internal notes](../../discussions/index.md#add-an-internal-note). + +External participants don't receive notifications for any other issue or ticket event. + +### View all external participants + +Get an overview of all external participants that receive a Service Desk email for a new comment. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To see a list of all external participants: + +1. Go to the issue or ticket. +1. Scroll down to the comment editor. +1. If the issue or ticket has external participants, you can see a warning under the comment editor + that lists all external participants. + + + +### Add an external participant + +Add an external participant using the `/invite_email` [quick action](../quick_actions.md) when you want +to include them in the conversation at any time. + +When added, the external participant starts receiving notifications using Service Desk emails. +GitLab doesn't send a `thank_you` email for manually added external participants. + +You should add external participants in a dedicated comment because they don't receive a notification +email for the comment that contains the `/invite_email` quick action. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To add an external participant to an issue or ticket: + +1. Go to the issue or ticket. +1. Add a comment that contains only the quick action `/invite_email user@example.com`. + You can chain up to 6 email addresses. For example `/invite_email user@example.com user2@example.com` + +You should see a success message and a new system note with the email address. + +### Remove an external participant + +Remove an external participant from an issue or Service Desk ticket using the `/remove_email` +[quick action](../quick_actions.md) when they should stop receiving notifications. + +After removing them from the issue or ticket they don't receive new notifications. +But they can still reply to emails they received before and create a new comment on the issue or ticket. + +Prerequisites: + +- You must have at least the Reporter role for the project. +- There must be at least one external participant on the issue or ticket. + +To remove an existing external participant from an issue or ticket: + +1. Go to the issue or ticket. +1. Add a comment that contains only the quick action `/remove_email user@example.com`. + You can chain up to 6 email addresses. For example `/remove_email user@example.com user2@example.com` + +You should see a success message and a new system note with the email address. diff --git a/doc/user/project/service_desk/img/service_desk_external_participants_comment_editor_warning_v17_0.png b/doc/user/project/service_desk/img/service_desk_external_participants_comment_editor_warning_v17_0.png new file mode 100644 index 0000000000000000000000000000000000000000..c956f085c277c6d32f5fb4f3f980d7244a0d2d5d Binary files /dev/null and b/doc/user/project/service_desk/img/service_desk_external_participants_comment_editor_warning_v17_0.png differ diff --git a/doc/user/project/service_desk/img/service_desk_external_participants_comment_v17_0.png b/doc/user/project/service_desk/img/service_desk_external_participants_comment_v17_0.png new file mode 100644 index 0000000000000000000000000000000000000000..9033a960fe64abb9a9bb5796abe35cc610772e7f Binary files /dev/null and b/doc/user/project/service_desk/img/service_desk_external_participants_comment_v17_0.png differ diff --git a/doc/user/project/service_desk/img/service_desk_external_participants_email_obfuscation_v17_0.png b/doc/user/project/service_desk/img/service_desk_external_participants_email_obfuscation_v17_0.png new file mode 100644 index 0000000000000000000000000000000000000000..a39f6b662e393c2e6b14684643248e983fd7757f Binary files /dev/null and b/doc/user/project/service_desk/img/service_desk_external_participants_email_obfuscation_v17_0.png differ diff --git a/doc/user/project/service_desk/index.md b/doc/user/project/service_desk/index.md index 27e3817ba5a34f83b13721451122cb92d0d1047a..6dc1a67aabc567aa7b6c54f5614c58680d2c3d3c 100644 --- a/doc/user/project/service_desk/index.md +++ b/doc/user/project/service_desk/index.md @@ -64,6 +64,10 @@ Meanwhile: - [Email contents and formatting](using_service_desk.md#email-contents-and-formatting) - [Convert a regular issue to a Service Desk ticket](using_service_desk.md#convert-a-regular-issue-to-a-service-desk-ticket) - [Privacy considerations](using_service_desk.md#privacy-considerations) +- [External Participants](external_participants.md) + - [Service Desk tickets](external_participants.md#service-desk-tickets) + - [As an external participant](external_participants.md#as-an-external-participant) + - [As a GitLab user](external_participants.md#as-a-gitlab-user) ## Troubleshooting Service Desk diff --git a/doc/user/project/service_desk/using_service_desk.md b/doc/user/project/service_desk/using_service_desk.md index 054918343ccd95e1285bc8bd7fee59afe8005d03..5271e442707280650dedc777586e7754c1f32f0e 100644 --- a/doc/user/project/service_desk/using_service_desk.md +++ b/doc/user/project/service_desk/using_service_desk.md @@ -39,8 +39,8 @@ are sent as emails: Any responses they send via email are displayed in the issue itself. -For information about headers used for treating email, see -[the incoming email documentation](../../../administration/incoming_email.md#accepted-headers). +For additional information see [External participants](external_participants.md) and the +[headers used for treating email](../../../administration/incoming_email.md#accepted-headers). ### Create a Service Desk ticket in GitLab UI