OTRS 6 - Admin Manual

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
1. Introduction
Trouble Ticket Systems - The Basics
What is a trouble ticket system, and why do you need one?
What is a trouble ticket?
OTRS Help Desk
Basics
Features
Hardware and Software Requirements
Community
Professional Services for OTRS
2. Installation
The Simple Way - Installation of Pre-Built Packages
Installing the RPM on a SUSE Linux server
Installing OTRS on a Red Hat Enterprise Linux or CentOS system
Installing OTRS on a Debian or Ubuntu system
Installation From Source (Linux, Unix)
Using the Web Installer
OTRS on Windows
How to migrate existing Windows installations to Linux
Updating OTRS
Additional Applications
FAQ
3. First Steps
Agent Web Interface
Customer Web Interface
Public Web Interface
First Login
The Web Interface - an Overview
The Dashboard
What is a Queue?
What is the Queue Overview?
User Preferences
4. Administration
The Administration Area of OTRS
Basics
Agents, Groups and Roles
Customer Users and Customers
Queues
Salutations, Signatures, Attachments and Templates
Auto Responses
System Email Addresses
Ticket Notifications
S/MIME
PGP
States
System Configuration
Using Mail Accounts
Filtering Incoming Email Messages
Executing Automated Jobs with the GenericAgent
Administrative Messages
Session Management
System Maintenance
System Log
Communication Log
SQL Queries via the SQL Box
Package Manager
Web Services
Dynamic Fields
Calendars
System Configuration
OTRS config files
Configuring the System Through the Web Interface
Backing Up the System
Backup
Restore
Email Settings
Sending/Receiving Emails
Secure Email with PGP
Secure Email with S/MIME
Using External backends
Customer Data
Customer User Backend
Backends to Authenticate Agents and Customers
Customizing the Customer Self-Registration
Ticket Settings
Ticket States
Ticket Priorities
Ticket Responsibility & Ticket Watching
Date and Time Related Functions
Setting up business hours, holidays and time zones
Automated Unlocking
Customizing the PDF Output
Statistics
Statistics Configuration and Usage
Statistics System Administration
Dynamic Fields
Introduction
Configuration
Generic Interface
Generic Interface Layers
Generic Interface Communication Flow
Web Services
Web Service Graphical Interface
Web Service Command Line Interface
Web Service Configuration
Connectors
The OTRS Daemon
OTRS Daemon Graphical Interface
OTRS Daemon Command Line Interface
5. Customization
Access Control Lists (ACLs)
Introduction
Definition
Examples
Reference
Process Management
Introduction
Example process
Implementing the example
Process configuration reference
Import Ready2Adopt process
Localization of the OTRS Front End
6. Appointment Calendar
Introduction
Features
Usage
Calendar Management
Exporting calendars and/or appointments
Importing calendars and/or appointments
Calendar Overview
Agenda Overview
Management of calendar appointments
Repeating appointments
Notifications
Event-based appointment/calendar notifications
Link tickets to appointments
Managed ticket appointments
Dashboard widget for upcoming appointments
7. Performance Tuning
OTRS
TicketIndexModule
Ticket Search Index
Article Storage (Email, Phone and Internal Articles)
Archiving Tickets
Cache
Database
MySQL
PostgreSQL
Webserver
Pre-established database connections
Preloaded modules - startup.pl
Reload Perl modules when updated on disk
Choosing the Right Strategy
mod_gzip/mod_deflate
A. Additional Resources
B. Configuration Options Reference
CloudService
CloudService → Admin → ModuleRegistration
Core
Core → AppointmentCalendar
Core → AppointmentCalendar → Plugin
Core → AppointmentCalendar → TicketAppointments
Core → Auth → Agent → TwoFactor
Core → Auth → Customer
Core → Auth → Customer → TwoFactor
Core → Autoload
Core → Cache
Core → CommunicationChannel
Core → CommunicationChannel → MIMEBase
Core → CommunicationLog
Core → Crypt → PGP
Core → Crypt → SMIME
Core → DB → Mirror
Core → Draft
Core → DynamicFields → DriverRegistration
Core → DynamicFields → ObjectTypeRegistration
Core → Email
Core → Email → PostMaster
Core → Event → AppointmentCalendar
Core → Event → CustomerCompany
Core → Event → CustomerUser
Core → Event → DynamicField
Core → Event → LinkObject
Core → Event → Package
Core → Event → Queue
Core → Event → Ticket
Core → LinkObject
Core → Log
Core → MailQueue
Core → PDF
Core → Package
Core → PerformanceLog
Core → Permission
Core → ProcessManagement
Core → Queue
Core → ReferenceData
Core → SLA
Core → SOAP
Core → Service
Core → Session
Core → Stats
Core → SupportDataCollector
Core → SystemMaintenance
Core → Ticket
Core → Ticket → ACL
Core → Ticket → DynamicFieldDefault
Core → Ticket → FulltextSearch
Core → Ticket → Permission
Core → Time
Core → Time → Calendar1
Core → Time → Calendar2
Core → Time → Calendar3
Core → Time → Calendar4
Core → Time → Calendar5
Core → Time → Calendar6
Core → Time → Calendar7
Core → Time → Calendar8
Core → Time → Calendar9
Core → WebUserAgent
Daemon
Daemon → Log
Daemon → ModuleRegistration
Daemon → SchedulerCronTaskManager → Task
Daemon → SchedulerGenericAgentTaskManager
Daemon → SchedulerGenericInterfaceTaskManager
Daemon → SchedulerTaskWorker
Frontend → Admin
Frontend → Admin → ModuleRegistration
Frontend → Admin → ModuleRegistration → AdminOverview
Frontend → Admin → ModuleRegistration → Loader
Frontend → Admin → ModuleRegistration → MainMenu
Frontend → Admin → ModuleRegistration → MainMenu → Search
Frontend → Admin → View → CustomerCompany
Frontend → Admin → View → CustomerUser
Frontend → Admin → View → NotificationEvent
Frontend → Admin → View → SelectBox
Frontend → Admin → View → SysConfig
Frontend → Agent
Frontend → Agent → ArticleComposeModule
Frontend → Agent → FrontendNotification
Frontend → Agent → LinkObject
Frontend → Agent → MIMEViewer
Frontend → Agent → ModuleRegistration
Frontend → Agent → ModuleRegistration → Loader
Frontend → Agent → ModuleRegistration → MainMenu
Frontend → Agent → ModuleRegistration → MainMenu → Search
Frontend → Agent → TicketOverview
Frontend → Agent → TicketOverview → MenuModule
Frontend → Agent → ToolBar
Frontend → Agent → View → CustomerInformationCenter
Frontend → Agent → View → CustomerUserAddressBook
Frontend → Agent → View → CustomerUserInformationCenter
Frontend → Agent → View → CustomerUserSearch
Frontend → Agent → View → Dashboard
Frontend → Agent → View → Dashboard → EventsTicketCalendar
Frontend → Agent → View → Dashboard → TicketFilters
Frontend → Agent → View → LinkObject
Frontend → Agent → View → Preferences
Frontend → Agent → View → Stats
Frontend → Agent → View → TicketBounce
Frontend → Agent → View → TicketBulk
Frontend → Agent → View → TicketClose
Frontend → Agent → View → TicketCompose
Frontend → Agent → View → TicketCustomer
Frontend → Agent → View → TicketEmailNew
Frontend → Agent → View → TicketEmailOutbound
Frontend → Agent → View → TicketEmailResend
Frontend → Agent → View → TicketEscalation
Frontend → Agent → View → TicketForward
Frontend → Agent → View → TicketFreeText
Frontend → Agent → View → TicketHistory
Frontend → Agent → View → TicketLocked
Frontend → Agent → View → TicketMerge
Frontend → Agent → View → TicketMove
Frontend → Agent → View → TicketNote
Frontend → Agent → View → TicketOwner
Frontend → Agent → View → TicketPending
Frontend → Agent → View → TicketPhoneInbound
Frontend → Agent → View → TicketPhoneNew
Frontend → Agent → View → TicketPhoneOutbound
Frontend → Agent → View → TicketPrint
Frontend → Agent → View → TicketPriority
Frontend → Agent → View → TicketProcess
Frontend → Agent → View → TicketQueue
Frontend → Agent → View → TicketResponsible
Frontend → Agent → View → TicketSearch
Frontend → Agent → View → TicketService
Frontend → Agent → View → TicketStatus
Frontend → Agent → View → TicketWatch
Frontend → Agent → View → TicketZoom
Frontend → Agent → View → TicketZoom → ArticleAction
Frontend → Agent → View → TicketZoom → MenuModule
Frontend → Base
Frontend → Base → Loader
Frontend → Base → NavBarModule
Frontend → Base → OutputFilter
Frontend → Customer
Frontend → Customer → FrontendNotification
Frontend → Customer → ModuleRegistration
Frontend → Customer → ModuleRegistration → Loader
Frontend → Customer → ModuleRegistration → MainMenu
Frontend → Customer → View → Preferences
Frontend → Customer → View → TicketMessage
Frontend → Customer → View → TicketOverview
Frontend → Customer → View → TicketPrint
Frontend → Customer → View → TicketProcess
Frontend → Customer → View → TicketSearch
Frontend → Customer → View → TicketZoom
Frontend → Public
Frontend → Public → ModuleRegistration
GenericInterface
GenericInterface → ErrorHandling → ModuleRegistration
GenericInterface → Invoker → ModuleRegistration
GenericInterface → Mapping → ModuleRegistration
GenericInterface → Operation
GenericInterface → Operation → ModuleRegistration
GenericInterface → Operation → TicketCreate
GenericInterface → Operation → TicketSearch
GenericInterface → Operation → TicketUpdate
GenericInterface → Transport → ModuleRegistration
C. GNU Free Documentation License
0. PREAMBLE
1. APPLICABILITY AND DEFINITIONS
2. VERBATIM COPYING
3. COPYING IN QUANTITY
4. MODIFICATIONS
5. COMBINING DOCUMENTS
6. COLLECTIONS OF DOCUMENTS
7. AGGREGATION WITH INDEPENDENT WORKS
8. TRANSLATION
9. TERMINATION
10. FUTURE REVISIONS OF THIS LICENSE
How to use this License for your documents

List of Figures

2.1. Welcome screen
2.2. GNU GENERAL PUBLIC LICENSE
2.3. Database Selection
2.4. Database credentials
2.5. Database settings
2.6. Successful database setup
2.7. System settings
2.8. Mail configuration
2.9. Web installer final screen
2.10. Download OTRSCloneDB - screenshot
2.11. Install OTRSCloneDB - screenshot
2.12. Get target database password - screenshot
2.13. Configurate OTRSCloneDB SysConfig 1 - screenshot
2.14. Configurate OTRSCloneDB SysConfig 2 - screenshot
2.15. Run OTRSCloneDB script 1 - screenshot
2.16. Run OTRSCloneDB script 2 - screenshot
2.17. Run OTRSCloneDB script 3 - screenshot
3.1. Login screen of the agent interface
3.2. Login screen of the customer interface
3.3. Public web interface
3.4. Request new password
3.5. Dashboard of the agent interface
3.6. Footer
3.7. Dashboard widgets
3.8. Events Ticket Calendar widget
3.9. Dashboard Settings
3.10. Queue View (Default) for Agents
3.11. Agent Queue View visual alarms
3.12. Agent's personal preferences
3.13. Customer's personal preferences
4.1. OTRS Administration Overview Screen
4.2. Agent Management
4.3. Adding a new agent
4.4. Group management
4.5. Agent <-> group management
4.6. Change the groups an agent belongs to
4.7. Change the agents that belong to a specific group
4.8. Role management
4.9. Adding a new role
4.10. Change the roles associated with an agent
4.11. Change the agents associated with a specific role
4.12. Manage roles-groups relations
4.13. Change group relations for a role
4.14. Change role relations for a group
4.15. Customer User management
4.16. Adding a customer user
4.17. Customer Users-Customers relations management
4.18. Customer Users-Group relations management
4.19. Change Group relations for a Customer User
4.20. Change Customer user relations for a Group
4.21. Customers-Group relations management
4.22. Change Group relations for a Customer User
4.23. Change Customer user relations for a Group
4.24. Queue management
4.25. Adding a new queue
4.26. Salutation management
4.27. Adding a new salutation
4.28. Signatures management
4.29. Adding a new signature
4.30. Attachments management
4.31. Adding a new attachment
4.32. Linking Attachments to Templates
4.33. Change Attachment relations for a Template
4.34. Change Template relations for an Attachment
4.35. Template management
4.36. Adding a template
4.37. Template-Queue relations management
4.38. Change Queue relations for a Template
4.39. Change Template relations for a Queue
4.40. Auto response management
4.41. Adding an auto response
4.42. Queue <-> auto response relations management
4.43. Change auto response relations for a queue
4.44. System email addresses management
4.45. Adding a system email address
4.46. Ticket notification management
4.47. Customizing a notification
4.48. Customizing a notification's recipients
4.49. Customizing notification methods
4.50. S/MIME management
4.51. PGP management
4.52. State management
4.53. Graphical user interface of the system configuration.
4.54. Mail account management
4.55. PostMaster filter management
4.56. Add a PostMaster filter
4.57. Job list for the GenericAgent
4.58. Creating a job for the GenericAgent
4.59. Admin notification screen
4.60. Session management
4.61. Session details
4.62. The system maintenance overview screen with some scheduled periods
4.63. The system maintenance edit screen
4.64. System Log
4.65. Communication Log Overview
4.66. Communication Log Time Range Selection
4.67. Communication Log Account Status
4.68. Communication Log Account Status
4.69. Communication Log Detail View
4.70. Communication Log Priority Filter
4.71. SQL Box
4.72. Package Manager
4.73. Package Manager Update All Installed Packages Button
4.74. Package Manager Update All Installed Packages In Progress Notification
4.75. Package Manager Update All Installed Packages Summary
4.76. The graphical interface for web services
4.77. The dynamic fields overview screen with some dynamic fields
4.78. The calendar management screen with some calendars
4.79. The graphical interface for system configuration
4.80. System configuration deployment
4.81. Adding a mail account
4.82. Changing the Responsibility of a ticket in its zoomed view
4.83. Pop-up dialog to change a ticket's responsibility
4.84. Subscribing to watching a ticket in its zoomed view
4.85. Unsubscribing from watching a ticket in its zoomed view
4.86. Watched tickets view
4.87. Overview of the standard statistics.
4.88. Viewing a specific statistic.
4.89. Adding a new statistic, first step.
4.90. Adding a new statistic, second step.
4.91. Configuring the x-axis of a statistic.
4.92. Configuring the y-axis of a statistic.
4.93. Configuring the data filter of a statistic.
4.94. Configuring the data filter of a statistic.
4.95. Statistics import
4.96. Dynamic fields overview screen.
4.97. Dynamic field Text configuration dialog
4.98. Dynamic field Textarea configuration dialog
4.99. Dynamic field Checkbox configuration dialog
4.100. Dynamic field Dropdown configuration dialog
4.101. Dynamic field Multiselect configuration dialog
4.102. Dynamic field Date configuration dialog
4.103. Dynamic field Date / Time configuration dialog
4.104. Dynamic field overview screen filled with sample data
4.105. Field1 in New Phone Ticket Screen
4.106. Field1 in New Phone Ticket Screen as mandatory
4.107. Several fields in New Phone Ticket Screen as mandatory
4.108. Some deactivated fields in New Phone Ticket Screen as mandatory
4.109. Field1 in Ticket Zoom Screen
4.110. Field1 in Ticket Overview Small Screen
4.111. Field1 in User preferences screen
4.112. The graphical interface layers
4.113. Web services overview
4.114. Web services add
4.115. Web service clone
4.116. Web services export
4.117. Web services import
4.118. Web service history
4.119. Web service delete
4.120. Web service debugger
4.121. Web services change
4.122. Web service provider network transport (HTTP::SOAP)
4.123. Web service provider network transport (HTTP::REST)
4.124. Web service operation
4.125. Web service requester network transport (HTTP::SOAP)
4.126. Web service requester network transport (HTTP::REST)
4.127. Web service invoker
4.128. Web service invoker event
4.129. Web service mapping
4.130. Daemon notification
4.131. Start Daemon
5.1. ACL 100-Example-ACL
5.2. ACL 102-Example-ACL
5.3. ACL 102-Second-Example-ACL
5.4. ACL 103-Third-ACL-Example
5.5. ACL 104-Only-Hardware-Services-for-HW-Queues-ACL
5.6. ACL 105-Disallow-Process-For-CustomerID
5.7. OTRS Admin screen - System Administration
5.8. Create New Process button
5.9. Add new process
5.10. Create New Activity Dialog button
5.11. Add new Activity Dialog
5.12. Edit field details (Article)
5.13. Create New Transition button
5.14. Add new Transition
5.15. Create New Transition Action button
5.16. Add new Transition Action
5.17. Create New Activity button
5.18. Drag first Activity into the canvas
5.19. Drag second Activity into the canvas
5.20. Drag a Transition into the canvas
5.21. Connect Activities using Transitions
5.22. Assign Transition Actions
5.23. Book ordering complete process path
5.24. Import Ready2Adopt Processes widget
6.1. Calendar management overview
6.2. Calendar edit screen
6.3. Color picker in calendar edit screen
6.4. Appointment import in calendar management overview
6.5. Calendar overview screen
6.6. Sidebar in calendar overview screen
6.7. View modes in calendar overview screen
6.8. Weekly view in calendar overview screen
6.9. Monthly view in calendar overview screen
6.10. Navigation controls in calendar overview screen
6.11. Today and Jump buttons in calendar overview screen
6.12. User preferences for calendar overview screen
6.13. Agenda overview screen
6.14. Appointment edit screen
6.15. Appointment display in calendar overview screen
6.16. Appointment tooltip
6.17. Edit screen of a repeating appointment
6.18. Repeating appointments in calendar overview screen
6.19. Edit screen of a repeating child appointment
6.20. Repeating settings of a child appointment
6.21. Notification settings in appointment edit screen
6.22. Calendar/Appointment notification management link
6.23. Calendar/Appointment notification management overview
6.24. Sidebar in calendar/appointment notification overview
6.25. Table in calendar/appointment notification overview
6.26. Event definition for calendar/appointment notifications
6.27. Filter settings in calendar/appointment notifications
6.28. Recipient settings in calendar/appointment notifications
6.29. Notification methods in calendar/appointment notifications
6.30. Notification body in calendar/appointment notifications
6.31. Show in agent preferences option in calendar/appointment notifications
6.32. Ticket link option in appointment edit screen
6.33. Linked appointments table in ticket zoom screen
6.34. Appointment linking from ticket zoom screen
6.35. New appointment link in ticket zoom screen
6.36. Ticket appointments configuration in calendar edit screen
6.37. Ticket appointment rule in calendar edit screen
6.38. Ticket appointment in calendar overview screen
6.39. Edit screen of a ticket appointment
6.40. Today filter in upcoming appointments dashboard widget
6.41. Soon filter in upcoming appointments dashboard widget
A.1. Bugtracking Tool

List of Tables

4.1. Default groups available on a fresh OTRS installation
4.2. Rights associated with OTRS groups
4.3. Additional permission groups
4.4. Events for auto responses
4.5. Function of the different X-OTRS-headers
4.6. The following fields will be added into the system:
A.1. Mailing Lists

List of Examples

4.1. Sort spam mails into a specific queue
4.2. Routing via Procmail Using otrs.Console.pl
4.3. .fetchmailrc
4.4. Example jobs for the filter module Kernel::System::PostMaster::Filter::Match
4.5. Example job for the filter module Kernel::System::PostMaster::Filter::CMD
4.6. Example job for the filter module Kernel::System::PostMaster::Filter::ExternalTicketNumberRecognition
4.7. Configuring a DB customer backend
4.8. Using Company Tickets with a DB Backend
4.9. Configuring an LDAP customer backend
4.10. Using Company tickets with an LDAP backend
4.11. Using more than one customer backend with OTRS
4.12. Authenticate agents against a DB backend
4.13. Authenticate agents against an LDAP backend
4.14. Authenticate Agents using HTTPBasic
4.15. Authenticate Agents against a Radius backend
4.16. Customer user authentication against a DB backend
4.17. Customer user authentication against an LDAP backend
4.18. Customer user authentication with HTTPBasic
4.19. Customer user authentication against a Radius backend
4.20. Default statistics permission group
4.21. Customized statistics permission group
4.22. Activate Field1 in New Phone Ticket Screen.
4.23. Activate Field1 in New Phone Ticket Screen as mandatory.
4.24. Activate several fields in New Phone Ticket Screen.
4.25. Deactivate some fields in New Phone Ticket Screen.
4.26. Activate Field1 in Ticket Zoom Screen.
4.27. Activate Field1 in Ticket Overview Small Screens.
4.28. Activate Field1 in TicketCreate event.
4.29. Activate Field1 in the User preferences.
4.30. Example to start the OTRS Daemon
4.31. Example to list all configured daemons
4.32. Example to a summary of all daemon tasks
5.1. ACL allowing movement into a queue of only those tickets with ticket priority 5.
5.2. ACL allowing movement into a queue of only those tickets with ticket priority 5 stored in the database.
5.3. ACL disabling the closing of tickets in the raw queue, and hiding the close button.
5.4. ACL removing always state closed successful.
5.5. ACL only showing Hardware services for tickets that are created in queues that start with "HW".
5.6. ACL to restrict a Process in the customer frontend using the CustomerID.
5.7. Reference showing all possible important ACL settings.