Documentation OTRS 5 - Admin Manual Build Date: 2015-05-26 OTRS 5 - Admin Manual Copyright © 2003-2015 OTRS AG This work is copyrighted by OTRS AG. You may copy it in whole or in part as long as the copies retain this copyright statement. All trade names are used without the guarantee for their free use and are possibly registered trade marks. All products mentioned in this manual may be trade marks of the respective manufacturer. The source code of this document can be found at github, in the repository doc-admin. Contributions are more than welcome. You can also help translating it to your language at Transifex. Table of Contents Preface........................................................................................................................... xi 1. Introduction ................................................................................................................ 1 1. Trouble Ticket Systems - The Basics .................................................................. 1 1.1. What is a trouble ticket system, and why do you need one? ................... 1 1.2. What is a trouble ticket? ......................................................................... 2 2. OTRS Help Desk ................................................................................................. 2 2.1. Basics ....................................................................................................... 2 2.2. Features ................................................................................................... 2 2.3. Hardware and Software Requirements .................................................... 8 2.4. Community ............................................................................................... 9 2.5. Professional Services for OTRS ................................................................ 9 2. Installation ................................................................................................................ 11 1. The Simple Way - Installation of Pre-Built Packages ......................................... 11 1.1. Installing the RPM on a SUSE Linux server ............................................ 11 1.2. Installing OTRS on a Red Hat Enterprise Linux or CentOS system ......... 13 1.3. Installing OTRS on a Debian or Ubuntu system ..................................... 17 2. Installation From Source (Linux, Unix) .............................................................. 17 3. Using the Web Installer .................................................................................... 22 4. OTRS on Windows ............................................................................................ 27 4.1. How to migrate existing Windows installations to Linux ........................ 27 5. Upgrading OTRS from 4 to 5 ........................................................................... 38 6. Additional Applications ..................................................................................... 45 6.1. FAQ ......................................................................................................... 45 3. First Steps ................................................................................................................ 46 1. Agent Web Interface ........................................................................................ 46 2. Customer Web Interface ................................................................................... 47 3. Public Web Interface ........................................................................................ 47 4. First Login ......................................................................................................... 48 5. The Web Interface - an Overview .................................................................... 49 6. The Dashboard ................................................................................................. 50 7. What is a Queue? ............................................................................................. 56 8. What is the Queue Overview? .......................................................................... 56 9. User Preferences .............................................................................................. 58 4. Administration.......................................................................................................... 60 1. The Administration Area of OTRS ..................................................................... 60 1.1. Basics ..................................................................................................... 60 1.2. Agents, Groups and Roles ...................................................................... 60 1.3. Customers and Customer Groups .......................................................... 67 1.4. Queues ................................................................................................... 69 1.5. Salutations, Signatures, Attachments and Templates ............................ 71 1.6. Auto Responses ..................................................................................... 76 1.7. System Email Addresses ........................................................................ 78 1.8. Ticket Notifications ................................................................................. 79 1.9. S/MIME ................................................................................................... 81 1.10. PGP ....................................................................................................... 82 1.11. States................................................................................................... 82 1.12. SysConfig ............................................................................................. 83 1.13. Using Mail Accounts ............................................................................. 84 1.14. Filtering Incoming Email Messages ...................................................... 84 1.15. Executing Automated Jobs with the GenericAgent ............................... 87 1.16. Administrative Messages ..................................................................... 88 1.17. Session Management ........................................................................... 89 1.18. System Maintenance ............................................................................ 90 1.19. System Log .......................................................................................... 91 1.20. SQL Queries via the SQL Box .............................................................. 92 iii 1.21. Package Manager ................................................................................. 92 1.22. Web Services ....................................................................................... 93 1.23. Dynamic Fields ..................................................................................... 93 2. System Configuration ....................................................................................... 94 2.1. OTRS config files.................................................................................... 94 2.2. Configuring the System Through the Web Interface .............................. 94 3. Backing Up the System .................................................................................... 95 3.1. Backup ................................................................................................... 95 3.2. Restore ................................................................................................... 96 4. Email Settings .................................................................................................. 96 4.1. Sending/Receiving Emails ...................................................................... 96 4.2. Secure Email with PGP ......................................................................... 102 4.3. Secure Email with S/MIME ................................................................... 104 5. Using External backends ................................................................................ 109 5.1. Customer Data ..................................................................................... 109 5.2. Customer User Backend ...................................................................... 109 5.3. Backends to Authenticate Agents and Customers ............................... 116 5.4. Customizing the Customer Self-Registration ........................................ 121 6. Ticket Settings ................................................................................................ 123 6.1. Ticket States ........................................................................................ 123 6.2. Ticket Priorities .................................................................................... 126 6.3. Ticket Responsibility & Ticket Watching ............................................... 126 7. Time Related Functions .................................................................................. 129 7.1. Setting up business hours, holidays and time zones ........................... 129 7.2. Automated Unlocking ........................................................................... 129 8. Customizing the PDF Output .......................................................................... 130 9. Statistics ......................................................................................................... 130 9.1. Statistics Configuration and Usage ...................................................... 131 9.2. Statistics System Administration ......................................................... 136 10. Dynamic Fields ............................................................................................. 137 10.1. Introduction ........................................................................................ 137 10.2. Configuration ...................................................................................... 137 11. Generic Interface .......................................................................................... 153 11.1. Generic Interface Layers .................................................................... 153 11.2. Generic Interface Communication Flow ............................................. 155 11.3. Web Services ..................................................................................... 158 11.4. Web Service Graphical Interface ........................................................ 158 11.5. Web Service Command Line Interface ............................................... 177 11.6. Web Service Configuration ................................................................. 177 11.7. Connectors ......................................................................................... 183 12. The OTRS Daemon ....................................................................................... 199 12.1. OTRS Daemon Graphical Interface .................................................... 201 12.2. OTRS Daemon Command Line Interface ............................................ 201 5. Customization ........................................................................................................ 203 1. Access Control Lists (ACLs) ............................................................................ 203 1.1. Introduction .......................................................................................... 203 1.2. Definition .............................................................................................. 203 1.3. Examples.............................................................................................. 204 1.4. Reference ............................................................................................. 209 2. Process Management ..................................................................................... 212 2.1. Introduction .......................................................................................... 212 2.2. Example process .................................................................................. 213 2.3. Implementing the example .................................................................. 213 2.4. Process configuration reference ........................................................... 238 2.5. Import example process ...................................................................... 259 3. Creating Your Own Themes ............................................................................ 260 4. Localization of the OTRS Front End ................................................................ 260 6. Performance Tuning ............................................................................................... 261 iv 1. OTRS ............................................................................................................... 261 1.1. TicketIndexModule ............................................................................... 261 1.2. SearchIndexModule.............................................................................. 261 1.3. TicketStorageModule ............................................................................ 262 1.4. Archiving Tickets .................................................................................. 263 1.5. Cache ................................................................................................... 264 2. Database ........................................................................................................ 264 2.1. MySQL.................................................................................................. 264 2.2. PostgreSQL........................................................................................... 264 3. Webserver....................................................................................................... 265 3.1. Pre-established database connections ................................................. 265 3.2. Preloaded modules - startup.pl ............................................................ 265 3.3. Reload Perl modules when updated on disk ........................................ 265 3.4. Choosing the Right Strategy ................................................................ 265 3.5. mod_gzip/mod_deflate......................................................................... 265 A. Additional Resources .............................................................................................. 266 B. Configuration Options Reference ........................................................................... 268 1. CloudService ................................................................................................... 268 2. Daemon .......................................................................................................... 269 3. DynamicFields................................................................................................. 280 4. Framework ...................................................................................................... 284 5. GenericInterface ............................................................................................. 398 6. ProcessManagement ....................................................................................... 408 7. Ticket .............................................................................................................. 416 C. GNU Free Documentation License ......................................................................... 605 0. PREAMBLE....................................................................................................... 605 1. APPLICABILITY AND DEFINITIONS ................................................................... 605 2. VERBATIM COPYING ........................................................................................ 606 3. COPYING IN QUANTITY ................................................................................... 606 4. MODIFICATIONS.............................................................................................. 607 5. COMBINING DOCUMENTS ............................................................................... 608 6. COLLECTIONS OF DOCUMENTS ...................................................................... 608 7. AGGREGATION WITH INDEPENDENT WORKS .................................................. 609 8. TRANSLATION .................................................................................................. 609 9. TERMINATION.................................................................................................. 609 10. FUTURE REVISIONS OF THIS LICENSE .......................................................... 609 How to use this License for your documents ..................................................... 610 v List of Figures 2.1. Welcome screen .................................................................................................... 23 2.2. GNU Affero General Public License....................................................................... 23 2.3. Database Selection ............................................................................................... 24 2.4. Database credentials ............................................................................................ 24 2.5. Database settings ................................................................................................. 25 2.6. Successful database setup ................................................................................... 25 2.7. System settings .................................................................................................... 26 2.8. Mail configuration ................................................................................................. 26 2.9. Web installer final screen ..................................................................................... 27 2.10. Download OTRSCloneDB - screenshot ................................................................ 28 2.11. Install OTRSCloneDB - screenshot ...................................................................... 29 2.12. Get target database password - screenshot ....................................................... 31 2.13. Configurate OTRSCloneDB SysConfig 1 - screenshot .......................................... 32 2.14. Configurate OTRSCloneDB SysConfig 2 - screenshot .......................................... 33 2.15. Run OTRSCloneDB script 1 - screenshot ............................................................. 34 2.16. Run OTRSCloneDB script 2 - screenshot ............................................................. 35 2.17. Run OTRSCloneDB script 3 - screenshot ............................................................. 36 3.1. Login screen of the agent interface ..................................................................... 46 3.2. Login screen of the customer interface ................................................................ 47 3.3. Public web interface ............................................................................................. 48 3.4. Request new password ......................................................................................... 49 3.5. Dashboard of the agent interface ......................................................................... 49 3.6. Footer .................................................................................................................... 50 3.7. Dashboard widgets ............................................................................................... 51 3.8. Events Ticket Calendar widget ............................................................................. 53 3.9. Dashboard Settings ............................................................................................... 55 3.10. Queue View (Default) for Agents ........................................................................ 57 3.11. Agent Queue View visual alarms. ....................................................................... 57 3.12. Agent's personal preferences ............................................................................. 58 3.13. Customer's personal preferences ....................................................................... 59 4.1. OTRS Administration Overview Screen ................................................................. 60 4.2. Agent Management ............................................................................................... 61 4.3. Adding a new agent ............................................................................................. 61 4.4. Group management .............................................................................................. 62 4.5. Agent <-> group management ............................................................................ 62 4.6. Change the groups an agent belongs to .............................................................. 63 4.7. Change the agents that belong to a specific group .............................................. 63 4.8. Role management ................................................................................................. 65 4.9. Adding a new role ................................................................................................. 65 4.10. Change the roles associated with an agent ........................................................ 66 4.11. Change the agents associated with a specific role ............................................. 66 4.12. Manage roles-groups relations ............................................................................ 66 4.13. Change group relations for a role ....................................................................... 67 4.14. Change role relations for a group ....................................................................... 67 4.15. Customer management ...................................................................................... 68 4.16. Adding a customer .............................................................................................. 68 4.17. Customer-Group relations management ............................................................. 69 4.18. Change Group relations for a Customer ............................................................. 69 4.19. Change Customer relations for a Group ............................................................. 69 4.20. Queue management ........................................................................................... 70 4.21. Adding a new queue ........................................................................................... 70 4.22. Salutation management ...................................................................................... 71 4.23. Adding a new salutation ..................................................................................... 71 4.24. Signatures management ..................................................................................... 72 4.25. Adding a new signature ...................................................................................... 72 vi 4.26. Attachments management .................................................................................. 73 4.27. Adding a new attachment .................................................................................. 73 4.28. Linking Attachments to Templates ...................................................................... 73 4.29. Change Attachment relations for a Template ..................................................... 74 4.30. Change Template relations for an Attachment ................................................... 74 4.31. Template management ....................................................................................... 75 4.32. Adding a template .............................................................................................. 75 4.33. Template-Queue relations management ............................................................. 75 4.34. Change Queue relations for a Template ............................................................. 76 4.35. Change Template relations for a Queue ............................................................. 76 4.36. Auto response management ............................................................................... 76 4.37. Adding an auto response .................................................................................... 77 4.38. Queue <-> auto response relations management ............................................. 78 4.39. Change auto response relations for a queue ...................................................... 78 4.40. System email addresses management ............................................................... 78 4.41. Adding a system email address.......................................................................... 78 4.42. Ticket notification management ......................................................................... 79 4.43. Customizing a notification .................................................................................. 80 4.44. Customizing a notification's recipients ............................................................... 80 4.45. Customizing notification methods ....................................................................... 81 4.46. S/MIME management .......................................................................................... 82 4.47. PGP management ............................................................................................... 82 4.48. State management ............................................................................................. 82 4.49. The graphical interface for system configuration (SysConfig) ............................ 84 4.50. Mail account management ................................................................................. 84 4.51. PostMaster filter management ............................................................................ 85 4.52. Add a PostMaster filter ....................................................................................... 87 4.53. Job list for the GenericAgent .............................................................................. 87 4.54. Creating a job for the GenericAgent ................................................................... 88 4.55. Admin notification screen ................................................................................... 89 4.56. Session management .......................................................................................... 89 4.57. Session details .................................................................................................... 90 4.58. The system maintenance overview screen with some scheduled periods .......... 90 4.59. The system maintenance edit screen ................................................................. 91 4.60. System Log ......................................................................................................... 91 4.61. SQL Box .............................................................................................................. 92 4.62. Package Manager ................................................................................................ 92 4.63. The graphical interface for web services ............................................................ 93 4.64. The dynamic fields overview screen with some dynamic fields .......................... 93 4.65. The graphical interface for system configuration ............................................... 94 4.66. Adding a mail account ........................................................................................ 97 4.67. Changing the Responsibility of a ticket in its zoomed view .............................. 127 4.68. Pop-up dialog to change a ticket's responsibility .............................................. 127 4.69. Subscribing to watching a ticket in its zoomed view ........................................ 128 4.70. Unsubscribing from watching a ticket in its zoomed view ................................ 128 4.71. Watched tickets view ........................................................................................ 128 4.72. Overview of the standard statistics. ................................................................. 131 4.73. Viewing a specific statistic. ............................................................................... 131 4.74. Adding a new statistic, first step. ..................................................................... 132 4.75. Adding a new statistic, second step. ................................................................ 133 4.76. Configuring the x-axis of a statistic. ................................................................. 134 4.77. Configuring the y-axis of a statistic. ................................................................. 134 4.78. Configuring the data filter of a statistic. ........................................................... 134 4.79. Configuring the data filter of a statistic. ........................................................... 135 4.80. Statistics import ................................................................................................ 135 4.81. Dynamic fields overview screen. ...................................................................... 138 4.82. Dynamic field Text configuration dialog ............................................................ 140 4.83. Dynamic field Textarea configuration dialog ..................................................... 141 vii 4.84. Dynamic field Checkbox configuration dialog ................................................... 141 4.85. Dynamic field Dropdown configuration dialog .................................................. 143 4.86. Dynamic field Multiselect configuration dialog ................................................. 144 4.87. Dynamic field Date configuration dialog ........................................................... 145 4.88. Dynamic field Date / Time configuration dialog ................................................ 146 4.89. Dynamic field overview screen filled with sample data .................................... 146 4.90. Field1 in New Phone Ticket Screen ................................................................... 148 4.91. Field1 in New Phone Ticket Screen as mandatory ............................................ 148 4.92. Several fields in New Phone Ticket Screen as mandatory ................................. 149 4.93. Some deactivated fields in New Phone Ticket Screen as mandatory ................ 150 4.94. Field1 in Ticket Zoom Screen ............................................................................ 151 4.95. Field1 in Ticket Overview Small Screen ............................................................ 151 4.96. Field1 in User preferences screen ..................................................................... 153 4.97. The graphical interface layers .......................................................................... 154 4.98. Web services overview ..................................................................................... 159 4.99. Web services add .............................................................................................. 160 4.100. Web service clone ........................................................................................... 161 4.101. Web services export ....................................................................................... 162 4.102. Web services import ....................................................................................... 163 4.103. Web service history ........................................................................................ 164 4.104. Web service delete......................................................................................... 165 4.105. Web service debugger .................................................................................... 166 4.106. Web services change ...................................................................................... 167 4.107. Web service provider network transport (HTTP::SOAP) ................................... 168 4.108. Web service provider network transport (HTTP::REST) ................................... 170 4.109. Web service operation .................................................................................... 171 4.110. Web service requester network transport (HTTP::SOAP) ................................. 172 4.111. Web service requester network transport (HTTP::REST) ................................. 174 4.112. Web service invoker ........................................................................................ 175 4.113. Web service mapping..................................................................................... 176 4.114. Daemon notification ........................................................................................ 201 4.115. Start Daemon .................................................................................................. 201 5.1. ACL 100-Example-ACL......................................................................................... 205 5.2. ACL 102-Example-ACL......................................................................................... 206 5.3. ACL 102-Second-Example-ACL............................................................................ 207 5.4. ACL 103-Third-ACL-Example ................................................................................ 208 5.5. ACL 104-Only-Hardware-Services-for-HW-Queues-ACL........................................ 208 5.6. ACL 105-Disallow-Process-For-CustomerID .......................................................... 209 5.7. OTRS Admin screen - System Administration ..................................................... 217 5.8. Create New Process button ................................................................................ 217 5.9. Add new process ................................................................................................. 218 5.10. Create New Activity Dialog button .................................................................... 218 5.11. Add new Activity Dialog .................................................................................... 219 5.12. Edit field details (Article) .................................................................................. 219 5.13. Create New Transition button ........................................................................... 222 5.14. Add new Transition ........................................................................................... 222 5.15. Create New Transition Action button ................................................................ 223 5.16. Add new Transition Action ................................................................................ 224 5.17. Create New Activity button ............................................................................... 225 5.18. Drag first Activity into the canvas .................................................................... 226 5.19. Drag second Activity into the canvas ............................................................... 227 5.20. Drag a Transition into the canvas ..................................................................... 227 5.21. Connect Activities using Transitions .................................................................. 228 5.22. Assign Transition Actions .................................................................................. 228 5.23. Book ordering complete process path .............................................................. 230 5.24. Import example process widget ........................................................................ 259 A.1. Bugtracking Tool................................................................................................. 267 viii List of Tables 4.1. Default groups available on a fresh OTRS installation .......................................... 61 4.2. Rights associated with OTRS groups .................................................................... 63 4.3. Additional permission groups ................................................................................ 64 4.4. Events for auto responses .................................................................................... 77 4.5. Function of the different X-OTRS-headers ............................................................. 85 4.6. The following fields will be added into the system: ............................................ 139 A.1. Mailing Lists ........................................................................................................ 266 ix List of Examples 4.1. Sort spam mails into a specific queue ................................................................. 87 4.2. Routing via Procmail Using otrs.Console.pl ...................................................... 98 4.3. .fetchmailrc....................................................................................................... 99 4.4. Example jobs for the filter module Kernel::System::PostMaster::Fil- ter::Match.................................................................................................................. 99 4.5. Example job for the filter module Kernel::System::PostMaster::Filter::CMD ......... 100 4.6. Example job for the filter module Kernel::System::PostMaster::Fil- ter::ExternalTicketNumberRecognition ............................................................... 100 4.7. Configuring a DB customer backend .................................................................. 109 4.8. Using Company Tickets with a DB Backend ....................................................... 112 4.9. Configuring an LDAP customer backend ............................................................. 112 4.10. Using Company tickets with an LDAP backend ................................................. 114 4.11. Using more than one customer backend with OTRS ......................................... 114 4.12. Authenticate agents against a DB backend ...................................................... 116 4.13. Authenticate agents against an LDAP backend ................................................ 117 4.14. Authenticate Agents using HTTPBasic .............................................................. 118 4.15. Authenticate Agents against a Radius backend ................................................ 119 4.16. Customer user authentication against a DB backend ....................................... 119 4.17. Customer user authentication against an LDAP backend ................................. 119 4.18. Customer user authentication with HTTPBasic ................................................. 120 4.19. Customer user authentication against a Radius backend ................................. 120 4.20. Default statistics permission group .................................................................. 133 4.21. Customized statistics permission group ............................................................ 133 4.22. Activate Field1 in New Phone Ticket Screen. .................................................... 147 4.23. Activate Field1 in New Phone Ticket Screen as mandatory. .............................. 148 4.24. Activate several fields in New Phone Ticket Screen. ......................................... 148 4.25. Deactivate some fields in New Phone Ticket Screen. ....................................... 149 4.26. Activate Field1 in Ticket Zoom Screen. ............................................................. 150 4.27. Activate Field1 in Ticket Overview Small Screens. ............................................ 151 4.28. Activate Field1 in TicketCreate event. .............................................................. 152 4.29. Activate Field1 in the User preferences. ........................................................... 152 4.30. Example to start the OTRS Daemon ................................................................. 201 4.31. Example to list all configured daemons ............................................................ 202 4.32. Example to a summary of all daemon tasks .................................................... 202 5.1. ACL allowing movement into a queue of only those tickets with ticket priority 5. ................................................................................................................................ 204 5.2. ACL allowing movement into a queue of only those tickets with ticket priority 5 stored in the database. .............................................................................................. 205 5.3. ACL disabling the closing of tickets in the raw queue, and hiding the close but- ton. ............................................................................................................................. 206 5.4. ACL removing always state closed successful. ................................................... 207 5.5. ACL only showing Hardware services for tickets that are created in queues that start with "HW". ......................................................................................................... 208 5.6. ACL to restrict a Process in the customer frontend using the CustomerID. ......... 209 5.7. Reference showing all possible important ACL settings. ..................................... 210 x