Migrate from OTRS to Zammad

The OTRS importer only carries over password hashes when the source system runs OTRS 3.3 or later. Before you commit to a cutover date, confirm the exact OTRS version in your environment, because this single fact decides how agents and customers sign in on day one. If your installation predates 3.3, the imported accounts will exist in Zammad but will not carry working passwords, so every user will need a reset path. Plan that path as a deliberate step rather than something support discovers on the first morning after cutover.

The importer also limits which people come across. Only customers who appear on tickets are imported. A customer who has never opened or been named on a ticket will not exist in Zammad after the run, even if they hold an active account in OTRS. If your business expects those customers to log in to a portal, submit requests or receive notifications, they need a separate route. Options include creating them through the Zammad API from an export you produce, or inviting them after go-live. Ask your team to export the list of OTRS customer accounts without tickets now, so the gap is sized before the test import rather than after.

Three decisions should be settled before the test import runs. First, name the agents and customers who must log in on day one, and decide whether any group waits. Second, decide how password resets are communicated: who sends the message, which channel is used, what the user is told to do, and how you will verify that a reset request reached the right mailbox. Third, assign an owner for customer data cleanup. Imported records often include duplicates, stale addresses and inconsistent names, and Zammad will not resolve them for you. The cleanup owner should review the test import output and sign off on what moves into production.

These decisions also determine how you use the test import. Because a differential import is only possible if nobody changes data in Zammad after the first run, any cleanup performed in Zammad during testing will complicate the cutover. Agree with the cleanup owner that corrections happen in the source data or in a documented export, not in the target. Record the login approach, the customer scope and the cleanup sign-off in the migration plan so that the production run, which must follow the same rules, has no open questions left.

Decide the cutover approach only after you have confirmed how your OTRS database stores and presents times. Zammad expects OTRS timestamps in UTC. If your OTRS instance keeps ticket times in a local zone, or the display time zone setting in OTRS differs from what the database holds, every imported article, state change and escalation time can shift by the offset. Agents then see history that appears to have happened at the wrong hour, and SLA and reporting figures built on those times become unreliable. Ask your OTRS administrator to confirm the storage format and the configured time zone, then compare the created and updated values of several known tickets in the database with what the agent interface shows. Record the result before you plan any import run.

A differential import depends on one rule: no data may change in Zammad after the first import. Any agent reply, state or priority change, merge, tag edit or customer update made in Zammad after that run becomes a difference the next run may not reconcile correctly. If a delta run is part of the plan, agents must keep working in OTRS until cutover, and the team must agree on which objects are covered by that freeze, including users, groups and roles that are imported alongside tickets. Make the freeze a written rule, assign someone to enforce it on the Zammad side, and test it with a trial import before anyone relies on it. Confirm in the current Zammad OTRS migration documentation exactly which objects the differential logic covers for your version.

The choice is between one full import at cutover and a staged approach with differential runs. A single full import keeps the runbook short: OTRS is frozen once, the complete history loads in one window, and one verification pass decides go or no-go. The cost is that the whole load, including large ticket histories, must finish inside that window, which is why the read and total timeout variables, ZAMMAD_OTRS_IMPORT_READ_TIMEOUT and ZAMMAD_OTRS_IMPORT_TOTAL_TIMEOUT, need testing with a representative copy of your data. A staged approach moves most history early, lets agents review it in Zammad and shortens the final freeze, but it extends the period in which two systems hold data, adds verification work for each run and requires that OTRS stays the working system until cutover. Staff time on both sides, and any extra environment you run for trials, are the main recurring costs.

Confirm which approach the current documentation supports before you commit. The Zammad OTRS migrator covers OTRS 3.1 up to 6.x, and it needs the version-specific Znuny4OTRS-Repo and OTRS Migration Plugin packages installed in OTRS. Check the migration documentation for the exact version pair you plan to use, and check that the Znuny and plugin packages match your OTRS version. If the documentation supports differential runs for your combination, ask for that in writing from your Zammad partner or vendor contact, along with the steps for the delta. If it does not, the cutover is a single import and your trial runs become the only rehearsal. Either way, write the chosen approach, the freeze window owner and the go or no-go criteria into the migration plan before any production import starts.

Large OTRS ticket histories can run into timeouts during import into Zammad, and the Zammad OTRS migration documentation names two environment variables for this case: ZAMMAD_OTRS_IMPORT_READ_TIMEOUT and ZAMMAD_OTRS_IMPORT_TOTAL_TIMEOUT. The read timeout governs how long a single request waits for data, while the total timeout caps the whole import run. Before changing either value, confirm in the current Zammad documentation what each one controls, its default and its unit, because the unit determines whether a number like 600 means seconds or minutes in your environment.

Start by measuring how large the history actually is on the copy you will import from, not on the live OTRS system. Count tickets, articles and attachments per year or per queue, and note the largest individual ticket threads, since a few very long threads can slow a request even when the overall count looks modest. Check the size of the OTRS database and the attachment storage as well. These figures give you a baseline to compare against the import log and show whether the import is slow because of data volume, network latency or the Zammad host itself.

Set the values in the environment configuration for the deployment method you chose. For a Docker Compose installation, this usually means the environment file read by the Zammad containers that run the import, and for a Kubernetes Helm deployment it means the values passed to the chart. Restart the services that consume the variables so the new values take effect, then confirm inside the running container that they are set. Keep the change in version-controlled configuration where possible so the same values can be reapplied to the final import run.

Test the timeout values on the test import, not for the first time at cutover. A test run shows whether the chosen values are long enough for your largest tickets and whether the total timeout leaves room for the full dataset at its current size. It also gives you the import duration to plan the cutover window. Because OTRS data cannot be changed in Zammad if a differential import is planned, a timeout failure during the final run leaves little room to adjust and retry under pressure. Treat the test as the place where you find the right values.

Record every value used during testing: the variable names, the numbers and units confirmed from the documentation, the Zammad and OTRS versions, the deployment method, the dataset size and the import duration. Store this record with your migration runbook. The final import then repeats the same configuration, and any difference in results can be traced to data growth or infrastructure rather than to an untested setting. Ask whoever runs the import to confirm that the record matches the environment before the cutover begins.