Internally Extending the Znuny Core System

In this article, you will learn how to customize Znuny directly in the core – via XML configuration, Perl modules, and templates. We will show you step-by-step how to integrate your own “HelloWorld” module into the system.

---

1. Directory Structure

All customizations are located within your Znuny clone in the Kernel/ directory:

Kernel/
├─ Config/Files/           # XML registrations
│  └─ XML/
├─ System/                 # Business logic modules (Core)
├─ Modules/                # Frontend controllers (Agent/Customer)
├─ Output/HTML/Standard/   # Template Toolkit (TT) templates
└─ Language/               # Translations

---

2. XML Configuration

New modules and routes are registered via XML. Create a file HelloWorld.xml in Kernel/Config/Files/XML/:

<?xml version="1.0" encoding="UTF-8"?>
<znuny_config version="2.0" init="Application">

  <!-- 1. Register frontend module -->
  <Setting Name="Frontend::Module###AgentHelloWorld" Required="1" Valid="1">
    <Navigation>Frontend::Agent::ModuleRegistration</Navigation>
    <Value>
      <Item ValueType="FrontendRegistration">
        <Hash>
          <Item Key="Group"><Array><Item>users</Item></Array></Item>
          <Item Key="Description" Translatable="1">HelloWorld module</Item>
          <Item Key="Title"       Translatable="1">HelloWorld</Item>
          <Item Key="NavBarName">HelloWorld</Item>
        </Hash>
      </Item>
    </Value>
  </Setting>

</znuny_config>

---

3. Core Module (Business Logic)

Create your logic in Kernel/System/HelloWorld.pm:

package Kernel::System::HelloWorld;
use strict;
use warnings;
our @ObjectDependencies = ();

sub new {
    my ($Type, %Param) = @_;
    return bless {}, $Type;
}

sub GetHelloWorldText {
    my ($Self, %Param) = @_;
    return $Self->_FormatText(String => 'Hello World');
}

sub _FormatText {
    my ($Self, %Param) = @_;
    return uc $Param{String};
}

1;

---

4. Frontend Module (Controller)

In Kernel/Modules/AgentHelloWorld.pm, you integrate your logic into the Agent frontend:

package Kernel::Modules::AgentHelloWorld;
use strict;
use warnings;

sub new { bless {}, shift }

sub Run {
    my ($Self, %Param) = @_;

    my $HelloObj    = $Kernel::OM->Get('Kernel::System::HelloWorld');
    my $LayoutObj   = $Kernel::OM->Get('Kernel::Output::HTML::Layout');
    my %Data;

    $Data{Text} = $HelloObj->GetHelloWorldText();

    return
        $LayoutObj->Header(Title => 'HelloWorld')
      . $LayoutObj->NavigationBar()
      . $LayoutObj->Output(
          TemplateFile => 'AgentHelloWorld',
          Data         => \%Data,
        )
      . $LayoutObj->Footer();
}

1;

---

5. Templates (TT)

Create the following template in Kernel/Output/HTML/Standard/AgentHelloWorld.tt:

[% Data.Text %]

<p>This is your custom HelloWorld module!</p>

---

6. Example Workflow

1. Reload:

   bin/znuny.Console.pl Maint::Config::Rebuild

2. Clear cache:

   bin/znuny.Console.pl Maint::Cache::Delete

3. Open browser: Agent interface → Menu → “HelloWorld”

---

7. Tips & Best Practices

• Declare ObjectDependencies cleanly (e.g., DB, Layout).
• Don’t forget POD documentation in Perl modules.
• Maintain translations under Kernel/Language/en_*.pm.
• Set up unit tests with Mojolicious (optional).
• After every change, perform a Config rebuild & clear cache.

With this, you have a solid template for implementing further core extensions in Znuny. Happy coding!

Custom Znuny plugin & module development

Need custom features or legacy package updates? Softoft builds maintainable, release-ready Perl and web modules for Znuny.

Request development

Frequently asked questions

Where do Znuny core customizations live?

Customizations for the Znuny core system are systematically organized within the Kernel/ directory of your Znuny installation. This directory serves as the central hub for all custom components, ensuring a structured approach to extensions. Specifically, XML configuration files, which are crucial for registering new modules and routes, are placed in Kernel/Config/Files/XML/. Business logic modules, containing the core functionalities, reside in Kernel/System/. Frontend controllers, responsible for integrating logic into the agent or customer interface, are found in Kernel/Modules/. Template Toolkit (TT) templates, used for rendering the user interface, are located in Kernel/Output/HTML/Standard/. Lastly, translation files for internationalization are stored in Kernel/Language/. This clear separation helps in maintaining and managing custom code effectively.

Quellen

• Internally Extending the Znuny Core System | Znuny Community Docs
• System architecture — Znuny documentation

How do you register a new frontend module in Znuny?

To register a new frontend module in Znuny, you must create an XML configuration file within the Kernel/Config/Files/XML/ directory. This XML file defines the module's properties and makes it discoverable by the Znuny system. Inside the XML, you'll use a <Setting> tag with a Name attribute like Frontend::Module###AgentYourModule to specify the module type and its unique identifier. Key details to include are the module's Group (e.g., users), a Description and Title (both translatable for multi-language support), and a NavBarName which determines how it appears in the navigation bar. This registration process is essential for integrating your custom module into the Znuny agent or customer interface, allowing users to access its functionalities through the frontend.

Quellen

• Internally Extending the Znuny Core System | Znuny Community Docs
• Znuny Internals: How Configuration Works

How do you implement the business logic for a custom Znuny module?

The business logic for a custom Znuny module is implemented in a Perl module located within the Kernel/System/ directory. This module acts as the core component, encapsulating the specific functionalities and operations that your extension provides. For instance, in a "HelloWorld" example, you would create a file like Kernel/System/HelloWorld.pm. Within this Perl package, you define methods that perform the actual work, such as data processing, calculations, or interactions with other system components. It's crucial to declare any dependencies using @ObjectDependencies and to follow standard Perl object-oriented practices, including a new constructor. This separation of concerns ensures that your core logic remains independent of the frontend presentation, promoting reusability and maintainability.

Quellen

• Internally Extending the Znuny Core System | Znuny Community Docs
• System architecture — Znuny documentation

What is the purpose of the frontend module (controller) in a Znuny core extension?

The frontend module, often referred to as the controller, serves as the intermediary between the user interface and the core business logic in a Znuny extension. It resides in the Kernel/Modules/ directory (e.g., Kernel/Modules/AgentHelloWorld.pm) and is responsible for handling user requests, orchestrating data flow, and preparing the data for display. The Run method within this module is the entry point where it retrieves necessary objects from the Kernel::OM (Object Manager), such as the core logic module (Kernel::System::HelloWorld) and the layout object (Kernel::Output::HTML::Layout). It then calls methods on the core logic to fetch or process data, and finally uses the layout object to render the appropriate template with the prepared data, ensuring a cohesive user experience.

Quellen

• Internally Extending the Znuny Core System | Znuny Community Docs
• System architecture — Znuny documentation

How are templates used to render the output of a custom Znuny module in Znuny?

Templates in Znuny are used to define the visual presentation of a custom module's output, separating the display logic from the application's core functionality. These templates are typically written using Template Toolkit (TT) syntax and are stored in the Kernel/Output/HTML/Standard/ directory (e.g., Kernel/Output/HTML/Standard/AgentHelloWorld.tt). The frontend module (controller) is responsible for passing data to these templates. Within the template, placeholders like [% Data.Text %] are used to dynamically insert the data prepared by the controller. The Kernel::Output::HTML::Layout object then processes the template, injecting the data and wrapping it with standard Znuny headers, navigation, and footers to ensure a consistent look and feel across the agent or customer interface.

Quellen

• Internally Extending the Znuny Core System | Znuny Community Docs
• System architecture — Znuny documentation

What are the essential steps to deploy and test a new internal Znuny core extension?

After developing your custom XML configuration, Perl modules, and templates for a Znuny core extension, there are two essential steps to deploy and test it effectively. First, you must rebuild the Znuny configuration by running the command bin/znuny.Console.pl Maint::Config::Rebuild. This command ensures that the system recognizes your new XML registrations and module definitions. Second, it's crucial to clear the system cache with bin/znuny.Console.pl Maint::Cache::Delete. Clearing the cache ensures that Znuny loads the most up-to-date versions of your files and configurations, preventing issues caused by outdated cached data. Once these steps are completed, you can access your new module through the Znuny agent interface (e.g., via the "HelloWorld" menu item) to verify its functionality.

Quellen

• Internally Extending the Znuny Core System | Znuny Community Docs
• Znuny Internals: How Configuration Works