Upgrade from ADOIT 16.0 to ADOIT 17.0 (ArchiMate Library)
If you are planning to upgrade from ADOIT 16.0 to ADOIT 17.0, this guide will walk you through the necessary steps to ensure a smooth transition.
Prerequisites
Before you proceed, note the following prerequisites:
Before installing, make sure that all Hardware/Software Requirements are met.
Download the ADOIT 17.0 installation package (your ADOIT consultant will email you a link).
Create a backup of the ADOIT database.
ArchiMate Application Library for ADOIT 17.0
You can get started right away if you are using the default ArchiMate Application Library that comes with ADOIT.
Please contact your ADOIT consultant if you are using an ArchiMate Application Library with changes in the metamodel to upgrade your application library.
Stop Services
First, the ADOIT 16.0 application server and the Apache Tomcat web server have to be stopped.
To stop the services (on Windows):
Open Services. Press <Windows> + <R> to open the Run box, enter services.msc, and then click OK.
Stop the ADOIT application server (service name e.g. "ADOITServer16.0Service") and the Apache Tomcat web server (service name e.g. "Tomcat9").
Export Component Settings
Component settings allow you to adapt a wide range of library-specific features. To ensure you don't lose your settings during the upgrade, it's essential to export the ADOIT 16.0 component settings now. Later, you will have to re-import them after updating the application library.
To export the component settings:
In the ADOIT 16.0 Administration Toolkit, go to Library Management > Component Settings.
Select your library, and then click Export component settings.
Select Export all component settings to export all settings at once. Alternatively, you can clear the check box and select the component settings you want to export.
In the Export file box, enter a name for the export file.
Click Export. The data is exported.
Backup Deployment-Specific Data
Deployment-specific data encompasses various settings and information that are not stored in the database. This includes comments on models and objects, settings such as server ports, and more.
Depending on your ADOIT 16.0 installation, you have to back up the following folders and files:
ADOIT Application Server Configuration
<ADOIT 16.0 application server>/conf/server.conf
(contains the database name, application server or aworker processes ports, and trusted IP address of the web server).<ADOIT 16.0 application server>/conf/adoxx.conf
(optional, if parameters have been changed from their default value)<ADOIT 16.0 application server>/conf/adoxx_web_conf.js
(optional, if parameters have been changed from their default value)<ADOIT 16.0 application server>/conf/module/afts_server.conf
(optional, if the Java heap size for the full-text search engine has been increased)
Apache Tomcat Configuration
<Tomcat>/webapps/ADOIT16_0/adoxx_web.properties
(contains the application server IP address and definition of aworker processes)<Tomcat>/webapps/ADOIT16_0/WEB-INF/classes/logback.xml
(optional, if logging parameters have been changed)<Tomcat>/webapps/ADOIT16_0/WEB-INF/web.xml
(optional, if additional file types have been whitelisted for uploading)<Tomcat>/webapps/ADOIT16_0/WEB-INF/registry/rest/RESTAuthorization.xml
(part of the REST API configuration)<Tomcat>/webapps/conf/server.xml
(contains encoding settings (UTF-8), SSL/TLS configuration, and more)
Comment Data
<Tomcat>/webapps/ADOIT16_0/WEB-INF/registry/collaboration
(contains XML files that hold all comments for a model or object)<Tomcat>/webapps/ADOIT16_0/WEB-INF/registry/upload
(contains files that were uploaded along with comments)<Tomcat>/webapps/ADOIT16_0/WEB-INF/registry/axw.ids
(contains the last assigned and highest comment ID)
Upgrade the Database Schema
The database schema has changed between ADOIT 16.0 and ADOIT 17.0 to accommodate new features. To
continue using your existing database with ADOIT 17.0, you must run an upgrade script. This script
can be found in the ADOIT 17.0 installation package under
02 Application Server\BOC\ADOIT 17.0\data\migration\platform
.
Upgrade Database Schema for Microsoft SQL Server
For Microsoft SQL Server databases, use the tool »SQL Server Management Studio« to run the upgrade script:
Start SQL Server Management Studio. In the Connect to Server dialogue box, enter the required information such as Server type, Server Name and Authentication mode. Then, click Connect.
Open the script
sqlserver_upgrade2800aTo2900b.sql
by clicking the Open File button. Select your database from the Available Databases dropdown list and run the script with Execute ("F5").Close SQL Server Management Studio.
Upgrade Database Schema for Oracle
For Oracle databases, use the tool »SQL Plus« to run the upgrade script:
Open a Windows command prompt and enter the command
sqlplus.exe system@<DB name>
, replacing<DB name>
with your database name. When prompted, enter the password for the database usersystem
.Run the script
oracle_upgrade2800aTo2900b.sql
with the following command:start <pathname>\oracle_upgrade2800aTo2900b.sql
, where<pathname>
is the script's location.Close SQL Plus with exit.
Upgrade Database Schema for PostgreSQL
For PostgreSQL databases, use the tool »pgAdmin« to run the upgrade script:
Start pgAdmin and enter the master password you have set during the PostgreSQL server installation.
Select your database and click the Query Tool button. Click Open File and open the script
postgresql_upgrade2800aTo2900b.sql
. Then, run the script with Execute/Refresh ("F5").Close pgAdmin.
Install and Configure ADOIT 17.0 Application Server
Now, it's time to install and configure the ADOIT 17.0 application server. Detailed instructions are provided in the following sections.
In earlier versions of ADOIT, you also had to install the desktop application "Administration Toolkit" at this stage. Starting with ADOIT 17.0, this step is no longer necessary because the new ADOIT Administration is integrated into the web application and can be accessed directly from the browser.
Perform Installation
Install the ADOIT 17.0 application server on the designated server machine. To perform the installation:
- Double-click
setup.exe
located in the02 Application Server
folder within the ADOIT 17.0 installation package, and then follow the instructions provided by the setup wizard.
For detailed instructions on the installation process, see Install Application Server.
Configure Application Server
After the installation is complete, configure the ADOIT 17.0 application server. Unlike a new installation where you'd set initial values, you will use your backup ADOIT 16.0 application server configuration files and transfer the values from there.
To configure the application server:
Navigate to the directory
<ADOIT 17.0 application server>/conf
.Edit the configuration file
server.conf
and transfer the values from your backup file, including the database name, application server or aworker processes ports, and the trusted IP address of the web server.Optional: Edit the configuration files
adoxx.conf
,adoxx_web_conf.js
andmodule/afts_server.conf
, and transfer the values from your backup files if parameters in these files were changed in ADOIT 16.0.
Example
For example, if you previously modified the file adoxx_web_conf.js
to set the standard language
ADOIT should be started with, then copy the value of the parameter ADOXX_WEB_CLIENT_LANGUAGE
to
the new adoxx_web_conf.js
file.
Always merge your changes into the new configuration files - never overwrite them!
Install Application Server as a Service
With the application server installation and configuration tasks completed, it's now time to install the ADOIT 17.0 application server as a service.
Open the Windows Command Prompt as an administrator. Press <Windows> + < R> to open the Run box, enter cmd, and then press <Ctrl> + <Shift> + <Enter>.
Navigate to the directory
<ADOIT 17.0 application server>
.Type
aserver.exe -i
to install the Windows Service (e.g. ADOITServer17.0Service).
The application server is now installed as a service. Do not start the service yet.
Install and Configure ADOIT 17.0 Web Application
Now, you need to deploy the ADOIT 17.0 web application and configure it using backup files from your ADOIT 16.0 deployment. You'll need to upgrade your Apache Tomcat environment to version 10.1 (previously supported versions 8 or 9) and your Java installation to version 17 (from versions 8 or 11). Detailed instructions are provided in the following sections.
Install Java and Apache Tomcat
The ADOIT 17.0 web application requires Java 17 and Tomcat 10.1 to run.
Download and Install Java 17
Download and install OpenJDK 17 (LTS) from https://adoptopenjdk.net/. On Windows, select the installer, not the .zip bundle. You can use the default settings during installation.
Alternatively, if you have a commercial license from Oracle, you can use Oracle JDK 17 with ADOIT 17.0.
Download Tomcat 10.1 and Install as a Service
- Download and install Tomcat 10.1 from the Tomcat download page. On Windows, select the 32-bit/64-bit Windows Service Installer version.
For detailed instructions, see Install Apache Tomcat Web Server.
Configure Tomcat Java Settings
You have to ensure that the memory settings for Tomcat are set up properly according to the needs of ADOIT.
Open the folder "<Tomcat installation>/bin" and execute the file
tomcat10w.exe
.Modify the values on the Java tab as described here:
In the Java Virtual Machine box, specify the path to
jvm.dll
in the folder "<Java installation>".In the Java Options box, add the parameter "-Dfile.encoding=UTF-8"
Set Initial memory pool to 512MB, Maximum memory pool to at least 2048MB, and Thread stack size to 256KB.
Deploy Web Application
Deploy the ADOIT 17.0 web application to Apache Tomcat now by copying the necessary files:
- Copy the file
ADOIT17_0.war
to the directory<Tomcat>/webapps
. This file can be found in the folder03 Web Application
within the ADOIT 17.0 installation package.
The ADOIT 17.0 web application is now deployed. Do not start the Apache Tomcat service yet.
Configure Web Application
Now, it's time to configure the ADOIT 17.0 web application. You will use your backup ADOIT 16.0 Apache Tomcat configuration files and transfer the values from there. You will also import the comment data.
To configure the web application:
Navigate to the directory
<Tomcat>/webapps
.Open the file
ADOIT17_0.war
with a file archiver and perform the following steps on its contents:Edit the configuration file
adoxx_web.properties
. Transfer the values from your backup file, including the application server IP address and definition of aworker processes.Optional: Edit the configuration files
WEB-INF/classes/logback.xml
,WEB-INF/web.xml
andWEB-INF/registry/rest/RESTAuthorization.xml
, and transfer the values from your backup files if parameters in these files were changed in ADOIT 16.0.Copy the backup folders
collaboration
andupload
, as well as the backup fileaxw.ids
, to the folderWEB-INF/registry
.
Save the changes.
Navigate to the directory
<Tomcat>
.Edit the configuration file
server.xml
. Transfer the values from your backup file, including the encoding settings (UTF-8) and SSL/TLS configuration.
Always merge your changes into the new configuration files - never overwrite them!
Uninstall ADOIT 16.0
You've completed the ADOIT 17.0 installation; now, it's time to uninstall ADOIT 16.0.
Uninstall the ADOIT 16.0 application server, and any other ADOIT 16.0 rich client installations for using the Administration Toolkit. You can do this through the control panel.
Remove the ADOIT 16.0 web application from Apache Tomcat.
For detailed instructions on how to uninstall, see Uninstall ADOIT.
Start Services
Start the ADOIT 17.0 application server and the Apache Tomcat web server now so you can perform the final migration steps in the new environment.
To start the services (on Windows):
Open Services. Press <Windows> + <R> to open the Run box, enter services.msc, and then click OK.
Start the ADOIT application server (service name e.g. "ADOITServer17.0Service") and the Apache Tomcat web server (service name e.g. "Tomcat10").
You can access ADOIT via the following address: http://<SERVER_NAME>:<TOMCAT_PORT>/ADOIT17_0/
.
Here, <SERVER_NAME>
represents the server machine's name, and <TOMCAT_PORT>
corresponds to the
HTTP/1.1 Connector Port that was configured during setup (the default value is “8000”).
Post-Installation Tasks
To complete the upgrade to ADOIT 17.0, you need to perform some post-installation tasks.
Update Application Library
Next, your application library needs to be updated.
How Does This Affect My Library?
If you are using the default ArchiMate Application Library: Databases created with ADOIT 16.0 can still be used with ADOIT 17.0. However, you will not have access to improvements in the ArchiMate Application Library. Optional: Update the library in the ADOIT database. A new version of the ArchiMate Application Library can be found in the folder
04 Sample Data\Library
in the installation package.If you are using an ArchiMate Application Library with changes in the metamodel: Databases created with ADOIT 16.0 can still be used with ADOIT 17.0. However, you will not have access to improvements in ArchiMate Application Library. Optional: Contact your ADOIT consultant to upgrade your application library.
Perform Update
To upgrade your application library:
Open the ADOIT 17.0 Administration, go to Libraries > More options, and then click Update library.
Click Browse and select the file you want to import. You can also drag a file from your computer to the Drag and drop files here to upload area.
Select the Import component settings check box.
Click Import. When prompted to continue, click Yes. The library is updated.
If Import component settings is enabled, your existing component settings will be overwritten with those from the import file. This is necessary for adding new component settings not present in ADOIT 16.0. Later, you will re-import your exported component settings to restore your previous settings for all component settings that were already present in ADOIT 16.0.
Import Component Settings
If you've updated the application library in the previous step, it's time to re-import your exported component settings.
To import the component settings:
In the ADOIT 17.0 Administration, go to Settings > More options, and then click Import settings.
Click Browse and select the file you want to import. You can also drag a file from your computer to the Drag and drop files here to upload area.
Select Import all settings at the top to import all component settings at once.
Click Import. When prompted to continue, click Yes. The data is imported.
Execute Migration Scripts
If you're using the ArchiMate Application Library, and updated it, it's essential to execute
migration scripts at this point. You can find these scripts in the ADOIT 17.0 installation package
under 05 Migration
.
The ArchiMate Application Library has evolved from ADOIT 16.0 to ADOIT 17.0, incorporating methodical improvements. To prevent potential data loss, you need to adjust your repository content to fit the new method. Additionally, in ADOIT 17.0, workspaces are now accessible as objects within the Explorer, requiring them to be relocated from the root directory to a designated folder.. This is where the migration scripts come into play.
To execute the migration script:
In the ADOIT 17.0 Administration, go to Home > More options, and then click Script Execution.
Click Browse and select the file
17.0 - DATA_OBJECT_migrate_type_attr.js
. You can also drag the file from your computer to the Drag and drop files here to upload area.Select Execute on server to execute the script on the application server.
Click Execute Script and follow the prompts. Once completed, a success message will appear. Close it to finish.
Repeat steps 2 - 4 for the script
17.0 - Workspaces_location_migration.js
.
For details on the script, see Migration Scripts.