Helpdeskers, Support Multiple Customers in a Single YouTrack Thread

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.

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).

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):

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.

Dear Richard,
You are absolutely right about reporterEmail, var word is missed in this sample (I assume that I defined this variable ealier and forgot to show that line here, my apologies). As for sendMail function, empty subject and body mean that you should write your own text there.
UPD: I’ve fixed the example. Thank you for noticing that!

1) If I include the code to create a confirmation e-mail on message creation and create a ticket from an e-mail address that has an account, he/she receives 2 e-mails back in response – one from the added code and one just the normal response.

2) If I reply to the one created by the above code snippit, it creates a new ticket and *sometimes* also relates it to the original ticket. I’ve used as the subject issue.summary and the body, “From your message we automatically created the ticket ” + issue.getId() + “ in our tracking system You will continue to receive email notifications as a staff memeber is assigned and works on your request. Feel freel to reply to this message with any further information or requests.Regards, the G4 Team”. How do I ensure it will be added as a comment instead of generating a new ticket?

Unfortunately, you can’t use mailbox templates in current implementation of workflow (please feel free to vote for the corresponding feature request).

You can either set up sending usual notifications to users (automatically creating accounts for every new customer) or use this workflow to send messages to unregistered users. You can not distinguish registered and unregistered users when processing messages, but I have created another feature request for you.

As for you last question, I consider this to be a bug, as normally all such replies should become comments. I would be very grateful, if you create a bug in our YouTrack with some messages samples.

Not sure why there’s no reply link below your response… anyway, thanks for creating the two tickets, I voted. And I’ll create the bug report shortly.

I have one other question tho – I would like to include the e-mail that created the ticket in the response to the user. Is the e-mail body accessable to workflows? I realize I could use issue.description but I’d prefer to use the e-mail body itself preserving the html formatting.

I also have one other question – If I modify the jetbrains supplied workflows, what happens when I update YT? Will they be overwritten? If not, what if there are updates to those particular workflows? Should I be creating new ones in a separate group that are clones?

On your first question: the only way you can work with email body is via issue description, you are right. The body is used internally only.

On your second question: if you modify supplied workflows, they are not updated when you update YT. If there you want to get the modified version you can manually update them (the link will be available near the workflows you’ve manually modified). If you want to preserve your modified versions, you’d better create their copies with different workflow and rules names (via copy-pasting in editor).

I think it’s important to note that if you use the same ‘Helpdesk User’ email account for the Mailbox Integration as the user nominated for the ‘Always set as reporter’ then that account should have it’s email notifications turned off, otherwise YouTrack will start to duplicate comments (Since the user’s email notifications will again be picked up again as comments on the issue).

Is there a way to have ignore the creation email box, in your example that would be youtrack.demo.helpdesk@gmail.com during email collection?
Reason being am trying to work this into our current setup and it causes a loop on closing the ticket.

I’ve noticed in some cases, the field “All related emails” contains the text “Last message related emails” in addition to a space separated list of e-mail addresses and I see in the comment that appears to have caused this in the Related Changes section:

Last message related
emails No last message related emails→No last message related emails

Custom field ‘Last message related emails’ uses as an intermediate step, to remember email addresses related to last message.
However, please provide me with the screenshot of your full screen issue with History tab expanded, I’ll investigate sequence of steps and the field changes. You’re welcome to send it to youtrack-feedback@jetbrains.com

We’re just trying to implement this in the lastest version of YouTrack using the Workflow editor build 3384.

We aren’t able to put the email notification code into teh rule as the editor doesn’t appear to like the code and so it’s highlighted red. We’ve tried manually entering the code but still have problems with it accepting it. Is there a revised version of the code above to work with the latest version?

Hi Dan,
I had the same issue. I copied the lines and I had the same issue.
So I restarted the service of youtrack and re-opened the youtrack workflow, resynchronised it.
Then I wrote every word manually(you can use ctrl+space to show available options) and workflow accepted this.
This helped me to solve it.
Cheers

Since there’s no way to comment tutorial in Confluence, I need to write it here.

1. This documentation: https://confluence.jetbrains.com/display/YTD65/How-to+Use+YouTrack+as+a+Help+Desk contains bug – At first steps describe the process using notifyMultipleUnregisteredUsers workflow, but in the summary section you mention different workflow, with different post processing actions – very confusing, because now I’m not sure if the following next 2 issues are not result of workflow misconfiguration or not:

2. If non-registered user responds to email, the comment is being added, but it contains ALL email body. Is there a way to add something like “## reply above this line ##” in the template? Otherwise it’s useless for me.

3. Do the templates really have to be so ugly? YT has beautiful email templates for registered users. Also the documentation shows screenshot of nice “comment has been added” template, and when I do my tests, it looks pretty much like a plain email sent by project member to customer directly, not a message sent in result to posting new comment in YT. Please advise

2. Actually, the e-mail quotes should be found and hidden under the + sign in comments. If this feature is broken for you, could you please create an issue in youtrack.jetbrains.com and attach an example of your customers reply eml?

3. The idea of the unregistered users support was to hide software presence from the customers, so that the support process will look for them as an email conversation. If you want to use standard YouTrack notifications you should set up another form of feedback support that YouTrack provides – via creating a separate user account for each new customer.

Ad.3. Well, I’d love to do that, as then everything would work like we want it to, but since YouTrack licensing model changed in 2013, we simply can’t afford it. We’re a small team serving lots of occasional customers. Sometimes people email us once or twice a year, there’s no way we can keep cleaning our users list on a daily basis. Unless there is some other way I’m not aware of?

Btw. if the idea was not to show software, then the default ‘signature’ added to each email ruins it anyway: “You have received this message because you are a participant of the conversation in the issue SD-7. Sincerely yours, YouTrack”, don’t you think ? 😉

3. Well, in your case there is no sense to create new users, that’s right. As for the signature, it is small and gray and very rarely noticed by anyone

As for making pretty notifications, there are two variants indeed:
1) You can modify the template inside the corresponding workflow.
2) You can upvote this issue – https://youtrack.jetbrains.com/issue/JT-24494 . It is not planned yet but the more votes it has the more chances there are that it will be implemented in one of the next releases.

Please clarify if it is possible to write variable ${from}, ${reply-to}, ${to}, ${cc} into different attributes using “Command on New Issues” in postprocessing rules of mailbox integration settings.
In the example you writing everything in one field and then parse it in the editor. Can I write a simple command somehow to keep it simple?
For example: Sender ${from} Copy ${cc}

That’s right, you can use several fields to store different variables. These variables are just placeholders, that are replaced with corresponding strings when processing a message. I also suggest you using “-s to ensure correct command processing: Sender “${from}” Copy “${cc}”.

Another question. Is it possible to attach issue files to be emailed with the help of workflow. For example, I want to exclude mailbox browser from communications and send all replies from youtrack. Can I do that when I get attachments to send?
//Client access to youtrack is not a solution.