Skip to content

Service Desk with email

Context

In scope use cases

System admin activates service desk by checking the checkbox. The checkbox is visible by anybody who can access the project settings. But only the system admin has permission to check or uncheck the checkbox.

  • Behind the scenes, GitLab manages a special support-bot user to do issue creation / comment adding.
  • This user (username, email, and avatar) shows up in the GitLab UI.
  • That support-bot username is defaulted to support-bot and email is defaulted to support-bot@gitlab-instance-url.com.
  • The system will automatically change that username and email if it's already taken.
  • That support-bot account cannot be used by a human to log into GitLab.
  • That support-bot has an avatar: https://gitlab.com/gitlab-org/gitlab-ee/uploads/bc0e5966ad151c5fe6cbe9ec6c9b09ca/avatar-support-bot-3.png
  • GitLab provides a special email address to send in issues, e.g. zxcv1234asdf@company.com. (See mockups.)
  • GitLab communicates to the system admin that they should use a friendly email address and have that forward to an internal email address. Example: support@company.com forwarding to zxcv1234asdf@company.com.
  • GitLab also has a warning message that users could potentially spam the email address. So GitLab should warn the system admin of this, and recommend that they implement some email spam solution themselves. GitLab does not have one.
  • If the configuration checkbox is not checked, any new emails coming through the email address don't do anything. (It is fine for the email address to bounce. But not necessary.) No new issues are created.
  • If the configuration checkbox is not checked, any existing issues immediately "stop working". That is, if the external user can still reply back to an existing support issue, then nothing happens on the GitLab side. And if support users can keep commenting on the thread in the issue, no emails are generated.

External user

  • Suppose GitLab support has been set up as in above.
  • External user sends an email to support@company.com.
  • They get an automated email back from the company acknowledging the email request.
  • The automated email has a link / button, that allows the user to click to stop the support thread. This is useful because if a malicious user spoofed the original support request email, then the real owner of the email account can indicate that there was an error. They are opting-out.
  • If the external user does opt out, this generates an email back to the GitLab issue, leaving a comment. So then the support staff knows to close the issue.
  • They get an email back from a human support user.
  • The external user carries on with the support user thread, back and forth, like regular email.
  • Rich media is not supported. Only plain text is supported.

Internal human GitLab support user

  • Suppose GitLab support has been set up as in above.
  • Suppose there is an incoming email to support@company.com.
  • A confidential issue is created in that GitLab project.
    • The issue author is the specially configured dedicated GitLab account, i.e. support-robot from above.
    • The issue title is the subject line of the incoming email. So using the example below, it would be I'm having some problems with accessing my account.
    • The issue description has some email header and body information, for example:
From: Victor Wu <victor@gitlab.com>
Date: Thu, 9 Feb 2017 10:43:53 -0500
Subject: I'm having some problems with accessing my account
To: support@company.com

Hi there. I just opened an account on your site. But I'm having some issues with it. Can somebody there give me a call? Here's an attached screenshot. as well. My phone number is 123-456-7890.

Regards,
Victor
  • The system sends back an automated email, allowing the external user to opt out of the support thread.
  • The automated email is recorded as a comment in the GitLab issue.
  • The human GitLab support user opens the issue and comments on the issue. The content of the comment is sent back to the external user in the same email thread.
  • The email being returned has a properly configured reply-to setting so that the external user can keep emailing back.
  • When the external user emails back, only the body of the email appears in the comment. The author of the comment in GitLab is support-robot.
  • Editing or deleting any comment in the comment thread of the issue has not further effect. (No emails are generated.)
  • Rich media is not supported. Only plain text is supported. Text styling is stripped out. Images or other media are stripped out in both directions. (In the example above, the screenshot is stripped out.)

Acceptance criteria / gotchas

  • Make sure email threads look good on the external user side. Test in at least gmail.
  • Test with HTML emails and images. Test with inline attachments.
  • Make sure we do not get into any infinite email loop scenarios with OOO replies and other auto replies set up by the customer, and the support user accounts.

Design

Documentation

Add it. This is a brand new feature.

Stretch goals

  • Default friendly support email address already set up based on the gitlab instance name, i.e. something like: incoming+gitlab-org/gitlab-ee@gitlab.com
  • Support images.
  • Depending on the implementation, the comments created by the external user (via support-robot) might get really long. Use some email parsing solution so it's not messy.

Out of scope

  • What happens when an issue is closed? No strict requirements here.

Original issue description

Description

Companies who sell softwares, need to support their customers. To do so, they need a service desk to communicate with them. They also need an issue tracker to fix and track issues that come out of this. That's two different systems to set up. While they can communicate with APIs, they are not integrated.

We can provide a simple solution for this problem: use our own issue tracker as a simple service desk.

Proposal

Flow:

  1. Each project can have a support user set.
  2. That user's private issue creation email address will be shown in the project settings to people who can admin the project, so we should make it very clear it shouldn't be someone's personal user.
  3. Customer emails this email address
  4. This creates a confidential issue
  5. This issue's author is a user, associated with a non-reply email address, created by the admin.
    • A new metadata is assigned to the issue: the identity of the customer (name + email)
    • That way, we don't have to create a special status for this customer (no need to take care of the seat count or permissions to read anything else in the repository)
    • We'll use this metadata information to send replies back to the customer
  6. All team members can contribute to the ticket submitted by the customer, as long as they have the right permissions (at least reporter access).
  7. We send comments, but not other issue changes (assignee, milestone, labels, etc.) to the email on that issue, without linking to the issue.
  8. The customer can only participate to the discussion by email.

Specifications:

  • New: Project settings screen

    • A dropdown in the project settings screen to associate a user as the default support user

  • New: Receiving emails to the address email defined as the support agent

    • When someone sends an email to this email address, an issue is created (subject line = title, body email = body issue).
    • Two new metadata are added to the issue: name+email (both taken from the sender's information)
    • The email address of the customer (stored in the metadata of the issue) is used to send emails back to the customer.

  • New: Email that is sent back upon ticket submitted

    • Once the email is received on the server, and the issue created, we will send an email back to the sender, saying that we have received the request and get back to him quickly.
    • This should only happen the first time a ticket is submitted - not on every comment made after that.
    • Email does not contain a link to the issue.

  • Updated: Subsequent emails

    • Each time a new comment is added to the thread, an email is sent to the customer. However, the email does not contain a link to the discussion.

Wireframe

Service desk off Service desk on
project-settings--service-desk-off project-settings--service-desk-on

Out of scope

  • Private comments
  • Spam filter: this should be handled outside of GitLab.

References

Similar to:

Needed:

This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

Edited by 🤖 GitLab Bot 🤖