Home Explore Help
Sign In
SMusatov
/
zammad
mirror of https://github.com/zammad/zammad.git
1
0
Fork 0
Files
Branch: develop
Branches Tags
zammad
/
BREAKING_CHANGES.md

BREAKING_CHANGES.md 13 KB
Permalink History Raw

Breaking Changes

6.5

Textarea object manager attribute values

When used as template variables, the textarea object manager attributes are now replaced with an HTML representation of their value. This is a consequence of a bugfix for #5330, which expects newline characters are respected for these attributes in all contexts, including the rich text article body. The administrators are advised to check for usage of such variables in their objects (e.g. triggers, text modules, etc), by making sure the new value type will not break their existing workflows.

Changes to search API endpoints

All search endpoints (/:object/search) have been revised, extended and unified. This will also result in breaking changes in the existing endpoints. Be prepared that the structure in the responses may change (have a look at the API documentation where you can find updated examples).

The standard search (e.g. /ticket/search) returned a hash for some objects, such as the ticket. This will no longer be the case.

The structure for the expanded search (e.g. /ticket/search?expand=true) remains the same.

The structure of the full search (e.g. /ticket/search?full=true) remains the same, but is supplemented by a total_count, which counts all results.

Some objects used an object-related hash key, such as ticket_ids. This is now always record_ids.

The count search (e.g. /ticket/search?only_total_count=true) is a new feature.

API performance optimization of asset return data

Most API endpoints have some parameter called full=true which returns the data with all related assets. In order to improve the front end performance, we decided to reduce certain assets which are populated on the login. Normally this parameter is mainly used to show additional data to our legacy app. We have some static data which rarely changes and are currently added on every object like:

  • Ticket Priority
  • Ticket State
  • Ticket Group
  • Role

This information will not be added in the future any more when requesting a user or a ticket. If you have an external script which is for example requesting tickets with assets and using the group name or some role information out of the assets, you need to adjust your code to do either:

  1. Do a separate request to the object specific endpoint e.g. /api/v1/groups
  2. Get the global assets before requesting the ticket e.g. /api/v1/signshow

Limit to one merged state

It will not be possible to have more than one state of the merged type. Additional states will be changed to the closed type automatically with that update. If you want to prevent that, make sure to only have one state of the type merged before you make an update to the next release.

APP_RESTART_CMD and Zammad self-shutdown

Zammad will now cause a self-shutdown of all running processes after certain configuration changes by default. It is the responsibility of the controlling process manager (e.g. Docker, Kubernetes, systemd) to bring them up again by way of a proper restart policy. This is the default for vanilla Docker, Kubernetes or Package deployments of Zammad.

The previous environment variable APP_RESTART_CMD is not supported any more.

For systems where this behaviour is not wanted, it can be disabled by setting the Zammad Setting auto_shutdown to false.

nginx configuration update

Please update your nginx configuration file to insert the line proxy_set_header Host $http_host; to the location /ws and location /cable sections like in the example below:

@@ -38,10 +38,11 @@ server {
   # legacy web socket server
   location /ws {
     proxy_http_version 1.1;
     proxy_set_header Upgrade $http_upgrade;
     proxy_set_header Connection "Upgrade";
+    proxy_set_header Host $http_host;
     proxy_set_header CLIENT_IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto $scheme;
     proxy_read_timeout 86400;
     proxy_pass http://zammad-websocket;
@@ -50,10 +51,11 @@ server {
   # action cable
   location /cable {
     proxy_http_version 1.1;
     proxy_set_header Upgrade $http_upgrade;
     proxy_set_header Connection "Upgrade";
+    proxy_set_header Host $http_host;
     proxy_set_header CLIENT_IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto $scheme;
     proxy_read_timeout 86400;
     proxy_pass http://zammad-railsserver;

6.4

JavaScript Package Manager Change

This version changes the JavaScript toolchains to be based on pnpm rather than yarn. This is only relevant for source installations, where you need to provide a recent version of pnpm in order to run the assets:precompile command.

Changed CSV-format for user/organization import/export

We slightly changed the format of the CSV-files you use for importing/exporting users and organizations. If you somehow do that in an automated process via our REST-API, you will need to review that process before updating to Zammad 6.4. Check the details in our documentation.

6.3

Knowledge base granular permissions setup changed

Zammad allows configuration of a granular permission structure for knowledge base access. Previous Zammad versions allowed to misconfigure this in cases of allowing agents editor access to only some, but not all categories: it was possible to grant editor access at a higher level in the category tree, and then restricting access to reader or none for sub-categories. This was not effective due to permission inheritance.

Such a misconfiguration is no longer possible in Zammad 6.3. Administrators with existing knowledge base granular permission structures should review their configuration to ensure that at top-level only reader access is granted, and editor access only for the relevant sub-categories.

Permissions for Ticket State and Priority REST-API

With this release, we will introduce new permissions for the ticket state and priority management. It will no longer be possible to access the corresponding REST-API with "admin.object" permission. Existing roles and/or access tokens that are used for these specific REST-API endpoints need to be updated to include the new permissions ("admin.ticket_state" and "admin.ticket_priority").

6.2

Default SSL Verification in UserAgent

The default SSL behaviour of the UserAgent class in Zammad was changed. Previously, it would not perform SSL verification unless explicitly requested. Now, it will perform SSL verification unless explicitly rejected.

This may cause issues on systems with custom addons using the UserAgent to access other systems via https, if these systems have self-signed certificates. In such cases, these certificates or the CA certificates used for their generation should be uploaded via the new SSL Certificates management screen of Zammad. Alternatively, custom code can be adjusted to pass verify_ssl: false to UserAgent calls to restore the old behaviour.

Oversized Email Handling

The handling of emails larger than the size limit changed. Previously, Zammad would send a reply and save the emails locally in var/spool/oversized_email (if the setting postmaster_send_reject_if_mail_too_large is true). No ticket is created in this case.

The new behaviour is that Zammad sends the reply like before, but no longer creates files for these emails locally - they are discarded.

Reserved Delimiter in Group Name

The double colon (::) is now a reserved delimiter in the group name, in order to facilitate nested structure for complex hierarchies. Previously, it was possible to freely use this set of characters as part of the group name, but now it is forbidden.

On existing systems, the group names that contain the now reserved delimiter will be renamed, with sets of double colons being replaced by a dash (-) during the migration process.

Additionally, existing custom group object attributes named name_last and parent_id will be renamed too, by adding an underscore in front (_name_last and _parent_id). This is due to these attributes now being part of the group model, requiring dedicated table columns under the reserved names.

Disallowed URL Values in User's Name Attributes

Text values that resemble valid URI addresses are now disallowed for user's first and last name attributes. Previously, it was possible to save any text in these attributes. The administrators should take a note of this change since it can have an impact on existing user data.

No migration will be run for existing users on update to Zammad 6.2. In case there are user records that contain URLs in their name attributes, they will be sanitized during subsequent updates. No manual action from administrator will be required, as the URI scheme or protocol will be automatically stripped from offending values.

6.1

New Organization Attribute vip

Zammad 6.1 creates a new vip attribute for organizations. For systems with previously created vip attributes, there is special caution needed. In case of boolean attributes, Zammad will adjust them to the new settings and keep using them. For attributes of other types, Zammad will rename the existing attribute to _vip and add a new vip boolean attribute. This may cause issues if the previous attribute was used in other parts of the system, e.g. Triggers. In such cases, the relevant configurations must be reviewed and adjusted.

Support for the Unicorn Web Server is removed

It seems that the Unicorn Web Server is no longer really used with Zammad. Therefore, we have decided to remove it with Zammad 6.1 after it was deprecated in Zammad 6.0.

6.0

nginx configuration update

When updating to Zammad 6.0 from a previous version, the system administrator needs to add some content to the configuration of the reverse proxy.

Example for Apache:

ProxyPass /cable ws://127.0.0.1:3000/cable

Example for nginx:

location /cable {
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "Upgrade";
  proxy_set_header CLIENT_IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_read_timeout 86400;
  proxy_pass http://zammad-railsserver;
}

This is required to enable the new Rails Action Cable based realtime communication. You can find more details about this change at this github commit.

Mandatory Redis Dependency

Starting with Zammad version 6.0, Redis is required to run Zammad. For package-based installations, the new dependency is automatically installed in the system during the update.

Note: Hosted customers do not need to take any further action regarding this change!

Health Check API Changes

Starting with Zammad 6.0, the "health check" monitoring API at /api/v1/monitoring/health_check will no longer echo the used authentication token in the response payload.

Excel Export Format Change

Starting with Zammad version 6.0, all Excel exports will be exported exclusively in xlsx format. The original xls format will no longer be supported.

Storage location of unprocessable/oversized emails

Zammad stores emails that were unprocessable or rejected due to size constraints in the file system. The location of such emails changed from tmp/unprocessable_mail and tmp/oversized_mail to var/spool/unprocessable_mail and var/spool/oversized_mail within the /opt/zammad directory. Existing emails are automatically moved to the new location.

Naming change in Token model and EmailAddress model

The token model is used to store access tokens and had field names which may have caused confusion for developers using them. Therefore, the field previously called name: now has the correct identifier token: (as it stores the actual token value), and the field previously called label: is now called name: for better consistency with other models. The EmailAddress model is used to information about email addresses Zammad receives mail for. For consistency reasons, its realname: field is now called name:.

This means that the attribute via the REST API also changes: from token or realname to "name".

Docker image zammad-docker was archived

The repository zammad-docker was intended for testing / development purposes only. This repository was archived and will receive no further updates. Please use zammad-docker-compose instead.