This is a reference for folks configuring (or thinking about configuring) an OTRS Help Desk in-house. OTRS Help Desk is an open-source trouble ticket system. It’s one of the most sophisticated and widely-used technical support systems out there. I’ve helped implement a few help desk systems over the last year, and I’ve been especially impressed with OTRS, especially considering that it’s free!
The documentation and community support for OTRS are equally impressive, but I found a few bits and pieces a little difficult to wrap my head around at first. The official documentation was a good start, and there were some forum discussions that helped. But, I’m a dummy. And as I am wont to do, I started making notes to explain it to myself. I’m in the habit of doing this for two reasons.
First, projects stall out. You work hard on something for a month, you’re just getting into a groove and reaching maximum productivity when you have to stop work on project A and move to project B. Two weeks later, project A is top priority again. You’ve forgotten most of what was at the front of your mind, and now you have to start the learning process all over again. When I make my own notes, that re-ramp goes a lot quicker.
The second reason I make myself notes is turnover. You never know when you’re going to be out sick, find another job, or have to hand a project off to someone else for any number of reasons. There are things about any implementation that are unique to your organization, and having that stuff documented, at least in some form, makes for much smoother transitions.
I’m not officially a trainer, but documentation also helps with training. You don’t have to rely on your own memory for everything, and you can give people homework! (Maybe that’s how you ended up here right now!)
Anyway, I thought these notes might be of use to others trying to set up OTRS for the first time. This will be the first part of a series of posts on configuring OTRS. It will cover some of the high-level concepts about how to organize access rights within OTRS. If you’re planning to implement OTRS, this can help you plan an effective setup and possibly save you some refactoring of your environment later.
Scope of Application
(The “scope of application” section is a convention I’ll be using regularly. Software gets updated, blog posts go out of date, etc. It can be really useful to know what the original author was working with to figure out if any of it applies to you–and how directly.)
The descriptions and screenshots in this document were generated for and from a Linux system with the following setup:
- CentOS 6.4 or 6.5 | OpenSuSE 13.1
- MySQL 5.1.71
- OTRS 3.3.3 | OTRS 3.3.4
- Apache 2.2.15 (Unix)
- Viewed with Firefox 26
You might want to set up your own installation (they have it for Windows and Mac, too) to follow along. But I’ll provide plenty of screenshots.
This is the first of three posts. If you like what you read here, you might want to check out Part 2 and Part 3.
Queues, Groups, and Roles
If you’re going to use OTRS, you will benefit from a detailed understanding of Queues, Groups, and Roles—and the relationships between them. Read the OTRS documentation on these subjects, and accept that mastery of these concepts will require some practice. I provide a brief description of each item here, and I follow that with a concrete example.
(Settle in for it. This is a long one!)
(Also, just so you know, I’m going to be weird about capitalizing the terms Queue, Group, and Role. It just helps me keep everything straight.)
When a customer reports an issue or incident, whether through the web interface or by sending an email directly into the system, this is a “Ticket.” We can organize or collect tickets into user-defined Queues. It might be helpful to think of Queues as issue categories or problem types.
In a shop of any size, it’s not hard to imagine a period of a few hours where tickets come in for a variety of issues: hardware, software, network, phone, etc. By collecting tickets into common buckets that reflect the type of problem at hand, we can target our focus and our efforts. It can also help managers make faster and more accurate decisions about how to prioritize the current workload.
You define what Queues and Sub-queues you want to use. OTRS provides a few out of the box, but they are non-descript. By default, tickets flow into a single Queue, and you can reassign them from there based on the content of the ticket. As you gain a better understanding of the system features, you can start filtering tickets to specific Queues or use multiple incoming email addresses (or aliases) to direct tickets to the desired Queue.
When you create a Queue, you will need to associate it with a Group. Group rights are how you define Queue access. Before you create your Queues, you’ll need to create some Groups.
Tip: It would probably be a good idea to define your Queues and Groups on paper first. In my mind, you would want to define Queues first, and then you can define the Groups that should have access to those Queues. Once these are defined, in OTRS you would create the Groups first, and then the Queues. You can experiment with creating the Groups and Roles within OTRS as you define them, but keep in mind that you cannot delete them from the system. You will avoid clutter by defining Queues, Groups, and Roles before you start creating them in the system.
Groups in OTRS should be thought of as collections of access rights. To some extent, you can also think of Groups as collections of Queues, though that limits their scope a bit. There are a few modules, including Stats (reporting) and FAQs, that don’t have Queues associated with them by default, but you still define access rights to their functionality through Groups. For this reason, you should not get in the habit of thinking of Groups exclusively as collections of Queues.
Groups define the following rights:
- MOVE_INTO (move tickets into these queues)
- CREATE (create tickets/articles in these queues)
- NOTE (add notes to tickets in these queues)
- OWNER (change the owner of tickets in these queues)
- PRIORITY (change the priority of tickets in these queues)
- RW (read-write access to tickets/modules in this group)
- RO (read-only access to tickets/modules in this group)
You can see that the first five rights apply primarily to Queues, while the last two (RW/RO) are more closely related to modules like Stats and FAQ. Nevertheless, there is some overlap. Develop a bias toward thinking of Groups as collections of rights rather than collections of Queues.
When you associate a Queue with a Group, you are granting all the access rights defined by that Group to the selected Queue. (Don’t worry, there will be pictures soon.)
Now that you have some Queues that allow you to classify tickets, and you have Groups that define access rights to those Queues, you need to find a way to grant those rights to an Agent. There are two ways to do this. The first is to assign Agents directly to Groups. This is not generally regarded as best practice for large implementations. Instead, I recommend setting up Roles. Using Roles instead of assigning Group rights directly to Agents offers the following advantages:
- You only have to configure the rights once, for the role.
- You can associate multiple Agents with a Role in one swoop.
- When Agents assume or discard a Role, you can add/remove rights by disassociating them from the Role—no need to update multiple rights on multiple groups.
- When the responsibilities of a Role change, you only have to update them once for everyone associated with that Role.
The trade-off of using Roles is it requires a little more work up front. You have to define your Groups and Roles clearly to make sure that Agents get the rights they need. In the long-run, though, it will simplify administration.
Concrete Example of Queues, Groups, and Roles
Our Company and Where We’re Starting From
You work for the IT Department of Anonymous Business Company (ABC), a company of about 1500 employees with branches spread throughout the United States. You have a central IT location, so the vast majority of your support is handled remotely.
You have been using a home-brew Help Desk system for several years. Now that the company has grown, you’ve decided to implement OTRS to add functionality and features to your Help Desk that won’t require an investment in custom software development. You know that OTRS is powerful software that will bring you a lot of advantages, but it’s up to you to get the configuration right so this will be a smooth transition.
You’ve read through the OTRS documentation and understand that creating the right Queues, Groups, and Roles are vital to setting up an efficient workflow. Luckily, you’ve been in business for quite some time already. You’ve got a pretty effective workflow. There’s room for improvement, but you don’t have to start from scratch.
What OTRS calls Queues, you’ve called Categories—or work categories. OTRS is going to upgrade how you work with those categories, but the basic concept is the same. What they call Roles, you’ve also called Roles—Tier 1, Tier 2, Tier 3, Manager. What they call Groups, though, is new to you. You’re not quite sure where those fit. You know Groups define system access rights, but your home-brew system only had one set of rights. If you were in the system, you could do anything. Access and rights were enforced through training team members on what tickets they were responsible for and which ones they shouldn’t touch.
Let’s look at our current workflow. Before we start trying to upgrade or make changes, we’ll just try to match what we’ve got now as closely as possible.
Existing Workflow (Simplified)
The above example is, admittedly, oversimplified. To design your Queues, Groups, and Roles, you’ll need to have an intimate understanding of your entire process. For example, which Roles are allowed to review requests? When they assign it to a category, how do they determine which category it should be? When they assign it to an individual, how do they determine which individual should work the ticket? What does it mean to “work a ticket” or to “QA the work”?
I don’t attempt to answer those questions. Instead, I offer a more abstract example that doesn’t distract from primary concepts by going too deep into details that may or may not match your workflow. The above pattern should match that of any IT department that has committed to or is working toward industry best practices.
Matching the Existing Workflow
Based on the workflow above, we know we’re going to need OTRS equivalents for the following:
- A web interface for entering requests
- A way to label tickets as “Unassigned”
- An account with permission to view and assign tickets
- An account with permission to work a ticket
- Multiple ticket categories and a way to label a ticket with its category
- A way to label tickets as “In-Progress”
- A way to label tickets as “QA”
- An account with permission to view, update, and either reassign or close tickets labeled as QA
First, let’s just see if there’s a direct translation in OTRS for each of these:
|Way to label tickets “Unassigned”
|Account w/permission to view and assign
||Group/Role combinations to define and grant rights
|Account w/permission to work a ticket
|Multiple ticket categories and a way to label a ticket with its category
|A way to label tickets as “In-Progress”
||Combination of user- and system-defined ticket states
|A way to label tickets as “QA”
||Multiple solutions. No one-to-one match
|Account with permission to view, update, close QA tickets
||Group/Role combinations to define and grant rights
Not everything has a one-to-one match, but we’re pretty close. So let’s go ahead and try to create this workflow in OTRS.
Defining Queue-Group-Role Relationships
Before we create any Queues, we should really have some Groups and Roles in place. Earlier we identified Tier 1, Tier 2, Tier 3, and Manager as Roles in our current environment. They represent different scopes and levels of responsibility. But tickets go into Queues, and Roles can’t access Queues directly. They have to access them through associations with Groups… Ugh!
Before we try to tackle that, let’s see what the Queue-to-Role relationships are.
Consider the following relationship diagram, where the boxes are the Queues, and the figures with the checkmarks by their heads are the Roles:
This may or may not match your organization’s relationships exactly, but you can see that those with a Manager Role have responsibility for 6 Queues where those with a Tier 1 Role only have responsibility for (and therefore access to) only 3 Queues. You probably have a similar hierarchical model, whether formal or informal.
- Standard requests can be fielded by any member of the team.
- Network outages will be assigned to Tier 2 and above because these folks have enough training and familiarity with the environment to respond with the appropriate urgency.
- Only Tier 3 and above can respond to VIP requests, as VIPs require distinct treatment.
- Finally, only Managers have permission to approve and execute large hardware expenses.
Think about how your department handles different categories of problems with varying degrees of severity. You can probably come up with a diagram a lot like the one above to similarly define the Roles and Queues you’ll use in your organization.
The scope of responsibilities for each Role ends up looking something like this, growing with each additional Role:
Okay. We have an idea of a few Queues we want to use, and we have some idea of what Roles we’ll need and what kind of access they should be granted. How do Groups fit in?
To get a better sense of how using Roles can make your life easier, let’s take a look at the Agent Management tools in OTRS.
For a moment, let’s assume you don’t trust me. (And why should you?) You don’t buy this whole notion of using Roles to intermediate between Agents and Groups. OTRS provides a way to assign Agents directly to Groups, so let’s just do that.
When you manage Agent-Group relationships, you can either select a single Agent and make multiple Group assignments or select a single Group and make multiple Agent assignments.
Let’s start by selecting a Group.
Notice that this is actually pretty accessible. If you want to give all users MOVE_INTO rights to Queues in this Group, you just click the top checkbox in that column, and everyone gets those rights.
There are a couple limitations, though. You can only set rights for one agent or one group at a time. There’s no way, for example, to give Manny Manager and Tami Threetier Tier 1, Tier 2, and Tier 3 rights at the same time. You’d have to either give Manny rights to the three groups, then give Tami rights to the same three groups, or you’d have to give them both rights to Tier 1, then to Tier 2, then to Tier 3. Now imagine that you have half a dozen Groups and fifty Agents.
Actually, let’s look at an example with a larger user group. Here would be the Tier 1 Group access settings in a system with 16 Agents (including root):
Simple. Everyone who is an Agent is at least a Tier 1. Just click that top check box on each column (7 clicks). But say that only five of my folks are Tier 3. To set my Tier 3 rights to the below costs 35 clicks:
And now imagine that you want Tier 2 people to have MOVE_INTO rights to Queues in the Tier 3 Group. You don’t want them working those tickets, but you want to give them a chance to direct them to the right place. Clickety-click-click.
Three weeks later, tmoore is relieved of Tier 3 duties. The poor fella just wasn’t ready. That’s 7 more clicks to take those rights away. Two months after that, four Tier 2 folks get promoted to Tier 3—28 more clicks. The relationship looks a little like this:
We have to manage 16 individual relationships with the Tier 1 Group. That’s a lot of maintenance.
With Roles we simplify administration and cut down on potential and actual errors by reducing the number of clicks. The initial setup will seem just as labor-intensive, but if you design the relationships well, it will make long-term maintenance exponentially easier.
Let’s look at Queue-to-Role relationship with the Groups intervening (Manager Role and Group omitted for the sake of space):
Instead of having to manage 16 relationships with the Tier 1 Group, we only have to manage 4 (including the Manager Role—not pictured).
I know what you’re thinking. There are still 16 relationships to manage. How is throwing Roles into the mix making that easier? Don’t we have to manage 20 relationships now? Well, technically yes. But before you throw out the baby with the bathwater, let’s look at the Admin interface in OTRS again.
Managing Role-Group relationships is exactly the same as managing Agent-Group relationships. You can manage the relationship between a single Role and multiple Groups or between a single Group and multiple Roles.
In our case, it makes more sense to manage a single Role with multiple Groups. For the sake of this example, we have Groups and Roles for Tier 1, Tier 2, Tier 3, and Manager. Look at the settings below in order:
Tier 1 Role:
Tier 2 Role:
Tier 3 Role:
These assignments should remind you of something…
It’s clear that administering these four relationships instead of 16 will be easier. We’ve cut out 75% of the effort. Well, almost. We still have to manage Agent-Role relationships.
The first thing you’ll notice is that the Agent-Role relationship management interface looks exactly like the other relationship management interfaces:
So what’s the difference? Let’s look at our Tier 3 assignments:
Instead of setting 7 rights per Group for each Agent, we only have to click once per Agent to assign them all the appropriate rights for the Role. By setting up the Role permissions correctly once, we’ve eliminated the need to set them up again for each Agent. And remember how we set up the Tier 3 Role so it includes all the rights to the Tier 2 and Tier 1 Groups? When we manage the Tier 2 Role relationships, if we forget to put a check next to tmoore’s name, he’ll still have all the rights he needs (until a couple weeks from now when he gets demoted again).
Remember the situation we considered before where we determined that folks in the Tier 2 Role should have MOVE_INTO rights on Tier 3 tickets so they can redirect tickets to the proper Queues. Suppose we have 10 Tier 2 people at that time. To change the rights for all 10 people, we only have to click once in the Tier 2 Role.
Easy peasy. Right?
There is a trade-off. It’s a minor one, in my opinion, but it’s worth noting. When you make direct Agent-to-Group assignments, you can refine the rights to a much higher degree. This may offer certain advantages in smaller shops where there aren’t really defined Roles (and you have the administrative slack to edit the access granted to individuals completely willy-nilly). Hopefully it’s clear that in larger organizations, you’d just be asking for trouble trying to administer every individual’s rights to every Group—especially where positions are fluid or turnover is high.
If Groups, Roles, and Queues still seem completely mysterious, I have some exercises designed to walk you through setting up a system to accommodate a sample workflow in Part 2. There’s also a Part 3, if you want to skip Part 2.
Love and kisses,