Table of Contents
OTRS comes with a dedicated mechanism to manage configuration options via a graphical interface (SysConfig). This section describes how it works internally and how you can provide new configuration options or change existing default values.
The default configuration file of OTRS is Kernel/Config/Defaults.pm.
This file should be left untouched as it is automatically updated on framework updates.
In Kernel/Config/Files you can find some automatically generated configuration files:
ZZZAAuto.pm # Perl cache of the XML configuration's default values ZZZACL.pm # Perl cache of ACL configuration from database ZZZAuto.pm # Contains all the settings the user changed in their SysConfig ZZZProcessManagement.pm # Perl cache of ProcessManagement configuration from database
These files should never be manually changed as they are overwritten by OTRS.
In OTRS, configuration options that the administrator can configure via SysConfig are provided via
XML files with a special format.
XML config files are located at $OTRS_HOME/Kernel/Config/Files/*.xml.
The file Kernel/Config/Files/ZZZAAuto.pm is a cached Perl version of the XML that contains
all settings with their default value. It can be (re-)generated with bin/otrs.Console.pl Maint::Config::Rebuild.
All changes the administrator makes are stored in Kernel/Config/Files/ZZZAuto.pm.
Each XML config file has the following layout:
<?xml version="1.0" encoding="utf-8" ?>
<otrs_config version="1.0" init="Changes">
<!-- config items will be here -->
</otrs_config>
The init attribute describes where the config options should be loaded. There are different levels available and will be loaded/overloaded in the following order: Framework (for framework settings e. g. session option), Application (for application settings e. g. ticket options), Config (for extensions to existing applications e. g. ITSM options) and Changes (for custom development e. g. to overwrite framework or ticket options).
If you want to add config options, here is an example:
<ConfigItem Name="Ticket::Hook" Required="1" Valid="1" ConfigLevel="300">
<Description Lang="en">The identifier for a ticket. The default is Ticket#.</Description>
<Description Lang="de">Ticket-Identifikator. Als Standard wird Ticket# verwendet.</Description>
<Group>Ticket</Group>
<SubGroup>Core::Ticket</SubGroup>
<Setting>
<String Regex="">Ticket#</String>
</Setting>
</ConfigItem>
If required is set to 1, the config variable is included and cannot be disabled.
If valid is set to 1, the config variable is active.
If it is set to 0, the config variable is inactive.
If the optional attribute ConfigLevel is set, the config variable might not be edited by the administrator,
depending on his own config level. The config variable ConfigLevel sets the level of technical experience
of the administrator. It can be 100 (Expert), 200 (Advanced) or 300 (Beginner).
As a guideline which config level should be given to an option, it is recommended that all options
having to do with the configuration of external interaction, like Sendmail, LDAP, SOAP,
and others should get a config level of at least 200 (Advanced).
The config variable is defined in the Setting element.
The XML config settings support various types of variables.
<Setting>
<String Regex="" Check="File"></String>
</Setting>
A config element for numbers and single-line strings.
Checking the validity with a regular expression is possible (optional).
The optional Check attribute checks elements on the file system.
<Setting>
<String Translatable="1">My Setting</String>
</Setting>
The optional Translatable attribute marks this setting as translatable, which
will cause it to be included in the OTRS translation files.
This attribute can be placed on any tag (see also below).
This config element offers preset values as a pull-down menu.
<Setting>
<Option SelectedID="0">
<Item Key="0" Translatable="1">No</Item>
<Item Key="1" Translatable="1">Yes</Item>
</Option>
</Setting>
You can also choose the default value by "Value":
<Setting>
<Option SelectedValue="No">
<Item Key="0" Translatable="1">No</Item>
<Item Key="1" Translatable="1">Yes</Item>
</Option>
</Setting>
With this config element arrays can be displayed.
<Setting>
<Array>
<Item>First item</Item>
<Item>Second item</Item>
</Array>
</Setting>
With this config element hashes can be displayed.
<Setting>
<Hash>
<Item Key="1" Translatable="1">Value 1</Item>
<Item Key="2" Translatable="1">Value 2</Item>
</Hash>
</Setting>
A hash can also contain nested arrays or hashes.
<Setting>
<Hash>
<Item Key=""></Item>
<Item Key="">
<Hash>
<Item Key=""></Item>
<Item Key=""></Item>
</Hash>
</Item>
<Item Key="">
<Array>
<Item></Item>
<Item></Item>
</Array>
</Item>
<Item Key=""></Item>
</Hash>
</Setting>
Module registration for Agent Interface:
<Setting>
<FrontendModuleReg>
<Description>Agent Dashboard</Description>
<Title></Title>
<NavBarName>Dashboard</NavBarName>
<NavBar>
<Description Translatable="1"></Description>
<Name Translatable="1">Dashboard</Name>
<Link>Action=AgentDashboard</Link>
<LinkOption></LinkOption>
<NavBar>Dashboard</NavBar>
<Type>Menu</Type>
<Block>ItemArea</Block>
<AccessKey>d</AccessKey>
<Prio>50</Prio>
</NavBar>
<Loader>
<CSS>Core.Agent.Dashboard.css</CSS>
<CSS>Core.AllocationList.css</CSS>
<CSS>thirdparty/fullcalendar-1.6.1/fullcalendar.css</CSS>
<CSS>thirdparty/d3js/nv.d3.css</CSS>
<JavaScript>thirdparty/flot-0.8.3/excanvas.js</JavaScript>
<JavaScript>thirdparty/flot-0.8.3/jquery.flot.js</JavaScript>
<JavaScript>thirdparty/fullcalendar-1.6.1/fullcalendar.min.js</JavaScript>
<JavaScript>thirdparty/d3js/d3.v3.min.js</JavaScript>
<JavaScript>thirdparty/d3js/nv.d3.min.js</JavaScript>
<JavaScript>thirdparty/d3js/models/OTRSmultiBarChart.js</JavaScript>
<JavaScript>thirdparty/d3js/models/OTRSstackedAreaChart.js</JavaScript>
<JavaScript>Core.UI.Chart.js</JavaScript>
<JavaScript>Core.UI.AdvancedChart.js</JavaScript>
<JavaScript>Core.UI.AllocationList.js</JavaScript>
<JavaScript>Core.Agent.TableFilters.js</JavaScript>
<JavaScript>Core.Agent.Dashboard.js</JavaScript>
</Loader>
</FrontendModuleReg>
</Setting>
Module registration for Admin Interface:
<Setting>
<FrontendModuleReg>
<Group>admin</Group>
<Description>Admin</Description>
<Title Translatable="1">Customers <-> Groups</Title>
<NavBarName>Admin</NavBarName>
<NavBarModule>
<Module>Kernel::Output::HTML::NavBarModuleAdmin</Module>
<Name Translatable="1">Customer User <-> Groups</Name>
<Description Translatable="1">Link customer user to groups.</Description>
<Block>Customer</Block>
<Prio>400</Prio>
</NavBarModule>
</FrontendModuleReg>
</Setting>
You can read and write (for one request) the config options via the core module Kernel::Config.
If you want to read a config option:
my $ConfigOption = $Kernel::OM->Get('Kernel::Config')->Get('Prefix::Option');
If you want to change a config option at runtime and just for this one request/process:
$Kernel::OM->Get('Kernel::Config')->Set(
Key => 'Prefix::Option'
Value => 'SomeNewValue',
);