How to Upgrade your OTRS Extensions to Newer Versions of OTRS

Upgrading OTRS Extensions from 2.4 to 3.0
Translation of configuration file descriptions.
Configuration of NavBarModule was Changed
Configuration of NavBar was Changed
Configuration Setting Frontend::NavBarModule was Renamed
PreferencesGroups configuration

Usually, new major OTRS releases also bring changes in the internals which need to be reflected in extension modules too. This chapter will describe these changes for each version upgrade.

Upgrading OTRS Extensions from 2.4 to 3.0

Translation of configuration file descriptions.

Previously, OTRS had translations for items in the sysconfig in multiple language in the XML files. Starting OTRS 3.0.x, the translations are removed from the configuration file. The configuration file only stores the English descriptions. If needed, you can localize the descriptions in your translation file in the way 'regular' strings in the web interface are translated. This has the added benefit that if a translator wants to localize a module's configuration, this can be fully done from the translation file. The otrs.CreateTranslationFile.pl script has been adjusted to also grab strings from the SysConfig.

Additionaly, if you have tags that are configured in SysConfig but displayed in the GUI, you can indicate with the option Translatable="1" that this is a field that should be added to the translation file.

    <ConfigItem Name="ProductName" Required="1" Valid="1">
        <Description Lang="en">This setting controls the name of the application as is shown in the web interface as well as the tabs and title bar of your web browser.</Description>
        <Description Lang="de">Im WebFrontend angezeigter Name der Software.</Description>
        <Group>Framework</Group>
        <SubGroup>Core</SubGroup>
        <Setting>
            <String Regex="">OTRS</String>
        </Setting>
    </ConfigItem>
        

New Style:

    <ConfigItem Name="ProductName" Required="1" Valid="1" ConfigLevel="200">
        <Description Translatable="1">Defines the name of the application, shown in the web interface, tabs and title bar of the web browser.</Description>
        <Group>Framework</Group>
        <SubGroup>Core</SubGroup>
        <Setting>
            <String Regex="">OTRS</String>
        </Setting>
    </ConfigItem>
        

Please note that the Block names changed (Agent, Customer, Email, Queue, Ticket and System are available). An additional Description tag has been added.

Configuration of NavBarModule was Changed

Old Style:

<ConfigItem Name="Frontend::Module###AdminUser" Required="0" Valid="1">
    <Description Lang="en">Frontend module registration for the AdminUser object in the admin area.</Description>
    <Description Lang="de">Frontendmodul-Registrierung des AdminUser-Objekts im Admin-Bereich.</Description>
    <Group>Framework</Group>
    <SubGroup>Frontend::Admin::ModuleRegistration</SubGroup>
    <Setting>
        <FrontendModuleReg>
            <Group>admin</Group>
            <Description>Admin</Description>
            <Title>User</Title>
            <NavBarName>Admin</NavBarName>
            <NavBarModule>
                <Module>Kernel::Output::HTML::NavBarModuleAdmin</Module>
                <Name>Users</Name>
                <Block>Block1</Block>
                <Prio>100</Prio>
            </NavBarModule>
        </FrontendModuleReg>
    </Setting>
</ConfigItem>
        

New Style:

    <ConfigItem Name="Frontend::Module###AdminUser" Required="0" Valid="1">
        <Description Translatable="1">Frontend module registration for the agent interface.</Description>
        <Group>Framework</Group>
        <SubGroup>Frontend::Admin::ModuleRegistration</SubGroup>
        <Setting>
            <FrontendModuleReg>
                <Group>admin</Group>
                <Description>Create and manage agents.</Description>
                <Title>Agents</Title>
                <NavBarName>Admin</NavBarName>
                <NavBarModule>
                    <Module>Kernel::Output::HTML::NavBarModuleAdmin</Module>
                    <Name Translatable="1">Agents</Name>
                    <Description Translatable="1">Create and manage agents.</Description>
                    <Block>Agent</Block>
                    <Prio>100</Prio>
                </NavBarModule>
            </FrontendModuleReg>
        </Setting>
    </ConfigItem>
            

Please note that the Block names changed (Agent, Customer, Email, Queue, Ticket and System are available). An additional Description tag has been added.

Configuration of NavBar was Changed

Old Style:

    <ConfigItem Name="Frontend::Module###AgentTicketSearch" Required="0" Valid="1">
        <Description Lang="en">Frontend module registration for the AgentTicketSearch object in the agent interface.</Description>
        <Description Lang="de">Frontendmodul-Registration des AgentTicketSearch-Objekts im Agent-Interface.</Description>
        <Group>Ticket</Group>
        <SubGroup>Frontend::Agent::ModuleRegistration</SubGroup>
        <Setting>
            <FrontendModuleReg>
                <Description>Search Tickets</Description>
                <Title>Search</Title>
                <NavBarName>Ticket</NavBarName>
                <NavBar>
                    <Description>Search Tickets</Description>
                    <Name>Search</Name>
                    <Image>search.png</Image>
                    <Link>Action=AgentTicketSearch</Link>
                    <NavBar>Ticket</NavBar>
                    <Type></Type>
                    <Block></Block>
                    <AccessKey>s</AccessKey>
                    <Prio>300</Prio>
                </NavBar>
            </FrontendModuleReg>
        </Setting>
    </ConfigItem>
            

New Style:

    <ConfigItem Name="Frontend::Module###AgentTicketSearch" Required="0" Valid="1">
        <Description Translatable="1">Frontend module registration for the agent interface.</Description>
        <Group>Ticket</Group>
        <SubGroup>Frontend::Agent::ModuleRegistration</SubGroup>
        <Setting>
            <FrontendModuleReg>
                <Description>Search Ticket</Description>
                <Title>Search</Title>
                <NavBarName>Ticket</NavBarName>
                <NavBar>
                    <Description Translatable="1">Search Ticket</Description>
                    <Name Translatable="1">Search</Name>
                    <Link>Action=AgentTicketSearch</Link>
                    <LinkOption></LinkOption>
                    <NavBar>Ticket</NavBar>
                    <Type></Type>
                    <Block></Block>
                    <AccessKey>s</AccessKey>
                    <Prio>300</Prio>
                </NavBar>
            </FrontendModuleReg>
        </Setting>
    </ConfigItem>
            

Please note that the NavBar names changed (Description Name Link LinkOption NavBar Type Block AccessKey Prio are available). An additional LinkOption tag has been added and Image tag has been removed.

Configuration Setting Frontend::NavBarModule was Renamed

Frontend::NavBarModule was renamed to Frontend::ToolBarModule. Block option need to get replaced, ToolBarItem is now used.

PreferencesGroups configuration

Up to this point, the PreferencesGroups (which can be used to create a section in the Agent or Customer configuration dialog) had either a description (Desc), or a field label (Key), or both. With the new GUI, the interface was slightly changed so that now the Key always must be provided.

The existing entries were changed so that either the Desc was shortened and turned into a Key instead, or a concise Key was added to describe the setting in Question.

This is also what should be done (either of the two options) when porting a custom PreferencesGroups module to OTRS 3.0.

Example:

    <ConfigItem Name="PreferencesGroups###RefreshTime" Required="0" Valid="1">
        <Description Translatable="1">Parameters for the RefreshTime object in the preference view of the agent interface.</Description>
        <Group>Ticket</Group>
        <SubGroup>Frontend::Agent::Preferences</SubGroup>
        <Setting>
            <Hash>
                <Item Key="Module">Kernel::Output::HTML::PreferencesGeneric</Item>
                <Item Key="Column">Other Settings</Item>
                <Item Key="Label" Translatable="1">QueueView Refresh Time</Item>
                <Item Key="Desc" Translatable="1">If enabled, the QueueView will automatically refresh after the specified time.</Item>
                <Item Key="Key" Translatable="1">Refresh QueueView after</Item>
                <Item Key="Data">
                    <Hash>
                        <Item Key="0">off</Item>
                        <Item Key="2"> 2 minutes</Item>
                        <Item Key="5"> 5 minutes</Item>
                        <Item Key="7"> 7 minutes</Item>
                        <Item Key="10">10 minutes</Item>
                        <Item Key="15">15 minutes</Item>
                    </Hash>
                </Item>
                <Item Key="DataSelected">0</Item>
                <Item Key="PrefKey">UserRefreshTime</Item>
                <Item Key="Prio">2000</Item>
                <Item Key="Active">1</Item>
            </Hash>
        </Setting>
    </ConfigItem>
            

Key is mandatory, Desc is optional.