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:

  1. Valery, a customer, emails the help desk, CC’ing two other customers.

img_1

2. Thom, a support engineer, replies by posting a comment in YouTrack.

img_3_2

 

 

 

 

3. Valery and the other two customers on CC receive notifications of this.

img_41_last

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.

img_5_2

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:

  1. Configure email notifications.
  2. Configure a help desk project.
  3. Attach a workflow.
  4. Configure mailbox integration.
  5. 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.

  1. Open Administration > Settings, and scroll down to the ‘Email’ section.
  2. Select the ‘Email’ check-box to enable sending email notifications.
  3. 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:

  1. Open Administration > Projects and click Create new project link.
  2. Set the project’s name (‘Help Desk’), ID, and select a project lead.
  3. 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.

New Help Desk project

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:

  1. Open Administration > Projects page, open your Help Desk project and navigate to the Workflow tab.
  2. Click the Attach Workflow link and select ‘jetbrains-youtrack-notifyMultipleUnregisteredUsers’.
  3. Make sure to apply the two suggested quick-fixes. You need to apply them both, otherwise notifications will NOT be sent!
  4. Click Save.

attaching workflow

 

 

 

 

 

 

 

 

 

 

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.

  1. 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.
  2. 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.
  3. 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!).

attaching workflow1

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.

mail rule

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!

This entry was posted in features, how-to, release, tips and tagged , , . Bookmark the permalink.

16 Responses to Helpdeskers, Support Multiple Customers in a Single YouTrack Thread

  1. Richard says:

    The issue creation rule doesn’t work – it sends a message with a blank subject and blank body. You actually need to specify the full subject and body as the arguments to the sendMail function.

    You’re also missing a “var” from the line that starts “reporterEmail = …”; without it, you’ll get an error that the LHS must be a variable.

    • mariyadavydova says:

      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!

      • Jerry Hoffmeister says:

        I would like to use the same template for this as is used if the submitter has an account – how can I do this from a workflow? I’d like to use the “Mailbox submitted issue” template.

        • Jerry Hoffmeister says:

          Two other issues I see here:

          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?

          • mariyadavydova says:

            Dear Jerry,

            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.

          • Jerry Hoffmeister says:

            Hi mariyadavydova,

            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.

          • Jerry Hoffmeister says:

            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?

          • mariyadavydova says:

            Dear Jerry,

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

  2. Fran says:

    Is there a way to limit comments added being forwarded to the customer email unless they are added by a specific user?

    We have some comments on the issues to be internal only and only comments added by the Project Lead forwarded to the customer

    • Richard says:

      It looks like setting “Visible to” to anything other than “All users” will prevent the notification from being sent.

  3. Sebastian Nemeth says:

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

  4. Ian says:

    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.

    • Ian says:

      Change the post processing rules to omit the ${To} field fixed the issue.

      Last message related emails ${from} ${cc}

  5. Pingback: Using YouTrack 5.1 as Your Help Desk | YouTrack — Agile Issue & Project Tracker

  6. Jerry Hoffmeister says:

    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

    and

    All related emails
    → No last message related emails

    • Andrey Tigay says:

      Hello Jerry,

      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

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">