Moving off OTRS/Znuny without a big-bang migration

Step by step

The migration has six phases. You can stay in any phase for as long as you like, from a day to several months. Every phase before the last one can be undone without restoring a backup.

Who owns what, phase by phase

Phase 0
Back up, and prove the backup restores

Before anything touches the production database, take a dump and restore it into a scratch database. A backup job that reports success does not prove the restore works. The same restored copy is a good staging environment for trying out phases 1–4.

# MariaDB / MySQL: --single-transaction avoids locking a live Znuny
mysqldump --single-transaction --routines --triggers \
  -h db.example.internal -u backup_user -p \
  znuny_production > znuny_pre_tiqora_$(date +%Y%m%d).sql

# PostgreSQL
pg_dump --format=custom -h db.example.internal -U backup_user \
  znuny_production > znuny_pre_tiqora_$(date +%Y%m%d).dump

Phase 1
Install Tiqora next to Znuny

Deploy the tiqora-api and tiqora-worker containers, plus Redis and Meilisearch (both are in the example Compose file). Give Tiqora its own database user with SELECT, INSERT, UPDATE, DELETE on the Znuny database. Do not grant ALTER or DROP, and do not reuse Znuny's credentials. Then point DATABASE_URL at the existing database:

environment:
  DATABASE_URL: mysql+aiomysql://tiqora:…@db.example.internal:3306/znuny_production
  # or: postgresql+asyncpg://tiqora:…@db.example.internal:5432/znuny_production
  # TIQORA_SCHEMA_OWNERSHIP stays unset for the whole parallel period

Create Tiqora's own tables and build the search index:

docker compose run --rm --entrypoint tiqora tiqora-api migrate upgrade
docker compose run --rm --entrypoint tiqora tiqora-api index rebuild

tiqora migrate upgrade only creates tiqora_* tables. The migrations that may touch Znuny's tables sit in a separate chain that stays locked until phase 5. Check Admin → System info to confirm the detected schema profile matches your Znuny version.

If you use PGP or S/MIME, mount Znuny's keyring and certificate directories into the containers. Tiqora uses the same key stores and respects the same SysConfig switches. The customer portal is off by default; turn it on with TIQORA_PORTAL_ENABLED=true.

Now give a small pilot group the Tiqora URL. Technically they can already edit tickets, so tell them clearly that this is an evaluation for now.

Phase 2
Keep Znuny's cache in step

Znuny caches tickets in memory. When Tiqora writes straight to the database, Znuny does not see the change until the cache expires. The fix is TiqoraSync, a small optional OPM add-on (GPL-3.0, Framework 6.0.x–7.3.x). Install it into the running Znuny:

bin/znuny.Console.pl Admin::Package::Install /path/to/TiqoraSync-1.1.1.opm
# OTRS 6.0: bin/otrs.Console.pl

It adds one Znuny scheduler task that runs every minute. The task reads the invalidation signals Tiqora writes alongside each ticket change and clears those tickets from Znuny's cache. Worst-case staleness in the Znuny UI is therefore about 60 seconds. If you cannot install add-ons, lowering Znuny's cache TTLs is the documented fallback.

Check it: create or edit a queue in Tiqora and confirm it shows up in Znuny without a restart.

Phase 3
Agents switch, Znuny keeps the daemons

There is no global "writes on" switch. This step is a decision you communicate: tell a team that Tiqora is now their main interface for their queues. Expand team by team. Znuny's daemon keeps fetching mail, sending notifications and running escalations, so nothing about mail flow changes yet.

Tickets edited in Tiqora are stored in Znuny's format with Znuny's history rows, so an agent who opens the same ticket in Znuny sees a normal Znuny ticket.

Phase 4
Hand over the daemons, one flag at a time

Each background duty moves on its own. Every Tiqora worker job has a flag in tiqora_settings, off by default, which you switch under Admin → Services. The worker picks up the change on its next tick without a restart. Run each duty on one side only, or work gets done twice: two tickets for one mail, notifications sent twice. Always switch Znuny's side off first, then turn Tiqora's on.

Recommended order:

Escalations go first because the math is deterministic: a short overlap just computes the same value twice. Inbound mail goes last because a mistake there costs the most. With POP3/IMAP delete-after-fetch, two fetchers can create duplicate tickets or lose mail. Auto-responses do not get a flag of their own; they move with the postmaster. Pending reminders only reach anyone once notifications are on Tiqora's side.

A cron task is switched off in Znuny like this:

bin/znuny.Console.pl Admin::Config::Update \
  --setting-name "Daemon::SchedulerCronTaskManager::Task###MailAccountFetch" \
  --valid 0
# then deploy, and confirm the task is really gone:
bin/znuny.Console.pl Maint::Daemon::Summary

Before taking over notifications, list which events your rules actually listen to:

SELECT ne.name, nei.event_key, nei.event_value
  FROM notification_event ne
  JOIN notification_event_item nei ON nei.notification_id = ne.id
 WHERE ne.valid_id = 1 AND nei.event_key IN ('Events', 'Recipients')
 ORDER BY ne.id;

Rules carried over from older OTRS versions are often bound to the legacy Notification* events. Tiqora emits those too, but a rule bound to an event nobody emits never fires, even while the takeover reports healthy runs. Also set notification.sender_email explicitly so notifications do not go out from the queue's address.

For each duty: disable the Znuny task, set the Tiqora flag, wait at least one interval, and check that the work happened exactly once (one ticket per test mail, one history row per escalation event). Only then move on to the next duty. GenericAgent jobs with NewDelete stay inactive until you also set daemon.generic_agent.allow_delete.

Phase 5
Cutover: Znuny off, schema ownership on

You get here when all six flags have run cleanly in production for a representative period. The cutover runbook has its own preconditions. The most important ones: a freshly tested restore, a maintenance window, and an inventory of everything the Znuny host still does (OS cron jobs, add-ons, calendar jobs, the outgoing mail_queue). Then:

1. Freeze Znuny's web UI. Put a 503 maintenance response on the nginx vhost in front of index.pl/customer.pl, and leave Tiqora reachable.
2. Check the flags and stop the Znuny daemon. All six daemon.*.enabled flags must be 1. Stop the daemon and confirm it stays stopped through at least one full interval and the next scheduled job time.
3. Repoint GenericInterface clients (optional). Only needed if external integrations call Znuny's webservices. An nginx rewrite from nph-genericinterface.pl to Tiqora's /znuny-compat layer covers the common Session* and Ticket* operations over REST and SOAP. Test each operation your integrators use.
4. Monitor. Watch error rates and per-service status under Admin → Services for at least an hour, or a business day for a cautious rollout.
5. Set the operation mode on purpose. Switching system.operation_mode to tiqora_primary can activate AI auto-reply rules that were configured but inactive. Review them first.
6. Take schema ownership. Only now may Tiqora run migrations that touch Znuny's tables. This takes two separate switches:

tiqora ownership status
tiqora ownership enable --confirm "I have shut down Znuny"
# preflight: ticket_history idle ≥ 15 min, Znuny sessions table empty

# then set TIQORA_SCHEMA_OWNERSHIP=1 on every Tiqora process and restart
tiqora migrate upgrade
tiqora ownership orphan-report   # optional, read-only

The first owned migration today only adds three composite indexes. It does not change any rows. Afterwards, archive Znuny's crontab and decommission its frontend. TiqoraSync is retired together with Znuny.

What is not there yet, and what is out of scope

Tiqora covers everyday agent, customer-portal and admin work. Some things are still missing or narrower than in Znuny. Check this list against how your team actually works (as of 1 October 2026):

The daemon ports also have documented simplifications. Escalation "notify before" uses one fixed window instead of per-SLA percentages. Notifications send by email only and ignore per-agent opt-outs. The postmaster converts HTML mail to plain text more crudely and matches customers by login or email only. The full lists are in the compatibility notes and in the "Uncertainties" sections of the parallel-operation guide. Read them before phase 4; this is exactly where running both systems side by side helps, because you find out on real traffic and can still switch back.

FAQ