Skip to main content
Version: 17.1

Upgrade from ADOIT 17.0 to ADOIT 17.1 (ArchiMate Library)

If you are planning to upgrade from ADOIT 17.0 to ADOIT 17.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 17.1 installation package (your ADOIT consultant will email you a link).

  • Create a backup of the ADOIT database.

ArchiMate Application Library for ADOIT 17.1

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 17.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. "ADOITServer17.0Service") and the Apache Tomcat web server (service name e.g. "Tomcat10").

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 17.0 component settings now. Later, you will have to re-import them after updating the application library.

To export the component settings:

  1. In the ADOIT 17.0 Administration, go to Settings > More options, and then click Export settings.

  2. Select Export all settings to export all settings at once. Alternatively, you can clear the check box and select the component settings you want to export.

  3. 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 settings such as server ports, and more.

Depending on your ADOIT 17.0 installation, you have to back up the following folders and files:

ADOIT Application Server Configuration

  • <ADOIT 17.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 17.0 application server>/conf/adoxx.conf (optional, if parameters have been changed from their default value)

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

  • <ADOIT 17.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/ADOIT17_0/adoxx_web.properties (contains the application server IP address and definition of aworker processes)

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

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

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

note

In earlier versions of ADOIT, you also had to back up the comment data files from Tomcat folder at this stage. Starting with ADOIT 17.0, this step is no longer necessary because comments are now stored directly in the database.

Install and Configure ADOIT 17.1 Application Server​

Now, it's time to install and configure the ADOIT 17.1 application server. Detailed instructions are provided in the following sections.

Perform Installation​

Install the ADOIT 17.1 application server on the designated server machine. To perform the installation:

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

For detailed instructions on the installation process, see Install Application Server.

Configure Application Server​

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

To configure the application server:

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

caution

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.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 17.1 application server>.

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

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

Install and Configure ADOIT 17.1 Web Application​

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

Deploy Web Application​

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

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

The ADOIT 17.1 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.1 web application. Use your backup ADOIT 17.0 Tomcat configuration files and transfer the values from there.

To configure the web application:

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

  2. Open the file ADOIT17_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 17.0.

  3. Save the changes.

caution

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

Uninstall ADOIT 17.0​

You've completed the ADOIT 17.1 installation; now, it's time to uninstall ADOIT 17.0.

  • Uninstall the ADOIT 17.0 application server. You can do this through the control panel.

  • Remove the ADOIT 17.0 web application from Apache Tomcat.

note

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

Start Services​

Start the ADOIT 17.1 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.1Service") 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_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”).

Post-Installation Tasks​

To complete the upgrade to ADOIT 17.1, 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 17.0 can still be used with ADOIT 17.1. 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 17.0 can still be used with ADOIT 17.1. 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:

  1. Open the ADOIT 17.1 Administration, go to Libraries > More options, and then click Update library.

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

  3. Select the Import component settings check box.

  4. Click Import. When prompted to continue, click Yes. The library is updated.

note

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 17.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 17.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:

  1. In the ADOIT 17.1 Administration, go to Settings > More options, and then click Import settings.

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

  3. Select Import all settings at the top to import all component settings at once.

  4. Click Import. When prompted to continue, click Yes. The data is imported.

Execute Migration Script​

Finally, you need to execute a migration script. You can find this script in the ADOIT 17.1 installation package under 05 Migration.

Why a Migration Script?

ADOIT 17.0 makes workspaces accessible as objects in the Explorer. When upgrading to ADOIT 17.0, the script 17.0 - Workspaces_location_migration.js is used. This script moves all Workspace objects from the "Objects" group, the main object group in the Object Catalogue, to the special folder Workspaces.

ADOIT 17.1 reverses these changes. Workspaces are no longer accessible as objects in the Explorer. At the same time, the new script 17.1 - Invisible_workspaces_location_migration is used which moves the (now invisible) workspaces back to the root directory, removes the Workspaces folder, and grants users write access to all workspaces where they are designated as members or admins.

To execute the migration script:

  1. In the ADOIT 17.1 Administration, go to Home > More options, and then click Script Execution.

  2. Click Browse and select the file 17.1 - Invisible_workspaces_location_migration. You can also drag the file from your computer to the Drag and drop files here to upload area.

  3. Select Execute on server to execute the script on the application server.

  4. Click Execute Script and follow the prompts. Once completed, a success message will appear. Close it to finish.