Skip to content

Migrate from Easit GO 2023.11 and earlier to Easit GO 2024.06 and later

A fundamental change from Easit GO 2023.11 (and earlier) to Easit GO 2024.06 (and later) is that Easit GO 2024.06 (and later) is a Spring Boot application. This change means that Easit now provides a single jar file that contains everything need to run the application.

In this guide we will try to walk you through the steps you need to take in order to "migrate" your Easit GO installation from the Apache Tomcat base installation to the "new way of doing things". We will make some assumptions, we will assume that Easits root directory is D:\Easit and in that directory you have a directory named 'GOProd' which in turn contains directories named config, tomcat, files and solr (or solrfiles). The tomcat directory contain a jre, logs, bin and conf directory (along with other directories).

Please advise the technical change log before upgrading: Change log

References

  • [EasitRoot] = D: \ Easit
  • [SystemName] = GOProd
  • [BackupRoot] = D: \ Easit \ _Backup
  • [SystemBackupDir] = D: \ Easit \ _Backup \ GOProd \ YYYYMMDD
  • [InstallDir] = D: \ Easit \ GOProd

Before you continue with this guide, please note the values for the references above specific for your installation.

Prerequisites

  • Installation package: Zip file downloaded from DownloadPortal.
  • Install directory: Root directory for Easit GO.
  • Service name: Name of Windows service for Easit GO.
  • If you have the Graph API enabled in Easit GO, an updated license file (contact Easit for more information).

Stop Easit GO and additional services

  1. Stop other services such as connectors (e.g. Email2GO, Jira, Azure Devops) and any scheduled tasks (for e.g. ImportClient and EmailRequest).
  2. Stop the service for Easit GO.
  3. Copy settings from Java Options in your Apache Tomcat configuration and note the memory settings (Initial memory pool (JvmMs) and Maximum memory pool (JvmMx)).
  4. Note the account used on the tab Log on.
  5. Uninstall the service for Easit GO by opening PowerShell as administrator and run the following commands.
    1. Set-Location [InstallDir]\tomcat\bin
    2. .\service.bat remove ((Get-ChildItem -Recurse -Include '*.exe' -Exclude '*tomcat*').Name -Replace 'w.exe','')

Backup

  1. Backup the database for Easit GO.
  2. Create a folder structure in [BackupRoot] so you have the following path [BackupRoot] \ [SystemName] \ YYYYMMDD
  3. Copy [InstallDir]\config to [SystemBackupDir]
  4. Copy [InstallDir]\tomcat\conf to [SystemBackupDir]
  5. Compress [InstallDir]\tomcat\logs to [SystemBackupDir].
  6. Delete the tomcat directory inside [InstallDir]
  7. Delete the files log4j2.xml, log4j2_audit.xml, properties.xml inside [InstallDir]\config.
  8. If you have a directory called solrfiles, rename it to solr.

Installation

  1. Navigate to [EasitRoot] and rename the directory [SystemName] to easitgo.
  2. Expand the zip file (a.k.a installation package) to [EasitRoot] and when asked how to handle already existing files / folders, choose to skip them. Do NOT choose to overwrite.
  3. Rename the directory easitgo back to [SystemName].
  4. Navigate to [InstallDir]\bin and edit easit-service.xml.
    1. Update the value for Xmx in arguments (\<arguments>-Xmx2g -XX:+Use....) so it has the same value as JvmMx had in the Apache Tomcat configuration. (Examples: -Xmx4g OR -Xmx4092m)
    2. If you have more then one Easit GO installed, or plan to have, change id, name and description to reflect this. (e.g easitgo-service-test or easitgo-service-prod)
    3. Additional details:
      1. id = Specifies the ID that Windows uses internally to identify the service. This has to be unique among all the services installed in a system, and it should consist entirely out of alpha-numeric characters.
      2. name = Short display name of the service, which can contain spaces and other characters. This shouldn't be too long, like id, and this also needs to be unique among all the services in a given system.
      3. description = Long human-readable description of the service. This gets displayed in Windows service manager when the service is selected.
      4. arguments = Specifies the arguments to be passed to the executable. Any customizations made under Java Option in Apache Tomcat needs to be added here.
    4. If another account than LocalSystem account was used by Apache Tomcat, please advise this page for help to setup the new service with the correct account easit-service.xml configuration file.
  5. Open Command Prompt or PowerShell as administrator and navigate to [InstallDir]\bin
  6. Execute one the following commands below to install a new Windows Service for Easit GO.
    1. CMD: easitgo-service.exe install
    2. PowerShell: .\easitgo-service.exe install
  7. If you have an updated or new license file, copy and replace the current one in [InstallDir]\config with it.

Update settings

Starting with Easit GO 2024.06 we have simplified the configuration of Easit GO by embedding Apache Tomcat in the jar file provided by Easit. This means that most, not all, configuration options have been moved to properties.xml. We will now guide you through the process of moving the configuration options that requires it to properties.xml.

properties.xml

Open [SystemBackupDir]\config\properties.xml and note the values for the following entries:

  • dataSource.url
  • dataSource.username
  • dataSource.password.

Also include any of the following if the condition is not met.

  • fileSystem.rootPath = [InstallDir]\files
  • solr.home = [InstallDir]\solr
  • trace.outputPath = [InstallDir]\trace

Using this information, update the values for the corresponding entries in [InstallDir]\config\properties.xml.

1
2
3
4
5
6
7
8
9
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <entry key="dataSource.driverClassName">...</entry>
    <entry key="dataSource.url">...</entry>
    <entry key="dataSource.username">....</entry>
    <entry key="dataSource.password">...</entry>
    <entry key="hibernate.dialect">com.easit.util.hibernate.EasitMSSql2016Dialect</entry>
</properties>

server.xml

Open [SystemBackupDir]\tomcat\conf\server.xml and note the value for port in this element.

1
2
3
4
5
<Connector port="8585" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               maxParameterCount="1000"
               />
Then we need to find the settings for the AJP connector, the element looks like this. If the connector is disabled in your server.xml, you do not need to copy any settings to [InstallDir]\config\properties.xml.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
<!-- Example when enabled -->
    <Connector protocol="AJP/1.3"
        address="127.0.0.1"
        port="xxxx"
        redirectPort="xxxx"
        tomcatAuthentication="false"
        packetSize="32768"
        allowedRequestAttributesPattern=".*"
        secret=""
        />

<!-- Example when disabled -->
<!--
    <Connector protocol="AJP/1.3"
               address="::1"
               port="8009"
               redirectPort="8443"
               maxParameterCount="1000"
               />
    -->

Using the information above, add the corresponding key(s) to [InstallDir]\config\properties.xml.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <entry key="dataSource.driverClassName">...</entry>
    <entry key="dataSource.url">...</entry>
    <entry key="dataSource.username">....</entry>
    <entry key="dataSource.password">...</entry>
    <entry key="hibernate.dialect">com.easit.util.hibernate.EasitMSSql2016Dialect</entry>
    <entry key="server.port">8003</entry> <!-- Only add if port is other than 8080 -->
    <entry key="ajp.enabled">true</entry> <!-- Only add if ISAPI filter in IIS is used -->
    <entry key="ajp.address">valueFromServer.xml</entry> <!-- Only provide this if ajp.enabled = true -->
    <entry key="ajp.port">valueFromServer.xml</entry> <!-- Only provide this if ajp.enabled = true -->
    <entry key="ajp.redirectPort">valueFromServer.xml</entry> <!-- Only provide this if ajp.enabled = true -->
    <entry key="ajp.tomcatAuthentication">valueFromServer.xml</entry> <!-- Only provide this if ajp.enabled = true -->
    <entry key="ajp.packetSize">valueFromServer.xml</entry> <!-- Only provide this if ajp.enabled = true -->
    <entry key="ajp.allowedRequestAttributesPattern">valueFromServer.xml</entry> <!-- Only provide this if ajp.enabled = true -->
    <entry key="ajp.secret">valueFromServer.xml</entry> <!-- Only provide this if ajp.enabled = true -->
</properties>

If you have more then one Easit GO installed and would like to have http://localhost:port/test/ for your test application you can add the following: entry key="server.servlet.context-path" with the value /test/. This will add /test/ to the url.

Further reading about Properties.xml

log4j2.xml

If you have a customized version of log4j2.xml or log4j2_audit.xml you need to copy the customizations from the file in [SystemBackupDir]\config to the corresponding file in [InstallDir]\config. Customizations if most often made by adding one or more logger to the Loggers section.

If you don't want to use the new log4j2.xml provided by Easit you need to update the property named default-log-directory with the following

  • Before 2024.06: \${sys:catalina.base}
  • From 2024.06: \${sys:bpeLogsPath}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Properties>
        <Property name="default-log-directory">${sys:bpeLogsPath}</Property>
    </Properties>

    <Appenders>
        ...
    </Appenders>

    <Loggers>
        ...
        <Root level="WARN">
            ....
        </Root>
    </Loggers>
</Configuration>

Recommended properties:

1
2
3
4
5
6
7
8
9
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Properties>
        <Property name="default-log-pattern">%d{yyyy-MM-dd HH:mm:ss.SSS}{CET} %-5level - %m [%c]%n</Property>
        <Property name="default-log-directory">${sys:bpeLogsPath}</Property>
        <Property name="default-log-maxAge">30</Property>
        <Property name="default-log-name">EasitGO</Property>
    </Properties>
</Configuration>

Further reading about log4j2.xml

Update database and start Easit GO

Before starting Easit GO we need to run SQL scripts against the database.

  1. Open your preferred database management tool and connect to the database server.
  2. Verify that isolation mode for the database is set to 1.
    1.  1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
      DECLARE @DATABASENAME AS VARCHAR(255), @ALTERSQL AS VARCHAR(255)
SET @DATABASENAME=db_name()
IF (SELECT is_read_committed_snapshot_on FROM sys.databases
WHERE name=@DATABASENAME) = 0
BEGIN
SET @ALTERSQL = 'ALTER DATABASE ['+@DATABASENAME+'] SET SINGLE_USER WITH
ROLLBACK IMMEDIATE;ALTER DATABASE ['+@DATABASENAME+'] SET
read_committed_snapshot ON;ALTER DATABASE ['+@DATABASENAME+'] SET
MULTI_USER';
EXEC(@ALTERSQL)
END
IF (SELECT snapshot_isolation_state FROM sys.databases
WHERE name=@DATABASENAME) = 0
BEGIN
SET @ALTERSQL = 'ALTER DATABASE ['+@DATABASENAME+'] SET SINGLE_USER WITH
ROLLBACK IMMEDIATE;ALTER DATABASE ['+@DATABASENAME+'] SET
allow_snapshot_isolation ON;ALTER DATABASE ['+@DATABASENAME+'] SET
MULTI_USER';
EXEC(@ALTERSQL)
END
SELECT is_read_committed_snapshot_on, snapshot_isolation_state
FROM sys.databases
WHERE name = @DATABASENAME
      The expected result is is_read_committed_snapshot_on=1 and snapshot_isolation_state=1.
  3. Disconnect from the database server.
  4. Start Easit GO.
    1. PowerShell: 
      1
      Start-Service -Name 'easitgo'
    2. CMD: 
      1
      sc start "easitgo"
    3. services.msc: Find the service for Easit GO, select it and click on start.
  5. Give Easit GO a couple of minutes to start and you are done.

You probably have an URL that you use to connect to Easit GO, try go to it. If you want to verify that Easit GO is up and running you can enter *http://localhost:[server.port]/ in to the browser on the application server and see if you get the login page for Easit GO.