Use YouTrack as a Help Desk

The Mailbox Integration is a key feature that lets you create issues from email messages and add replies as comments, in effect turning YouTrack into a help desk.

You can involve your customers in your issue tracking process without creating user accounts for them in YouTrack. Plus, YouTrack can involve multiple help desk customers in a single email thread.

When you use YouTrack as a help desk, your support workflow is clean and simple.

Your customers don't need user accounts in YouTrack to follow up on issues.
Your support engineers don't have to monitor a support mailbox.
Customers are notified when comments are added to issues.
Support engineers can read replies from customers as comments in YouTrack
When a customer adds recipients to a reply, they are also notified when the issue is updated. Additional recipients can add their own comments when they reply to the notification or the message from the original reporter.

This step-by-step guide shows you how to configure YouTrack to process and manage support requests.

Process Overview

To configure and use a YouTrack project as a help desk, follow these steps:

Enable Email Notifications in YouTrack.
Set Up a Project for Your Help Desk.
Configure the Mailbox Integration.

Enable Email Notifications in YouTrack

First, make sure that email notifications are enabled and the connection to an email service is configured correctly on your YouTrack server.

If you use a Google mail service to send email notifications, use the same email address as your global From address and your help desk notifications. Google does not let you use a substitute email address. If you use an email address as the From address in your project that differs from the address in the global settings, the mail service does not deliver the messages.

You don't have to do anything special here, just follow the basic setup instructions and test the connection to the mail service. For specific instructions, see Email Server Settings.

When email notifications are enabled and configured in YouTrack, you are ready to create and configure your help desk project.

Set Up a Project for Your Help Desk

The project that you use for your help desk should be configured differently from a project that is used for a development team. You probably want to use a different set of custom fields, and will need to set the email address that is used for notifications in the project.

You also need to attach a workflow to the project that manages email notifications. To learn more about this workflow, see Notify Multiple Unregistered Users.

The configuration of the project is specific to this use case, so we describe it here in some detail.

To create a new project to use for the help desk:

Click the Projects link in the header, then click the Create Project button.
Enter a name (Help Desk), and a description for the project.
Select the project type that you want to use. Any type will work just fine, but if you select a Kanban project, YouTrack automatically creates an agile board that your support engineers can use to manage issues. This project type also uses fewer default custom fields, which makes it easier to configure for your help desk.
Click the Create project button.
- The project overview for the new project opens.
In the Administration section of the sidebar, click the Settings link.
- The Edit Project page opens.
Set the manager of the help desk as the Project owner and click the Apply changes button.
Select the Notifications tab and set the from address or sender name for email messages in the project.
- If your YouTrack installation is connected to your own email service, you can customize the From address. Enter the email address that you want to use to send notifications for the help desk project.
- If you're working with a YouTrack Cloud instance that uses the default configuration for email notifications, you can only customize the Sender name.
If your from address doesn't process replies, enter the email address that you want to use as the Reply-To address.
Click the Apply changes button.
Select the Fields tab and configure the custom fields in the new project:
- Add your support engineers to the list of assignees.
- Configure the custom fields that you want to use in the project. For a help desk, you can get by with Type, Priority, Assignee, and State. The project administrator can add more custom fields as needed.
- Remove any unrelated default custom fields.
Select the Workflow tab.
Detach any unrelated workflows. For example, if you used the Kanban project template, you can detach the Kanban workflow. It's more appropriate for development teams, not support engineers.
Click the Attach workflows button and select Notify Multiple Unregistered Users from the drop-down list.
- The workflow is attached to the project.
- The requires setup flag indicates that the workflow uses custom fields that are not used in the project.

Add the missing fields and field values to the project:

Expand the workflow and select the first workflow rule.
Click a Configure project button to add the required field to the project.
Click the Apply button to create the custom field if it didn't exist before and attach it to your project.
Repeat the process for the second required custom field.

The following custom fields are added to the project:

Custom Field	Description
All related emails	Stores the email addresses for all of the participants in the discussion. The workflow uses this list to send email messages to recipients who are not registered users in YouTrack.
Last message related emails	Stores only the email addresses that were included in the most recent message that was processed by the mailbox integration. This field is updated when YouTrack processes an incoming email message. The workflow copies these email addresses to the All related emails field every time an issue is updated. This ensures that recipients who were not included in the most recent email message are not sent notifications.

Custom Field

Description

All related emails

Stores the email addresses for all of the participants in the discussion. The workflow uses this list to send email messages to recipients who are not registered users in YouTrack.

Last message related emails

Stores only the email addresses that were included in the most recent message that was processed by the mailbox integration. This field is updated when YouTrack processes an incoming email message. The workflow copies these email addresses to the All related emails field every time an issue is updated. This ensures that recipients who were not included in the most recent email message are not sent notifications.

When finished, check the list of custom fields in the project to verify that all of the required fields are in place.

Configure the Mailbox Integration

The last step is to configure the mailbox integration for the help desk project.

The configuration is specific to this use case, so we describe it here in some detail. For general instructions, see Mailbox Integration.

To configure the mailbox integration:

From the Administration menu, select Mailbox Integration.
Set the Fetching interval. For details, see Set the Schedule for Fetching Email Messages.
Connect to the mail service that you use to receive email messages. For details, see Connect to a Mail Service.
Click the Add Mailbox Rule button and configure the following settings:
Setting
Description
Mailbox
Select the mailbox that you provided as the From address in your project.
Project
Select the project that you configured to use for the help desk.
Click to expand the Filter section and enter values for the following settings:
Setting
Description
Folder
Select the folder from which you fetch email messages from the mail service.
Click to expand the Reporter section.
Select the Always set predefined user as reporter option and select the predefined user to set as the reporter for all issues that are created from incoming email messages. This option guarantees that YouTrack does not create a user account for each new customer who sends a support request.
Click to expand the Postprocessing section.
In the Command on New Issues input field, enter the following command:
Last message related emails ${from} ${to} ${cc} ${bcc}
This command stores all of the email addresses that are included in processed email messages. When an issue is updated, the workflow processes this data, updates the All related emails field, sends notifications, and clears this field. For this reason, you will probably never see any values in the Last message related emails field.
Copy the same command to the Command on New Comment field.
Click the Add Rule button.

Setting	Description
Mailbox	Select the mailbox that you provided as the From address in your project.
Project	Select the project that you configured to use for the help desk.

Setting	Description
Folder	Select the folder from which you fetch email messages from the mail service.

When you have finished with the configuration of the mailbox integration, you're all set. You are ready to use YouTrack as a help desk and handle incoming requests that are sent to the email address for your customer support team.

Key Configuration Settings

The configuration for the mailbox integration requires setup on a few different pages in YouTrack. If you're having problems and need to verify the setup, check that the following settings are configured correctly.

Page	Setting
Global Settings > Notifications	Email notifications are enabled and configured for your YouTrack server.
Edit Project > Notifications	The settings that configure your email message headers are set up correctly. If your installation is connected to an external email service, the From address is set to the email address that customers use to send support requests. The Reply-to address is set to the email where you want your customers to send their email replies.
Edit Project > Fields	The string-type fields All related emails and Last message related emails are added to your project. You can add these fields to your project when you attach the Notify Multiple Unregistered Users workflow and update the fields in your project.
Edit Project > Workflow	The Notify Multiple Unregistered Users is attached to your project.
Mailbox Integration Settings > Mailbox Rule	The Mailbox is set to the mail service that processes email messages that are sent to the address that you used as the From address in your project. If you're using the default mailbox configuration, the Mailbox is set to the default mailbox `instancename@youtrack.cloud` or `instancename@service.myjetbrains.com`.
Mailbox Integration Settings > Mailbox Rule > Reporter	The Always set predefined user as reporter option is enabled. This setting prevents the creation of new user account for each customer who sends an email message to your support address.
Mailbox Integration Settings > Mailbox Rule > Postprocessing	The command `Last message related emails ${from} ${to} ${cc} ${bcc}` is set for both the Command on New Issues and Command on New Comment input fields.

The Help Desk in Action

Now that you've configured YouTrack to function as a help desk, let's see how it works. Here is how YouTrack handles a sample customer request.

Your customer sends an email message to your help desk address.
The email message is processed by the mailbox integration. A new issue is created based on the email message.
YouTrack stores the email address of the customer in the issue.
A support engineer adds a comment to the issue to respond to the customer request.
The customer receives an email message that includes the new comment.
The customer replies to the email message.
YouTrack adds the text in the reply as a comment in the original issue.

From the customers' point of view, all they do is exchange emails with your support team. Your support team simply reads and adds comments to the issue. Plus, you get to take advantage of using a full-featured issue tracking system.

Enhancements

This setup shows you how to set up YouTrack to manage support requests. You can configure your YouTrack system to support additional use cases and match your support routine.

Review this section for additional features that you want to activate or configure in your project.

Customize the Delimiter for Replies

YouTrack automatically enables a default delimiter for the replies when you set up mailbox integration for a project. It helps the mailbox integration transform replies into comments with greater precision.

If a user writes an email reply and puts their text above the delimiter line, YouTrack will then show only the latest reply and collapse the rest of the thread in a comment. Replying above the delimiter lets you keep only the relevant information in the YouTrack comments.

The delimiter text is appended to the beginning of each reply that your team members post as a comment in the help desk project. The default delimiter text reads Please enter your reply above this line, and it is localized to the language of your YouTrack if you change the locale. If you customize the delimiter text, it will remain the same regardless of the YouTrack language.

To disable the delimiter, open the Notifications tab in the Edit Project page and disable the Use delimiter for replies option.

To change the text of the delimiter, enter the new text in the Delimiter text field.

Customize the Email Message

The workflow that sends notifications to unregistered users adds a line of text to the end of the message. To update this part of the message, edit the text in the Send notifications to all unregistered users rule. For more information, see Notify Multiple Unregistered Users.

Note that the message text in the default workflow has been localized. To customize the message, you need to remove the i18n method and replace the localized text string with a static string literal in the desired language. For more information, see Workflow Localization.

Change Priority Based on Issue Age

You can automatically raise the priority of an issue based on the amount of time it has been open. For more information, see SLA Priority.

Use Multiple Support Email Addresses

We use this setup for the YouTrack team. You can contact us at youtrack-feedback@jetbrains.com or youtrack-support@jetbrains.com. All of these requests end up in one Gmail inbox. As you can only use one From field in a project, we use a workflow to manage each email address.

The solution is to create a workflow rule and attach it to your help desk project:

const entities = require('@jetbrains/youtrack-scripting-api/entities');

exports.rule = entities.Issue.onChange({
  title: 'Remove additional feedback emails from All related emails',
  guard: (ctx) => {
    return ctx.issue.fields.isChanged(ctx.allEmails);
  },
  action: (ctx) => {
    const fields = ctx.issue.fields;
    const feedbackEmail = 'email@test.com';
    fields.allEmails = fields.allEmails.replace(feedbackEmail, '');
  },
  requirements: {
    allEmails: {
      name: 'All related emails',
      type: entities.Field.stringType
    }
  }
});

Send Confirmation Emails for New Issues

We prefer to minimize the number of notifications that customers receive from YouTrack. This is why we don't send notifications when issues are created.

If you choose to send a notification, apply the following changes to the Collect related emails on issue creation rule of the Notify Multiple Unregistered Users workflow:

Add a reference to the notifications module in the requirement declarations section.
Add the definition for an email message that is sent when an issue is created in the project.

Use the following version of the workflow rule as a guide:

              const entities = require('@jetbrains/youtrack-scripting-api/entities');
              const notifications = require('@jetbrains.youtrack-scripting-api/notifications');

              exports.rule = entities.Issue.onChange({
                  title: 'Collect related emails on issue creation',
                  guard: (ctx) => {
                      return ctx.issue.becomesReported;
                  },
                  action: (ctx) => {
                      const issue = ctx.issue;
                      const lastMessageRelatedEmailsStr = issue.fields.lastEmails;
                      const isBlank = function (str) {
                          return !str || str.trim().length === 0;
                      };
                      const lastMessageRelatedEmails = isBlank(lastMessageRelatedEmailsStr) ? [] : lastMessageRelatedEmailsStr.split(' ');

                      if (lastMessageRelatedEmails.length) {
                          const fromServiceEmail = issue.project.notificationEmail;
                          const isEmailAllowed = function (email) {
                              return email && email.length && email.toUpperCase() !== fromServiceEmail.toUpperCase();
                          };
                          const allRelatedEmailsStr = issue.fields.allEmails;
                          const allRelatedEmails = isBlank(allRelatedEmailsStr) ? [] : allRelatedEmailsStr.split(' ');

                          const newUsersEmails = lastMessageRelatedEmails.filter(function (email) {
                              return isEmailAllowed(email) && allRelatedEmails.indexOf(email) === -1;
                          });
                          if (newUsersEmails.length) {
                              issue.fields.allEmails = allRelatedEmails.concat(newUsersEmails).join(' ');
                          }
                          issue.fields.lastEmails = null;

                          const message = {
                            fromName: 'YouTrack',                      // set the name you want to use as the sender of the email message
                            to: lastMessageRelatedEmails.slice(0, 1),  // set the message recipient
                            subject: '[YouTrack] New Issue',           // set the subject line for the message
                            body: [                                    // compose the email message
                                '<div style="font-family: sans-serif">',
                                '  <div style="padding: 10px 10px; font-size: 13px; border-bottom: 1px solid #D4D5D6;">',
                                '    The YouTrack support team has received your request (' + issue.id + ') and will get back to you shortly.',
                                '    To add additional comments, please reply to this email or follow this link:' + issue.url,
                                '  </div>',
                                '<\div>'
                                ].join('\n')
                            };
                          notifications.sendEmail(message, issue);
                      }
                  },
                  requirements: {
                      lastEmails: {
                          name: 'Last message related emails',
                          type: entities.Field.stringType
                      },
                      allEmails: {
                          name: 'All related emails',
                          type: entities.Field.stringType
                      }
                  }
              });

Last modified: 06 July 2022