OTRS Developer Manual Release 8.0 OTRS AG Jul 08, 2020 Contents 1 Getting Started 3 1.1 Development Environment ..................................... 3 1.1.1 Obtain the Source Code .................................. 3 1.1.2 Useful Tools ......................................... 3 1.1.3 Linking Expansion Modules ................................ 4 1.2 Architecture Overview ........................................ 4 1.2.1 Directories .......................................... 7 1.2.2 Files ............................................. 7 1.2.3 Core Modules ........................................ 7 1.2.4 Front End Handle ...................................... 8 1.2.5 Front End Modules ..................................... 8 1.2.6 CMD Front End ....................................... 8 1.2.7 Generic Interface Modules ................................. 8 1.2.8 Scheduler Task Handler Modules ............................. 9 1.2.9 Database .......................................... 10 2 OTRS Internals - How it Works 11 2.1 Config Mechanism .......................................... 11 2.1.1 Defaults.pm: OTRS Default Configuration ...................... 11 2.1.2 Automatically Generated Configuration Files ....................... 11 2.1.3 XML Configuration Files .................................. 11 2.1.4 Accessing Config Options at Runtime .......................... 20 2.2 Database Mechanism ........................................ 21 2.2.1 SQL ............................................. 21 2.2.2 XML ............................................. 22 2.2.3 Database Drivers ...................................... 25 2.2.4 Supported Databases ................................... 25 2.3 Log Mechanism ........................................... 25 2.3.1 System Log ......................................... 25 2.3.2 Communication Log .................................... 26 2.4 Date and Time ............................................ 28 2.4.1 Introduction ......................................... 28 2.4.2 Creation of a DateTime Object .............................. 29 2.4.3 Time Zones ......................................... 29 2.4.4 Method Summary ...................................... 29 2.4.5 Deprecated Package Kernel::System::Time .................... 30 i 2.5 Skins ................................................. 31 2.5.1 Skin Basics ......................................... 31 2.5.2 How Skins Are Loaded ................................... 31 2.5.3 Creating a New Skin .................................... 33 2.6 The CSS and JavaScript Loader .................................. 34 2.6.1 How it works ........................................ 35 2.6.2 Basic Operation ....................................... 35 2.6.3 Configuring the Loader: JavaScript ............................ 36 2.6.4 Configuring the Loader: CSS ............................... 38 2.7 Templating Mechanism ....................................... 38 2.7.1 Template Commands .................................... 38 2.7.2 Using a Template File ................................... 46 2.8 Creating Your Own Themes .................................... 46 2.9 Localization / Translation Mechanism ............................... 46 2.9.1 Marking Translatable Strings in the Source Files ..................... 47 2.9.2 Collecting Translatable Strings Into The Translation Database ............. 48 2.9.3 The Translation Process Itself ............................... 49 2.9.4 Using The Translated Data From The Code ....................... 49 3 How to Extend OTRS 51 3.1 Writing A New OTRS Front End Module .............................. 51 3.1.1 What we want to write ................................... 51 3.1.2 Default Config File ..................................... 51 3.1.3 Front End Module ...................................... 53 3.1.4 Core Module ........................................ 54 3.1.5 Template File ........................................ 56 3.1.6 Language File ........................................ 56 3.1.7 Summary .......................................... 57 3.2 Writing A New OTRS Front End Component ........................... 57 3.2.1 The Goal .......................................... 57 3.2.2 Using The Skeleton Command .............................. 57 3.2.3 The Route Configuration .................................. 58 3.2.4 Component Template Code ................................ 59 3.2.5 Component Core Code ................................... 60 3.2.6 Component Style Code .................................. 60 3.2.7 Passing Parameters to the Route Component ...................... 60 3.2.8 Component Folders .................................... 61 3.2.9 Packaging Additional Vendor Modules .......................... 62 3.3 Using the power of the OTRS module layers ........................... 64 3.3.1 Agent Authentication Module ............................... 65 3.3.2 Authentication Synchronization Module .......................... 68 3.3.3 Customer Authentication Module ............................. 70 3.3.4 Customer User Preferences Module ........................... 73 3.3.5 Queue Preferences Module ................................ 77 3.3.6 Service Preferences Module ................................ 79 3.3.7 SLA Preferences Module ................................. 82 3.3.8 Log Module ......................................... 85 3.3.9 Output Filter ......................................... 88 3.3.10 Stats Module ........................................ 89 3.3.11 Ticket Number Generator Modules ............................ 108 3.3.12 Ticket Event Module .................................... 109 3.3.13 Dashboard Module ..................................... 111 3.3.14 Notification Module ..................................... 115 3.3.15 Ticket Menu Module .................................... 117 ii 3.3.16 Root Application Module Layer .............................. 120 3.3.17 Network Transport ..................................... 121 3.3.18 Mapping ........................................... 126 3.3.19 Invoker ............................................ 131 3.3.20 Operation .......................................... 135 3.3.21 OTRS Daemon ....................................... 146 3.3.22 OTRS Scheduler ...................................... 150 3.3.23 Overview .......................................... 152 3.3.24 Dynamic Fields Framework ................................ 153 3.3.25 Dynamic Field Interaction With Front End Modules ................... 158 3.3.26 How To Extend The Dynamic Fields ........................... 160 3.3.27 Create New Dynamic Field ................................ 164 3.3.28 Creating a Dynamic Field Functionality Extension .................... 191 3.3.29 Ticket Postmaster Module ................................. 198 3.3.30 Process Management ................................... 200 4 How to Publish Your OTRS Extensions 209 4.1 Package Management ....................................... 209 4.1.1 Package Distribution .................................... 209 4.1.2 Package Commands .................................... 209 4.2 Package Building .......................................... 210 4.2.1 Package Spec File ..................................... 210 4.2.2 Example .sopm ....................................... 215 4.2.3 Package Build ........................................ 216 4.2.4 Package Life Cycle ..................................... 217 4.3 Package Porting ........................................... 217 4.3.1 Front End Messages .................................... 217 4.3.2 Styling Improvements ................................... 218 4.3.3 Encode API Changed ................................... 220 4.3.4 LinkObject API Changed .................................. 220 4.3.5 Event Handling Changes .................................. 221 4.3.6 MojoUserAgent Added, WebUserAgent Deprecated ................. 223 5 Documentation 225 5.1 Documentation Infrastructure .................................... 225 5.2 reStructuredText Primer ....................................... 225 5.2.1 Headings .......................................... 225 5.2.2 Paragraphs ......................................... 226 5.2.3 Inline Markups ....................................... 226 5.2.4 Lists ............................................. 227 5.2.5 Literal Blocks ........................................ 227 5.2.6 Tables ............................................ 228 5.2.7 Hyperlinks .......................................... 228 5.2.8 Images ............................................ 229 5.2.9 Colored Boxes ....................................... 229 5.3 Style Guide .............................................. 229 5.3.1 Writing Content ....................................... 230 5.3.2 Screenshots ......................................... 230 5.3.3 Capitalization in Documentation .............................. 232 5.3.4 Buttons and Screen Names ................................ 233 5.3.5 Wording ........................................... 233 5.3.6 Variable Names ....................................... 233 5.4 Translating the Documentation ................................... 234 iii 6 Contributing to OTRS 237 6.1 Sending Contributions ........................................ 237 6.2 Translating .............................................. 238 6.3 Code Style Guide .......................................... 238 6.3.1 Perl ............................................. 238 6.3.2 JavaScript .......................................... 250 6.3.3 HTML ...........................................