Zammad Package Best Practices

There seems to be lots of movement around packages the past months! This is really great for the community.

Here are a few I know of:

I’m in the process of refactoring our Signal and WhatsApp channels from our zammad repo into packages, so I hope to add them to that list soon!

We’ve learned some things about how best to structure packages, and how to achieve certain things. However there’s a few questions I have on how best to refactor certain changes from the source tree into a package:


These are things we still don’t know how to do. @thorsteneckel perhaps you can shed some light on these?

1. How to update config.active_record.observers in config/application.rb?

We want to add the signal and whatsapp observers into config/application.rb. How do we do this with a package?


2. How to add icons?

All the SVG icons are combined into one file at public/assets/images/icons.svg. How can we add an icon to this file, or otherwise make it available (without overwriting the entire file)?

You can see here how we add a custom article type action for replying with Signal, using the signal icon. This works when we can add the icon to public/assets/images/icons.svg. Is there another search path for icons?

3. Testing

Once you move your changes out of the source tree, it becomes difficult to test of course.

We’ve solved this by including tests inside the szpm, installing the package on a dev machine and running rake test like normal.

Is there a better way?

Also, it would be SUPER amazing if you all could share your CI base image ( or at least the Dockerfile for it. Then we could setup a CI pipeline for packages that includes the selenium tests and everything else.

How to…

Here is what we do know! Hopefully this helps someone.


As per thorsten’s info:

You need to place them in db/addon/your_package_name and need to define self.up and/or self.down on them. Rails change method will not work!
For testing purposes you can use Package::Migration.migrate('YourPackageName') or Package::Migration.migrate('YourPackageName', 'reverse') on the Zammad rails console.

Here is an example migration.

You can achieve a lot with migrations, for example:

  • Set default system settings
  • Create new Object Attributes
  • Anything you can do from the rails console


CSS files should go in app/assets/stylesheets/addons/. SCSS is also supported.

General file overwrite

You can overwrite any file in the installation, however if you overwrite official files you will not receive updates when the Zammad Core team changes them. So generally speaking it is best not to overwrite existing files.

Auto installation

If you place your .zpm file into RAILS_ROOT/auto_install, then it will be automatically installed when the rake db:seed task is executed. You can trigger the auto install your self from the console Package.auto_install.

Note: Until PR #2933 is merged, the extension of the package must be .zpm.