Upgrading Augmented Search

As with any modules, before upgrading to a more recent version please make sure to consult the release notes to identify if any of the features you're using have been modified (or deprecated) or if any changes in behavior should be expected. This document assumes you are upgrading either from Augmented Search 1.4.4 to 1.5x or from Augmented Search 3.0.3 to 3.1x.

If you are upgrading from an earlier version of Augmented Search, please review earlier versions of this page. In most cases, you will be able to upgrade from earlier versions directly to the latest version of Augmented-Search, but please make sure to review past release notes and upgrade instructions.

If you are using a custom mapping (for example through augmented-search-custom-configuration) with a previous version, make sure to update your mapping prior to re-indexing data with AS 1.5+/3.1+.

Please also make sure to validate the upgrade in a staging or pre-prod environment before applying the change to your production environment.

Impact on existing Augmented Search sites

This version of Augmented Search introduces an entirely new structure (mapping) for Elasticsearch indices when compared to previous versions (below 1.4.4 and below 3.0.3). Although the older structure and the newer structure will not conflict with each other, upgrading to this newer version of Augmented Search will have an impact on the ability to search while upgrading (and its first indexing) is taking place, since Augmented Search 1.5.0 and 3.1.0 will not be able to communicate with search indices generated with version 1.4.4/3.0.3 and below.

Since indices will not conflict between versions, it remains possible to "warm-up" the Elasticsearch cluster with 1.5x & 3.1x indices in advance by either:

• Copying the data to a separate Jahia host, install Augmented Search 1.5x/3.1x, link it to the Elasticsearch cluster, and trigger a re-indexing
• Installing AS 1.5x/3.1x on only one host of your cluster, ensuring not search traffic get sent to that host, and trigger a re-indexing

Once the Elasticsearch cluster has been warmed-up with the new indices, you can simply upgrade Augmented Search, and finally, trigger an (optional) full re-indexing once done to ensure the latest data is available for search.

Note that the above procedure only applies to situations in which downtime of Augmented Search is not acceptable. If the unavailability of search results is acceptable (for example during a scheduled maintenance window), then the upgrade can be performed by upgrading Augmented-Search and performing a re-indexing on all sites. Since Augmented Search supports indexing per site, so you can prioritize which sites to be re-indexed first.

In all cases, make sure to validate the upgrade in a staging or pre-prod environment before applying the change to your production environment.

Upgrading to Augmented Search 1.5.2/3.1.2

As part of the release of Augmented-Search 1.5.2/3.1.2, a dependent module was renamed from "elasticsearch-connector-7" to "elasticsearch-connector". Although Augmented Search 1.5.2/3.1.2 is a maintenance release that does not introduce any breaking change, the rename of the module requires a slightly adjusted upgrade procedure since the database connection is not shared between "elasticsearch-connector-7" and "elasticsearch-connector".

This upgrade procedure does not require re-indexing but involves a minimal interruption of the search services while the module is being installed and until the new configuration is set. The upgrade procedure is as follow:

1. Install elasticsearch-connector-7 7.4.4 (for Jahia 7x) or elasticsearch-connector-7 7.4.5 (for Jahia 8x). This new version of elasticsearch-connector-7 aims at bringing compatibility between elasticsearch-connector-7 and elasticsearch-connector (the new module), allowing both to be running together on the platform. At that point, search functionalities are interrupted.
2. Remove the previous version of elasticsearch-connector-7 from the platform. This will restore search functionalities. 
3. Install elasticsearch-connector 2.0.0 (for Jahia 7x) or elasticsearch-connector 3.0.0 (for Jahia 8x). At that point, the availability of Augmented Search is not impacted.
4. In Jahia Administration, navigate to database connection and create a new connection using the new module (the one not specifying "version 7.x.x"). Point it to the same elasticsearch cluster as before but use a different connection id. At that point, the availability of Augmented Search is not impacted.
5. Upgrade Augmented Search to version 1.5.2 / 3.1.2 and wait for the module to start. At that point, search functionalities are interrupted.
6. In Jahia Administration, navigate to Augmented Search configuration and set the database connection to the one you created in step 2. This will restore search functionalities.
7. (optional) You can now remove elasticsearch-connector-7 if it is not used by other modules

Jahia with both elasticsearch-connector (in red) and elasticsearch-connector-7

Step 6 can be easily scripted with the following GraphQL query:

mutation {
  admin {
    search {
      setDbConnection(connectionId: "new-connection-id")
    }
  }
}

Previously installed modules versions

Having multiple versions of Augmented Search and Jahia GraphQL Core Provider installed on the same Jahia might generate conflicts. As part of your upgrade process, please make sure to remove all previous versions of these two modules, keeping only the most recent ones.