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. For example, an update from nJAMS Server 5.0 to 5.1 can be performed by deploying the WAR file.

• Updating nJAMS Server across major versions are required to be performed by nJAMS installer. For example, an update from nJAMS Server 4.4 to 5.0 has to be rolled out by using nJAMS installer.

• Updating across major version must be done to the intial minor version, e.g., updating from 4.4 to 5.0 is supported, while updating from 4.4 to 5.1 is not.

• Updating nJAMS Server should 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? Certainly, it is also possible to update Elasticsearch without updating nJAMS Server, provided that the supported version constraints are respected.

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.4, updated to version 5.0, and you are now planning to update to version 5.1.

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

It is not recommended to update nJAMS Server 4.4 directly to 5.1. Please update first to nJAMS Server 5.0 and afterwards update to 5.1.

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, 5.0, and 5.1 support Elasticsearch 6, while nJAMS Server 5.1 also supports Elasticsearch 7.

If you are already running nJAMS Server with Elasticsearch 6, everything is fine. This is the best scenario for directly updating to nJAMS Server 5.1.

When you are still using nJAMS Server 4.4 with Elasticsearch 5, you have to upgrade from Elasticsearch 5 to Elasticsearch 6, before you can update to nJAMS Server 5.1. In addition, it is not possible to upgrade from Elaticsearch 5 directly to Elasticsearch 7! You have to upgrade first to Elasticsearch 6 as an intermediate step.

Note

nJAMS Server 5.1 uses the Java REST/HTTP Client of Elasticsearch to connect to Elasticsearch 7. When nJAMS Server 5.1 connects to Elasticsearch 6, the previous Transport Client of Elasticsearch is used. Both client types use different ports for connecting to the cluster.

Do you want to use version 7 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 6 (njams_server_es6_<version>.war) and there is a package file for using Elasticsearch 7 (njams_server_es7_<version>.war). nJAMS installer will detect the currently 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 6 to 7, you have to deploy ES7 package file of nJAMS Server.

After upgrading Elasticsearch, the existing indexes of Elasticsearch will still remain in format v6, whereas new indexes will be automatically created in format v7. Elasticsearch 7 is compatible with the previous index format v6.

With re-indexing, v6 indexes can be converted to v7. But depending on the amount of monitoring data you have, the re-indexing process may be time consuming, and there is no mandatory need for doing it.

The re-indexing process of format v6 to v7 can be executed within nJAMS Server 5.1 after the upgrade has been performed successfully. During the re-indexing process nJAMS Server 5.1 cannot process monitoring data.

Caution

It is possible that your Elasticsearch cluster contains indexes that are older than format v6. For example, if you already upgraded from nJAMS Server 4.3 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 7 is not compatible to indexes of version v5! That means, you cannot upgrade to Elasticsearch 7, respectively Elasticsearch 7 will not start, if you try anyway! If your cluster contains nJAMS indexes of v5, you have to use nJAMS Server 5.0 for re-indexing these indexes to v6 or to delete them, before updating nJAMS Server to 5.1. If your cluster contains other v5 indexes, you have to either re-index those indexes by using Elasticsearch tools, or decide to remove them. You can use the Administration -> Connections -> Indexer -> Index Management tab for verfying whether or not your v6 cluster contains old v5 indexes.

Caution

Please also note, using Elasticsearch 7 may mean that queries of your nJAMS Custom Reports have to be adapted to the new Elasticsearch API. 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 6 of Elasticsearch?:

There is no loss of performance or functionality whatsoever, if you stay with Elasticsearch 6. For using nJAMS Server 5.1 it makes no difference, whether you use Elasticsearch 6 or 7. But you might want to consider that some minor versions of Elasticsearch 6 are 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 6.

nJAMS plugins

Another aspect is the usage of extensions in nJAMS Server. Plugins such as nJAMS Replay or IM Flows are obsolete now. Starting with version 5.1 the functionality of all plugins is moved into the nJAMS Server core component. nJAMS Replay and IM Flows are now features of nJAMS Server that just have to be unlocked. A software license has to be acquired for each feature. The software license comes with license key and this key is used to activate the feature.

When you are updating your nJAMS Server instance that includes plugins, it is required to deploy the placeholder WAR files of the used plugins next to the nJAMS Server WAR file. The placeholder WAR files are available at Integration Matters Download Portal. After restarting the nJAMS Server instance, the update procedure automatically converts the plugins into unlocked features.

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.