Skip to content
Other versions

Loading…

Migration from 7.1 to 8.2

The OpenKM migration tool installs OpenKM 8.2 next to an OpenKM 7.1 installation, on a new database, and copies the 7.1 repository into it. It copies the data straight between the two databases, so it takes seconds or minutes instead of the hours the Database import would need, and it reuses the text 7.1 had already extracted. OpenKM 7.1 is only read: its database and documents don’t change, and it keeps its service until the migration succeeds. You can download it from https://download.openkm.com/okm/OKMMigrator.jar.

It’s the same tool used for the migration from 8.1 to 8.2: it detects that the old installation is 7.1 and switches to this mode by itself.

Folders, documents with all their versions, records and mails, with their metadata (and its history), notes, keywords, categories, permissions, subscriptions, locks, relations, tasks, bookmarks, users (with their password) and roles, and stamps.

It doesn’t migrate profiles, automation, configuration, activity log, reports, scheduled tasks, mail accounts, OCR templates or workflows. Users with a custom 7.1 profile get the 8.2 default profile: review that profile afterwards (for instance, so the metadata groups are visible). Mail attachments are extracted again by 8.2 from the mail itself.

  • Stamps are migrated with the users they are assigned to, and they work the same: the position expressions and the scripts use the same variables in 8.2. Only a script that uses OpenKM classes may need changes.

These have to be set up again by hand in OpenKM 8.2, before users start working with it:

  • Reports: upload them again in Administration > Reports. OpenKM 8.2 uses JasperReports 7, which only reads its own JRXML format, not the JasperReports 6 one of OpenKM 7.1: open each report in Jaspersoft Studio 7 and save it in the new format first, or it fails with “Unable to load report”. Reports that use OpenKM classes may also need changes.

  • LDAP or Active Directory authentication: it’s not migrated, and its configuration changed in 8.2, so don’t copy the 7.1 keys as they are. Set it up again following LDAP configuration:

    • In openkm.properties, 8.2 only uses okm.authentication.ldap, ldap.server, ldap.base, ldap.manager.distinguished.name, ldap.manager.password, ldap.referral and ldap.user.search.filter. The ldap.role.* keys of 7.1 no longer exist.
    • ldap.manager.password goes in plain text: if in 7.1 it starts with {DES} or {AES}, it’s encrypted, and 8.2 can’t read it.
    • Users and roles are synchronized from the LDAP with the principal.ldap.* settings, in Administration > Configuration.

    Users and roles stored in the database are migrated.

  • OpenKM 7.1 must have a single tenant (the usual case), on MySQL, MariaDB or PostgreSQL.
  • As a database administrator, create the empty 8.2 database, on the same server as the 7.1 one and granted to the same database user. If it doesn’t exist, the tool shows the exact SQL and stops without doing anything. For instance, on MySQL or MariaDB:
CREATE DATABASE okmdb82 DEFAULT CHARACTER SET utf8mb3 COLLATE utf8mb3_bin;
GRANT ALL ON okmdb82.* TO 'openkm'@'localhost';

And on PostgreSQL:

CREATE DATABASE okmdb82 WITH OWNER openkm ENCODING 'UTF8' TEMPLATE template0;
  • External metadata schemas: if a 7.1 metadata group fills its drop-downs with a query to another database (for instance, optionsQuery="select ct_id, ct_name from ama.Origen"), that schema is not copied. Since OpenKM 8.2 uses the same database user as 7.1, on MySQL and MariaDB it can already read it. On PostgreSQL that schema lives inside the 7.1 database: create it in the 8.2 one too, with its data, before starting OpenKM 8.2. Otherwise those drop-downs show up empty and, if someone saves the group like that, the values could be erased.
  • Take a backup of the 7.1 database and repository. The tool doesn’t change them, but it doesn’t take any backup either.
  • Have your OpenKM download portal user and password ready, the same ones you use for the installer. They are needed to download OpenKM 8.2.
  • Download the tool into the base directory of the 7.1 installation (the folder where the tomcat symlink is located) and run it from there:
Terminal window
$ cd /opt/openkm
$ wget https://download.openkm.com/okm/OKMMigrator.jar
$ java -jar OKMMigrator.jar
  • Answer its questions. Each one suggests a value, which you accept by pressing Enter:
    • Folder to install OpenKM 8.2 in: next to the 7.1 one, for instance /opt/openkm-8.2. It’s installed there without touching the 7.1 tomcat symlink or service.
    • Name of the new OpenKM 8.2 database: okmdb82.
    • Folder for the OpenKM 8.2 documents: see Documents.
  • Before changing anything, it checks the requirements and shows what it will install and which folders the documents will be moved from and to. Then it asks for your download portal user and password, and for a confirmation ([y/N]). Type y to continue.
  • From there, it’s automatic: it stops OpenKM 7.1, installs OpenKM 8.2, starts it once so it creates its database schema, copies the data and the documents and, only if everything went well, registers the OpenKM service for 8.2 in place of the 7.1 one.
  • When it’s done, you’ll see ### MIGRATION 7.1 -> 8.2: DONE ### followed by the remaining steps:
    • Start OpenKM 8.2 with its service. Users, okmAdmin included, log in with their 7.1 password.
    • Open <OpenKM URL>/management/updaterUtils and run MailPreviewFromRaw. It regenerates the mail previews and gets the mails ready to extract their text and attachments again.
    • In Administration > Crontab, activate the Mail Extractor Worker task again. The tool leaves it stopped because, without the previous step, it would mark the mails as extracted with no text or attachments.
    • Rebuild the search index from Administration > Utilities > Rebuild indexes. Until then the documents are there, but they don’t show up in searches.
    • Register the license of OpenKM 8.2. It’s a new installation, with its own Installation ID, so it needs its own license, covering all your active users: ask OpenKM for it once OpenKM 8.2 has started for the first time. Until then, it only allows 10 users.

The tool moves the 7.1 documents (datastore) and extracted text (extraction) to new OpenKM 8.2 folders, on the same disk as the 7.1 ones, so it can use hardlinks: it’s instant and takes no extra space. By default:

  • If 7.1 keeps them inside its Tomcat (the usual case), OpenKM 8.2 keeps them inside its own Tomcat.
  • If 7.1 has its repository.home outside Tomcat (for instance, repository.home=/data/repository), OpenKM 8.2 gets its own next to it, with the -8.2 suffix (/data/repository-8.2), as long as it’s on the same disk, and keeps them at the same place inside it: /data/repository-8.2/tenant_1/datastore and /data/repository-8.2/tenant_1/extraction.
  • Otherwise, next to the 7.1 folder, with the -8.2 suffix. For instance, if 7.1 keeps the documents in /mnt/datastore_71, OpenKM 8.2 uses /mnt/datastore_71-8.2.

You can choose another folder for the documents when the tool asks for it. If it’s on another disk, the documents are copied, and the disk needs as much free space as the 7.1 repository takes. To always copy them, even on the same disk, add --copy-files.

If the 7.1 documents folder is a symbolic link (for instance, repository/datastore pointing to /mnt/datastore_71), the tool uses the real folder, and the OpenKM 8.2 one goes next to it (/mnt/datastore_71-8.2), on the same disk. Symbolic links inside the 7.1 folders are not supported: the tool looks for them in the initial checks and stops without changing anything, so replace them with the real folders first.

If OpenKM 8.2 is going to read the documents where they already are (for instance, the same /mnt/datastore_71 or shared storage), add --skip-datastore: they aren’t moved, and the tool sets OpenKM 8.2 to read them there. --skip-extraction does the same with the extracted text. If 7.1 keeps the documents in an S3 bucket, set repository.datastore.type=s3 and its repository.datastore.s3.key-prefix in the 8.2 openkm.properties before starting it.

If 7.1 spreads the documents over several shards (several disks), its folder includes ${shard.id}, for instance /diskN/openkm/${shard.id}/${tenant.id}/datastore. The folder suggested for OpenKM 8.2 keeps it, so each shard stays on its own disk: /diskN/openkm/${shard.id}/${tenant.id}/datastore-8.2.

Once you have checked for a few days that OpenKM 8.2 works correctly, you can remove OpenKM 7.1. Before that, make sure that the Mail Extractor Worker task has processed all the mails (their text and attachments are extracted again from the mail itself) and that the search index has been rebuilt. Until then, keep everything: OpenKM 7.1 is the only way back.

  • Service: nothing to do. The service keeps its name (openkm on Linux, OpenKM on Windows) and now starts OpenKM 8.2; the tool replaced the 7.1 one at the end of the migration. With --no-service, no service was registered.

  • 7.1 database (for instance, okmdb): take a last backup and drop it, for instance DROP DATABASE okmdb;. Don’t drop the database user: OpenKM 8.2 uses the same one. On MySQL and MariaDB, don’t drop either the external schemas that the metadata drop-downs read (see Before you start).

  • 7.1 installation folder (for instance, /opt/openkm, with the 7.1 Tomcat and its tomcat symlink; OpenKM 8.2 is in /opt/openkm-8.2): it can be deleted, and so can the 7.1 documents folders outside Tomcat (for instance, /mnt/datastore_71, or the 7.1 folder of each shard), but first check how the documents were moved (see Documents):

    • Hardlinked (same disk, the usual case): deleting the 7.1 folders removes only the 7.1 names of the files. OpenKM 8.2 keeps its own, so nothing is lost, but no disk space is freed for the documents either: they were never duplicated.
    • Copied (another disk, or --copy-files): the 7.1 files are a duplicate. Deleting them frees that space.
    • 7.1 repository.home outside Tomcat (for instance, repository.home=/data/repository): it can be deleted as a whole. The OpenKM 8.2 one is another folder, /data/repository-8.2: don’t delete it.
    • Not moved (--skip-datastore or --skip-extraction): OpenKM 8.2 reads those folders where they are. Don’t delete them. If they are inside the 7.1 Tomcat, keep that folder too, or first move them and change repository.datastore.home or repository.extraction.home in the 8.2 openkm.properties.

    If the 7.1 folder was a symbolic link, the files were moved from the real folder it points to (for instance, /mnt/datastore_71), which can be deleted like any other 7.1 folder; the link itself goes away with the 7.1 Tomcat. The console summary and OKMMigrator.log say how many files were hardlinked and how many copied. On Linux, ls -l shows a link count of 2 or more on a hardlinked file.

  • Leftovers: OKMMigrator.jar and OKMMigrator.log (in the folder you ran the tool from, inside the 7.1 one), and OKMInstaller.jar and OKMUpdater.jar in the 8.2 folder. Keep OKMUpdater.jar for future updates.

Parameter Description
-p, –old-properties Path to the openkm.properties file of the 7.1 installation. By default, ./tomcat/openkm.properties.
-d, –parent-dir Folder to install OpenKM 8.2 in, without asking.
--target-datastore Folder for the OpenKM 8.2 documents, without asking. It can include ${tenant.id} and ${shard.id}.
--target-extraction Folder for the OpenKM 8.2 extracted text. By default, on the same disk as the 7.1 one.
--source-datastore 7.1 documents folder. By default, the one set in its openkm.properties.
--source-extraction 7.1 extracted text folder. By default, the one set in its openkm.properties.
--copy-files Copy the documents even when they could be moved with hardlinks.
--skip-datastore Don’t move the documents: OpenKM 8.2 is set to read them where they already are.
--skip-extraction Don’t move the extracted text: OpenKM 8.2 is set to read it where it already is.
--no-service OpenKM 7.1 is not configured as a service: its Tomcat is stopped with shutdown.sh, and no service is registered for OpenKM 8.2.
-f, –force Skip the confirmation prompt (for non-interactive or scripted use).
-h, –help Show help information.

The folders passed with --source-* replace the openkm.properties setting, so they can’t be used with a repository spread over several shards.

If the tool stops in the initial checks, nothing has changed: fix what it reports and run it again. If it fails later, OpenKM 7.1 is left as it was, with its service (start it again if you need it), and OpenKM 8.2 half-installed: delete what the message says, drop and create the 8.2 database again, and run the tool again.

Save the full console output and the OKMMigrator.log file (it’s left in the folder you ran it from) and contact OpenKM support if you need help.