admin/extensions: Add config for Elasticsearch 7

New in Mahara 22.04: Elasticsearch 7 can be used
as fulltext search plugin (Bug #1890356).

manual-build @ 8dad5047

-Subproject commit d96c1bb119a8a49147681d28a6bea3633612321e
+Subproject commit 8dad5047d8ab10b94ad1f6b79727076b0ae6646b

source/administration/config_site.rst

@@ -345,10 +345,10 @@ Search settings
    .. seealso::
       You can configure the internal search plugin in the :ref:`administration of the search plugin <plugin_search>`.
 
-      Elasicsearch is another search plugin that is supported by Mahara out of the box. The search server will need to be installed separately though. Elasticsearch is useful for fulltext search and is required for advanced reporting.
+      :ref:`Elasicsearch <plugin_fulltext_search>` is another search plugin that is supported by Mahara out of the box. The search server will need to be installed separately though. Elasticsearch is useful for fulltext search and is required for advanced reporting. Mahara supports Elasticsearch 5/6 and |new in Mahara 22.04| Elasticsearch 7.
 
    .. note::
-      You need to choose the Elasticsearch plugin if you turn on :ref:`'Event log reporting' <logging_settings>`.
+      You need to choose one of the Elasticsearch plugins if you turn on :ref:`'Event log reporting' <logging_settings>`.
 
 #. **Show people in public search**: If allowed, :index:`usernames can appear in public search results <single: Administration; Show people in public search>`. In addition, this feature needs to have the :index:`value <single: config.php; publicsearchallowed>` ``$cfg->publicsearchallowed = true;`` set in your config.php file and requires a search plugin that allows public search, e.g. Elasticsearch.
 

source/administration/extensions.rst

@@ -593,18 +593,20 @@ You can view all :index:`Identity Providers <single: SAML Identity Provider list
 #. **Delete IdP**: Click the *Delete* button |delete| to remove the IdP that should not be used any more on the site. You see the button only for IdPs that are not used in any institution.
 
 .. index::
-   pair: Plugins - configurable; Fulltext search
+   pair: Plugins - configurable; Elasticsearch 5/6
    single: Fulltext search
 
 .. _plugin_fulltext_search:
 
-Search: Elasticsearch
+Search: Elasticsearch 5/6
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The regular Mahara search is limited to finding accounts and in certain places titles, descriptions, and tags of pages or collections. However, Mahara can be extended with full text search capabilities via `Elasticsearch <https://www.elastic.co/products/elasticsearch>`_. Elasticsearch is is a powerful and extensible full text search engine that is also used for the learning analytics reporting in Mahara. It does require a Java server, e.g. Tomcat, to run.
 
+Mahara still supports Elasticsearch 5 and 6, identified as 'elasticsearch' in the *Plugin administration*.
+
 .. note::
-   If you are upgrading from a version of Mahara prior to Mahara 17.10 and you already had Elasticsearch in use, please take a look at the `upgrade instructions <https://git.mahara.org/mahara/mahara/blob/18.04_STABLE/htdocs/search/elasticsearch/upgrade_elasticsearch.readme>`_. That documentation also provides information on how you can set up Elasticsearch on a computer for development purposes.
+   If you are upgrading from a version of Mahara prior to Mahara 17.10 and you already had Elasticsearch in use, please take a look at the `upgrade instructions for Elasticsearch 5/6 <https://git.mahara.org/mahara/mahara/blob/18.04_STABLE/htdocs/search/elasticsearch/upgrade_elasticsearch.readme>`_. That documentation also provides information on how you can set up Elasticsearch on a computer for development purposes.
 
 .. figure:: /images/administration/plugin_elasticsearch.*
    :alt: Configure the Elasticsearch plugin
@@ -614,15 +616,15 @@ The regular Mahara search is limited to finding accounts and in certain places t
 The majority of the Elasticsearch configuration must be done on the server. This page displays that information, but does not allow you to set many configuration values.
 
 #. At the top of the screen you see the overall status of Elasticsearch.
-#. **Host**: The hostname of the Elasticsea`rch server. The default is ``127.0.0.1``.
+#. **Host**: The hostname of the Elasticsearch server. The default is ``127.0.0.1``.
 #. **Elasticsearch port**: The port used by Elasticsearch. The default is ``9200``.
 #. **Scheme**: Whether to use ``http`` or ``https``. Preferred is ``https`` for added security.
 #. **Authentication username**: The username required for the specific Elasticsearch index for this site to access information. This value is optional. It is only required when you have multiple sites accessing one Elasticsearch cluster.
 #. **Authentication password**: The password used to secure the 'Authentication username'. This value is optional.
-#. **Authentication write username**: The username for writing to the search index. This field is optional.
+#. **Authentication write username**: The username for writing to the search index. This value is optional.
 #. **Authentication write password**: The password used to secure the 'Authentication write username'. This value is optional.
 #. **Index name**: The name of the search index. The default is 'mahara'.
-#. **Bypass index**: This index can be used to load data in instead of the main one. this value is optional.
+#. **Bypass index**: This index can be used to load data in instead of the main one. This value is optional.
 #. **Elasticsearch analyzer**: The analyzer class. The default is 'mahara_analyzer'.
 #. **Elasticsearch types**: A comma-separated list of all the elements that Elasticsearch indexes. The default values are ``usr, interaction_instance, interaction_forum_post, group, view, artefact``.
 #. **Cron record limit**: Decide on the maximum number of records to be passed from the queue to the Elasticsearch server on each cron run. An empty field or ``0`` means that there is no limit.
@@ -648,6 +650,122 @@ The majority of the Elasticsearch configuration must be done on the server. This
 .. seealso::
    You can find more information about `Elasticsearch in Mahara on the wiki <https://wiki.mahara.org/index.php/Developer_Area/Specifications_in_Development/Elasticsearch>`_. There are also some `developer notes <https://wiki.mahara.org/index.php/Developer_Area/Specifications_in_Development/Elasticsearch_Plugin>`_ to get you started.
 
+.. index::
+   pair: Plugins - configurable; Elasticsearch 7
+   single: Fulltext search with
+   single: Elasticsearch 7; General settings
+
+.. _plugin_elasticsearch7:
+
+|new in Mahara 22.04| Search: Elasticsearch 7
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:index:`Support <single: New in Mahara 22.04; Elasticsearch 7>` for Elasticsearch 7 was introduced in Mahara 22.04. It is still possible to use Elasticsearch 5 or 6, but since they are not supported any more, it is recommended that you upgrade.
+
+The regular Mahara search is limited to finding accounts and in certain places titles, descriptions, and tags of pages or collections. However, Mahara can be extended with full text search capabilities via `Elasticsearch <https://www.elastic.co/products/elasticsearch>`_. Elasticsearch is is a powerful and extensible full text search engine that is also used for the learning analytics reporting in Mahara. It does require a Java server, e.g. Tomcat, to run.
+
+General Elasticsearch 7 settings
+""""""""""""""""""""""""""""""""""""""""
+
+The settings for Elasticsearch 7 resemble those for Elasticsearch 5 and 6. Some enhancements were made to requeue items and see the status of the cluster.
+
+.. figure:: /images/administration/plugin_elasticsearch7.*
+   :alt: Configure the Elasticsearch 7 plugin
+
+   Configure the Elasticsearch 7 plugin
+
+#. Statement on whether the plugin is currently in use and where to change it in the :ref:`Site settings <site_settings>`.
+#. **Plugin status**: Items that give a quick overview of the :ref:`Elasticsearch 7 plugin status <elasticsearch7_plugin_status>`.
+#. **Cluster configuration**: Items that are configured on the server for the :ref:`Elasticsearch 7 cluster configuration <elasticsearch7_cluster_config>`.
+#. **Cron record limit**: Decide on the maximum number of records to be passed from the queue to the Elasticsearch server on each cron run. An empty field or ``0`` means that there is no limit.
+
+   .. note::
+      If you use Elasticsearch for development purposes on a computer, choose a small number, e.g. ``1,500``.
+
+#. **Shards**: The number of pieces that the index makes. The default is ``5``.
+#. **Replica shards**: The number of copies of the shards. If you only have one node, set this value to ``0``, e.g. when you run Elasticsearch on a development computer connecting to a local Elasticsearch setup.
+#. **Indexing on cron**: Decide whether you want the indexing to happen automatically.
+#. **Artefact types**: The artefact types that you want to include in the search index. Only artefact types that have a hierarchy defined below are valid. You will need to reset artefacts in the queue below for your changes to take effect.
+#. Click the **Select all** or **Select none** buttons if you want to change your mind about the current selection quickly.
+#. Select individual artefact types that you want to include into or exclude from the indexing.
+#.  **Artefact types hierarchy**: Enter the hierarchy for each artefact type that you selected separated by ``|`` (a pipe). Place each artefact type on a row by itself.
+
+   .. note::
+      The first item is the artefact type, the second item is the category to which it belongs. This is an additional filter option. The third item is the main type, i.e. the tabs on the search result page.
+
+#. **Index reset**: Items relating to the resetting of the :ref:`Elasticsearch 7 index reset options <elasticsearch7_index_reset>`.
+#. Click the *Save* button to accept your changes.
+
+.. index::
+  single: Elasticsearch 7; Plugin status
+
+.. _elasticsearch7_plugin_status:
+
+Plugin status
+""""""""""""""""""""""""""""""""""
+
+See the status of the Elasticsearch 7 plugin.
+
+.. figure:: /images/administration/plugin_elasticsearch7_status.*
+   :alt: See the status of the Elasticsearch 7 plugin
+
+   See the status of the Elasticsearch 7 plugin
+
+You can quickly check if the plugin is working or which parts you may need to investigate. The overall percentage of everything fully functioning is provided.
+
+The plugin status provides information on:
+
+* Runing of the cron
+* Server access for Elasticsearch to Mahara
+* Server health: If the server is running
+* Custer health: If the Elasticsearch cluster is running
+* Index status: If there are any issues with the Elasticserach index
+
+.. index::
+  single: Elasticsearch 7; Cluster configuration
+
+.. _elasticsearch7_cluster_config:
+
+Cluster configuration
+"""""""""""""""""""""""""""""""""""""""""""
+
+The access to the Elasticsearch cluster is configured on the server so that site administrators don't change settings accidentally.
+
+.. figure:: /images/administration/plugin_elasticsearch7_cluster.*
+   :alt: View the cluster configuration of Elasticsearch 7
+
+   View the cluster configuration of Elasticsearch 7
+
+#. **Host**: The hostname of the Elasticsearch server. The default is ``127.0.0.1``.
+#. **Elasticsearch port**: The port used by Elasticsearch. The default is ``9200``.
+#. **Scheme**: Whether to use ``http`` or ``https``. Preferred is ``https`` for added security.
+#. **Authentication username**: The username required for the specific Elasticsearch index for this site to access information. This value is optional. It is only required when you have multiple sites accessing one Elasticsearch cluster.
+#. **Authentication password**: The password used to secure the 'Authentication username'. This value is optional.
+#. **Authentication write username**: The username for writing to the search index. This value is optional.
+#. **Authentication write password**: The password used to secure the 'Authentication write username'. This value is optional.
+#. **Index name**: The name of the search index. The default is 'mahara'.
+#. **Bypass index**: This index can be used to load data in instead of the main one. This value is optional.
+#. **Elasticsearch analyzer**: The analyzer class. The default is 'mahara_analyzer'.
+#. **Elasticsearch types**: A comma-separated list of all the elements that Elasticsearch indexes. The default values are ``usr, interaction_instance, interaction_forum_post, group, view, artefact``.
+
+.. _elasticsearch7_index_reset:
+
+Index reset
+"""""""""""""""""""""""""""""""""""""""""""
+
+This section shows how many records are currently in the Elasticsearch index, and how many are queued for indexing. Typically, the cron runs every five minutes and puts items into the index. In Elasticsearch 7 you can reset individual item types and thus don't have to reset all indexes, which saves times especially on large sites.
+
+.. figure:: /images/administration/plugin_elasticsearch7_index.*
+   :alt: Configure the Elasticsearch 7 plugin
+
+   Configure the Elasticsearch 7 plugin
+
+#. **Type**: The item type available for indexing.
+#. **In queue**: The number of items awaiting to be indexed for each type.
+#. **In index**: The number of items that are in the index for each type.
+#. Click the *Requeue all items* next to a type.
+#. Click the *Reset* button if you want to reset all indexes. Note: This will take several hours on large sites, and the items are not available in the fulltext search while they are being indexed.
+
 .. index::
    pair: Plugins - configurable; Internal search
    single: Exact people search