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:
First, make sure that email notifications are enabled and configured correctly on your server.
If you are using YouTrack InCloud and haven't changed the default settings, skip this step and continue with Set Up a Project for Your Help Desk. Email notifications are enabled and configured by default in your InCloud instance.
If you are have changed the default email notification settings in your YouTrack InCloud instance, or are using YouTrack Standalone edition, verify that email notification is enabled and the connection to an email server is configured.
If you use a Google mail server 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 server 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 server. For specific instructions, see Notifications.
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.
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 InCloud 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 the Update fields button to add the required fields to the project.
Repeat this process for the second workflow rule.
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.
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:
Open the Administration > Mailbox Integration page.
Connect to the mail server that you use to receive email messages. For details, see Connect to a Mail Server.
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 on the mail server.
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}
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 Save button.
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 > General
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 server that processes email messages that are sent to the address that you used as the From address in your project.
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.
The command Last message related emails ${from} ${to} ${cc} 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 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 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 Localizing Workflow Messages.
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-incloud-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:
var entities = require('@jetbrains/youtrack-scripting-api/entities');
exports.rule = entities.Issue.onChange({
title: 'Remove additional feedback emails from All related emails',
guard: function(ctx) {
return ctx.issue.fields.isChanged(ctx.allEmails);
},
action: function(ctx) {
var fields = ctx.issue.fields;
var 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:
var entities = require('@jetbrains/youtrack-scripting-api/entities');
var workflow = require('@jetbrains/youtrack-scripting-api/workflow');
var notifications = require('@jetbrains/youtrack-scripting-api/notifications');
exports.rule = entities.Issue.onChange({
title: workflow.i18n('Collect related emails on issue creation'),
guard: function(ctx) {
return ctx.issue.becomesReported;
},
action: function(ctx) {
var issue = ctx.issue;
var lastMessageRelatedEmailsStr = issue.fields.lastEmails;
var isBlank = function(str) {
return !str || str.trim().length === 0;
};
var lastMessageRelatedEmails = isBlank(lastMessageRelatedEmailsStr) ? [] : lastMessageRelatedEmailsStr.split(' ');
if (lastMessageRelatedEmails.length) {
var fromServiceEmail = issue.project.notificationEmail;
var isEmailAllowed = function(email) {
return email && email.length && email.toUpperCase() !== fromServiceEmail.toUpperCase();
};
var allRelatedEmailsStr = issue.fields.allEmails;
var allRelatedEmails = isBlank(allRelatedEmailsStr) ? [] : allRelatedEmailsStr.split(' ');
var 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;
var message = {
fromName: 'YouTrack', // set whichever name you prefer
toEmails: lastMessageRelatedEmails.slice(0, 1),
subject: '[YouTrack] New Issue', // set a subject you like
body: 'The text of the notification' // set a full body of your notification
};
notifications.sendEmail(message, issue);
}
},
requirements: {
lastEmails: {
name: 'Last message related emails',
type: entities.Field.stringType
},
allEmails: {
name: 'All related emails',
type: entities.Field.stringType
}
}
});
