Starting with v5.1, YouTrack can be used as a helpdesk without having to create accounts for your customers (the setup process is described here). Well, we’ve just released YouTrack 5.2 which enhances this functionality by allowing you to support multiple helpdesk customers in a single email thread!
Use case
We want to support our helpdesk customers by email using YouTrack. Customers shouldn’t have to log into YouTrack, and our support engineers shouldn’t need to check their support mailbox. Our customers should receive all the notifications with the engineers’ comments, and the engineers should get all the customers’ replies as comments in YouTrack. If customers include additional recipients in ‘To’ and ‘CC’ fields, all those recipients should become participants of the corresponding conversation, get notifications and be able to add comments by replying to them (or to the original reporter).
Here’s a simple example:
- Valery, a customer, emails the help desk, CC’ing two other customers.
2. Thom, a support engineer, replies by posting a comment in YouTrack.
3. Valery and the other two customers on CC receive notifications of this.
4. Customer John replies to the notification, adding Valery in ‘CC’. The answer is added as an issue comment, and customer Johnny receives a notification of the John’s comment. Valery is excluded from the notification list, as she has already received the email.
Note how none of these customers had to create user accounts in YouTrack, meaning that this process doesn’t affect your license limitations at all. Isn’t that cool?
If you’re ready to try this out, let’s delve a little deeper into the configuration process.
Step-by-step configuration
Basically, the configuration process includes the following steps:
- Configure email notifications.
- Configure a help desk project.
- Attach a workflow.
- Configure mailbox integration.
- Resolve specific problems (if applicable).
Configuring email notifications
First of all, we need to make sure that email notifications are enabled and configured correctly on our server.
If you are using YouTrack InCloud edition and have NOT changed the default settings, you can skip this step and move on to the second step. In this case we have already enabled and configured sending email notifications for you.
If you are using YouTrack InCloud edition and you have changed the default settings, or if you are using YouTrack Standalone edition, you need to make sure that sending email notifications is enabled and working properly.
- Open Administration > Settings, and scroll down to the ‘Email’ section.
- Select the ‘Email’ check-box to enable sending email notifications.
- Provide SMTP server configuration and test the connection.
Important note about using Google mail:
If you are using Google mail server for sending email notifications, please make sure that the email address you use for the notifications is the same address you use for the helpdesk notifications. Google does not allow substituting sender’s email addresses. Thus, the per-project address you provide for a helpdesk project will not work if differs from the system-wide email notifications address.
When sending notifications is enabled and configured, you are ready to proceed to the next step.
Creating and configuring your helpdesk project
Create a new project, which you will use for the helpdesk:
- Open Administration > Projects and click Create new project link.
- Set the project’s name (‘Help Desk’), ID, and select a project lead.
- Assign an email address for the Help Desk project. Please pay attention to this step: To keep conversation with our users in YouTrack, we need a separate, unique email address for our project, so our customers get notifications from and reply to this particular email address. Typically this would be your support/feedback email address.
4. Configure issue fields for the Help Desk project: add assignees, remove unrelated default fields, configure related fields. In our case, we decided to leave only four fields: Type, Priority, Assignee and State (we renamed it to ‘Request State’).
Attaching a workflow
There are two possible use cases that we can address:
A. You are configuring helpdesk support in YouTrack for the first time.
OR
B. You have already configured NotifyUnregisteredUsers workflow in YouTrack 5.1.
A. You are configuring helpdesk support in YouTrack for the first time.
In this case all you need to do is to attach a new workflow:
- Open Administration > Projects page, open your Help Desk project and navigate to the Workflow tab.
- Click the Attach Workflow link and select ‘
jetbrains-youtrack-notifyMultipleUnregisteredUsers’.
- Make sure to apply the two suggested quick-fixes. You need to apply them both, otherwise notifications will NOT be sent!
- Click Save.
B. You have already configured the NotifyUnregisteredUsers workflow in YouTrack 5.1.
Note: If you like how your existing workflow works and don’t need to support multiple email addresses in ‘To’ and ‘CC’ fields, you can just leave everything as is. The old workflow will continue working. Still, the new version is compatible with the old one and also contains a prettier notification template. Give it a try!
Note: If you already have a running Mailbox Integration rule, make sure to delete your rule to prevent fetching emails while you are setting up the new workflow. You should change it anyway, as described in the next section.
- First, detach the previous version of the workflow. Select Administration > Projects, click the name of your Help Desk project, and in the Workflow tab click ‘Detach’ for the ‘
jetbrains-youtrack-notifyUnregisteredUsers’ workflow.
- Rename the additional fields you have in your project according to the requirements of the new workflow: Open the Fields tab of your project, rename ‘Customer email’ to ‘All related emails’, and rename ‘Last comment author’ to ‘Last message related emails’. To do that, just click the field’s name and enter the new name.
- Attach the new workflow: Open the Workflow tab, click the ‘Attach workflow’ link and select ‘
jetbrains-youtrack-notifyMultipleUnregisteredUsers’ (tiny hint: check the word ‘Multiple’ in its name!).
Configuring mailbox integration
1. Go to Administration > Mailbox Integration.
Add the mailbox for your project’s email (the one you provided as Project ‘from’ email while creating the Help Desk project). In our case we used ‘youtrack.demo.helpdesk@gmail.com’.
2. Add a mail processing rule: click the Add Rule link and set up the following parameters:
On the Main tab select project (Help Desk), mailbox (the one we’ve just created), and choose a rule maintainer.
3. Switch to the Filter tab, click the Folder drop-down list and select the folder from which we will fetch the emails. We used INBOX for our IMAP account.
4. In the Reporter tab, select the option ‘Always set as reporter’ and select a user who will be the reporter of all issues created from collected emails. (This is what guarantees that YouTrack will not create a user account for each customer who sends you a request.)
5. In the Postprocessing tab, provide the following command for two fields, ‘on issue created’ and ‘on comment added’:
Last message related emails ${from} ${to} ${cc}
(Feel free to copy & paste it from here without the leading spaces.) This command is used to temporarily store all the related emails on every message fetched. The fetching workflow will process this data, store some emails in ‘All related emails’ field, send some notifications and clean this field. So you will probably never see anything in the ‘Last message related emails’ field in your issues.
Congratulations! You are done with the basic configuration and should be good to go with your help desk project. Still, we thought of a few tips to help you resolve specific problems (if applicable, of course).
Some tips for specific use cases
You have several aliases for your support email
Actually, this is our team’s case: you can contact us at youtrack-feedback@jetbrains.com or youtrack-incloud-support@jetbrains.com, and all these requests end up in one Gmail mailbox. As you can set up only one email in a project’s ‘From’ field, any additional emails should be processed via an additional workflow.
The solution is to create the following rule and attach it to your help desk project:
rule Remove additional feedback emails from All related emails
when All related emails.changed {
All related emails = All related emails.replace(
"email@test.com", "");
}
Repeat the ‘All related emails = All related emails.replace(“email@test.com”, “”);’ line in the rule as many times as needed, changing the email address as appropriate.
If you have any troubles with writing workflows, please don’t hesitate to contact our support team at youtrack-feedback@jetbrains.com or youtrack-incloud-support@jetbrains.com.
You want your customers to receive a confirmation message on issue creation
We prefer to minimize the number of notifications unregistered customers receive from YouTrack. That is why we do not notify them about creating issues from their messages.
However, if you do want to implement this type of behavior, simply add the following lines in the rule ‘Collect related emails on issue creation’ of the workflow ‘jetbrains-youtrack-notifyMultipleUnregisteredUsers’ workflow (right before the ‘Last message related emails=null‘ line):
var reporterEmail = Last message related emails.split(
" ",preserveAllTokens).first
sendMail(reporterEmail, “Your subject”, “Your email body”)
Summary
The idea of this version of the workflow is to support multiple users in a single thread so that they don’t even need to know about YouTrack (unless they enjoy reading small-font grey text at the bottom of their incoming emails). This updated workflow supports much more complicated cases than the previous one. The original customer can add more To and/or CC recipients at any moment of the conversation, and each of them, once added, becomes a participant of the issue.
We hope this blog post has already inspired you to try YouTrack as a helpdesk! All you need to do is Get YouTrack 5.2 and start using it as helpdesk right away.
If you already use YouTrack stand-alone, simply upgrade to the latest version 5.2 to enjoy all the fresh goodies. If you prefer to use YouTrack InCloud, we’ll do the upgrade for you, according to our Maintenance Calendar.
Get YouTrack 5.2 and helpdesk with pleasure!
Dmitri Nesteruk is a developer, speaker, podcaster and a technical evangelist for JetBrains. His interests lie in software development and integration practices in the areas of computation, quantitative finance and algorithmic trading. His technological interests include C#, F# and C++ programming as well high-performance computing using technologies such as CUDA. Dmitiri has been a C# MVP since 2009.
