Incompatibility Changes (Breaking Changes) for Zammad 4.0

Zammad 4.0 does not only include features worthy of a major release - we have also taken the opportunity to change or completely remove features and interfaces for various reasons. The corresponding details and necessary adjustments are explained below.

Manual Actions

We try to avoid manual actions with every new Zammad version. Usually we manage, but sometimes there is no other way. The manual customizations you need to take if you use the functionality are described below.

Update Elasticsearch Index

Careful: This process can take several hours depending on the amount of data in the system.

Note: The following manual actions only affect Zammad systems that have not been installed by the operating system's package manager. For package installations, the action is performed automatically.

For the new reporting functionalities, it was necessary to change the structure of the Elasticsearch index. Therefore, the Elasticsearch index must be rebuilt by running the following command:

rake searchindex:rebuild

Change in the structure of advanced search queries

For the new reporting functionalities, it was necessary to change the structure of the Elasticsearch index - and therefore also the structure of advanced search queries.


Instead of = Support, you now need to use = Support. The difference is the .name.

More information and examples can be found in the To-do documentation.

Facebook permissions

It's been a while since the Zammad <> Facebook integration was released. In the meantime, a lot has happened in terms of Facebook and the interface used. Now it has come to the point that the interface Zammad uses is being discontinued by Facebook and can no longer be applied. Therefore, we have updated the integration to the most current Facebook interface version. As part of this, it is necessary to update the permissions as the name and scope on Facebook's site have changed.

To enable the new permissions for Zammad, the Facebook integration must be updated. This requires adding a new Facebook integration using the same API credentials. Zammad will recognize the credentials and update the integration instead of adding a new one.

Removed Functionalities

The following functionalities have been completely removed and are no longer available in Zammad 4.0. They were rarely if ever used. However, the reasons for removal are different.

Facebook user posts

Facebook has been criticized often on the topic of data protection. Among other things, it was possible for third parties to access user posts via public interfaces. The analyzed data could be used to create new personal profiles, which were then used for illegal purposes.

Zammad uses the same interfaces to manage user pages in addition to Facebook company pages and to import posts to reply to them.

This interface has been disabled and removed by Facebook. As a result, the feature is no longer available to Zammad either. Company pages are not affected and can still be integrated and used in Zammad.

Generic OAuth2 Provider

With Zammad, it should be possible to easily integrate other or your own in-house OAuth2 providers to authenticate users, in addition to the well-known OAuth2 providers like Facebook, Microsoft, etc. Unfortunately, this is not possible with the "Generic OAuth2 Provider", which always leads to confusion and questions. Therefore, we have decided to remove the function completely until further notice.

However, this function will come in the future. You can subscribe to to be informed about the progress.

Changes to internal and REST APIs

Zammad's open architecture allows for a variety of extensions and connections. Interfaces are always used, whether they are internal code interfaces or HTTP REST interfaces for API clients. Sometimes, these interfaces are added, adapted, or removed. Here’s what’s changing:

HTTP Status Code 401 / 403

In the past, the HTTP status code 401 (Unauthorized) was incorrectly used to report missing access permissions. This caused some SSO setups to automatically log out users when they sought unauthorized access to resources. In fact, this happens faster than you’d think, for example when a ticket in one's taskbar is moved to a group where one has no permissions.

The correct HTTP status code for this is 403 (Forbidden). We have made the corresponding corrections. Zammad now returns 401 as the HTTP status for login errors and 403 instead of 401 for access without permissions. This may need to be corrected in clients or other integrations that access the HTTP REST API directly.