Examples of zpm files?

Infos:

  • Used Zammad version: 3.1
  • Used Zammad installation source: source
  • Operating system: Mac OS X
  • Browser + version: Chrome 75.0.3770.142

I wonder if there are any examples of zpm files somewhere on the web?

I started digging around in the model “Package” (more specifically the method “install”) in order to understand
what the page “Packages” in the GUI actually expects.

Its basically a json
file, with keys “name”,“version”,“vendor” and “files”? So with this I can
basically break everything. Are there any assumptions about these
files, good practice?

Thanks in advance

As far as I’m aware we currently have no examples for that (and no useful documentation for public).

Maybe @thorsteneckel has an example in his back hand.

Hi @njfranck - I just put some lines together to give you an impression on how a szpm file looks like. There is no magic involved:

{
  "name": "Addon",
  "version": "1.0.0",
  "vendor": "Zammad GmbH",
  "license": "GNU AGPL v2",
  "url": "http://zammad.org/",
  "change_log": [
    {
      "version": "1.0.0",
      "date": "2019-08-05 13:37:42 UTC",
      "log": "Initial version."
    }
  ],
  "description": [
    {
      "language": "en",
      "text": "Adding custom functionality XY."
    }
  ],
  "files": [
    {
      "location": "app/model/custom.rb",
      "permission": 644
    }
  ]
}

To get a installable zpm file from this you have to encode the files content via base64 and add it to the corresponding record and add the "encode": "base64", attribute, too. Additionally the buildhost and builddate attributes should get set. The final zpm file would look like this:

{
  "name": "Addon",
  "version": "1.0.0",
  "vendor": "Zammad GmbH",
  "license": "GNU AGPL v2",
  "url": "http://zammad.org/",
  "buildhost": "build.zammad.com",
  "builddate": "2019-08-05 13:37:42 UTC",
  "change_log": [
    {
      "version": "1.0.0",
      "date": "2019-08-05 13:37:23 UTC",
      "log": "Initial version."
    }
  ],
  "description": [
    {
      "language": "en",
      "text": "Adding custom functionality XY."
    }
  ],
  "files": [
    {
      "location": "app/model/custom.rb",
      "permission": 644,
      "encode": "base64",
      "content": "cHV0cyAiSGVsbG8gdGhlcmUgOikgRHJvcCB1cyBhIG1haWwgYXQgam9ic0B6YW1tYWQuY29tIC0gd2UnZCBsaWtlIHRvIHRhbGsgdG8geW91IPCfpbAi"
    }
  ]
}

There is an undocumented gem which does some szpm/zpm handling. We’re using it in our build system.

However, we won’t put much more effort in the szpm/zpm eco system because we will replace the whole packaging mechanism in the future. However, since we have quite a few customer and internal packages we will provide a straight forward migration mechanism / documentation when the time comes. So your work wont be lost if you decide to create a zpm file.

Let me know if I can help you any further.

PS: What are you building? :slight_smile:

Thanks for your reply.

As I thought, it just puts files in the project directory.

For the moment I’m not building anything, but I was wondering
on how zammad could be extended or flavoured. So a bunch
of initializers that reopen models would redefine the existing models.

Absolutely. You can also overwrite any file which comes with the downside of not receiving any updates for this certain file. However, our design goal is to make everything in the frontend and backend overwrite- and customizable.

What would be a good place to start looking if you want to make a package that adds functionality to the GUI?

Hey @mattronix - it depends on what you want to do. If you can give me a rough idea I can provide you a starting point.

Hello Thorsten,

I am trying to add a dynamically generated attribute to a user profile that shows when the user is a customer on a ticket.

A pin code more or less and at some point want to add it to the CTI interface.

Ok perfect. So what I do in these situations where I don’t know where to find a certain part of the frontend application is that I open up my browser console and select the most unique element in the component. From there I search for the most unique HTML or CSS class. For example in the sidebar I’d pick the class sidebar-content. If possible I’d pick a class having a js- prefix which indicates an element with JS enriched functionality. After I picked a reference string I search the codebase for it. Usually I limit the search to the matching filename extension:

*.eco when searching for HTML strings
*.coffee when searching for JS related code
*.rb when searching for ruby/backend functionality

My search leads me to the file app/assets/javascripts/app/views/generic/sidebar_tabs.jst.eco. This is the actual HTML template I was looking for. Now I want to know where this templated is filled with the data. For this I need to take the part after app/assets/javascripts/app/views/ without the .jst.eco file extension. Now searching for generic/sidebar_tabs with the limitation to JS files (*.coffee) I find that the template is used in the file app/assets/javascripts/app/controllers/_application_controller_generic.coffee on line 737 (current state of develop / f50c079df955118c643c17257a54b063eb32b894). Looking around I see an array of itemsLocal getting passed into the template rendering logic as argument items. This array is filled some lines above with calls to a sidebarItem(). Searching for sidebarItem with file extension filter *.coffee leads me to a list of search results. Reading the names of the found files indicates that app/assets/javascripts/app/controllers/ticket_zoom/sidebar_customer.coffee is the file that I was looking for. It is responsible for rendering the customer sidebar element in the ticket zoom.

This search goes on and on until I hit the spot I was looking for. Sometimes I need to add some console.log or debugger statements to find my way.

One note: I strongly advise you to have a dedicated test system (in developer mode) to have the easiest developer experience and not risking your production environment.

I hope this helps in any way.

Bests,
Thorsten

1 Like

Hi, I needed to integrate our own SMS gateway instead of using twilio and thanks to this explanation of how the zpm file should look like, it was really easy to create a package.
I have described what I did in a blog post and also put up the files on github. So if anyone needs to add a new SMS gateway, this should be very straight forward now but also might help others with starting their own packages.

2 Likes