docs(metadata): refactor metadata customization with new solr script I…

…QSS#7903

doc/sphinx-guides/source/admin/metadatacustomization.rst

@@ -639,32 +639,38 @@ Updating the Solr Schema
 Once you have enabled a new metadata block you should be able to see the new fields in the GUI but before you can save
 the dataset, you must add additional fields to your Solr schema.
 
-An API endpoint of your Dataverse installation provides you with a generated set of all fields that need to be added to the Solr schema
-configuration, including any enabled metadata schemas:
+An API endpoint of your Dataverse installation provides you with a generated set of all fields that need to be added to
+the Solr schema configuration, including any enabled metadata schemas:
 
-``curl http://localhost:8080/api/admin/index/solr/schema``
+``curl "http://localhost:8080/api/admin/index/solr/schema"``
+
+You can use :download:`update-fields.sh <../../../../conf/solr/8.8.1/update-fields.sh>` to easily add these to the
+Solr schema you installed for your Dataverse installation.
+
+The script needs a target XML file containing your Solr schema. (See the :doc:`/installation/prerequisites/` section of
+the Installation Guide for a suggested location on disk for the Solr schema file.)
+
+You can either pipe the downloaded schema to the script or provide the file as an argument. (We recommended you to take
+a look at usage output of ``update-fields.sh -h``)
+
+.. code-block::
+    :caption: Example usage of ``update-fields.sh``
+
+    curl "http://localhost:8080/api/admin/index/solr/schema" | update-fields.sh /usr/local/solr/server/solr/collection1/conf/schema.xml
 
-For convenience and automation you can download and consider running :download:`updateSchemaMDB.sh <../../../../conf/solr/8.8.1/updateSchemaMDB.sh>`. It uses the API endpoint above and writes schema files to the filesystem (so be sure to run it on the Solr server itself as the Unix user who owns the Solr files) and then triggers a Solr reload.
-Due to `an issue with schema.xml including the generated schema_dv_mdb_copies.xml file <https://github.com/IQSS/dataverse/issues/7864>`_ additional steps are currently needed. Once schema_dv_mdb_copies.xml has been generated by the script, you'll need to copy/paste the set of <copyField> elements in the generated file into schema.xml manually and then restart solr (or trigger a Solr reload).
+You will need to reload your Solr schema via an HTTP-API call, targeting your Solr instance:
 
-By default, it will download from your Dataverse installation at `http://localhost:8080` and reload Solr at `http://localhost:8983`.
-You may use the following environment variables with this script or mix'n'match with options:
+``curl "http://localhost:8983/solr/admin/cores?action=RELOAD&core=collection1"``
 
-====================  ======  ===============================================  =========================================================
-Environment variable  Option  Description                                      Example
-====================  ======  ===============================================  =========================================================
-`DATAVERSE_URL`       `-d`    Provide the URL to your Dataverse installation   *http://localhost:8080*
-`SOLR_URL`            `-s`    Provide the URL to your Solr instance            *http://localhost:8983*
-`UNBLOCK_KEY`         `-u`    If your installation has a blocked admin API     *xyz* or */secrets/unblock.key*
-                              endpoint, you can provide either the key itself
-                              or a path to a keyfile
-`TARGET`              `-t`    Provide the config directory of your Solr core   */usr/local/solr/solr-8.8.1/server/solr/collection1/conf*
-                              "collection1"
-====================  ======  ===============================================  =========================================================
+You can easily roll your own little script to automate the process (which might involve fetching the schema bits
+from some place else than your Dataverse installation).
 
-See the :doc:`/installation/prerequisites/` section of the Installation Guide for a suggested location on disk for the Solr schema file.
+Please note that reconfigurations of your Solr index might require a re-index. Usually release notes indicate
+a necessary re-index, but for your custom metadata you will need to keep track on your own.
 
-Please note that if you are going to make a pull request updating ``conf/solr/8.8.1/schema.xml`` with fields you have added, you should first load all the custom metadata blocks in ``scripts/api/data/metadatablocks`` (including ones you don't care about) to create a complete list of fields.
+Please note also that if you are going to make a pull request updating ``conf/solr/8.8.1/schema.xml`` with fields you have
+added, you should first load all the custom metadata blocks in ``scripts/api/data/metadatablocks`` (including ones you
+don't care about) to create a complete list of fields. (This might change in the future.)
 
 Reloading a Metadata Block
 --------------------------