Documentation OTRS 3.4 - Admin Manual

701 Pages·2014·9.18 MB·English

Documentation
OTRS 3.4 - Admin Manual
Build Date:
2013-04-30
OTRS 3.4 - Admin Manual
Copyright © 2003-2013 OTRS AG
René Bakker, Stefan Bedorf, Michiel Beijen, Shawn Beasley, Hauke Böttcher, Jens Bothe, Udo Bretz, Martin Edenhofer,
Carlos Javier García, Martin Gruner, Manuel Hecht, Christopher Kuhn, André Mindermann, Marc Nilius, Elva María
Novoa, Henning Oschwald, Martha Elia Pascual, Thomas Raith, Carlos Fernando Rodríguez, Stefan Rother, Burchard
Steinbild, Michael Thiessmeier, Daniel Zamorano.
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.
The source code of this document can be found at github, in the repository doc-admin.
UNIX is a registered trademark of X/Open Company Limited. Linux is a registered trademark of Linus Torvalds.
MS-DOS, Windows, Windows 95, Windows 98, Windows NT, Windows 2000, Windows XP, Windows 2003, Windows
Vista and Windows 7 are registered trademarks of Microsoft Corporation. Other trademarks and registered trademarks
are: SUSE and YaST of SUSE Linux GmbH, Red Hat and Fedora are registered trademarks of Red Hat, Inc. Mandrake is
a registered trademark of MandrakeSoft, SA. Debian is a registered trademark of Software in the Public Interest, Inc.
MySQL and the MySQL Logo are registered trademarks of Oracle Corporation and/or its affiliates.
All trade names are used without the guarantee for their free use and are possibly registered trade marks.
OTRS AG essentially follows the notations of the manufacturers. Other products mentioned in this manual may be
trademarks of the respective manufacturer.
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 ......................................................... 11
2.4. Community .................................................................................................. 12
2.5. Professional Services for OTRS ................................................................... 12
2. Installation ..................................................................................................................... 13
1. The simple way - Installation of pre-built packages .............................................. 13
1.1. Installing the RPM on a SUSE Linux server ................................................. 13
1.2. Installing OTRS on a Red Hat Enterprise Linux or CentOS system .............. 15
1.3. Installing OTRS on a Debian or Ubuntu system .......................................... 20
1.4. Installing OTRS on Microsoft Windows systems .......................................... 20
2. Installation from source (Linux, Unix) .................................................................... 22
2.1. Preparing the installation from source ........................................................ 22
2.2. Installation of Perl modules ........................................................................ 23
2.3. Configuring the Apache web server ............................................................ 24
2.4. Configuring the database ........................................................................... 25
2.5. Setting up the cron jobs for OTRS .............................................................. 26
2.6. OTRS Scheduler Service ............................................................................. 29
3. Using the web installer ......................................................................................... 29
4. Upgrading the OTRS Framework ........................................................................... 33
5. Upgrading Windows Installer ................................................................................. 38
5.1. Performing patch level upgrades on Windows ............................................ 38
5.2. Performing minor level upgrades on Windows ............................................ 38
6. Additional applications .......................................................................................... 38
6.1. FAQ .............................................................................................................. 38
3. First steps ...................................................................................................................... 39
1. Agent web interface .............................................................................................. 39
2. Customer web interface ........................................................................................ 39
3. Public web interface .............................................................................................. 40
4. First login ............................................................................................................... 41
5. The web interface - an overview ........................................................................... 41
6. The Dashboard ...................................................................................................... 43
7. What is a queue? .................................................................................................. 47
8. What is the queue overview? ................................................................................ 48
9. User preferences ................................................................................................... 48
4. Administration ............................................................................................................... 51
1. The ADMIN area of OTRS ...................................................................................... 51
1.1. Basics .......................................................................................................... 51
1.2. Agents, Groups and Roles ........................................................................... 51
1.3. Customers and Customer Groups ............................................................... 60
1.4. Queues ........................................................................................................ 63
1.5. Salutations, signatures, attachments and templates .................................. 65
1.6. Auto responses ........................................................................................... 76
1.7. Email addresses .......................................................................................... 78
1.8. Notifications ................................................................................................ 79
iii
1.9. SMIME .......................................................................................................... 81
1.10. PGP ............................................................................................................ 82
1.11. States ........................................................................................................ 83
1.12. SysConfig .................................................................................................. 84
1.13. Using mail accounts .................................................................................. 84
1.14. Filtering incoming email messages ........................................................... 85
1.15. Executing automated jobs with the GenericAgent .................................... 88
1.16. Admin email .............................................................................................. 90
1.17. Session management ................................................................................ 90
1.18. System Log ............................................................................................... 91
1.19. SQL queries via the SQL box .................................................................... 92
1.20. Package Manager ...................................................................................... 93
1.21. Web Services ............................................................................................. 93
1.22. Dynamic Fields .......................................................................................... 94
2. System Configuration ............................................................................................ 95
2.1. OTRS config files ......................................................................................... 95
2.2. Configuring the system through the web interface .................................... 96
3. Backing up the system .......................................................................................... 97
3.1. Backup ........................................................................................................ 97
3.2. Restore ........................................................................................................ 97
4. Email settings ........................................................................................................ 98
4.1. Sending/Receiving emails ........................................................................... 98
4.2. Secure email with PGP .............................................................................. 103
4.3. Secure email with S/MIME ......................................................................... 106
5. Using external backends ..................................................................................... 109
5.1. Customer data .......................................................................................... 109
5.2. Customer user backend ............................................................................ 109
5.3. Backends to authenticate Agents and Customers .................................... 117
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 .................................................... 127
7. Time related functions ......................................................................................... 129
7.1. Setting up business hours, holidays and time zones ................................ 129
7.2. Automated Unlocking ................................................................................ 130
8. Customizing the PDF output ................................................................................ 131
9. Stats module ....................................................................................................... 131
9.1. Handling of the module by the agent ....................................................... 131
9.2. Administration of the stats module by the OTRS administrator ................ 141
9.3. Administration of the stats module by the system administrator .............. 141
10. Dynamic Fields .................................................................................................. 143
10.1. Introduction ............................................................................................. 143
10.2. Configuration ........................................................................................... 144
11. Generic Interface ............................................................................................... 164
11.1. Generic Interface Layers ......................................................................... 164
11.2. Generic Interface Communication Flow .................................................. 166
11.3. Web Services ........................................................................................... 169
11.4. Web Service Graphical Interface ............................................................. 169
11.5. Web Service Command Line Interface .................................................... 189
11.6. Web Service Configuration ...................................................................... 191
11.7. Connectors .............................................................................................. 198
12. OTRS Scheduler ................................................................................................. 214
12.1. Scheduler Graphical Interface ................................................................. 215
iv
12.2. Scheduler Command Line Interface ........................................................ 216
5. Customization .............................................................................................................. 221
1. Access Control Lists (ACLs) ................................................................................. 221
1.1. Introduction ............................................................................................... 221
1.2. Definition ................................................................................................... 221
1.3. Examples ................................................................................................... 222
1.4. Reference .................................................................................................. 226
2. Process Management ........................................................................................... 230
2.1. Introduction ............................................................................................... 230
2.2. Example process ....................................................................................... 230
2.3. Implementing the example ....................................................................... 230
2.4. Process configuration reference ................................................................ 256
3. Creating your own themes .................................................................................. 278
4. Localization of the OTRS frontend ....................................................................... 279
6. Performance Tuning ..................................................................................................... 280
1. OTRS .................................................................................................................... 280
1.1. TicketIndexModule ..................................................................................... 280
1.2. TicketStorageModule ................................................................................. 280
1.3. Archiving Tickets ....................................................................................... 281
2. Database .............................................................................................................. 281
2.1. MySQL ....................................................................................................... 282
2.2. PostgreSQL ................................................................................................ 282
3. Webserver ............................................................................................................ 282
3.1. Pre-established database connections ...................................................... 282
3.2. Preloaded modules - startup.pl ................................................................. 282
3.3. Reload Perl modules when updated on disk ............................................. 282
3.4. Choosing the Right Strategy ..................................................................... 282
3.5. mod_gzip/mod_deflate .............................................................................. 283
A. Additional Resources ................................................................................................... 284
1. Website OTRS Group ........................................................................................... 284
2. Mailing lists .......................................................................................................... 284
3. User Forums ........................................................................................................ 284
4. Bug tracking ........................................................................................................ 284
5. Commercial Support ............................................................................................ 285
B. Configuration Options Reference ................................................................................ 286
1. DynamicFields ...................................................................................................... 286
1.1. DynamicFields::Driver::Registration ........................................................... 286
1.2. DynamicFields::ObjectType::Registration ................................................... 287
1.3. Frontend::Admin::ModuleRegistration ........................................................ 288
1.4. Frontend::Agent::Preferences .................................................................... 291
2. Framework ........................................................................................................... 291
2.1. Core ........................................................................................................... 291
2.2. Core::Cache ............................................................................................... 300
2.3. Core::CustomerCompany .......................................................................... 301
2.4. Core::CustomerUser .................................................................................. 301
2.5. Core::LinkObject ........................................................................................ 301
2.6. Core::Log ................................................................................................... 302
2.7. Core::MIME-Viewer .................................................................................... 304
2.8. Core::MirrorDB ........................................................................................... 305
2.9. Core::PDF .................................................................................................. 305
2.10. Core::Package .......................................................................................... 308
2.11. Core::PerformanceLog ............................................................................. 310
2.12. Core::ReferenceData ............................................................................... 311
2.13. Core::SOAP .............................................................................................. 311
v
2.14. Core::Sendmail ........................................................................................ 312
2.15. Core::Session ........................................................................................... 314
2.16. Core::SpellChecker .................................................................................. 318
2.17. Core::Stats ............................................................................................... 319
2.18. Core::Stats::Graph ................................................................................... 320
2.19. Core::Time ............................................................................................... 324
2.20. Core::Time::Calendar1 ............................................................................. 327
2.21. Core::Time::Calendar2 ............................................................................. 330
2.22. Core::Time::Calendar3 ............................................................................. 332
2.23. Core::Time::Calendar4 ............................................................................. 335
2.24. Core::Time::Calendar5 ............................................................................. 337
2.25. Core::Time::Calendar6 ............................................................................. 340
2.26. Core::Time::Calendar7 ............................................................................. 342
2.27. Core::Time::Calendar8 ............................................................................. 345
2.28. Core::Time::Calendar9 ............................................................................. 347
2.29. Core::Web ................................................................................................ 350
2.30. Core::WebUserAgent ............................................................................... 362
2.31. Crypt::PGP ............................................................................................... 362
2.32. Crypt::SMIME ........................................................................................... 364
2.33. CustomerInformationCenter .................................................................... 366
2.34. Frontend::Admin ...................................................................................... 366
2.35. Frontend::Admin::AdminCustomerUser ................................................... 367
2.36. Frontend::Admin::ModuleRegistration ...................................................... 367
2.37. Frontend::Agent ....................................................................................... 378
2.38. Frontend::Agent::Dashboard .................................................................... 385
2.39. Frontend::Agent::LinkObject .................................................................... 389
2.40. Frontend::Agent::ModuleMetaHead ......................................................... 389
2.41. Frontend::Agent::ModuleNotify ................................................................ 389
2.42. Frontend::Agent::ModuleRegistration ...................................................... 391
2.43. Frontend::Agent::NavBarModule .............................................................. 397
2.44. Frontend::Agent::Preferences .................................................................. 397
2.45. Frontend::Agent::SearchRouter ............................................................... 402
2.46. Frontend::Agent::Stats ............................................................................. 402
2.47. Frontend::Customer ................................................................................. 405
2.48. Frontend::Customer::Auth ....................................................................... 412
2.49. Frontend::Customer::ModuleMetaHead ................................................... 418
2.50. Frontend::Customer::ModuleNotify .......................................................... 418
2.51. Frontend::Customer::ModuleRegistration ................................................ 419
2.52. Frontend::Customer::Preferences ............................................................ 420
2.53. Frontend::Public ....................................................................................... 423
2.54. Frontend::Public::ModuleRegistration ...................................................... 423
3. GenericInterface .................................................................................................. 424
3.1. Core::Ticket ............................................................................................... 424
3.2. Frontend::Admin::ModuleRegistration ........................................................ 424
3.3. GenericInterface::Invoker::ModuleRegistration .......................................... 428
3.4. GenericInterface::Mapping::ModuleRegistration ........................................ 428
3.5. GenericInterface::Operation::ModuleRegistration ...................................... 429
3.6. GenericInterface::Operation::TicketCreate ................................................ 430
3.7. GenericInterface::Operation::TicketSearch ................................................ 431
3.8. GenericInterface::Operation::TicketUpdate ............................................... 432
3.9. GenericInterface::Transport::ModuleRegistration ...................................... 433
3.10. GenericInterface::Webservice .................................................................. 434
4. ProcessManagement ............................................................................................ 435
4.1. Core ........................................................................................................... 435
vi
4.2. Core::Ticket ............................................................................................... 437
4.3. Core::Transition ......................................................................................... 437
4.4. DynamicFields::Driver::Registration ........................................................... 438
4.5. Frontend::Admin::ModuleRegistration ........................................................ 439
4.6. Frontend::Agent::Dashboard ...................................................................... 442
4.7. Frontend::Agent::ModuleRegistration ........................................................ 442
4.8. Frontend::Agent::NavBarModule ................................................................ 443
4.9. Frontend::Agent::Ticket::MenuModule ....................................................... 443
4.10. Frontend::Agent::Ticket::ViewProcess ...................................................... 444
4.11. Frontend::Agent::Ticket::ViewZoom ......................................................... 444
4.12. Frontend::Customer::ModuleRegistration ................................................ 445
4.13. Frontend::Customer::NavBarModule ........................................................ 446
5. Scheduler ............................................................................................................. 446
5.1. Core ........................................................................................................... 446
5.2. Core::Log ................................................................................................... 447
5.3. Core::Web .................................................................................................. 447
5.4. Frontend::Admin::ModuleRegistration ........................................................ 448
5.5. Frontend::Agent::ModuleNotify .................................................................. 448
6. Ticket ................................................................................................................... 448
6.1. Core ........................................................................................................... 448
6.2. Core::CustomerCompany .......................................................................... 449
6.3. Core::FulltextSearch .................................................................................. 449
6.4. Core::LinkObject ........................................................................................ 451
6.5. Core::PostMaster ....................................................................................... 452
6.6. Core::Stats ................................................................................................. 462
6.7. Core::Ticket ............................................................................................... 463
6.8. Core::TicketACL ......................................................................................... 480
6.9. Core::TicketBulkAction ............................................................................... 485
6.10. Core::TicketDynamicFieldDefault ............................................................. 485
6.11. Core::TicketWatcher ................................................................................ 491
6.12. Frontend::Admin ...................................................................................... 491
6.13. Frontend::Admin::AdminNotificationEvent ............................................... 492
6.14. Frontend::Admin::ModuleRegistration ...................................................... 493
6.15. Frontend::Agent ....................................................................................... 501
6.16. Frontend::Agent::Dashboard .................................................................... 509
6.17. Frontend::Agent::Dashboard::EventsTicketCalendar ............................... 518
6.18. Frontend::Agent::Dashboard::TicketFilters ............................................... 520
6.19. Frontend::Agent::ModuleMetaHead ......................................................... 520
6.20. Frontend::Agent::ModuleNotify ................................................................ 521
6.21. Frontend::Agent::ModuleRegistration ...................................................... 521
6.22. Frontend::Agent::Preferences .................................................................. 534
6.23. Frontend::Agent::SearchRouter ............................................................... 540
6.24. Frontend::Agent::Ticket::ArticleAttachmentModule ................................. 541
6.25. Frontend::Agent::Ticket::ArticleComposeModule ..................................... 541
6.26. Frontend::Agent::Ticket::ArticleViewModule ............................................ 542
6.27. Frontend::Agent::Ticket::ArticleViewModulePre ....................................... 542
6.28. Frontend::Agent::Ticket::MenuModule ..................................................... 543
6.29. Frontend::Agent::Ticket::MenuModulePre ................................................ 550
6.30. Frontend::Agent::Ticket::OverviewMenuModule ...................................... 553
6.31. Frontend::Agent::Ticket::ViewBounce ...................................................... 553
6.32. Frontend::Agent::Ticket::ViewBulk ........................................................... 555
6.33. Frontend::Agent::Ticket::ViewClose ......................................................... 557
6.34. Frontend::Agent::Ticket::ViewCompose ................................................... 564
6.35. Frontend::Agent::Ticket::ViewCustomer ................................................... 567
vii
6.36. Frontend::Agent::Ticket::ViewEmailNew .................................................. 567
6.37. Frontend::Agent::Ticket::ViewEscalation .................................................. 570
6.38. Frontend::Agent::Ticket::ViewForward ..................................................... 572
6.39. Frontend::Agent::Ticket::ViewFreeText ..................................................... 574
6.40. Frontend::Agent::Ticket::ViewHistory ....................................................... 581
6.41. Frontend::Agent::Ticket::ViewLocked ....................................................... 582
6.42. Frontend::Agent::Ticket::ViewMerge ........................................................ 583
6.43. Frontend::Agent::Ticket::ViewMove ......................................................... 585
6.44. Frontend::Agent::Ticket::ViewNote .......................................................... 588
6.45. Frontend::Agent::Ticket::ViewOwner ........................................................ 595
6.46. Frontend::Agent::Ticket::ViewPending ..................................................... 602
6.47. Frontend::Agent::Ticket::ViewPhoneInbound ........................................... 609
6.48. Frontend::Agent::Ticket::ViewPhoneNew ................................................. 612
6.49. Frontend::Agent::Ticket::ViewPhoneOutbound ........................................ 616
6.50. Frontend::Agent::Ticket::ViewPrint ........................................................... 619
6.51. Frontend::Agent::Ticket::ViewPriority ....................................................... 619
6.52. Frontend::Agent::Ticket::ViewQueue ....................................................... 626
6.53. Frontend::Agent::Ticket::ViewResponsible ............................................... 629
6.54. Frontend::Agent::Ticket::ViewSearch ....................................................... 637
6.55. Frontend::Agent::Ticket::ViewService ...................................................... 647
6.56. Frontend::Agent::Ticket::ViewStatus ........................................................ 649
6.57. Frontend::Agent::Ticket::ViewWatch ........................................................ 650
6.58. Frontend::Agent::Ticket::ViewZoom ......................................................... 651
6.59. Frontend::Agent::TicketOverview ............................................................. 654
6.60. Frontend::Agent::ToolBarModule .............................................................. 657
6.61. Frontend::Customer ................................................................................. 662
6.62. Frontend::Customer::ModuleMetaHead ................................................... 665
6.63. Frontend::Customer::ModuleRegistration ................................................ 665
6.64. Frontend::Customer::Preferences ............................................................ 668
6.65. Frontend::Customer::Ticket::ViewNew ..................................................... 669
6.66. Frontend::Customer::Ticket::ViewPrint ..................................................... 674
6.67. Frontend::Customer::Ticket::ViewSearch ................................................. 674
6.68. Frontend::Customer::Ticket::ViewZoom ................................................... 676
6.69. Frontend::Customer::TicketOverview ....................................................... 679
6.70. Frontend::Queue::Preferences ................................................................. 681
6.71. Frontend::SLA::Preferences ...................................................................... 681
6.72. Frontend::Service::Preferences ................................................................ 681
C. Credits ......................................................................................................................... 683
D. GNU Free Documentation License .............................................................................. 685
0. PREAMBLE ............................................................................................................ 685
1. APPLICABILITY AND DEFINITIONS ........................................................................ 685
2. VERBATIM COPYING ............................................................................................. 686
3. COPYING IN QUANTITY ......................................................................................... 686
4. MODIFICATIONS .................................................................................................... 687
5. COMBINING DOCUMENTS .................................................................................... 688
6. COLLECTIONS OF DOCUMENTS ........................................................................... 688
7. AGGREGATION WITH INDEPENDENT WORKS ....................................................... 689
8. TRANSLATION ....................................................................................................... 689
9. TERMINATION ....................................................................................................... 689
10. FUTURE REVISIONS OF THIS LICENSE ................................................................ 689
How to use this License for your documents .......................................................... 689
viii
List of Tables
2.1. Description of several cron job scripts. ...................................................................... 27
4.1. Default groups available on a fresh OTRS installation ............................................... 53
4.2. Rights associated with OTRS Groups ......................................................................... 55
4.3. Additional permission groups ..................................................................................... 56
4.4. Events for Auto answers ............................................................................................ 77
4.5. Function of the different X-OTRS-headers .................................................................. 86
4.6. The following fields will be added into the system: ................................................. 146
4.7. List of init scripts and supported Operating Systems .............................................. 217
A.1. Mailinglists ................................................................................................................ 284
ix
List of Examples
4.1. Sort spam mails into a specific queue ....................................................................... 88
4.2. .fetchmailrc ............................................................................................................... 100
4.3. Example jobs for the filter module Kernel::System::PostMaster::Filter::Match .......... 101
4.4. Example job for the filter module Kernel::System::PostMaster::Filter::CMD .............. 102
4.5. Example job for the filter module
Kernel::System::PostMaster::Filter::ExternalTicketNumberRecognition ............................ 102
4.6. Configuring a DB customer backend ....................................................................... 110
4.7. Using company tickets with a DB backend .............................................................. 112
4.8. Configuring an LDAP customer backend .................................................................. 112
4.9. Using Company tickets with an LDAP backend ........................................................ 114
4.10. Using more than one customer backend with OTRS .............................................. 114
4.11. Authenticate agents against a DB backend ........................................................... 117
4.12. Authenticate agents against an LDAP backend ..................................................... 117
4.13. Authenticate Agents using HTTPBasic ................................................................... 119
4.14. Authenticate Agents against a Radius backend ..................................................... 119
4.15. Customer user authentication against a DB backend ............................................ 119
4.16. Customer user authentication against an LDAP backend ....................................... 120
4.17. Customer user authentication with HTTPBasic ...................................................... 120
4.18. Customer user authentication against a Radius backend ...................................... 121
4.19. Definition of a value series - one element ............................................................. 139
4.20. Definition of a value series - two elements ........................................................... 139
4.21. Activate Field1 in New Phone Ticket Screen. ......................................................... 156
4.22. Activate Field1 in New Phone Ticket Screen as mandatory. ................................... 157
4.23. Activate several fields in New Phone Ticket Screen. .............................................. 158
4.24. Deactivate some fields in New Phone Ticket Screen. ............................................. 159
4.25. Activate Field1 in Ticket Zoom Screen. .................................................................. 160
4.26. Activate Field1 in Ticket Overview Small Screens. ................................................. 161
4.27. Activate Field1 in TicketCreate event. .................................................................... 162
4.28. Activate Field1 in the User preferences. ................................................................ 163
4.29. Example to start the OTRS Scheduler on linux ...................................................... 217
4.30. Example To Start The OTRS Scheduler .................................................................. 217
4.31. Example to force stop the OTRS Scheduler ........................................................... 218
4.32. Example to register the OTRS Scheduler as a Windows Service ............................ 218
4.33. Example to start the OTRS Scheduler on Windows ................................................ 219
4.34. Example to force stop the OTRS Scheduler on Windows ....................................... 219
5.1. ACL allowing movement into a queue of only those tickets with ticket priority 5. .... 222
5.2. ACL allowing movement into a queue of only those tickets with ticket priority 5
stored in the database. ................................................................................................... 223
5.3. ACL disabling the closing of tickets in the raw queue, and hiding the close but-
ton. .................................................................................................................................. 224
5.4. ACL removing always state closed successful. ........................................................ 225
5.5. ACL only showing Hardware services for tickets that are created in queues that
start with "HW". .............................................................................................................. 226
5.6. Reference showing all possible important ACL settings. .......................................... 227
x