Kimirock/zammad
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Maintenance: Overhaul breaking changes entries for 7.0, 7.1 and 7.2.

Browse Source 
Approved-by: Dusan Vuckovic <dv@zammad.com>
This commit is contained in:
Florian Liebe
2026-08-20 15:09:35 +02:00
parent 5f01c16a75
commit 94f5b9ec69
1 changed files with 224 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

324
BREAKING_CHANGES.md
View File

@@ -1,137 +1,239 @@
# Breaking Changes
## 7.3
### Enforced maintenance mode for import_mode
From Zammad 7.3 onwards, if the system is running in import mode, it will automatically also run in maintenance mode.
Import mode was never intended for use in productive environments.
From Zammad 7.2 onwards, you will receive a warning in the "Monitoring" section if your system is still in import mode.
## 7.2
## Upcoming releases
### Inline attachments will be listed separately in ticket article API responses
Ticket article REST API responses (e.g. `GET /api/v1/ticket_articles/{id}`) currently include
inline image attachments in the `attachments` list. Starting with Zammad 7.3, they will no
longer be part of the `attachments` list and will be returned in a dedicated
`inline_attachments` key instead.
**Who is affected?** Integrations that read inline images from the `attachments` list of ticket article
REST API responses.
⚠️ API integrations that rely on inline attachments being part of the `attachments` list
need to be updated to read the new `inline_attachments` key.
Ticket article responses such as `GET /api/v1/ticket_articles/{id}` currently include inline image
attachments in the `attachments` list. In a future release they will no longer be part of that list and
will be returned in a dedicated `inline_attachments` key instead.
### Deleting organizations via API by agents is deprecated
⚠️ Update such integrations to read inline images from the new `inline_attachments` key.
`DELETE /api/v1/organizations/:id` has historically been permitted to users
with only the `ticket.agent` permission. This is now deprecated and will be
restricted to `admin.organization` in Zammad 7.3.
**Related issue:** [#6254](https://github.com/zammad/zammad/issues/6254)
⚠️ API integrations that delete organizations using an agent token should
be updated to use an account with `admin.organization`.
### Deleting organizations via API will require the `admin.organization` permission
### Knowledge Base search index: new `publication_state` field
**Who is affected?** Integrations that call `DELETE /api/v1/organizations/:id` with a token that only
has the `ticket.agent` permission.
Issue #6142 adds a "Suggested searches" shortcut menu to the Knowledge Base search.
A new `publication_state` field is now indexed for `KnowledgeBase::Answer::Translation`,
reflecting the answer's current state (draft, internal, published, archived).
The endpoint has historically been permitted for users with only the `ticket.agent` permission. That is
deprecated and will be restricted to `admin.organization` in a future release; agent tokens will then
receive `403 Forbidden`.
To enable this field, a search index rebuild is required:
⚠️ Switch such integrations to an account with the `admin.organization` permission.
`zammad run rake zammad:searchindex:rebuild`
**Related issue:** [#6315](https://github.com/zammad/zammad/issues/6315)
Without a rebuild, `publication_state:draft` queries return no results.
### Import mode will also enable maintenance mode
### Elasticsearch 7 no longer supported
**Who is affected?** Admins of instances that are left in import mode while users are expected to work
in them.
Elasticsearch 7 has reached end of life and is no longer supported. Zammad now
requires **Elasticsearch 8** or later.
Import mode was never intended for productive environments. In a future release, an instance running in
import mode will automatically run in maintenance mode as well, which prevents non-admin users from
logging in.
⚠️ Please upgrade your Elasticsearch installation before updating to Zammad 7.2.
⚠️ Disable import mode before letting users work in the instance.
### Calendar iCal feed must be a URL
**Related issue:** [#6237](https://github.com/zammad/zammad/issues/6237)
The functionality of using local file paths for calendars iCal feed source was removed.
### `Exceptions::UnprocessableEntity` will be removed
### Deprecated `es-ca` locale inactivated
**Who is affected?** Developers of custom packages, patches or add-ons that still reference
`Exceptions::UnprocessableEntity`.
The deprecated `es-ca` locale (Catalan) is no longer offered for selection.
Users still set to `es-ca` are automatically migrated to the proper `ca`
locale. Existing Knowledge Base locales referencing `es-ca` are left
untouched and must be migrated manually due to the URL change.
The constant, deprecated since Zammad 7.1, will be removed in Zammad 8.0. Code still using it will then
raise `NameError: uninitialized constant Exceptions::UnprocessableEntity`.
### Stricter default Content-Security-Policy
⚠️ Switch to `Exceptions::UnprocessableContent` before updating to Zammad 8.0.
A new `frame-ancestors 'self'` directive was added to the default
Content-Security-Policy header.
**Related issue:** [#6198](https://github.com/zammad/zammad/issues/6198)
⚠️ Setups that previously allowed the Zammad web interface to be embedded in
an `<iframe>` on a different origin by overriding the `X-Frame-Options` header
at the reverse proxy will now be blocked again by the new `frame-ancestors 'self'`
CSP directive. To re-enable embedding from trusted origins, the `frame-ancestors`
directive of the `Content-Security-Policy` response header must be adjusted at
the reverse proxy as well.
### The deprecated `Rails.application.config.db_*` values will be removed
**Who is affected?** Developers of custom packages, patches or add-ons that read database preferences
from the Rails configuration.
The values deprecated with the removal of MySQL support in Zammad 7.0 will be removed in Zammad 8.0.
Until then they emit a deprecation warning and return the value that always applies to PostgreSQL:
- `Rails.application.config.db_null_byte` — always `false`
- `Rails.application.config.db_case_sensitive` — always `true`
- `Rails.application.config.db_like` — always `ILIKE`
- `Rails.application.config.db_column_array` — always `true`
⚠️ Remove branches that depend on these values from custom code and rely on the PostgreSQL behaviour
instead.
**Related issue:** [#5580](https://github.com/zammad/zammad/issues/5580)
## 7.2
### Import mode is reported as an issue by the health check
**Who is affected?** Admins of instances that are left in import mode after a migration, and monitoring
setups that alert on the `health_check` endpoint.
Import mode is only meant for bulk imports and migrations, never for productive operation. The
`health_check` endpoint and the "Monitoring" section therefore now report an issue while `import_mode`
is enabled, which turns a previously green monitoring check red. The same applies while
`system_init_done` is still `false`.
⚠️ Disable import mode once a migration is finished, or expect the monitoring check to stay red.
**Related issue:** [#6236](https://github.com/zammad/zammad/issues/6236)
### Knowledge Base answers index a new `publication_state` field
**Who is affected?** Admins of systems with Elasticsearch enabled who update to Zammad 7.2 without
rebuilding the search index.
The "Suggested searches" shortcut menu added to the Knowledge Base search introduced a new
`publication_state` field for `KnowledgeBase::Answer::Translation`, reflecting an answer's current
state (draft, internal, published, archived). Existing indices do not contain the field, so
`publication_state` queries such as `publication_state:draft` return no results.
⚠️ Rebuild the search index after the update: `zammad run rake zammad:searchindex:rebuild`
**Related issue:** [#6142](https://github.com/zammad/zammad/issues/6142)
### Elasticsearch 7 is no longer supported
**Who is affected?** Admins of systems that still run Elasticsearch 7.
Elasticsearch 7 has reached its end of life and was deprecated with Zammad 7.1. Support for it was
removed with this release, so Zammad requires **Elasticsearch 8** or later.
⚠️ Upgrade the Elasticsearch installation to version 8 or later before updating to Zammad 7.2.
**Related issue:** [#6314](https://github.com/zammad/zammad/issues/6314)
### Local file paths are no longer supported as calendar iCal feed source
**Who is affected?** Admins of instances with a calendar whose iCalendar feed points to a local `.ics`
file instead of an HTTP(S) URL.
Calendars can no longer read their iCal feed from the local file system. Only `http://` and `https://`
URLs are accepted, which is now enforced by a validation of the `ical_url` attribute. Calendars that
still hold a local path stop syncing their public holidays, and saving them fails until the value is
changed.
⚠️ Host the `.ics` file on an HTTP(S) server and update the calendar's iCalendar feed accordingly.
**Related issue:** [#6316](https://github.com/zammad/zammad/issues/6316)
### The deprecated `es-ca` locale was inactivated
**Who is affected?** Admins of instances with users or a Knowledge Base still set to the deprecated
Catalan locale `es-ca`.
The `es-ca` locale, deprecated since Zammad 7.0 in favour of the correct code `ca`, is no longer
offered for selection. Users still set to it are migrated to `ca` automatically. Knowledge Base locales
referencing `es-ca` are left untouched, because changing the locale of a Knowledge Base changes its
public URLs.
⚠️ Migrate a Knowledge Base that still uses the deprecated locale manually:
```ruby
zammad run rails r "KnowledgeBase::Locale.find_by(system_locale: Locale.find_by(locale: 'es-ca'))&.update!(system_locale: Locale.find_by(locale: 'ca'))"
```
**Related issue:** [#5886](https://github.com/zammad/zammad/issues/5886)
### The default Content-Security-Policy became stricter
**Who is affected?** Setups that embed the Zammad web interface in an `<iframe>` on a different origin.
A `frame-ancestors 'self'` directive was added to the default `Content-Security-Policy` response
header. Setups that previously re-enabled embedding by overriding the `X-Frame-Options` header at the
reverse proxy are blocked again by it.
⚠️ To allow embedding from trusted origins, adjust the `frame-ancestors` directive of the
`Content-Security-Policy` response header at the reverse proxy as well.
**Related issue:** [#6087](https://github.com/zammad/zammad/issues/6087)
## 7.1
### Elasticsearch 7 deprecated
### Elasticsearch 7 was deprecated
Elasticsearch 7 has reached end of life and is now deprecated.
**Who is affected?** Admins of systems that run Elasticsearch 7.
⚠️ A future version of Zammad now requires **Elasticsearch 8** or later.
Elasticsearch 7 has reached its end of life and was deprecated with this release. It is still
supported in Zammad 7.1, but a later release requires **Elasticsearch 8** or later.
### Calendar iCal feed must be a URL
⚠️ Plan the upgrade of the Elasticsearch installation to version 8 or later.
Calendars can no longer be configured with a local file path as the iCal feed source. Only HTTP/HTTPS URLs are accepted.
**Related issue:** [#6314](https://github.com/zammad/zammad/issues/6314)
Local file path support is now deprecated. In a future release of Zammad, this functionality will be removed.
### `Exceptions::UnprocessableEntity` was deprecated in favour of `Exceptions::UnprocessableContent`
⚠️ If you previously used a local `.ics`
file path, host the file on an HTTP server and update the calendar's iCal feed URL accordingly.
**Who is affected?** Developers of custom packages, patches or add-ons that reference
`Exceptions::UnprocessableEntity`.
### Exceptions::UnprocessableEntity error is deprecated in favor of Exceptions::UnprocessableContent
The exception was renamed to `Exceptions::UnprocessableContent`, following the rename of the HTTP
status code itself. The old constant still resolves, but it is deprecated and emits a deprecation
warning.
Exceptions::UnprocessableEntity will be removed in Zammad 8.0
⚠️ Replace references to `Exceptions::UnprocessableEntity` with `Exceptions::UnprocessableContent`.
**Related issue:** [#6198](https://github.com/zammad/zammad/issues/6198)
## 7.0
### MySQL support removed, database related application settings deprecated
### MySQL support was removed and database-related settings were deprecated
After a long period of deprecation, support for the MySQL database was removed.
Any systems still running on MySQL need to be migrated to PostgreSQL
_before updating to Zammad 7.0_.
**Who is affected?** Admins of instances still running on MySQL or MariaDB, and developers of custom
packages that read database preferences from the Rails configuration.
The following configuration values are now deprecated and will be removed with Zammad 8.0:
After a long period of deprecation, support for the MySQL and MariaDB databases was removed —
PostgreSQL is the only supported database. Alongside, the following configuration values were
deprecated and will be removed with Zammad 8.0:
- `Rails.application.config.db_null_byte`
- `Rails.application.config.db_case_sensitive`
- `Rails.application.config.db_like`
- `Rails.application.config.db_column_array`
### Fulltext search is now asciifolding
⚠️ Migrate a MySQL or MariaDB installation to PostgreSQL _before_ updating to Zammad 7.0, following the
[migration documentation](https://docs.zammad.org/en/latest/appendix/migrate-to-postgresql.html).
The global search, as well as other fulltext searches, are now [asciifolding](https://github.com/zammad/zammad/pull/5536).
To enable this behaviour, it is needed to rebuild the search index:
**Related issue:** [#5580](https://github.com/zammad/zammad/issues/5580)
`zammad run rake zammad:searchindex:rebuild`
### Fulltext search ignores diacritics by default
If the behaviour is unwanted then it also can be disabled and no rebuild is needed:
**Who is affected?** Admins of systems with Elasticsearch enabled, especially those who rely on
searches matching diacritics exactly.
The global search and other fulltext searches now use the Elasticsearch
[asciifolding](https://github.com/zammad/zammad/pull/5537) analyzer, which is enabled by default:
searching for `Munchen` matches `München` and vice versa. With the analyzer disabled, searching for
`Munchen` does not match `München`.
The new behaviour only applies to a rebuilt search index. To keep the previous behaviour instead,
disable the `es_asciifolding` setting — no rebuild is needed in that case:
`zammad run rails r "Setting.set('es_asciifolding', false)"`
Example for asciifolding searches:
**enabled (new default)**: Searching for `Munchen` will match `München`.
**disabled**: Searching for `Munchen` will not match `München`.
Thanks to [Jano Suchal](https://github.com/jsuchal) for the contribution.
### nginx configuration update
⚠️ Rebuild the search index after the update: `zammad run rake zammad:searchindex:rebuild`
Please update your nginx configuration file to insert the line `proxy_http_version 1.1;` to the `location /`
section like in the example below:
**Related issue:** [#3782](https://github.com/zammad/zammad/issues/3782)
### nginx configuration requires `proxy_http_version 1.1`
**Who is affected?** Admins of installations that use an nginx reverse proxy with a configuration file
from an earlier Zammad version.
The nginx configuration shipped with Zammad sets `proxy_http_version 1.1;` for the main location as
well, so that all proxied requests use HTTP/1.1 like the websocket and cable locations already did.
Existing configuration files are not changed by the update.
⚠️ Add the line to the `location /` section of the nginx configuration:
```diff
location / {
@@ -139,40 +241,62 @@ section like in the example below:
proxy_set_header Host $http_host;
```
### Disallow assigning the same organization as primary and secondary
**Related issue:** [#6317](https://github.com/zammad/zammad/issues/6317)
It is no longer allowed for the same organization to be assigned as both a primary and a
secondary organization of a user. An automatic migration makes sure the user data is in a consistent
state after the update.
### Assigning the same organization as primary and secondary is no longer allowed
⚠️ Before upgrading, ensure that no calls to the API are used that try to put users in this invalid state.
User records cannot have the same organization set as both primary and secondary anymore, and trying to
do this will now result in an API error.
**Who is affected?** Integrations that write user records via API and set the same organization as both
primary and secondary organization.
### Catalan locale change
The same organization can no longer be a user's primary and secondary organization at the same time.
Such requests now fail with a validation error, and an automatic migration brings existing user data
into a consistent state during the update.
The previously available Catalan locale used a wrong internal locale code and was deprecated. There is now a
new Catalan locale with the correct code "ca". The deprecated locale will be removed in a future release of Zammad.
An automatic update will switch the language preference of all Catalan user profiles to the new 'Catalan (Català)'
locale during the migration.
⚠️ Update API calls that put users into this state before updating.
The following applies only in case you are already using Knowledge Base with Catalan language. Please note the
deprecated Catalan locale will not be updated automatically. Changing the locale of a Knowledge Base causes a change in
the public URLs. You can migrate Knowledge Base at your own pace by running the following command:
**Related issue:** [#5254](https://github.com/zammad/zammad/issues/5254)
### The Catalan locale moved to the correct `ca` locale code
**Who is affected?** Admins of instances with users using the Catalan locale, and especially those with
a Catalan Knowledge Base.
The previously available Catalan locale used the wrong internal locale code `es-ca` and was deprecated;
it will be removed in a future release. A new Catalan locale with the correct code `ca` is available,
and a migration switches the language preference of all Catalan user profiles to the new
"Catalan (Català)" locale.
Knowledge Base locales are not migrated automatically, because changing the locale of a Knowledge Base
changes its public URLs.
⚠️ Migrate a Knowledge Base using the Catalan language at your own pace:
```ruby
zammad run rails r "KnowledgeBase::Locale.find_by(system_locale: Locale.find_by(locale: 'es-ca'))&.update!(system_locale: Locale.find_by(locale: 'ca'))"
```
### Slack integration removed
**Related issue:** [#5886](https://github.com/zammad/zammad/issues/5886)
The slack integration was remved from the codebase. It is recommended that you
[switch to pre-built webhooks instead](https://admin-docs.zammad.org/en/latest/manage/webhook/examples/slack-notifications.html).
Existing Slack integrations should be migrated manually, if not already done.
### The Slack integration was removed
### Twitter integration removed
**Who is affected?** Admins of instances that still use the Slack integration.
The Twitter integration was removed due to problems with API licensing. There is no replacement available.
The Slack integration was removed from the codebase; existing configurations stop working and are not
migrated automatically. Everything the integration did can be achieved with webhooks, see
[Slack notifications via webhook](https://admin-docs.zammad.org/en/latest/manage/webhook/examples/slack-notifications.html).
⚠️ Recreate existing Slack notifications as webhooks, if not already done.
**Related issue:** [#5583](https://github.com/zammad/zammad/issues/5583)
### The Twitter integration was removed
**Who is affected?** Admins of instances that still have a Twitter/X channel configured.
The Twitter integration was removed due to problems with the API licensing, and there is no replacement
available. Existing tickets and articles stay accessible, but no messages are fetched or sent any more.
**Related issue:** [#5581](https://github.com/zammad/zammad/issues/5581)
## 6.5.2