When updating your system, some custom configuration may cause conflicts if the updated configurations do not match the existing customizations.

Context

Conflicts occur when updating features. In rare cases, updating other master data also can cause conflicts. The actions described in this article are carried out in the censhare Admin Client.

Prerequisites

You should be familiar with the system configuration of censhare.

Introduction

When you update or patch your system censhare performs a comparison check of the updated configurations in order to detect incompatibilities. This avoids errors and system crashes, which is why you should never ignore warnings generated during a patch or update.

Conflicts can occur if your user custom configurations in the Master data that do not match the default data model. Adding, renaming, removing or changing the sort order of items can cause these conflicts. For example, if censhare tries to add an attribute to a feature but the feature has been renamed or removed, a conflict is thrown.

It is always recommended to check the configuration where the conflict occurred after an update. Read our best practices and recommendations in this article to learn how to do this.

Identify conflicts after an update

censhare writes conflicts that occur during an update in the server log file. The file can be accessed under the following path:

~/censhare/censhare-Server/work/logs/server-0.0.log

In the log file, check all "com.censhare.support.xml.XmlPatchExeption" messages and the respective patch commands. In the patch command, the feature where the conflict occurs is identified by its ID. For example: feature="censhare:keyword-ref". Copy the feature ID with a conflict to the clipboard.

Note: In most cases, update conflicts occur in features. However, conflicts can occur in any master data table during an update. The first attribute of the <patch/> command identifies the master data table.

Identify the conflicted configuration

Note: The following steps are carried out in the censhare Admin Client. You also need an XML editor to open and edit your custom configuration file.

  1. In the censhare Admin Client, open the Master data and double click the "Feature" directory or the respective directory where the conflict occurs..

  2. In the list, double click the item where the conflict occurs. The configuration dialog opens in a new window.

  3. In the part of the configuration where the conflict occurs, the message "THIS CONFIG HAS CONFLICTS" is shown.

  4. Scroll down to the section "Conflicts that occurred during a patch on this configuration". Here you find the necessary information to identify the conflict.

  5. The "error" message shows the cause of the conflict, for example: "Attribute '[name]' already exists".

  6. The "Patch command" field shows the update command censhare was executing when the conflict occurred, for example:

    <patch feature="censhare:keyword-ref" type="patch-index-config"
   <add-attr select="index-config" attr="isnull-column" value="true"/>
</patch>
    CODE

    • The <patch/> element wraps all commands and identifies the "feature" to be updated. The attribute value is the feature ID, for example: "censhare:keyword-ref".

    • The "type" attribute indicates which part of the configuration is updated. For example: "patch-index-config".

    • The <add-attr/> command is used to add a new parameter to the master data entry. Other possible commands are: <replace-attr/> or <remove-attr/>.

    • The "select" attribute contains an XPath expression that points to the node of the custom configuration. For example "index-config".

      The "attr" attribute references the attribute itself. The "value" attribute contains the value of the attribute.

  7. To decide whether any action is needed, download your custom configuration:

    • Go back to the "Master data/Feature" table and select the feature where the conflict occurs.

    • Click "Export" and save the configuration file on your computer:

      Icon

      Action

      Export configuration

  8. Open as well the downloaded XML configuration in an external editor.

  9. Search the element from the patch command snippet in the data structure of the XML configuration:

    <index-configs>
   <index-config is-custom="true" isnull-column="true"/>
</index-configs>
    CODE

    • In this example, censhare tries to add an attribute to the index configuration that already exists in the custom configuration. The conflict can be ignored.

  10. In the configuration dialog, select the field "Mark conflict as resolved" and click OK.

  11. If the conflict needs further action, adjust the XML configuration file and import it back into the system. For more information, see the following section.

Examples

The following examples give you some hints and solutions for conflicts that can occur during an update.

1. Add a new attribute that already exists

Conflict: During an update, censhare tries to add an attribute that already exists in a feature:

<patch feature="censhare:keyword-ref" type="patch-index-config"
   <add-attr select="index-config" attr="isnull-column" value="true"/>
</patch>
CODE

Custom configuration: The XML file shows that the attribute and value already exist.

<index-configs>
   <index-config is-custom="true" isnull-column="true"/>
</index-configs>
CODE

Solution: There is nothing to do. Mark the conflict as resolved and restart your server.

2. Remove an attribute that does not exist

Conflict: During an update, censhare tries to remove an attribute that does not exist from a feature.

<patch feature="censhare:keyword-ref" type="patch-index-config"
   <remove-attr select="index-config" attr="isnull-column" value="true"/>
</patch>
CODE

Custom configuration: In the XML file, the configuration and/or the attribute do not exist.

<index-configs/>

Solution: There is nothing to do. Mark the conflict as resolved and restart your server.

3. Replace attributes in a different sort order

Conflict: During an update, censhare tries to replace attributes and values of several features. The patch commands are executed consecutively in the defined order. A conflict is shown although all features are present in the configuration file. The conflict is caused because the sort order in the configuration file is different from the sort order in the patch command.

<patch feature="censhare:text.meta" type="patch-index-config">
  <replace-attr 
     select="index-config/fulltext/feature[@key='censhare:text.name']"
     attr="key"
     value="old_name"/>
  <replace-attr 
     select="index-config/fulltext/feature[@key='censhare:text.mimetype']"
     attr="key"
     value="censhare:text.name"/>
  <replace-attr 
     select="index-config/fulltext/feature[@key='censhare:text.wf_target']"
     attr="key"
     value="censhare:text.mimetype"/>
  <replace-attr 
     select="index-config/fulltext/feature[@key='censhare:text.modified_by']"
     attr="key"
     value="censhare:text.wf_target"/>
  <replace-attr select="index-config/fulltext/feature[@key='censhare:text.created_by']"
     attr="key"
     value="censhare:text.modified_by"/>
  <replace-attr 
     select="index-config/fulltext/feature[@key='censhare:text.checked_out_by']"
     attr="key"
     value="censhare:text.created_by"/>
  <replace-attr 
     select="index-config/fulltext/feature[@key='censhare:text.application']"
     attr="key"
     value="censhare:text.checked_out_by"/>
  <replace-attr 
     select="index-config/fulltext/feature[@key='censhare:text.id']"
     attr="key"
     value="censhare:text.application"/>
  <replace-attr 
     select="index-config/fulltext/feature[@key='censhare:text.type']"
     attr="key"
     value="censhare:text.id"/>
  <replace-attr 
     select="index-config/fulltext/feature[@key='old_name']"
     attr="key"
     value="censhare:text.type"/>
</patch>
CODE

Custom configuration: The virtual index shows a list of features that are indexed. The features are indexed with different priority. The sort order does not match the sort order of the patch commands.

<index-configs>
   <index-config type=“virtual-fulltext”>
      <fulltext>
      <!-- 1st prio indexes -->
         <feature key=“censhare:text.name” mode=“fulltext”/>
         <feature key=“censhare:text.type” mode=“fulltext”/>
         <feature key=“censhare:text.id” mode=“fulltext”/>
         <feature key=“censhare:text.application” mode=“fulltext”/>
         <feature key=“censhare:text.checked_out_by” mode=“fulltext”/>
         <feature key=“censhare:text.created_by” mode=“fulltext”/>
         <feature key=“censhare:text.modified_by” mode=“fulltext”/>
         <feature key=“censhare:text.wf_target” mode=“fulltext”/>
         <feature key=“censhare:text.mimetype” mode=“fulltext”/>
      <!-- 2nd prio indexes -->
         <feature key=“censhare:text.city” mode=“fulltext”/>
         <feature key=“censhare:text.annotation” mode=“fulltext”/>
         <feature key=“censhare:text.author” mode=“fulltext”/>
         <feature key=“censhare:text.description” mode=“fulltext”/>
         <feature key=“censhare:text.domain” mode=“fulltext”/>
         <feature key=“censhare:text.domain2" mode=“fulltext”/>
         <feature key=“censhare:text.keywords” mode=“fulltext”/>
         <feature key=“censhare:text.language” mode=“fulltext”/>
         <feature key=“censhare:text.storage_state” mode=“fulltext”/>
         <feature key=“censhare:text.wf_id” mode=“fulltext”/>
         <feature key=“censhare:text.wf_step” mode=“fulltext”/>
         <feature key=“censhare:text.wf_worst_state_id” mode=“fulltext”/>
       </fulltext>
    </index-config>
</index-configs>
CODE

Solution: The purpose of this update is to change the sort order of the features in the virtual index in order to enhance the search results of the quick search. You can do the following to resolve the conflict:

  • If you do not want to change the sort order of the virtual index and keep your custom configuration, mark the conflict as resolved and restart your server.

  • If you want to adopt the new sort order and discard your custom configuration, remove the custom configuration from your system. Mark the conflict as resolved and restart your server.

  • If you want to adopt the new sort order and keep your custom configuration, adjust the custom configuration file so that it matches the sort order of the patch commands. Import the adjusted configuration into your system. Mark the conflict as resolved and restart your server.

Result

The patch or update is installed without conflicts on your system.