Using YouTrack 5.1 as Your Help Desk

It’s been a while since we added mailbox integration in YouTrack. Mailbox integration is a key feature that allows you to create an issue from email and add replies as comments, in effect turning YouTrack into a help desk.

With YouTrack 5.1 we made great changes to our help desk support. Now you can involve your customers in your issue tracking process without the necessity to create user accounts for them in YouTrack. We made this possible with the help of a brand new workflow called NotifyUnregisteredUsers, comes with YouTrack 5.1.

Use Case

We want to have a project in which YouTrack will create issues from emails from our customers, but we don’t want to register every customer in our YouTrack. Yet we want to be able to notify these unregistered users about their requests, and hold a conversation with them in YouTrack. How can we do this?

Step-by-step Configuration for YouTrack Help Desk
Our help desk configuration contains the following parts:

  • Checking/Configuring system-wide email notification settings.
  • Creating and configuring a help desk project.
  • Attaching workflow to the project.
  • Configuring mailbox integration for the help desk project.

Quick note before we begin:
You must have low-level administration permissions to follow the described procedure.

Part I: Configuring System 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 haven’t change the default settings, you can skip this part and move on to the Part II. In this case we have already enabled and configured sending email notifications for you.

If you are using YouTrack InCloud edition and have change 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.
  4. 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 help desk notifications. Google does not allow substituting sender’s email addresses. Thus, the per-project address you provide for a help desk 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 Part II of the help desk configuration.

Part II: Creating and Configuring Your Help Desk Project

Create a new project, which you will use for the help desk:

  1. Open Administration > Projects and click the link Create new project.
  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

    New Help Desk project

  4. Configure issue fields the new project ‘Help Desk’: Add assignees, remove unrelated default fields, configure remaining related fields. In our case, we decided to leave only four fields: Type, Priority, Assignee and State (we renamed it to ‘Request State’).

Part III: Attaching the Workflow to the Help Desk Project

Attach the default NotifyUnregisteredUsers workflow to the Help Desk project. This configuration step is also important because this particular workflow implements sending notifications to your customers.

  1. Switch to Projects > Help Desk > Workflow tab and click the link Attach Workflow.
  2. In the ‘Workflows for Help Desk’ dialog box, select the workflow ‘jetbrains-youtrack-notifyUnregisteredUsers’.
    Selected workflow and suggested Quick Fixes

    Selected workflow and suggested Quick Fixes

    Important! Another key point in our configuration: When you select the workflow, YouTrack will suggest two Quick-Fixes to add a couple of additional fields to the project:

    • Customer Email — the field that will contain actual email address of the requester, hence allowing your customers to receive notifications without registering in your tracker.
    • Last comment author — the field that will allow your customers not to receive excessive notifications (as unregistered users they can’t configure their notifications, so in a way we will do this for them).

Please make sure you have applied these quick-fixes! Otherwise the workflow won’t work correctly for the help desk project.

Before we proceed to the next part of the configuration, let’s check the current list of issue fields in the project just to make sure all necessary fields are in place:

Issue fields in Help Desk project

Issue fields in Help Desk project

Okay, all fields are in place, so we can now set up Mailbox integration.

Part IV: Configuring Mailbox Integration

  1. Open Administration > Mailbox Integration page.
  2. 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’).

    "Add Mailbox" Dialogue

    “Add Mailbox” Dialogue

  3. Add mail processing rule: click the Add Rule link and set up the following parameters:
    1. On the Main tab select project-Help Desk, Mailbox (the one we have just created), and Maintainer:

      Main tab of a mailbox integration rule

      Main tab of a mailbox integration rule

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

      Filter tab of a mailbox integration rule

      Filter tab of a mailbox integration rule

    3. In the Reporter tab, select the option ‘Always set <username> as reporter’ and select the 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 new customer who sends you a request.

      Reporter tab of a mailbox integration rule

      Reporter tab of a mailbox integration rule

    4. In the Postprocessing tab, provide the following commands:
      • In the field “on issue created”, Customer email ${from}. This command will be applied to each new issue in the Help Desk project created from email. It actually assigns the ‘from’ email address—your customer’s email address—to the field ‘Customer email.’
      • In the field “on comment created”, Last comment author ${from} command, which will be applied to each new comment created from email in the Help Desk project created from email.

      Providing these commands is another key point in configuring your help desk system.

      Postprocessing tab of a mailbox integration rule

      Postprocessing tab of a mailbox integration rule

After saving the new mailbox integration rule, your configuration is finalized. Now your tracker is ready to start serving as your help desk system and handling email requests from your customers.

Summary of Configuration Key Points

Here we’d like to list once again the key points of the help desk configuration that you should keep in mind:

  • When creating a project, make sure to set the “Project ‘from’ email” to your feedback/support email. Thus the notifications will be sent to your unregistered customers from this email, and they will reply to the correct address.
  • Attach the notifyUnregisteredUsers default workflow to your help desk project.
  • Make sure to apply the quick-fixes suggested by the workflow to add these two fields to your project: ”Customer email”and “Last comment author”.
    If you somehow missed the quick-fix, you can create and/or add these fields manually. Just keep in mind that both of these fields must be attached to your project in order to make the help desk work.
  • The mailbox integration should be set for the same feedback/support email address as the Project ‘from’ email.
  • Use the Always set User as reporter option to exclude the possibility of creating new user accounts automatically.
  • Make sure to specify these two commands to apply during the post-processing of an email:
    • Customer email ${from}” command for each new issue created from the email.
    • Last comment author ${from}” command for each new comment created from the email.

How the Process Will Look to Your Customers

So we’ve just configured YouTrack to function as a help desk. To give you an idea of how the conversation between a customer and a support team looks like in such a help desk, here is a sample of typical processing of a customer request:

  1. Your customer sends an email to your help desk address:

    Original email from a customer

    Original email from a customer

  2. From the original email a new issue is created in YouTrack:
    New issue created from the customer's email

    New issue created from the customer’s email

    The customer’s email is stored in the issue.

  3. A support engineer adds a comment to the issue, replying to the customer request:

    Support engineer replies in a comment to the issue

    Support engineer replies in a comment to the issue

  4. Customer receives a notification with the comment:

    Customer receives notification by email

    Customer receives notification by email

  5. The customer replies to the received notification in email:

    Customer replies to the notification in email

    Customer replies to the notification in email

  6. From the customer’s reply email, YouTrack adds a new comment to the original issue:

    Comment created from the customer's reply

    Comment created from the customer’s reply

As you can see, for the customer this is nothing more than exchanging emails with your support team. For the support team, it comes down to simple commenting an issue. Plus, you get all the advantages of the tracking system. And, of course, you can enhance the help desk configuration and tweak it to match your support routine. For instance, you can apply additional commands to new issues in Mailbox Integration, or you can attach other default workflows to notify the project lead about unresolved issues.

Upgrading

Get YouTrack 5.1 and start using it as your help desk today.

NOTE: If you’re using YouTrack InCloud, your site will be upgraded to v5.1 automatically, according to our Maintenance Calendar.

Going Forward

This is the first in a series of posts demonstrating how YouTrack can be used as something more than an issue tracker, and showcasing the powers of YouTrack customization. Coming up next in this series will be Using YouTrack for Payment Management. Stay tuned to our news @youtrack.

We hope this post was useful for you and we look forward to receiving your feedback and ideas!

Track with pleasure,
YouTrack Team

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

38 Responses to Using YouTrack 5.1 as Your Help Desk

  1. Piero Sartini says:

    Great work, we really appreciate this feature.
    But:
    Is there a way to send an initial auto-reply to the external user as well? Right now the initial message is only send to the user creating the ticket (configured inside the Mail Rule)

    It seems to be essential to show some kind of reaction to the customer after he created a issue per email.

    • Ekaterina Ivanova says:

      Hello Piero, thanks for your feedback! We really appreciate it.
      The answer to your question, basically, is “yes, you can implement sending initial notification to the customer.” It could be done quite easily with another workflow rule, the one like this:

      rule notification about created issue

      when becomesReported() {
      if (Customer email != null) {
      sendMail(Customer email, "[YouTrack, Request created]", "Dear customer, We've recieved your email and have created support request in our tracker. Support team's reply will be sent to you as email notification about this request.");
      }
      }

      Of course, you can tweak this basic rule the way you see fit.
      The idea of informing the customer that his request has been received and processed somehow is very reasonable. When we decided to skip this initial notification in our “helpdesk workflow”, we focused on the idea that customer shouldn’t get “just auto-information”. Notification about the comment is actually an answer from the support team, and customer just replies to this email, if needed. We focused on plain email conversation, so to speak. :)

  2. Emelyanov Sergey says:

    Very nice feature! But not all tags and attachments can be used in comments, i try to use table – in email table does not have borders and if i attach a file in comment file dosnt attach in email.
    Thanks for great software :)

    • Ekaterina Ivanova says:

      Sergey, thanks for your feedback!
      Indeed, there’s a bug with parsing css styles from wiki in mail notifications. This bug causes the problem with table borders. We have created JT-23646 . Please feel free to vote or comment on the issue.
      As for attachments in notifications, could you elaborate your usecase? For example, if you’d like to paste an image, you can write !image.png! in your comment text with the name of the attached image. in the notification, the !image.png! will be transformed to img tag with the full path to the image file, and hence the image should be displayed. for a file, you can use [file: my.txt].

      • Emelyanov Sergey says:

        If i use !image.png! tag i see a img tag without src tag in email. If i use [file:my.txt] tag i see link without href attribute.
        I think we have this behavior because we have private Youtrack (without guest user)

  3. We actually implemented pretty much the same scheme however since workflows didn’t support notifications for non-existing users, we implemented this functionality within an SMTP proxy server that takes email notifications out of Youtrack and forwards them on with some logic.

    What seems to be not covered currently with the implemented workflow is if support user carbon copies (CCs) a bunch of other email addresses and they all need to be notified as well as the originator of the issue.

  4. Vasiliy Shiryaev says:

    This does now work for me:

    In the Postprocessing tab, provide the following commands:
    In the field “on issue created”, Customer email $(from). This command will be applied to each new issue in the Help Desk project created from email. It actually assigns the ‘from’ email address—your customer’s email address—to the field ‘Customer email.’
    In the field “on comment created”, Last comment author $(from) command, which will be applied to each new comment created from email in the Help Desk project created from email.

    The Customer email field is filled with string “$(from)”.
    Last comment author is never filled.
    Both issue and comment are added correctly though.

  5. Vasiliy Shiryaev says:

    How to localize emails?

    I have already changed workflow ” jetbrains-youtrack-notifyUnregisteredUsers”, reuploaded it to a server, checked that it contains russian text only, restarted YT service, reattached workflow to project but users still receives original emails.

    • Scott Cate says:

      I noticed that the new templates only affect new issues. Try and create a new issue for your test, and see if the new template is used for the new issue. (your mileage may vary, but this seemed to work for me)

      just a fellow user.

  6. Bob Williams says:

    The “Last comment author” field isn’t updating for me, either. Well, that’s not true: it’s updating, but rather than being set to the sender’s e-mail address, it gets reset to the default value that I specified in the field definition. I can see this by manually changing the value to some random value, then sending another message to trigger an auto-update.

    I verified that the command is exactly as typed above (I’ve tried copying-and-pasting it and typing it myself), and the “${from}” token (for which I get auto-completion) works just fine for the “Customer email” field.

    • Ekaterina Ivanova says:

      Bob, I’m sorry for the delayed answer.
      Actually, it works, but normally you won’t see it :) It is indeed reset to default value because of the workflow.
      Here is what happens:
      1. Mailbox integration: a new comment is added from user’s email, and immediately the “Last comment author” field is set to the customer’s address.
      2. Immediately, as the field has been changed, and issue has been updated, the “notifyUnregisteredUsers” workflow is triggered. It checks the field’s value, skips the notification, and it resets the “Last comment author” field to its default value.
      That’s it. As long as it happens quite fast, it might appear that the field is always set to the default.

      Actually, the “Last comment author” is more of a service field. It might be a good idea to make it private. However, please note, in this case the maintainer of the Mailbox Integration Rule should have permissions to update private fields.

  7. Todd says:

    I was working on enabling mailbox integration today. I noticed that on your example when the customer replies to email, the comment appears in youtrack exactly as written in the body of the email.

    However, when I (on InCloud) reply to an email, the comment I generate in youtrack inserts the email subject line with wiki header h2 markup (it uses ==Email subject==) before the comment itself from the body of the email.

    Is there a way to make it so that it doesn’t insert the subject line on comments? It’s distracting and directs attention away from the actual comment…

  8. Vitaliy says:

    Hi!

    I need help with the localization of messages sent by users.
    We consider your system for the organization of technical support, but I can not rebuild stantartny template.

    How can I correct it? I export the jetbrains-youtrack-notifyUnregisteredUsers, Got 3 file. How to edit them can not understand ((

  9. Lubomir Georgiev says:

    I am in a process of researching the YouTrack product (which looks really very good) and I have just configured the Mail integration.
    It seems that everything is working when I send an email to the configured mail address (a ticket is created successfully), but when I try to comment/reply on an issue I am getting an error which is saying that the App is not able to connect the the SMTP host. I have tried to use both – IMAPS and POP3S but the result is the same:

    org.springframework.mail.MailSendException: Mail server connection failed; nested exception is javax.mail.MessagingException: Could not connect to SMTP host: localhost, port: 0;
    nested exception is:
    java.net.ConnectException: Connection refused. Failed messages: javax.mail.MessagingException: Could not connect to SMTP host: localhost, port: 0;
    nested exception is:
    java.net.ConnectException: Connection refused; message exception details (1) are:
    Failed message 1:
    javax.mail.MessagingException: Could not connect to SMTP host: localhost, port: 0;

    Do you have any idea?

  10. Hi, the customer email field is not getting populated even after attaching the workflow. What can I do about this? Thanks!

    • Ekaterina Ivanova says:

      Ravindranath, which edition do you use – InCloud or Standalone? If you use Standalone version, did you look in to logs for any related errors?
      Did you provide Customer email ${from} command in Email Integration settings?

      I’d also recommend contacting our technical support via email: ‘youtrack-feedback@jetbrains.com’ or ‘youtrack-incloud-support@jetbrains.com’ depending on the YouTrack edition you use.

  11. Vitaliy says:

    Hi!

    I need to create a complex report on problems in youtrack
    for example
    Event, the number of comments, type, priority, response time (the first comment), closing

    implemented reports do not fit. Tell me how to implement it?

    • Ekaterina Ivanova says:

      Vitaliy, hi!
      Complex reports are being actively developed, we plan to implement them in the next major version.
      At the moment, you can create such reports only by getting data via REST and calculating reports on that data.

      • Vitaliy says:

        Am glad to hear that the reports will be developed.

        I have two more questions:
        1. Can I replace the description of the issue when receiving a new comment from the user by e-small
        2. When sending a letter to the user as follows: wikify (myComment.text), is not transmitted quote (>)

        Happy you holiday of March 8

        • Ekaterina Ivanova says:

          Vitaliy,
          As for your question, I would highly recommend you posting these particular questions at our forum

          btw, feel free to use Russian if it’s more convenient for you. :)

          p.s.: thanks for congratulations :)

          • Vitaliy says:

            Конечно удобнее :))

            На форуме я вопрос изначально и оставил по отчетам, но его даже никто не просмотрел.

            Но в любом случае почитаю. Спасибо

  12. Vitaliy says:

    And maybee you have a php client for rest api?

    • Ekaterina Ivanova says:

      Vitaliy, unfortunately no, we don’t have own PHP client, but I think there should be PHP-clients developed by our users.

      Thanks for your good wishes for March 8.

  13. Murat says:

    Hi, I want to set issue state to new when new comment comes from the customer. I tried bunch of workflow code but couldn’t make it happen. Can you help?
    thanks.

    • Vitaliy says:

      Hi.

      For example:
      rule
      when comments.added.isNotEmpty {
      if (comments.canBeUpdatedBy(“user”)) {
      issue.applyCommand(“state new”);
      }

  14. Grunin Yuri says:

    Hi,
    works for me only with manually fetching.
    How can i make it work automatically?

  15. Grunin Yuri says:

    One more problem, screenshots in comments are not fetched?

  16. Vitaliy says:

    Hi, Ekaterina Ivanova!

    When I get query “GET /rest/export/{projectId}/issues”, the answer comes only 10 issue.

    Please help

    • Ekaterina Ivanova says:

      Vitaliy,
      10 is the default limit for exporting issues via rest. to export more than 10, we need to use the ‘max’ parameter. it’s integer-type, so your request will look something like this: 'GET /rest/export/{projectId}/issues?max=350'
      I’ve updated the doc page. Sorry for the inconvenience.

      Another setting in YouTrack that affects the number of issues you can export, is 'Max Issues to Export' in system settings of your YouTrack instance. Check Administration > Settings > System panel. This parameter defines the number of issues that can be exported from your server with one request via rest api, reports, or for printing.
      This maximum number won’t be override by ‘max=N’ parameter of the rest export request.

      i hope you’ll find this helpful.
      Best regards,
      Kate

  17. Alex Martini says:

    Hi, I’m very glad to see YouTrack going forward in this direction. I think that being able to interact with customers without needing to create an individual account for each of them is the way to go.

    Unfortunately, I have a use case that doesn’t seem to be covered by the new functionality introduced in YT 5.1. I’ll try to describe it below.

    Many of my clients use to send support requests via email, with carbon copies (CCs) to other members of their organizations (who must be able to follow the entire request lifecycle, from the moment it’s sent to the moment it’s solved).

    AFAICS, YT will allow me to interact with the original sender of the request (the one in the “From” field), but not with the ones that were in the CC list (who should also get notifications as the request is being processsed). Another way to put it: every email address on the CC list should be added as a watcher of the request.

    Is there any workaround (or a special workflow) for this use case? And if there isn’t one yet, are you planning on supporting this on a future release?

    Regards,
    Alex

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="">