Skip to main content
Version: 15.1

Upgrade from ADOIT 12.0/12.1 to ADOIT 15.1

If you are planning to upgrade from ADOIT 12.0/12.1 to ADOIT 15.1, 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 15.1 installation package (your ADOIT consultant will email you a link).

  • Create a backup of the ADOIT database.

Application Library for ADOIT 15.1

You can get started right away if you are using a default library that comes with ADOIT (the ArchiMate Application Library or the ADOIT Standard Application Library).

Please contact your ADOIT consultant if you are using a different application library. This includes   ArchiMate Application Libraries or ADOIT Standard Application Libraries with changes in the metamodel or functional extensions or other specific libraries. You may need a new version of your library.

Stop Services​

First, the ADOIT 12.0/12.1 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. "ADOITServer12.1Service") 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 12.0/12.1 component settings now. Later, you will have to re-import them after updating the application library.

To export the component settings:

  • In the ADOIT 12.0/12.1 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 12.0/12.1 installation, you have to back up the following folders and files:

ADOIT Application Server Configuration

  • <ADOIT 12.x application server>/conf/server.conf (contains the database name, application server or aworker processes ports, and trusted IP address of the web server).

  • <ADOIT 12.x application server>/conf/adoxx.conf (optional, if parameters have been changed from their default value)

  • <ADOIT 12.x application server>/conf/adoxx_web_conf.js (optional, if parameters have been changed from their default value)

Apache Tomcat Configuration

  • <Tomcat>/webapps/ADOIT12_x/adoxx_web.properties (contains the application server IP address and definition of aworker processes)

  • <Tomcat>/webapps/ADOIT12_x/WEB-INF/classes/logback.xml (optional, if logging parameters have been changed)

  • <Tomcat>/webapps/ADOIT12_x/WEB-INF/web.xml (optional, if additional file types have been whitelisted for uploading)

  • <Tomcat>/webapps/ADOIT12_x/WEB-INF/registry/rest/RESTAuthorization.xml (part of the REST API configuration)

Comment Data

  • <Tomcat>/webapps/ADOIT12_x/WEB-INF/registry/collaboration (contains XML files that hold all comments for a model or object)

  • <Tomcat>/webapps/ADOIT12_x/WEB-INF/registry/upload (contains files that were uploaded along with comments)

  • <Tomcat>/webapps/ADOIT12_x/WEB-INF/registry/axw.ids (contains the last assigned and highest comment ID)

Upgrade the Database Schema​

The database schema has changed between ADOIT 12.0/12.1 and ADOIT 15.1 to accommodate new features. To continue using your existing database with ADOIT 15.1, you must run an upgrade script. This script can be found in the ADOIT 15.1 installation package under 02 Rich Client\BOC\ADOIT 15.1.x\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:

  1. 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.

  2. Open the script sqlserver_upgrade2600aTo2800a.sql by clicking the Open File button. Select your database from the Available Databases dropdown list and run the script with Execute ("F5").

  3. Close SQL Server Management Studio.

Upgrade Database Schema for Oracle​

For Oracle databases, use the tool »SQL Plus« to run the upgrade scripts:

  1. 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 user system.

  2. Run the script oracle_upgrade2600aTo2800a.sql with the following command: start <pathname>\oracle_upgrade2600aTo2800a.sql, where <pathname> is the script's location.

  3. Close SQL Plus with exit.

Install and Configure ADOIT 15.1 Rich Client​

Now, it's time to install and configure the ADOIT 15.1 rich client, which serves as an application server and is required for using the Administration Toolkit. Detailed instructions are provided in the following sections.

Perform Installation​

Install the ADOIT 15.1 rich client now. Depending on your deployment scenario, you must perform the following steps:

  • Install ADOIT as an application server on the designated server machine.

  • Install ADOIT for using the Administration Toolkit, for example on client machines or on a terminal server.

To perform the installation:

  • Double-click setup.exe located in the 02 Rich Client folder within the ADOIT 15.1 installation package, and then follow the instructions provided by the setup wizard.
note

For detailed instructions on the installation process, see Install Rich Client.

Configure Application Server​

After the installation is complete, configure the ADOIT 15.1 application server. Unlike a new installation where you'd set initial values, you will use your backup ADOIT 12.0/12.1 application server configuration files and transfer the values from there.

To configure the application server:

  • Navigate to the directory <ADOIT 15.1 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 and adoxx_web_conf.js, and transfer the values from your backup files if parameters in these files were changed in ADOIT 12.0/12.1.

Example

For example, if you previously modified the file adoxx_web_conf.js to set the standard language the web client should be started with, then copy the value of the parameter ADOXX_WEB_CLIENT_LANGUAGE to the new adoxx_web_conf.js file.

caution

Always merge your changes into the new configuration files - never overwrite them!

Execute Script to Modify Attribute IDs (ADOIT 12.1.2 only | ArchiMate only)​

If you're using the ArchiMate Application Library, and you are upgrading from ADOIT 12.1.2 (exact version), you need to execute a script before updating the application library in the next step. You can find this script in the ADOIT 15.1 installation package under 05 Migration.

Why a Script to Modify Attribute IDs?

Two technical attributes have different IDs in ADOIT 12.1.2 and in ADOIT 15.1, preventing a successful library update. The script ADOIT12.1.2_ArchiMate_MM_Script.js resolves this by deleting and recreating the technical attributes with correct IDs.

To execute the migration script:

  • Start the ADOIT 15.1 Administration Toolkit and log in to the ADOIT database.

  • Go to Settings > Execute JavaScript file.

  • Click Search... and select the file ADOIT12.1.2_ArchiMate_MM_Script.js. Then, click Execute.

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 or the default ADOIT Standard Application Library: Databases created with ADOIT 12.0/12.1 can still be used with ADOIT 15.1 after upgrading the database schema. However, you will not have access to improvements in your library. Optional: Update the library in the ADOIT database. A new version of your library can be found in the folder 04 Sample Data\Library in the installation package.

  • If you are using an   ArchiMate Application Library or ADOIT Standard Application Library with changes in the metamodel: Databases created with ADOIT 12.0/12.1 can still be used with ADOIT 15.1 after upgrading the database schema. However, you will not have access to improvements in your library. Optional: Contact your ADOIT consultant to upgrade your application library.

  • If you are using an   ArchiMate Application Library or ADOIT Standard Application Library with functional extensions or another specific library: Please contact your ADOIT consultant to clarify if a new version of your specific library is required before you proceed. Update the library in the ADOIT database if you received a new library file.

Perform Update

To upgrade your application library:

  1. Start the ADOIT 15.1 Administration Toolkit and log in to the ADOIT database.

  2. Go to Library Management, select your library, and then click Update library.

  3. Click Search... and select the file you want to import.

  4. Clear the Do not import component settings check box.

    note

    If Do not import component settings is disabled, 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 12.0/12.1. Later, you will re-import your exported component settings to restore your previous settings for all component settings that were already present in ADOIT 12.0/12.1.

  5. Click Import. The library is updated.

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 15.1 Administration Toolkit, go to Library Management > Component Settings.

  • Select your library, and then click Import component settings.

  • Click Search... and select the file you want to import. Then, click Import.

  • Click All to select all component settings for import, and then click OK. When prompted to continue, click Yes. The data is imported.

Execute Migration Scripts (ArchiMate only)​

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 15.1 installation package under 05 Migration.

Why Migration Scripts?

The ArchiMate Application Library has evolved from ADOIT 12.0/12.1 to ADOIT 15.1, incorporating methodical improvements. To prevent potential data loss, you need to adjust your repository content to fit the new method, and this is where the migration scripts come into play.

To execute the migration scripts:

  1. In the ADOIT 15.1 Administration Toolkit, go to Settings > Execute JavaScript file.

  2. Click Search... and select the file 15.0 - repo 1.js. Then, click Execute.

  3. Repeat steps 1 - 2 for the script 15.1 - repo grouping_layer.js.

note

For details on the scripts, see Migration Scripts.

Install Application Server as a Service​

With the rich client installation and configuration tasks completed, it's now time to install the ADOIT 15.1 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 15.1 application server>.

  • Type aserver.exe -i to install the Windows Service (e.g. ADOITServer15.1Service).

The application server is now installed as a service. Do not start the service yet.

Install and Configure ADOIT 15.1 Web Client​

Now, you need to deploy the ADOIT 15.1 web client and configure it using backup files from your ADOIT 12.0/12.1 deployment. You'll benefit from reduced configuration efforts by utilising the same Tomcat instance that already hosts the ADOIT 12.0/12.1 web client. Detailed instructions are provided in the following sections.

Deploy Web Client​

Deploy the ADOIT 15.1 web application to Apache Tomcat now by copying the necessary files:

  • Copy the file ADOIT15_1.war to the directory <Tomcat>/webapps. This file can be found in the folder 03 Web Client within the ADOIT 15.1 installation package.

The ADOIT 15.1 web client is now deployed. Do not start the Apache Tomcat service yet.

Configure Web Client​

Now, it's time to configure the ADOIT 15.1 web client. Unlike a new installation where you'd set initial values, you will use your backup ADOIT 12.0/12.1 Apache Tomcat configuration files and transfer the values from there. You will also import the comment data.

To configure the web client:

  1. Navigate to the directory <Tomcat>/webapps.

  2. Open the file ADOIT15_1.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 and WEB-INF/registry/rest/RESTAuthorization.xml, and transfer the values from your backup files if parameters in these files were changed in ADOIT 12.0/12.1.

    • Copy the backup folders collaboration and upload, as well as the backup file axw.ids, to the folder WEB-INF/registry.

  3. Save the changes.

caution

Always merge your changes into the new configuration files - never overwrite them!

Uninstall ADOIT 12.0/12.1​

You've completed the ADOIT 15.1 installation; now, it's time to uninstall ADOIT 12.0/12.1.

  • Uninstall the ADOIT 12.0/12.1 application server, and any other ADOIT 12.0/12.1 rich client installations for using the Administration Toolkit. You can do this through the control panel.

  • Remove the ADOIT 12.0/12.1 web application from Apache Tomcat.

note

For detailed instructions on how to uninstall, see Uninstall ADOIT.

Start Services​

Finally, the ADOIT 15.1 application server and the Apache Tomcat web server have to be started.

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. "ADOITServer15.1Service") and the Apache Tomcat web server (service name e.g. "Tomcat9").

You can access the web client via the following address: http://<SERVER_NAME>:<TOMCAT_PORT>/ADOIT15_1/. 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”).

note

After the migration, users will have the same system roles (and user groups) as before. Optional: If you're using the ArchiMate Application Library, you can transfer the users to the new standard system roles User, Reader and MM and Integration Administrator. For details, see Transfer Users to the New Standard System Roles.