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 from 5.1 to 5.2 is required to be performed by nJAMS installer.

• Updates should always be performed while keeping the major/minor version sequence. For example, updating from 5.0 to 5.2 while skipping 5.1 is not supported. Instead you have to update from 5.0 to 5.1 first, before you can finally update to 5.2.

• 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 5.1 in succession, and you are now planning to update to version 5.2.

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 5.0 directly to 5.2. Please update first to nJAMS Server 5.1 and afterwards update to 5.2.

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

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

When you are still using nJAMS Server 5.0 or 5.1 with Elasticsearch 6, you should consider to upgrade from Elasticsearch 6 to Elasticsearch 7, before you update to nJAMS Server 5.2. Nevertheless, you can stay on Elastisearch 6 while updating to nJAMS Server 5.2.

Note

nJAMS Server 5.1 and 5.2 use the Java REST/HTTP Client of Elasticsearch to connect to Elasticsearch 7. When nJAMS Server 5.1, 5.2 connect 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, 5.2 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.

Update WildFly

nJAMS installer requires a plain HTTP connection to the WildFly in order to be able to update an nJAMS instance automatically. That means the nJAMS installer requires your WildFly to allow HTTP connections. In case you secured your WildFly to use HTTPS/TLS connections, you have to make sure an HTTP connection is allowed for localhost. Since nJAMS installer is executed on the WildFly machine, an HTTP connection for localhost should be no security issue. Temporary availability of HTTP and immediate turn-off when it is no longer needed should always be possible.

Migrate internal database

Starting with nJAMS Server 5.2, nJAMS comes with a new version of H2 database (v2). The new format is incompatible with the old format. Therefore, an update of nJAMS Server to version 5.2 also requires a conversion from H2 database format v1 to v2.

When you update an existing nJAMS Server instance, the nJAMS installer automatically converts an existing v1 database into the new v2 format.

If you plan to manually update your nJAMS instance, please consider to convert your nJAMS H2 database file.

However, if you are using an external RDBMS, this step is not required.

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.