OTRS guide
This page is still a work in progress!
OTRS, short for Open-Source Ticket Request System, is an email helpdesk system that LizardNet uses for various customer support applications - for example, to allow operators of LizardNet Minecraft servers to respond and send emails to players. This page attempts to document how to use OTRS. OTRS is, admittedly, very complex, but only in that you have to know how to find the functions you want to use - in other words, it's very easy to get used to the system!
Herein, users of OTRS responding to emails and such are referred to as "agents", while the people sending those emails and asking for support are "customers".
Finally, note that all timestamps in OTRS are in UTC.
Contents
Getting an Account
Accounts can only be created by FastLizard4. An account requires three pieces of information:
- A username. This is the name you would use to log in to OTRS, and is only visible to you and OTRS administrators.
- An email address. This is the primary way you are identified on OTRS to other agents, and is also the address OTRS will send notifications (like a customer responding to a ticket you are marked as the owner/respondent of) to. This is visible to you and other OTRS agents. Customers never see your email address, as all correspondence is marked as being from the OTRS queue's address.
- A first and last name. This is also how you can be identified to other agents, but more importantly how you are identified to customers. Although real names are probably best, pseudonyms are allowed, though ones that sound real (e.g., have a first and last name) are preferred. If necessary, though, it is possible to set a single-word pseudonym as your first and last name as well.
Using OTRS
Logging In
To log in to OTRS, navigate to https://otrs.fastlizard4.org in your browser and enter your username and password. Simple, right? Just remember that if this is your first time logging in to change your temporary password to a new one! Remember to use a strong password.
The Dashboard
The first thing you'll see after logging in is the dashboard. The three most important things here are the lists "New Tickets" and "Open Tickets / Need to be answered". New Tickets is a list of new tickets that no one has yet looked at - that is, new emails from customers. Open Tickets is a list of tickets that someone has already claimed or an agent has either opened him or herself or has already responded to, but the customer replied. Usually, these tickets are locked to the agent that was handling them, and to filter the list to ones locked to you, select the "My locked tickets" filter. We'll talk more about ticket ownership and locking later. But, for now, know that when you click on a ticket in this list, you'll be directed to the ticket Zoom page.
There are also some buttons at the top of the screen you should be aware of:
- The Dashboard button returns you to the dashboard.
- The Customers button allows you to search the list of customers and tickets that belong to them
- The Tickets button allows you to go through a list of all opened and closed tickets, as well open new tickets.
- The Statistics button shows, well, statistics.
- The magnifying glass opens up an advanced search window, but...
- The text box labelled "Ticket Number" allows you to quickly search for a ticket by entering its ticket number (which looks like "2014020442000018"), or by simple fulltext search.
- The dropdown box to the left of that (which starts out saying just "-") is a list of saved searches, including one called "last-search" which repeats whatever search you've just performed.
- Clicking your name next to "You are logged in as" will open up your user preferences
- And the little power button icon (
) will log you out of OTRS.
Due to the nature of the information handled by OTRS, which is strictly confidential, please never use OTRS on a public computer, and always log out of OTRS or lock your entire computer when it is unattended.
User preferences
The user preferences screen contains some important settings you should look at before starting to use OTRS.
You will want to change your password, of course, after logging in for the firs time, to something that's not the default temporary password
Under "Email Settings", you can configure when the system will automatically email you - for example, if a new ticket is opened in one of your queues, or if a customer replies to a ticket you're the respondent on. In either case, you'll also need to define your queues under the "My Queues" header - control-click to highlight the queues you want to watch, then click Update.
Finally, if you are going to be away from your duties for a while, activate Out Of Office Time so other agents know that you won't be available.
Handling tickets
To handle a ticket, simply select it from one of the lists on the Dashboard. The first thing you'll see is:
Ticket Zoom
The ticket zoom screen is the screen seen when opening a ticket, displaying its contents and information about it. The central part of a ticket is the email thread, a record of emails to and from the customer as well as internal agent notes. When a ticket is "locked", only the owner (indicated in the sidebar to the right) can send emails to the customer, though any agent may add a note to the ticket. In addition, when a customer replies to a closed ticket, it's automatically reopened and locked to the owner.
In the thread listing, emails from the customer to OTRS are white and have an icon that looks like [ ] <-. Emails from OTRS to the customer are green in the list and have an icon that looks like [ ]->. Finally, internal notes that are not seen by the customer are red in the list and have an icon that simply looks like [ ]. Selecting an item from the thread list shows the complete message in the bottom pane.
We will cover some basic ticket operations here.
Linking tickets
It's possible to link two tickets together so they show up under each other's "Linked Objects" section. To do this, click the Link button near the top of the page and supply the ticket number of the ticket to be linked to. The only effects of this functionality are cosmetic.
Changing owner
Click the "Owner" button to change the owner of the ticket.
Adding notes
To add an internal note to the ticket, click the Note button. Note that notes cannot be seen by customers, only by OTRS agents.
Merging and Splitting tickets
If you feel a ticket is a duplicate of another (or continues another ticket when it really should be the same ticket), you can merge the two tickets together so that the various emails and notes of both tickets appear to belong to the same ticket.
Conversely, if you feel that a thread has now diverged to a different topic, you should split the thread into two tickets at the point of divergence.
Unlike linking, this also affects the tickets' presence, in addition to creating the cosmetic link.
Moving tickets
Tickets can be moved to different queues using the "- Move -" dropdown box. This is, for example, if you think that a ticket is off-topic for the queue it landed in and would be more appropriate for another queue (for example, a Minecraft question in the queue for Starbound).
Simply select the destination queue from the dropdown and the ticket will be moved.
Any tickets that are obvious spam should be left unclosed and moved to the Junk queue.
Responding to tickets
For each email-external item in a thread, there is a "- Reply -" dropdown and sometimes a "- Reply All -" dropdown. From these lists, you can select from a variety of templated responses, or simply "empty response" which does not load a template.
Of course, if you choose to send a templated response, you can (and often should) edit the templated reply before sending the message.
When you send a reply, you have the option of closing the ticket, but we'll get to that in the next section.
When sending a reply, you have the option of adding attachments to the email that will be seen by the customer. Please use this feature sparingly. You should also not touch the subject line, unless you have just merged or split the ticket before replying - and even then, you don't need to change the ticket number in the subject, just the text following.
Finally, when sending a reply, you can ignore the work units option, but never change the article type!
Closes and States
At any time, an agent (or if the ticket is locked, the ticket's owner) can close the ticket. Most often, this is done when a reply is sent - in fact, tickets should always be closed once replied to. The ticket will automatically reopen if the customer replies.
Tickets have the following possible states:
- Open - ticket has a new message that has not yet been replied to
- Closed states
- Closed successful - Ticket has been replied to, and agent believes that they have served the customer to the customer's satisfcation
- Closed unsuccessful - Ticket has been replied to, but it's obvious that the customer isn't/won't be satisfied with the resolution.
- Closed - no response needed - This state should only be replied to tickets that have never been replied to, but clearly don't warrant a reply - e.g., they are abusive in nature. This resolution shouldn't be used for obvious spam; obvious spam should instead be left Open and moved to the Junk queue.
- Pending states - When closing a ticket with a pending state, you must select a "pending date" upon which a certain action will be automatically taken (depending on the exact close type):
- Pending reminder - This is probably the most useful of the pending states. When the pending date if hit, a reminder message will be sent to all agents every 24 hours as a reminder that the ticket should be handled now. If the customer replies before the Pending Date has expired, the ticket will be reopened as usual.
- Pending auto close+ - If a customer replies to a ticket in this state, it is reopened as usual. Else, when the pending date hits, the ticket is automatically closed as "closed successful".
- Pending auto close- - Like "pending auto close+", but the ticket is closed as "closed unsuccessful" when the pending date hits.
Any of these states can be chosen on the reply to ticket form, but from the zoom page, if you want to change a ticket state to one of the "closed" states you must click the "Close" button, and to close to one of the "pending" states you must click the "Pending" button. Also, when closing a ticket from the zoom page (as opposed to the ticket reply prompt), you have to enter something for the internal note used to indicate the ticket close - but if the reason for the close is obvious, just type a single period in the text box.
Creating a ticket
Sometimes it's necessary to create a ticket to initiate conversation with a customer. To do this, click the "Ticket" button at the top of the screen, then click "New email ticket". This screen is a lot like the ticket reply screen, but with some important differences. This section assumes that you've read all the above and have basic familiarity with OTRS.
Once you have opened the new ticket screen:
- Select the proper queue for the ticket from the "From queue" dropdown.
- Enter the customer's email address in "To customer user" and "CustomerID".
- Set the "Owner" dropdown box to you
- Enter a descriptive subject line in the "Subject" box
- Optionally select a templated message from the "Text Template" box. Note that these are not the same templates as the "answer" templates used when replying to tickets. To start with a blank screen, simply leave the text template selection at "-".
- Type your message in the "Text" box, or if you're using a template, modify the message as necessary.
- The "Next ticket state" is at your discretion. You shouldn't leave it open though. If you're expecting a response from the user, "pending reminder" might be a good choice, or if this is just a notification and you don't expect the customer to reply, just set it as "closed successful".
- Leave "Priority" at "3 normal"
- Click "Send email"!
After creating a ticket, you will be (by default) taken to the Ticket Zoom page for the newly created ticket, unless you changed the relevant option in your user preferences.
Dealing With Spam (and Ham)
The OTRS mailserver, phazon.fastlizard4.org, like all LizardMail servers, runs a MIMEDefang milter and SpamAssassin. Every message incoming to OTRS is first analyzed for its spam status before being handed over to OTRS.
OTRS will then analyze the X-Spam-Score header left by MIMEDefang and automatically place messages with a score over the threshold (currently 5 points) into the Junk OTRS queue, preventing new ticket email notifications from being sent out (unless, for some reason, you deliberately specified the Junk queue as one of your "monitored" queues in your preferences...). Note that OTRS does not care about the *****SPAM***** prefix placed in the Subject line by MIMEDefang; it only analyzes the X-Spam-Score header.
Messages automatically relegated to the Junk queue are left marked as in the "New" state. This is to give agents a chance to review the Junk queue for good emails ("ham") accidentally marked as spam. Every day, at 00:00 UTC, a script will mark tickets in the Junk queue created more than 24 hours ago as in the "Removed" state, hiding them from normal view (they can still be seen by going to Tickets > Status View, though). Thus, the ~24 hour period before a Junk ticket is marked as "Removed" is the best time to screen for false positives, however, missing the 24 hour window will not mean the loss of the ticket. "Removed" Junk tickets can still be viewed until they are permanently deleted: Every week, on Sundays at 00:00 UTC, a script will automatically permanently delete any Junk ticket marked as "Removed" one month (or more) ago.
If you come across a Junk ticket that's actually ham, move it out of the Junk queue into the correct queue. This will prevent OTRS from taking automatic action on the ticket, unless it's moved back into the Junk queue. If you reply to a falsely Junked ticket, remember to remove the *****SPAM***** prefix added by MIMEDefang from the Subject line of any replies you make against the ticket!
Finally, as with all emails SpamAssassin finds to be spam, MIMEDefang will automatically attach to emails marked as *****SPAM***** a text file, SpamAssassinReport.txt, detailing what caused SpamAssassin to assess the email as spam. You can view the file either by downloading it from OTRS, or by viewing the raw contents of the email by clicking the Plain Format button.
