...
 | Upgrade process | The upgrade process is a "side-by-side upgrade". This means that the new dashboard WAR/ZIP file should be deployed alongside the existing WAR/ZIP/JAR file and any settings transferred from the existing to the new. |
|---|---|---|
| Where to run the upgrade? | The process must be run on the host server. |
| Obtain the installation media | Download the latest release of the required CAST Dashboard from CAST Extend. This media contains:
|
| Access to a CAST Storage Service/PostgreSQL instance (≥ 2.1) | When upgrading to ≥ 2.1 a graphical user interface has been implemented for managing the assignment of role and data authorizations to users and groups of users. This interface replaces the existing mechanism provided by the roles.xml and the authorizations.xml files. This new management interface relies on a schema hosted on a CAST Storage Service/PostgreSQL instance to store the roles/data authorizations. This schema is called cast_dashboards by default and will be created on first startup of the web application. |
| Stop all services | Before starting any upgrade process, you must ensure ALL services are stopped, for example stop Apache Tomcat or any existing Dashboards running in SpringBoot mode. |
| Anchor | ||||
|---|---|---|---|---|
|
...
| 1.x WAR file | 2.x WAR file | Notes |
|---|---|---|
| \META-INF\context.xml | Does not exist. Use new sections in \WEB-INF\classes\application.properties. | Configuration has changed. Refer to the following documentation (Step 2) for more information: |
\WEB-INF\authorizations.xml | \WEB-INF\classes\authorizations.xml | See Data authorization.
|
| \WEB-INF\domains.properties | \WEB-INF\classes\domains.properties | Configuration has changed. Refer to the following documentation (Step 2) for more information: |
| \WEB-INF\license.key | Only for the Engineering Dashboard. This file will not exist in the new Dashboard and can therefore be copied over as is to: \WEB-INF\classes\license.key | No change in configuration method. See Dashboard Service license key configuration. |
| \WEB-INF\license.xml | \WEB-INF\classes\license.xml | No change in configuration method. See Dashboard Service license key configuration and Data authorization. |
| \WEB-INF\log4j2.xml | Does not exist. Use \WEB-INF\classes\log4j2-spring.xml | No change in configuration method. See Configuring the Log and Audit Trail. |
| \WEB-INF\report.properties | Does not exist. Use equivalent section in \WEB-INF\classes\application.properties. | No change in configuration method. See CAST Report Generator - CAST Report Generator for Dashboards. |
| \WEB-INF\roles.xml | \WEB-INF\classes\roles.xml | See User roles.
|
| \WEB-INF\security.properties | Does not exist. Use equivalent section in \WEB-INF\classes\application.properties. | Configuration has changed. Refer to the following documentation: User authentication. |
| \WEB-INF\users.properties | \WEB-INF\classes\users.properties | No change in configuration method. See User authentication. |
| \engineering\resources\ed.json | WEB-INF\classes\config\ed\ed.json | If you have made configuration changes to .JSON files to create custom tiles or layout and you want to retain those changes in the new version of the Dashboard, you can re-use old .JSON files with the new Dashboard, however, please note that doing so will mean that you will not benefit from any improvements or features added to the current release of the Dashboard. |
\portal\resources\app.json | WEB-INF\classes\config\hd\app.json | |
| \portal\resources\cmp.json | WEB-INF\classes\config\hd\cmp.json | |
| \portal\resources\internal\app-navigation.json | Does not exist (withdrawn in ≥ 1.23). | - |
...
By default, the CAST Dashboard requires that at least one user is granted the ADMIN role following the first login after the User authentication configuration. This ensures that one user can access all data and configuration settings. See First login and become adminThis ensures that one user can access all data and configuration settings. This step is not required when using Dashboards 1.x and MUST be performed from the machine on which the dashboard is running, using the URL http://localhost:<port> - if you attempt it from another machine on the network, you will not be able to "become admin". See First login and become admin. This step is not required when using Dashboards 2.0 and can be skipped.
Instructions for transitioning between 1.x WAR file and 2.x ZIP file
...
| 1.x WAR file | 2.x ZIP file | Notes |
|---|---|---|
| \META-INF\context.xml | Does not exist. Use new sections in <unpacked_zip>\configurations\application.properties. | Configuration has changed. Refer to the following documentation (Step 2) for more information: |
\WEB-INF\authorizations.xml | <unpacked_zip>\configurations\authorizations.xml | See Data authorization.
|
| \WEB-INF\domains.properties | <unpacked_zip>\configurations\domains.properties | Configuration has changed. Refer to the following documentation (Step 2) for more information: |
| \WEB-INF\license.key | Only for the Engineering Dashboard. This file will not exist in the new Dashboard and can therefore be copied over as is to: <unpacked_zip>\configurations\license.key | No change in configuration method. See Dashboard Service license key configuration. |
| \WEB-INF\license.xml | <unpacked_zip>\configurations\license.xml | No change in configuration method. See Dashboard Service license key configuration and Data authorization. |
| \WEB-INF\log4j2.xml | Does not exist. Use <unpacked_zip>\configurations\log4j2-spring.xml | No change in configuration method. See Configuring the Log and Audit Trail. |
| \WEB-INF\report.properties | Does not exist. Use equivalent section in <unpacked_zip>\configurations\application.properties. | No change in configuration method. See CAST Report Generator - CAST Report Generator for Dashboards. |
| \WEB-INF\roles.xml | <unpacked_zip>\configurations\roles.xml | See User roles.
|
| \WEB-INF\security.properties | Does not exist. Use equivalent section in <unpacked_zip>\configurations\application.properties. | Configuration has changed. Refer to the following documentation: User authentication. |
| \WEB-INF\users.properties | <unpacked_zip>\configurations\users.properties | No change in configuration method. See User authentication. |
| \engineering\resources\ed.json | <unpacked_zip>\configurations\config\ed\ed.json | If you have made configuration changes to .JSON files to create custom tiles or layout and you want to retain those changes in the new version of the Dashboard, you can re-use old .JSON files with the new Dashboard, however, please note that doing so will mean that you will not benefit from any improvements or features added to the current release of the Dashboard. |
\portal\resources\app.json | <unpacked_zip>\configurations\config\hd\app.json | |
| \portal\resources\cmp.json | <unpacked_zip>\configurations\config\hd\cmp.json | |
| \portal\resources\internal\app-navigation.json | Does not exist (withdrawn in ≥ 1.23). | - |
...
| Info |
|---|
|
Step 4 - First login and become admin - ≥ 2.1 only
By default, the CAST Dashboard requires that at least one user is granted the ADMIN role following the first login after the User authentication configuration. This ensures that one user can access all data and configuration settings. See First login and become admin. This step is not required when using Dashboards 1.x and MUST be performed from the machine on which the dashboard is running, using the URL http://localhost:<port> - if you attempt it from another machine on the network, you will not be able to "become admin". See First login and become admin. This step is not required when using Dashboards 2.0 and can be skipped.
Step 5 - Undeploy the existing WAR file (optional)
Undeploy the existing war file from Apache Tomcat - you can use Apache Tomcat manager to do this, or simply delete the relevant folder and file in CATALINA_HOME\webapps. This step is optional and you may wish to leave this in place until the new dashboard is fully tested and working.
Instructions for transitioning between 2.x ZIP files
To transition between 2.x ZIP files (for example 2.0.0 to 2.1.0) is relatively simple although there is no managed "upgrade" process.
Step 1 - Deploy the new .ZIP file
Obtain the new .ZIP file and unzip it to any location on the host server.
Step 2 - Configure your new Dashboard
You will now need to transfer the details of your environment (stored in the configuration files such as web.xml/context.xml/other .properties/.xml/.json files) from the old Dashboard to the new. Please be aware that you should not perform a merge or overwrite configuration files (unless specifically requested to do so in the instructions below) - instead you must manually update the new configuration files with the details from the old configuration files.
Use the following table to find the location of the configuration files:
| 2.x ZIP file | Notes |
|---|---|
| <unpacked_zip>\configurations\application.properties. | Refer to the following documentation for more information:
See also CAST Report Generator - CAST Report Generator for Dashboards. |
| <unpacked_zip>\configurations\authorizations.xml | See Data authorization - 2.x and above. From 2.0.0 to ≥ 2.1.0 release authorizations.xml has been replaced with a graphical user interface to manage data authorizations for users/groups. Configuration is stored in a schema called "cast_dashboards" on a chosen CAST Storage Service/PostgreSQL instance. There are two choices for how to proceed:
From ≥ 2.1.0 release All authorization data is stored in the schema "cast_dashboards" and the authorizations.xml file is no longer used. CAST recommends re-using the "cast_dashboards" schema so that all existing authorizations are re-used. This is configured in the <unpacked_zip>\configurations\application.properties file. |
| <unpacked_zip>\configurations\domains.properties | Refer to the following documentation for more information: |
| Only for the Engineering Dashboard. This file will not exist in the new Dashboard and can therefore be copied over as is to: <unpacked_zip>\configurations\license.key | See Dashboard Service license key configuration. |
| <unpacked_zip>\configurations\license.xml | See Dashboard Service license key configuration and Data authorization. |
| <unpacked_zip>\configurations\log4j2-spring.xml | See Configuring the Log and Audit Trail. |
| <unpacked_zip>\configurations\roles.xml | See User roles - 2.x and above. From 2.0.0 to ≥ 2.1.0 release
From ≥ 2.1.0 release All roles data is stored in the schema "cast_dashboards" and the roles.xml file is no longer used. CAST recommends re-using the "cast_dashboards" schema so that all existing roles are re-used. This is configured in the <unpacked_zip>\configurations\application.properties file. |
| <unpacked_zip>\configurations\users.properties | See User authentication. |
| <unpacked_zip>\configurations\config\ed\ed.json | If you have made configuration changes to .JSON files to create custom tiles or layout and you want to retain those changes in the new version of the Dashboard, you can re-use old .JSON files with the new Dashboard, however, please note that doing so will mean that you will not benefit from any improvements or features added to the current release of the Dashboard. |
| <unpacked_zip>\configurations\config\hd\app.json | |
| <unpacked_zip>\configurations\config\hd\cmp.json |
Step 3 - Start the new Dashboard and check access
To start the dashboard, run the following file:
| Code Block |
|---|
<unpacked_zip>\startup.bat
<unpacked_zip>\startup.sh |
By default the dashboard is configured to run on port 8080. Use the following URL - where <server_name> is equal to the host name of the current server to access the dashboard. If you are testing on the server itself, you can use http://localhost:8080:
| Code Block |
|---|
http://<server_name>:8080 |
| Info |
|---|
|
Step 4 - First login and become admin
By default, the CAST Dashboard requires that at least one user is granted the ADMIN role following the first login after the User authentication configuration. This ensures that one user can access all data and configuration settings. This step MUST be performed from the machine on which the dashboard is running, using the URL http://localhost:<port> - if you attempt it from another machine on the network, you will not be able to "become admin". See First login and become admin.
Step 5 - Remove existing dashboard (optional)
Remove the existing Dashboard deployment if necessary. This step is optional and you may wish to leave this in place until the new dashboard is fully tested and working.
Instructions for transitioning to ≥ 2.5 JAR files
To transition to ≥ 2.5 JAR files files there is no managed upgrade process. Instead install the new dashboard side by side with the existing dashboard.
Step 1 - Deploy the new JAR file
| Info | ||||
|---|---|---|---|---|
Note that when deploying in Microsoft Windows, the installer will ask you whether you want to install a Windows Service to manage the deployment. If you have already installed a Windows Service for use with the ZIP files shipped in releases 2.0 - 2.4, then CAST highly recommends uninstalling this service before you proceed. You can do so using the following file:
or using the following command in command prompt (opened with elevated Administrator permissions), where <service_name> can be found in the properties of the Windows Service:
|
Obtain the new .JAR file and deploy it on the target server as described in:
- Standalone Engineering Dashboard deployment using JAR file
- Standalone Health Dashboard deployment using JAR file
- Standalone RestAPI deployment using JAR file
Step 2 - Configure your new Dashboard
You may now need to transfer the details of your environment (stored in the configuration files such as web.xml/context.xml/other .properties/.xml/.json files) from the old Dashboard to the new. Please be aware that you should not perform a merge or overwrite configuration files (unless specifically requested to do so in the instructions below) - instead you must manually update the new configuration files with the details from the old configuration files.
Use the following table to help. If you change any files in the new deployment, please ensure that you restart the Dashboard so that any changes are taken into account.
| Existing file | Notes |
|---|---|
| authorizations.xml | See Data authorization - 2.x and above. From 2.0.0 to ≥ 2.1.0 release authorizations.xml has been replaced with a graphical user interface to manage data authorizations for users/groups. Configuration is stored in a schema called "cast_dashboards" on a chosen CAST Storage Service/PostgreSQL instance. There are two choices for how to proceed:
From ≥ 2.1.0 release All authorization data is stored in the schema "cast_dashboards" and the authorizations.xml file is no longer used. CAST recommends re-using the "cast_dashboards" schema so that all existing authorizations are re-used. This is configured in the application.properties file. |
| license.xml | See Dashboard Service license key configuration and Data authorization. |
| log4j2-spring.xml | See Configuring the Log and Audit Trail. |
| roles.xml | See User roles - 2.x and above. From 2.0.0 to ≥ 2.1.0 release
From ≥ 2.1.0 release All roles data is stored in the schema "cast_dashboards" and the roles.xml file is no longer used. CAST recommends re-using the "cast_dashboards" schema so that all existing roles are re-used. This is configured in the <unpacked_zip>\configurations\application.properties file. |
| *.json | If you have made configuration changes to .JSON files to create custom tiles or layout and you want to retain those changes in the new version of the Dashboard, you can re-use old .JSON files with the new Dashboard, however, please note that doing so will mean that you will not benefit from any improvements or features added to the current release of the Dashboard. |
Step 3 - Undeploy the existing WAR file (optional)
Undeploy the existing war file from Apache Tomcat if you are using it - you can use Apache Tomcat manager to do this, or simply delete the relevant folder and file in CATALINA_HOME\webapps. This step is optional and you may wish to leave this in place until the new dashboard is fully tested and working.