Skip to content
Znuny Logo Znuny Community Docs

Plugin Development with OPM Packages

In this section, you will learn how to create, install, and distribute your own plugins as OPM packages for Znuny.

Section titled “In this section, you will learn how to create, install, and distribute your own plugins as OPM packages for Znuny.”

1. Structure of a .sopm

Section titled “1. Structure of a .sopm”

The SOPM file (*.sopm) contains all metadata for your package: `.sopm“

  • Name/Version/Framework: Unique package identifier and compatible Znuny version.
  • Filelist: All files that are copied during installation.

2. Files & Directory Structure

Section titled “2. Files & Directory Structure”

Create your package in its own directory, e.g., MyExtension/: *.sopm

  • Kernel/Config/Files/XML/: Registers modules, menus, or Dynamic Fields.
  • Kernel/System/: Business logic class.
  • Kernel/Modules/: Frontend controller.
  • Templates & Language: TT files + translation .pm.

3. Build & Install Package

Section titled “3. Build & Install Package”

3.1 Create OPM

Section titled “3.1 Create OPM”

Use the CLI tool to build an OPM from your SOPM: MyExtension/

3.2 Installation

Section titled “3.2 Installation”

Admin UI: Upload package under Admin → Settings → Package Manager. Console: Kernel/Config/Files/XML/MyExtension.xml To uninstall or update: Kernel/System/DynamicField/Driver/MyCustomField.pm

Section titled “Admin UI: Upload package under Admin → Settings → Package Manager. Console: Kernel/Config/Files/XML/MyExtension.xml To uninstall or update: Kernel/System/DynamicField/Driver/MyCustomField.pm”

4. Extension Points

Section titled “4. Extension Points”

4.1 Dynamic Fields

Section titled “4.1 Dynamic Fields”

In Kernel/Config/Files/XML/MyExtension.xml, you register a new Dynamic Field Driver: Kernel/System/Event/Handler/MyHandler.pm Implement the driver in Kernel/System/DynamicField/Driver/MyCustomField.pm.

4.2 Event Handler

Section titled “4.2 Event Handler”

Register your event handler: Run() Implement the handler in Kernel/System/Event/Handler/MyHandler.pm (Run() method).

4.3 Output Filter

Section titled “4.3 Output Filter”

Kernel/System/Output/Filter/MyFilter.pm Implement the filter in Kernel/System/Output/Filter/MyFilter.pm.

Section titled “Kernel/System/Output/Filter/MyFilter.pm Implement the filter in Kernel/System/Output/Filter/MyFilter.pm.”

5. Deployment & OTOpar

Section titled “5. Deployment & OTOpar”
  • Repository Index: Create Packages.xml for your own repo: Packages.xml
  • Add your repo URL under SysConfig Package::RepositoryList.
  • OTOpar: Upload your OPM to https://otopar.perl-services.de so that others can install it directly.

6. Example: MyCalendar Package

Section titled “6. Example: MyCalendar Package”
  1. Create SOPM with the name MyCalendar.
  2. DB script sql/create_calendar.sql for table calendar_events.
  3. Config XML defines new ticket field “Appointment”.
  4. Core module Kernel/System/CalendarEvent.pm with CRUD methods.
  5. Frontend modules Kernel/Modules/AgentCalendar.pm, template AgentCalendar.tt.
  6. Build package and upload to OTOpar.

7. Tips & Best Practices

Section titled “7. Tips & Best Practices”
  • Adjust version number in the sopm (SemVer).
  • Version DB migrations in sql/ cleanly.
  • Create unit tests for system and module classes.
  • Documentation in README plus POD in Perl modules.
  • Translations in Language/de_*.pm and en_*.pm. With this, you have a solid foundation to develop, distribute, and maintain your own Znuny plugins in customer projects. Have fun!

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

What are the essential components and structure of a Znuny OPM package?

A Znuny OPM (Open Package Manager) package is structured to encapsulate all necessary files and metadata for a plugin. At its core is the .sopm file, which serves as the package's manifest, containing crucial metadata like the package name, version, and compatible Znuny framework versions. It also lists all files that will be installed. The package's directory structure typically includes Kernel/Config/Files/XML/ for registering modules, menus, or Dynamic Fields, Kernel/System/ for business logic classes, Kernel/Modules/ for frontend controllers, and Templates & Language for Twig template files and translation .pm files. This organized structure ensures that all plugin components are correctly placed within the Znuny application during installation.

Quellen / Sources:

How do I build and install a custom Znuny OPM package?

To build a custom Znuny OPM package, you typically use a command-line interface (CLI) tool that processes your .sopm file and the associated plugin directory structure to generate the .opm package file. Once built, there are two primary methods for installation. For graphical installation, you can upload the .opm package directly through the Znuny Admin UI by navigating to Admin → Settings → Package Manager. Alternatively, for console-based installation, you can use a command-line utility, often found within the Znuny bin/ directory, to install the package. This method is particularly useful for automated deployments or server environments without direct UI access. The Package Manager also handles updates and uninstallation, ensuring a consistent lifecycle for your plugin.

Quellen / Sources:

What are the primary extension points available for developing Znuny plugins?

Znuny offers several extension points to integrate custom functionality into the system. One common method is through Dynamic Fields, where you can register a new Dynamic Field Driver in Kernel/Config/Files/XML/MyExtension.xml and implement its logic in Kernel/System/DynamicField/Driver/MyCustomField.pm. This allows for custom data input and display. Another powerful extension point is Event Handlers, which enable your plugin to react to specific events within Znuny. You register the handler and implement its Run() method in Kernel/System/Event/Handler/MyHandler.pm. Lastly, Output Filters allow you to modify the content generated by Znuny before it is displayed to the user. You implement the filter logic in Kernel/System/Output/Filter/MyFilter.pm. These extension points provide robust ways to customize and extend Znuny's core behavior.

Quellen / Sources:

How can I distribute my developed Znuny OPM package to other users or instances?

Distributing your Znuny OPM package involves making it accessible for others to install. One method is to create a Repository Index, which is an XML file named Packages.xml. This file lists all available OPM packages in your custom repository. Once Packages.xml is set up on a web server, users can add your repository URL to their Znuny system via the SysConfig setting Package::RepositoryList. This allows them to browse and install your packages directly from within their Znuny Package Manager, similar to official repositories. Another convenient option for broader distribution is to upload your OPM package to OTOpar (e.g., https://otopar.perl-services.de). OTOpar is a public platform where developers can share their OPM packages, enabling other Znuny users to easily discover and install them directly through the Package Manager.

Quellen / Sources:

What are some recommended best practices for developing and maintaining Znuny plugins?

Adhering to best practices ensures your Znuny plugins are robust, maintainable, and compatible. Always adjust the version number in your .sopm file following Semantic Versioning (SemVer) guidelines for clear release management. When dealing with database changes, meticulously version your DB migrations in the sql/ directory to ensure smooth updates and rollbacks. For critical functionality, create unit tests for your system and module classes to verify correctness and prevent regressions. Comprehensive documentation is vital; include a README file with installation and usage instructions, and use POD (Plain Old Documentation) within your Perl modules for in-code explanations. Finally, provide translations for your plugin by creating Language/de_*.pm and en_*.pm files, making your plugin accessible to a wider audience. These practices contribute to a high-quality plugin development experience.

Quellen / Sources: