General update considerations#
In preparation of performing an update of nJAMS Server, please read the following notes.
nJAMS Server Update path#
Updating nJAMS Server is basically straight forward. nJAMS updates are cumulative, which means you can update to the most recent version of nJAMS Server from any prior version. However, there are some preconditions that have to be considered:
Updating nJAMS Server within the same major version is performed by deploying an update WAR file inside nJAMS Server. Typically minor updates or hotfixes are deployed that way.
Updating nJAMS Server across major versions are required to be performed by nJAMS installer. For example, an update from nJAMS Server 4.4.11 to 5.0.0 has to be rolled out by using nJAMS installer.
Updating nJAMS Server must always be considered in context with upgrading Elasticsearch. Do you want to stay with current version of Elasticsearch or do you want to upgrade Elastisearch along with updating nJAMS Server?
The following chart shows the natural update path of nJAMS Server:
The diagram shows the natural update path of nJAMS Server including the corresponding Elasticsearch versions.
Natural update path means the approach to regularily update to the next available verson. For example, you started initially with nJAMS Server 4.3, updated to version 4.4, and you are now planning to update to version 5.0.
In additon, it is also possible to update from version 4.3 directly to version 5.0. As long as the version of Elasticsearch you are currently using in your nJAMS instance is supported by the version of nJAMS Server you want to update to, the update process is rather simple. If you are coming from an nJAMS Server version that uses a version of Elasticsearch, which is not supported by the new version of nJAMS Server, you have to consider an upgrade of your Elasticsearch Cluster.
Note
Although it is possible to update nJAMS Server from any version to version 5.0, we recommend to be on version 4.4, before updating to 5.0.
Upgrade Elasticsearch#
Since nJAMS Server is tightly linked with Elasticsearch, upgrading nJAMS Server must consequently be aligned with upgrading Elasticsearch. Before updating nJAMS Server, you have to make sure you are on the right version of Elasticsearch.
nJAMS Server 4.4 and 5.0 both support Elasticsearch 5 and 6, while nJAMS Server 4.2 and 4.3 only support Elasticsearch 5.
If you are already running nJAMS Server with Elasticsearch 6, everything is fine. This is the best scenario for updating to nJAMS Server 5.0. Of course, you can also update to nJAMS Server 5.0 while staying on Elasticsearch 5.
Or you may consider to upgrade from Elasticsearch 5 to Elasticsearch 6, before updating to nJAMS Server 5.
- Do you want to use version 6 of Elasticsearch?:
nJAMS Server is delivered in different packages, depending on used version of Elasticsearch. There is a package file for using nJAMS Server with Elasticsearch 5 (
njams_server_es5_<version>.war) and there is a package file for using Elasticsearch 6 (njams_server_es6_<version>.war). nJAMS installer will detect the used version of Elasticsearch and deploy the corresponding update package automatically. If you manually deploy a new version of nJAMS Server by using the update package file, you have to pay attention to deploy the correct package of nJAMS Server. Right after upgrading Elasticsearch from 5 to 6, you have to deploy ES6 package file of nJAMS Server, respectively start nJAMS installer and peform an update.After upgrading Elasticsearch, the existing indexes of Elasticsearch will still remain in format v5, whereas new indexes will be automatically created in format v6. Elasticsearch 6 is compatible with the previous index format v5.
nJAMS Server 5.0 is able to use v5 indexes within Elasticsearch 6, but there are limitations in searching for monitoring data from the past. As long as indexes are in format v5, nJAMS Server 5.0 is able to allow searching for process instances filtered by domain object or time as usual, but is not able to allow searching for specific event data like payload or stacktrace. If nJAMS Server 5.0 should be able to allow searching for that data as well, the v5 indexes must be converted into format v6. The conversion process is called “re-indexing”.
Please note, the new incoming monitoring data is fully searchable by nJAMS Server 5.0 instantly!
Depending on the amount of monitoring data you have, the re-indexing process may be time consuming.
If you have a big Elasticsearch Cluster to migrate, you may consider to skip the re-indexing process in favor of being able to use nJAMS Server as quickly as possible, especially because the new data is immediately fully searchable.
But if you need to be able to search for payload or stacktrace information in historic data, you have to re-index the Elasticsearch indexes from v5 to v6. The re-indexing process of format v5 to v6 can be executed within nJAMS Server 5.0 after the upgrade has been performed successfully. During the re-indexing process nJAMS Server 5.0 cannot process monitoring data.
Caution
It is possible that your Elasticsearch Cluster contains indexes that are older than format v5. For example, if you already upgraded from nJAMS Server 4.0 or 4.1 in the past, or your Cluster was also used by other software than nJAMS Server (e.g. Kibana), it is possible that there are old indexes of the old format. Elasticsearch 6 is not compatible to indexes of version v2! In case your Elasticsearch Cluster has indexes of version v2 in place, you cannot upgrade to Elasticsearch 6, respectively Elasticsearch 6 will not start! You have to either re-index those indexes by using Elasticsearch tools, or decide to remove them. Since release 4.3.6, nJAMS Server logs an info message in
njams.loglog file at startup. If your Elasticsearch Cluster contains indexes prior format v5, you will see a notification in the log file.Note
Please also note, using Elasticsearch 6 may mean that queries of your nJAMS Custom Reports have to be revised. There are some major changes in Elasticsearch 6 compared to 5 regarding Elasticsearch queries and request / response bodies. Please refer to Elasticsearch website for more information. Integration Matters Support Team can also provide valuable tips.
- Do you want to stick with current version 5 of Elasticsearch?:
There is no loss of performance or functionality whatsoever, if you stay with Elasticsearch 5. For using nJAMS Server 5.0 it makes no difference, whether you use Elasticsearch 5 or 6. But you might want to consider that Elasticsearch 5 is virtually obsolete and may be out of support yet.
If that is not significant to you, you can continue to use nJAMS Server with Elasticsearch 5.
nJAMS plugins#
Another aspect is the usage of extensions in nJAMS Server. When you are using extensions like nJAMS Replay, you have to ensure that the versions of the extensions are compatible with the new version of nJAMS Server. For example, nJAMS Server 5.0 requires nJAMS Replay 5.0, the previous versions of nJAMS Replay are not compatible.
Assume you are on nJAMS Server 4.4 including nJAMS Replay 4.4 and you want to upgrade to nJAMS Server 5.0. In this scenario you would update nJAMS Server to 5.0 first. After (re-)starting nJAMS Server nJAMS Replay 4.4 is disabled and you would update nJAMS Replay as usual.
Plan maintenance time#
Updating your nJAMS instance may take some time. During that time monitoring data cannot be processed by nJAMS Server and will be accumulated on your JMS Server. Keep an eye on the limits of your JMS Server and consider that processing the backlog of monitoring data may also take time.
Backup#
It is always recommended to have a current backup of your nJAMS instance before you start the upgrade process. In an emergency, you can easily restore your nJAMS instance.