Recent changes to Upgrading

Upgrading modified by Timothy Anyona

Timothy Anyona — Fri, 31 Oct 2025 09:06:33 -0000

--- v39
+++ v40
@@ -14,16 +14,12 @@
 * If using Tomcat, delete ART's Tomcat cache by deleting the art directory in the **TOMCAT_HOME\work\Catalina\localhost** directory
 * Copy the new version art directory (from the unzipped art.war) to the webapps directory of the application server
 * Copy the contents of the backup **art\WEB-INF\work** directory to the new version's directory. If you are using a custom work directory, this may not be necessary.
-* Copy the contents of the backup **art\WEB-INF\thymeleaf\jobs** directory to the new version's directory.
-* Copy the contents of the backup **art\js-templates** directory to the new version's directory
 * If you had modified the **art\WEB-INF\art-custom-settings.json** file, review the structure of the new version's file and copy appropriate details to the appropriate sections. New sections may have been added in a new version. If you are using a custom config directory set via system property, copying this file may not be necessary.
 * If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file to the new version's directory. If you are using a custom config directory set via system property, copying this file may not be necessary.
-* If you had put any **JDBC drivers** in the **art\WEB-INF\lib** directory, copy these drivers from the backup lib directory to the new version's lib directory.
 * Start the application server
 * Clear your browser's cache e.g. for Firefox, use the History | Clear Recent History menu

-
-The upgrade is complete. All users, reports, scheduled jobs etc should continue to work as before.
+The upgrade is complete. All users, reports, jobs etc should continue to work as before.

 #Notes
 Some upgrades may require special attention or additional effort due to feature changes and incompatibilities with previous versions.
@@ -54,12 +50,12 @@


 ##8.7
-The SQL Server JDBC driver has been updated in this release. This new version uses encryption by default to communicate with the SQL Server instance. It therefore requires all datasources using this driver to have some modification otherwise reports or jobs that use them will not run. Take the following steps for all datasources that use this driver after upgrading, or make appropriate modifications to the relevant records in the ART_DATABASES table.
+The SQL Server JDBC driver has been updated in this release. This new version uses encryption by default to communicate with the SQL Server instance. It therefore requires all datasources using this driver to have some modification otherwise reports or jobs that use them will not run. Use one of the following options for datasources that use this driver after upgrading, or make appropriate modifications to the relevant records in the ART_DATABASES table.

 1. Modify the **JDBC URL** and add `;trustServerCertificate=true` at the end to trust the self-signed certificate of the SQL Server instance
 2. Alternatively, add `;encrypt=false` at the end of the JDBC URL to prevent use of encryption
 3. Another option is to configure your SQL Server instance to use SSL, including adding a trusted SSL certificate. If the SQL Server instance was already properly configured for SSL, none of these modifications may be necessary.
-4. A final option is to revert the mssql-jdbc jar file from a previous ART version to maintain the previous working
+4. A final option is to revert to the mssql-jdbc jar file from a previous ART version to maintain the previous working

 If you are using SQL Server as your ART Database, you can make the appropriate changes to the **art-database.json** file in the art **WEB-INF\work** directory before starting the application server.

Upgrading modified by Timothy Anyona

Timothy Anyona — Tue, 09 Sep 2025 14:02:01 -0000

--- v38
+++ v39
@@ -16,9 +16,8 @@
 * Copy the contents of the backup **art\WEB-INF\work** directory to the new version's directory. If you are using a custom work directory, this may not be necessary.
 * Copy the contents of the backup **art\WEB-INF\thymeleaf\jobs** directory to the new version's directory.
 * Copy the contents of the backup **art\js-templates** directory to the new version's directory
-* If you had modified the **art\WEB-INF\art-custom-settings.json** file, review the structure of the new version's file and copy appropriate details to the appropriate sections. New sections may have been added in a new version. If you are using a custom config directory set via system property copying this file may not be necessary.
-* If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file to the new version's directory. If you a custom config directory set via system property copying this file may not be necessary.
-* If you were using the demo HSQLDB database, copy the database files to the **art\WEB-INF\hsqldb** directory of the new version, overwriting the existing files
+* If you had modified the **art\WEB-INF\art-custom-settings.json** file, review the structure of the new version's file and copy appropriate details to the appropriate sections. New sections may have been added in a new version. If you are using a custom config directory set via system property, copying this file may not be necessary.
+* If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file to the new version's directory. If you are using a custom config directory set via system property, copying this file may not be necessary.
 * If you had put any **JDBC drivers** in the **art\WEB-INF\lib** directory, copy these drivers from the backup lib directory to the new version's lib directory.
 * Start the application server
 * Clear your browser's cache e.g. for Firefox, use the History | Clear Recent History menu
@@ -63,3 +62,7 @@
 4. A final option is to revert the mssql-jdbc jar file from a previous ART version to maintain the previous working

 If you are using SQL Server as your ART Database, you can make the appropriate changes to the **art-database.json** file in the art **WEB-INF\work** directory before starting the application server.
+
+###References
+* https://learn.microsoft.com/en-us/sql/connect/jdbc/connecting-with-ssl-encryption?view=sql-server-ver16
+

Upgrading modified by Timothy Anyona

Timothy Anyona — Fri, 21 Feb 2025 05:30:42 -0000

--- v37
+++ v38
@@ -52,3 +52,14 @@
 **Non-labelled rules** | For reports that use rules, if the `#rules#` label doesn't exist in the sql source, such reports will need to be updated to include this label, so that rules can be applied.
 **Long parameters in JasperReports** | Parameters that were defined with a data type of `java.lang.Long` in JasperReports need to be modified to `java.lang.Integer`
 **defaultAutoCommit** | If using JNDI for the ART Database, make sure the **defaultAutoCommit** setting is set to **true**. This setting is for Tomcat but a similar change would be needed for other application servers.
+
+
+##8.7
+The SQL Server JDBC driver has been updated in this release. This new version uses encryption by default to communicate with the SQL Server instance. It therefore requires all datasources using this driver to have some modification otherwise reports or jobs that use them will not run. Take the following steps for all datasources that use this driver after upgrading, or make appropriate modifications to the relevant records in the ART_DATABASES table.
+
+1. Modify the **JDBC URL** and add `;trustServerCertificate=true` at the end to trust the self-signed certificate of the SQL Server instance
+2. Alternatively, add `;encrypt=false` at the end of the JDBC URL to prevent use of encryption
+3. Another option is to configure your SQL Server instance to use SSL, including adding a trusted SSL certificate. If the SQL Server instance was already properly configured for SSL, none of these modifications may be necessary.
+4. A final option is to revert the mssql-jdbc jar file from a previous ART version to maintain the previous working
+
+If you are using SQL Server as your ART Database, you can make the appropriate changes to the **art-database.json** file in the art **WEB-INF\work** directory before starting the application server.

Upgrading modified by Timothy Anyona

Timothy Anyona — Thu, 19 Oct 2023 06:20:55 -0000

--- v36
+++ v37
@@ -9,15 +9,15 @@
 * Unzip the **art.war** file to a directory e.g. one named `art`. You can use any zip/unzip utility as a .war file is a normal zip file.
 * Stop the application server
 * Backup the ART database
-* Backup the art directory on the application server
+* Backup the art directory on the application server. This is recommended even if you are using a custom **work** directory.
 * Delete the art directory and any art.war file in the webapps directory of the application server
 * If using Tomcat, delete ART's Tomcat cache by deleting the art directory in the **TOMCAT_HOME\work\Catalina\localhost** directory
 * Copy the new version art directory (from the unzipped art.war) to the webapps directory of the application server
-* Copy the contents of the backup **art\WEB-INF\work** directory to the new version's directory
-* Copy the contents of the backup **art\WEB-INF\thymeleaf\jobs** directory to the new version's directory
+* Copy the contents of the backup **art\WEB-INF\work** directory to the new version's directory. If you are using a custom work directory, this may not be necessary.
+* Copy the contents of the backup **art\WEB-INF\thymeleaf\jobs** directory to the new version's directory.
 * Copy the contents of the backup **art\js-templates** directory to the new version's directory
-* If you had modified the **art\WEB-INF\art-custom-settings.json** file, review the structure of the new version's file and copy appropriate details to the appropriate sections. New sections may have been added in a new version.
-* If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file to the new version's directory
+* If you had modified the **art\WEB-INF\art-custom-settings.json** file, review the structure of the new version's file and copy appropriate details to the appropriate sections. New sections may have been added in a new version. If you are using a custom config directory set via system property copying this file may not be necessary.
+* If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file to the new version's directory. If you a custom config directory set via system property copying this file may not be necessary.
 * If you were using the demo HSQLDB database, copy the database files to the **art\WEB-INF\hsqldb** directory of the new version, overwriting the existing files
 * If you had put any **JDBC drivers** in the **art\WEB-INF\lib** directory, copy these drivers from the backup lib directory to the new version's lib directory.
 * Start the application server

Upgrading modified by Timothy Anyona

Timothy Anyona — Wed, 11 Nov 2020 08:55:18 -0000

--- v35
+++ v36
@@ -9,7 +9,6 @@
 * Unzip the **art.war** file to a directory e.g. one named `art`. You can use any zip/unzip utility as a .war file is a normal zip file.
 * Stop the application server
 * Backup the ART database
-* Connect to the ART database and run any database upgrade scripts included in the download package to bring the ART database up to date
 * Backup the art directory on the application server
 * Delete the art directory and any art.war file in the webapps directory of the application server
 * If using Tomcat, delete ART's Tomcat cache by deleting the art directory in the **TOMCAT_HOME\work\Catalina\localhost** directory
@@ -19,7 +18,7 @@
 * Copy the contents of the backup **art\js-templates** directory to the new version's directory
 * If you had modified the **art\WEB-INF\art-custom-settings.json** file, review the structure of the new version's file and copy appropriate details to the appropriate sections. New sections may have been added in a new version.
 * If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file to the new version's directory
-* If you were using the demo HSQLDB database, after running the upgrade scripts on the ArtRepositoryDB database in the backup location, copy the updated files to the **art\WEB-INF\hsqldb** directory of the new version, overwriting the existing files. You can look at the [Tips](https://sourceforge.net/p/art/wiki/Tips/) documentation to see how you can upgrade an HSQLDB database.
+* If you were using the demo HSQLDB database, copy the database files to the **art\WEB-INF\hsqldb** directory of the new version, overwriting the existing files
 * If you had put any **JDBC drivers** in the **art\WEB-INF\lib** directory, copy these drivers from the backup lib directory to the new version's lib directory.
 * Start the application server
 * Clear your browser's cache e.g. for Firefox, use the History | Clear Recent History menu

Discussion for Upgrading page

Timothy Anyona — Thu, 24 Oct 2019 10:32:44 -0000

Hi,
Could you post this on the discussion forum for further replies and follow up.

Discussion for Upgrading page

fcbhusc — Thu, 24 Oct 2019 10:27:15 -0000

Hi. I want to upgrade my art 2 to 4.6. Where can I find the directory sctructre changes?
Cant find in oldest version f.e.: art\WEB-INF\work | art\WEB-INF\thymeleaf\jobs | art\WEB-INF\art-custom-settings.json fi | art\js-templates

Best Regards,
FCBHUSC

Upgrading modified by Timothy Anyona

Timothy Anyona — Tue, 27 Nov 2018 17:37:03 -0000

--- v34
+++ v35
@@ -6,23 +6,22 @@
 * Download the latest ART version
 * Extract the zip package to a temporary location
 * Review the **changelog.txt** file to see what has changed
-* Backup the ART directory contained on the application server 
+* Unzip the **art.war** file to a directory e.g. one named `art`. You can use any zip/unzip utility as a .war file is a normal zip file.
+* Stop the application server
 * Backup the ART database
 * Connect to the ART database and run any database upgrade scripts included in the download package to bring the ART database up to date
-* Deploy the new **art.war** file to the application server. There are a number of ways to do this. You can do the following if using Apache Tomcat.
-    * Stop Tomcat
-    * Delete the art directory and art.war file in the **TOMCAT_HOME\webapps** directory
-    * Delete ART's Tomcat cache by deleting the art directory in the **TOMCAT_HOME\work\Catalina\localhost** directory
-    * Copy the new art.war file to the webapps directory
-    * Start Tomcat 
+* Backup the art directory on the application server
+* Delete the art directory and any art.war file in the webapps directory of the application server
+* If using Tomcat, delete ART's Tomcat cache by deleting the art directory in the **TOMCAT_HOME\work\Catalina\localhost** directory
+* Copy the new version art directory (from the unzipped art.war) to the webapps directory of the application server
 * Copy the contents of the backup **art\WEB-INF\work** directory to the new version's directory
 * Copy the contents of the backup **art\WEB-INF\thymeleaf\jobs** directory to the new version's directory
 * Copy the contents of the backup **art\js-templates** directory to the new version's directory
-* If you had modified the **art\WEB-INF\art-custom-settings.json** file, copy the file from the backup directory to the new version's directory
-* If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file from the backup directory to the new version's directory
+* If you had modified the **art\WEB-INF\art-custom-settings.json** file, review the structure of the new version's file and copy appropriate details to the appropriate sections. New sections may have been added in a new version.
+* If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file to the new version's directory
 * If you were using the demo HSQLDB database, after running the upgrade scripts on the ArtRepositoryDB database in the backup location, copy the updated files to the **art\WEB-INF\hsqldb** directory of the new version, overwriting the existing files. You can look at the [Tips](https://sourceforge.net/p/art/wiki/Tips/) documentation to see how you can upgrade an HSQLDB database.
 * If you had put any **JDBC drivers** in the **art\WEB-INF\lib** directory, copy these drivers from the backup lib directory to the new version's lib directory.
-* Restart Tomcat
+* Start the application server
 * Clear your browser's cache e.g. for Firefox, use the History | Clear Recent History menu

@@ -39,18 +38,18 @@
 **URL changes** | URLs that were being used in bookmarks or other links will need updating. Review the new application to see the appropriate URL to use or look at the admin manual to see new URLs.
 **ART Database configuration** | The details of the ART Database will need to be entered afresh
 **Settings** | Application settings will need to be entered afresh
-**Internet Explorer** | If using Internet Explorer, you will need to use version 8 at a minimum. Some features may not work with Internet Explorer 8 so it is recommended, if using Internet Explorer, to use the latest version.
+**Internet Explorer** | If using Internet Explorer, you will need to use version 8 at a minimum. Some features may not work with Internet Explorer 8 so it is recommended, if using Internet Explorer, to use version 11.
 **Java** | Java 7 and above is required
 **Application server** | An application server that supports servlet 3.0 will be required e.g. Tomcat 7 and above
 **Renamed concepts** | Some concepts have been renamed e.g. "Queries" are now "Reports", "Graphs" are now "Charts", "View Modes" are now "Report Formats", "Report on Column" report types are now "Group" reports, "Pivot Table" report types are now "JPivot" reports.
-**Jxls templates** | Jxls templates need to be recreated. Review the sample templates located in the **ART_HOME\\WEB-INF\\work\\templates** directory, or the Jxls website, http://jxls.sourceforge.net/, to see the new template structure.
+**Jxls templates** | Jxls templates need to be recreated. Review the sample templates located in the **ART_HOME\WEB-INF\work\templates** directory, or the [Jxls website](http://jxls.sourceforge.net/) to see the new template structure.
 **Chained parameters** | Reports that use chained parameters will need to be modified. Review the chained parameter example in the demo database or the admin manual to see the new method of specifying chained parameters.
-**Directory location changes** | The templates directory has been moved to **ART_HOME\WEB-INF\work\\templates**. The export directory has been moved to **ART_HOME\WEB-INF\work\export**.
-**XMLA Repors** | For Mondrian XMLA and Microsoft XMLA reports, the url, username and password fields have been removed from the report definition page and instead a datasource needs to be created from the Datasource Configuration page and then used by selecting the Datasource field in the report definition.
+**Directory location changes** | The templates directory has been moved to **ART_HOME\WEB-INF\work\templates**. The export directory has been moved to **ART_HOME\WEB-INF\work\export**.
+**XMLA Reports** | For Mondrian XMLA and Microsoft XMLA reports, the url, username and password fields have been removed from the report definition page and instead a datasource needs to be created from the Datasource Configuration page and then used by selecting the Datasource field in the report definition.
 **Query tags** | The special hardcoded tags or placeholders than can be used within query sql, **:USERNAME**, **:DATE** and **:TIME** have been changed to include a colon at the end i.e. **:USERNAME:**, **:DATE:** and **:TIME:**
 **Dashboard XML** | If you have xml special characters within tag content, ensure to replace them with the relevant xml character entities e.g. if the `<url>` tag contains a url like `http://localhost:8080/art/app/runReport.do?reportId=1&p-param1=test`, you'll need to replace the `&` character with `&`, to have the url as `http://localhost:8080/art/app/runReport.do?reportId=1&p-param1=test`. For a list of the 5 special xml characters and their respective replacement strings or character entities, see http://support.esri.com/technical-article/000005870
 **LOOKUP rule values** | If you had any rule values of type **LOOKUP**, these will no longer be in effect as there is no longer an option for lookup rule values. Instead, define a user group, assign rule values to this user group and put the required users into this user group.
-**Non-labelled multi parameters** | For reports that use multi parameters where the parameter name is not included in the sql source e.g. `... IN(#param#)`, the reports will need to be updated to include the parameter placeholder in the sql source.
+**Non-labelled multi parameters** | For reports that use multi parameters where the parameter name is not included in the sql source, the reports will need to be updated to include the parameter placeholder in the sql source.
 **Non-labelled rules** | For reports that use rules, if the `#rules#` label doesn't exist in the sql source, such reports will need to be updated to include this label, so that rules can be applied.
 **Long parameters in JasperReports** | Parameters that were defined with a data type of `java.lang.Long` in JasperReports need to be modified to `java.lang.Integer`
-**defaultAutoCommit** | If using JNDI for the ART Database, make sure the **defaultAutoCommit** setting is set to **true** if you were previously using false. This setting is for Tomcat but a similar change would be needed for different application servers.
+**defaultAutoCommit** | If using JNDI for the ART Database, make sure the **defaultAutoCommit** setting is set to **true**. This setting is for Tomcat but a similar change would be needed for other application servers.
</url>

Upgrading modified by Timothy Anyona

Timothy Anyona — Wed, 26 Sep 2018 12:16:26 -0000

--- v33
+++ v34
@@ -15,11 +15,11 @@
     * Delete ART's Tomcat cache by deleting the art directory in the **TOMCAT_HOME\work\Catalina\localhost** directory
     * Copy the new art.war file to the webapps directory
     * Start Tomcat 
-* Copy the contents of the backup **art\WEB-INF\work** directory to the new version's work directory
-* Copy the contents of the backup **art\WEB-INF\thymeleaf** directory to the new version's thymeleaf directory
-* Copy the contents of the backup **art\js-templates** directory to the new version's js-templates directory
-* If you had modified the **art\WEB-INF\art-custom-settings.json** file, copy the file from the backup directory to the new version directory
-* If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file from the backup directory to the new version directory
+* Copy the contents of the backup **art\WEB-INF\work** directory to the new version's directory
+* Copy the contents of the backup **art\WEB-INF\thymeleaf\jobs** directory to the new version's directory
+* Copy the contents of the backup **art\js-templates** directory to the new version's directory
+* If you had modified the **art\WEB-INF\art-custom-settings.json** file, copy the file from the backup directory to the new version's directory
+* If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file from the backup directory to the new version's directory
 * If you were using the demo HSQLDB database, after running the upgrade scripts on the ArtRepositoryDB database in the backup location, copy the updated files to the **art\WEB-INF\hsqldb** directory of the new version, overwriting the existing files. You can look at the [Tips](https://sourceforge.net/p/art/wiki/Tips/) documentation to see how you can upgrade an HSQLDB database.
 * If you had put any **JDBC drivers** in the **art\WEB-INF\lib** directory, copy these drivers from the backup lib directory to the new version's lib directory.
 * Restart Tomcat

Upgrading modified by Timothy Anyona

Timothy Anyona — Mon, 20 Nov 2017 05:23:11 -0000

--- v32
+++ v33
@@ -16,8 +16,8 @@
     * Copy the new art.war file to the webapps directory
     * Start Tomcat 
 * Copy the contents of the backup **art\WEB-INF\work** directory to the new version's work directory
+* Copy the contents of the backup **art\WEB-INF\thymeleaf** directory to the new version's thymeleaf directory
 * Copy the contents of the backup **art\js-templates** directory to the new version's js-templates directory
-* Copy the contents of the backup **art\WEB-INF\thymeleaf** directory to the new version's thymeleaf directory
 * If you had modified the **art\WEB-INF\art-custom-settings.json** file, copy the file from the backup directory to the new version directory
 * If you had modified the **art\WEB-INF\groovy-whitelist.txt** file, copy the file from the backup directory to the new version directory
 * If you were using the demo HSQLDB database, after running the upgrade scripts on the ArtRepositoryDB database in the backup location, copy the updated files to the **art\WEB-INF\hsqldb** directory of the new version, overwriting the existing files. You can look at the [Tips](https://sourceforge.net/p/art/wiki/Tips/) documentation to see how you can upgrade an HSQLDB database.
@@ -45,7 +45,7 @@
 **Renamed concepts** | Some concepts have been renamed e.g. "Queries" are now "Reports", "Graphs" are now "Charts", "View Modes" are now "Report Formats", "Report on Column" report types are now "Group" reports, "Pivot Table" report types are now "JPivot" reports.
 **Jxls templates** | Jxls templates need to be recreated. Review the sample templates located in the **ART_HOME\\WEB-INF\\work\\templates** directory, or the Jxls website, http://jxls.sourceforge.net/, to see the new template structure.
 **Chained parameters** | Reports that use chained parameters will need to be modified. Review the chained parameter example in the demo database or the admin manual to see the new method of specifying chained parameters.
-**Directory location changes** | The templates directory has been moved to **ART_HOME\\WEB-INF\\work\\templates**. The export directory has been moved to **ART_HOME\\WEB-INF\\work\\export**.
+**Directory location changes** | The templates directory has been moved to **ART_HOME\WEB-INF\work\\templates**. The export directory has been moved to **ART_HOME\WEB-INF\work\export**.
 **XMLA Repors** | For Mondrian XMLA and Microsoft XMLA reports, the url, username and password fields have been removed from the report definition page and instead a datasource needs to be created from the Datasource Configuration page and then used by selecting the Datasource field in the report definition.
 **Query tags** | The special hardcoded tags or placeholders than can be used within query sql, **:USERNAME**, **:DATE** and **:TIME** have been changed to include a colon at the end i.e. **:USERNAME:**, **:DATE:** and **:TIME:**
 **Dashboard XML** | If you have xml special characters within tag content, ensure to replace them with the relevant xml character entities e.g. if the `<URL>` tag contains a url like `http://localhost:8080/art/app/runReport.do?reportId=1&p-param1=test`, you'll need to replace the `&` character with `&`, to have the url as `http://localhost:8080/art/app/runReport.do?reportId=1&p-param1=test`. For a list of the 5 special xml characters and their respective replacement strings or character entities, see http://support.esri.com/technical-article/000005870