Skip to content

Botium Box Migration Steps

Usually, Botium Box database migration is done automatically on the fly. There are some occasions where this is not possible. You fill find the manual steps described here.

IMPORTANT: When migrating over multiple versions, you have to follow the whole migration path - for example, when upgrading from 1.3 to 1.5, you will first have to upgrade from 1.3 to 1.4, and then from 1.4 to 1.5

The general process is:

  1. Follow the Update Instructions (On-Premise)

  2. Do what is described in the Upgrade Preparation Steps

  3. Start Botium Box to do the automated part of the migration

  4. Do what is described in the Upgrade Finalization Steps

x.x => 2.13.1

In some rare cases, especially when coming from a rather old Botium Box instance, it might happen that during the automatic database migration an error is shown like:

Migration name: 20220202153953_bot_2814_add_cascade_delete

Database error code: 1091

Can't DROP 'TrainerIgnoredTestScript_ibfk_1'; check that column/key exists

In these cases, there are some manual steps required to finish the database migration.

  • Connect to the Botium Box shell with docker exec -u 0 -it botiumbox_web_1 bash
  • Run these commands one after the other:
  • cd /app/server
  • npx prisma migrate diff --preview-feature --from-url "$DATABASE_URL" --to-schema-datamodel prisma/schema.prisma --script > /tmp/forward.sql
  • npx prisma db execute --preview-feature --url "$DATABASE_URL" --file /tmp/forward.sql
  • npx prisma migrate resolve --applied 20220202153953_bot_2814_add_cascade_delete
  • npx prisma migrate resolve --applied 20220202163336_bot_2759_test_session_aggregators
  • npx prisma migrate resolve --applied 20220204091221_bot_2759_test_project_script_aggregator
  • Finally, restart Botium Box with docker-compose restart

In case an error message is shown like:

Duplicate key name 'overallStat'

then please run the SQL statement ALTER TABLE TrainerSession DROP FOREIGN KEY TrainerSession_ibfk_1 manually on your MySQL database and repeat the above steps.

x.x => 2.11.0

Upgrading to Botium Box 2.11.0 is possible only from 2.10.2! So if you are not running 2.10.2, please upgrade to 2.10.2 first!

In your docker-compose.yml:

  • Remove the prisma service
  • Remove the PRISMA_ENDPOINT environment variable from web service
  • Add DATABASE_URL environment variable to web service: mysql://root:prisma@mysql:3306/box@prod2
  • Remove prisma from the depends_on of web service, and add mysql instead
  • Add command: "sleep 100000" to web service to prepare everything for the following migration steps
  • Restart with docker-compose up -d --remove-orphans

Now there are some steps involved to migrate the Botium Box 2.10.2 database to 2.11.0:

  • Connect to the Botium Box shell with docker exec -u 0 -it botiumbox_web_1 bash
  • Run this command to launch the database migration: cd /app/server && node prisma/migratefromprisma1.js
  • Run this command to finish the database migration: npx prisma migrate resolve --applied 20211022115835_initial_migration

Finally, remove the command: "sleep 100000" from the web service and restart Botium Box once again. The final migration steps will be done by Botium Box automatically, as usual.

x.x => 2.9.0

Starting with Botium Box 2.9.0, the the Botium processes within Docker are running with a non-root-user (node). On Linux, you have to change the host directory permissions to allow access for user id 1000 and group id 1000. In some cases, this can be done by using chown, in other cases please consult your Linux administrator.

> sudo chown -R 1000:1000 resources/
> sudo chown -R 1000:1000 testsets/
> sudo chown -R 1000:1000 botiumwork/

x.x => 2.2

With Botium Box 2.2, there is a new Prisma database version included, automatic data migration is not possible. When updating Botium Box 2.2, you will be presented with an empty Botium Box on first login (you have to use the default users to login). Don’t worry, your data is not gone, it is just in another storage an has to be migrated!


You can use this process to migrate data from a totally different Botium Box installation as well. It is possible to specify not only the Prisma endpoint form where to migrate, but also the Prisma secret:

  • PRISMA_SECRET field in rundatamigration.json

  • or RUNDATAMIGRATION_PRISMA_SECRET environment variable

  • by default, the Botium Box Prisma secret will be used).

File System Access available

Create file named rundatamigration.json with the following content and upload it to the resources folder of your Botium Box:

  "PRISMA_ENDPOINT": "http://prisma:4466/box/prod"

For Community Edition:

  "PRISMA_ENDPOINT": "http://prisma:4466/box/ce"


You can upload this file by FTP (when running Azure Web App), or copy directly to the server directory if you have access to it. You can as well use the File Browser in the Settings section of Botium Box.

Afterwards, restart Botium Box server to run the migration. This can take a while because a full data export and data import is done in the background. Watch the server log output for progress. When ready, Botium Box will restart once more automatically.


You can use the Restart button in the System Settings section of the Botium Box, or use your container technology to restart it.

Or With Environment Variables

Depending on your infrastructure, you maybe want to use environment variables instead of JSON file to trigger the migration. Using your container technology, set the environment variables:

  • RUNDATAMIGRATION_PRISMA_ENDPOINT (http://prisma:4466/box/prod or http://prisma:4466/box/ce)


When using this option to run the migration, you will have to restart Botium Box after the migration is ready - watch the server log output for progress. Important: Remove the environment variables before restarting, otherwise the migration will be done again!

1.x => 2.0

When upgrading from Botium Box 1 to Botium Box 2, there is some manual work to be done for database migration. After installation, the Botium Box Server will fail to start as the database migration is not possible. Follow these steps to migrate your data to Botium Box 2.0:

  1. Get SSH access to the container running Botium Box - see here

  2. Install a text editor for convenience, for example nano: apk add nano

  3. Edit the file /app/server/database/datamodel.graphql

    1. Comment out line 23 by adding a hashtag: # envs: …

    2. Comment out line 47 by adding a hashtag: #envs: …

  4. Run a first migration step: npm run prisma-deploy

  5. Again edit the file /app/server/database/datamodel.graphql and remove the hashtags in line 23 and line 47

  6. Logout


When upgrading directly from 1.x to 2.2, you won’t have to do this, you can use the instructions above to migrate to 2.2 directly and skip the 2.0 upgrade.

1.x => 1.8

  • Botium Box paid editions only: for Shared Folders in the “testsets” volume, now there are relative paths used. If you already registered shared folders in your Botium Box with absolute path (for example: /app/server/testsets/my-testset/), you have to convert it into a relativ path now for the agents to find them (./testsets/my-testset/).

  • Matching mode “regexp” is now case sensitive. For doing case insensitive regular expressions, use new matching mode “regexpIgnoreCase”

1.x => 1.7.4

  • Test case naming / partial convo naming in Excel files has changed for bot-triggered convos or partial convos

1.6 => 1.7

  • The Excel settings configuration are now global in the Test Set view (previous: in local repository), and are now valid for local as well as remote repositories. There is no automatic transfer of the settings done, you will have to reconfigure them manually.

  • The API Keys are now part of the permission system. You should have a look at your API Keys and restrict the access rights. By default, migrated API Keys have full API permissions (not recommended).

1.5 => 1.6

Manual steps required ? no

1.4 => 1.5

Manual steps required ? no

1.4 => 1.4.1

Manual steps required ? yes

Upgrade Preparation Steps


Upgrade Finalization Steps

Botium Box 1.4.1 has now client management. Existing users are migrated to the default client.

  • Open Botium Box and go to Settings / User Management

  • Review existing users and re-assign clients if needed

1.3 => 1.4

Manual steps required ? yes

Upgrade Preparation Steps


Upgrade Finalization Steps

Botium Box 1.4 has new user role management. Existing known users are migrated to the new roles.

  • Open Botium Box and go to Settings / User Management

  • Review existing users and re-assign roles if needed