How to Revert Retain 4 to Retain 3 Indexes

  • 7019102
  • 14-Sep-2015
  • 07-Aug-2017


Retain 4.x


Under certain - albeit rare - circumstances, a customer may need to re-index all of their messages.  This is a somewhat complex subject because of varying factors:

  • Retain developers changed the index schema to enhance indexing performance or for other unspecified reasons and some customers may want or need that new index schema.
  • Customer may not have had Retain indexing all supported attachment types or had pre-configured byte limits to what Retain would index (usually set by older versions of Retain).
  • Customer may have mistakenly selected the wrong indexing engine, going with the high performance indexer (a.k.a., "external HPI") rather than the standard ("internal") indexer and needs to correct that.
  • Indexes became corrupted through a hardware issues.


A customer should call in to GWAVA tech support and have a tech support engineer perform certain steps to cause Retain to re-index all of the messages. We discourage customers from doing these steps on their own.

Explanation of Which Steps Are Necessary in Your Situation

Not all the steps will need to be followed in some cases, so here is a guide:

  • The ASConfig.cfg step is only necessary if:
    • The migration never completed.
    • The customer does not have Retain 3 indexes to search while you are migrating again.
    • The customer selected the wrong index engine (HPI instead of standard) after the upgrade or installation of Retain 4.
  • Rename the HPIRemoteConfig.cfg and hpi.keystore files:

    Windows:C:\Program Files\Beginfinite\Retain\RetainServer\WEB-INF\solrweb\WEB-INF\cfg\

    Command Line Example (Linux):
    mvHPIRemoteConfig.cfg HPIRemoteConfig.cfg.old
    mvhpi.keystore hpi.keystore.old
  • Resetting the index state of all messages is needed every time except when the customer selected the wrong index engine after the upgrade or installation of Retain 4. 
  • Deleting the indexes is only necessary if:
    • The index schema was changed by Retain development and the customer wants or needs the new schema.  The old indexes will have to be deleted because they will no longer be valid in the new schema; or,
    • Confidence in the existing index integrity is in question; or,
    • The customer does not need to perform any searches while messages get re-indexed.  It is ideal to start off fresh. 
  • Logging into the Retain UI and clicking on the button the migrate the indexes is only necessary if the ASConfig.cfg was performed.

Steps for Re-indexing

Again, not all steps may need to be performed based on the criterion outlined above.

  1. Shut down tomcat.
  2. Revert back to pre-migration state.
    1. Back up the ASConfig.cfg.
    2. Edit the ASConfig.cfg:

​Former Lucene Customers

If the customer upgraded from Retain 3 and their former indexer was Lucene:

  1. Remove all the information between following tags (and remove the tags themselves):  

<activeIndexEngines> and </activeIndexEngines>

  1. Remove the entire tag (hint: search on frontEndSearchEngine)

 <frontEndSearchEngine class="com.gwava.model.indexing.SolrCloudConfig" reference="../activeIndexEngines/com.gwava.model.indexing.SolrCloudConfig"/>

  1. Save your changes and proceed to the next applicable major step.

Former Exalead Customers

If the customer upgraded from Retain 3 and their former indexer was Exalead:

a. Remove all the information between following tags (and remove the tags themselves):

<com.gwava.model.indexing.SolrCloudConfig> and </com.gwava.model.indexing.SolrCloudConfig>

b. Save your changes and proceed to the next applicable major step.​

  1. Reset the index state of all messages in the Retain database's t_message table, f_indexed column to 1:

MySQL example:  ​update [database name].t_message set f_indexed = 1;

For instructions on logging into MySQL click here.

It is assumed that systems using MS SQL and Oracle have a dba who would know how to run queries.

  1. Go to the index directory.
    1. Delete the log.1 file if it exists; if the customer does not need to perform searches using the old Retain 3 indexes, then also delete all remaining files in the index directory.
    2. Delete the solrhome subdirectory.
  2. Start up tomcat.
  3. Login to the RetainServer web admin UI, click on Server Configuration | Index  and click on the button to migrate the indexes.

Additional Information

This article was originally published in the GWAVA knowledgebase as article ID 2617.