Packages Tutorial

Development
, , , ,
7

Package migrations

Database migrations in the package can be done in a seperate addon specific folder. In this tutorial we will create a very simple migration which will update a setting of zammad.

  1. Create a new package directory:
ubuntu-rs@ubuntu-rs:/workspace/git_zammad$ mkdir Example-Setting
ubuntu-rs@ubuntu-rs:/workspace/git_zammad$ cd Example-Setting
  1. Init your github repository:
ubuntu-rs@ubuntu-rs:/workspace/git_zammad/Example-Setting$ git init
  1. Setup a szpm dummy source file:
ubuntu-rs@ubuntu-rs:/workspace/git_zammad/Example-Setting$ git zammad-new-szpm
ubuntu-rs@ubuntu-rs:/workspace/git_zammad/Example-Setting$ cat example-setting.szpm
{
  "name": "Example-Setting",
  "version": "1.0.0",
  "vendor": "Example GmbH",
  "license": "GNU AFFERO GENERAL PUBLIC LICENSE",
  "url": "http://example.com/",
  "files": []
}
  1. Now we need to add our migration. We will change the product name of our zammad instance. For this we need to create an migration:

db/addon/example_setting/20230825000000_create_base.rb

class CreateBase < ActiveRecord::Migration[4.2]
  def self.up
    Setting.set('product_name', 'Example Setting')
  end

  def self.down; end
end

self.up Runs on package installation
self.down Runs on package removal

So on installation of the package this file will update the Setting Product Name. You can find all settings here:
https://github.com/zammad/zammad/blob/1a1a092ceedf93b12ca865b715292f00bea2d76b/db/seeds/settings.rb

Setting.get is used to get the state of the setting.
Setting.set is used to change the state of the setting.
Setting stores the configuration of the setting.

(https://github.com/zammad/zammad/blob/1a1a092ceedf93b12ca865b715292f00bea2d76b/app/models/setting.rb)

  1. To update the file list of our szpm file, we can use our alias. It will update the file list for our szpm file:
ubuntu-rs@ubuntu-rs:/workspace/git_zammad/Example-Setting$ git zammad-update-szpm
ubuntu-rs@ubuntu-rs:/workspace/git_zammad/Example-Setting$ cat example-setting.szpm
{
  "name": "Example-Setting",
  "version": "1.0.0",
  "vendor": "Example GmbH",
  "license": "GNU AFFERO GENERAL PUBLIC LICENSE",
  "url": "http://example.com/",
  "files": [
    {
      "location": "db/addon/example_setting/20230825000000_create_base.rb",
      "permission": 644
    }
  ]
}
  1. Now we can build a release for our setting changing package:
ubuntu-rs@ubuntu-rs:/workspace/git_zammad/Example-Setting$ git zammad-create-zpm 1.0.0
ubuntu-rs@ubuntu-rs:/workspace/git_zammad/Example-Setting$ cat example-setting-1.0.0.zpm
{
  "name": "Example-Setting",
  "version": "1.0.0",
  "vendor": "Example GmbH",
  "license": "GNU AFFERO GENERAL PUBLIC LICENSE",
  "url": "http://example.com/",
  "files": [
    {
      "location": "db/addon/example_setting/20230825000000_create_base.rb",
      "permission": 644,
      "encode": "base64",
      "content": "Y2xhc3MgQ3JlYXRlQmFzZSA8IEFjdGl2ZVJlY29yZDo6TWlncmF0aW9uWzQu\nMl0KICBkZWYgc2VsZi51cAogICAgU2V0dGluZy5zZXQoJ3Byb2R1Y3RfbmFt\nZScsICdFeGFtcGxlIFNldHRpbmcnKQogIGVuZAoKICBkZWYgc2VsZi5kb3du\nOyBlbmQKZW5kCg=="
    }
  ]
}
  1. Take your example-setting-1.0.0.zpm build and install it into your zammad. Afterwards, you will need to run the following commands:
zammad> rake zammad:package:migrate
root> systemctl restart zammad

rake zammad:package:migrate to run the migrations of your package
systemctl restart zammad Should always run after the installation of a package

  1. Check your settings in the admin interface (Admin → Branding). Your product name should have changed to:

Example Setting

2 Likes