⁠Chapter 16. Data Import Strategy

16.1. Import Strategy Overview
16.1.1. Portal Configuration
16.1.2. Page Data
16.1.3. Navigation Data
In the portal extension mechanism, developers can define an extension that portal data can be customized by.
There are several cases when it can be useful to define how to customize the Portal data; for example modifying, overwriting or inserting data into the data defined by the Portal. The portal also defines several modes for each case so that a developer only has to clarify the use-case and configure the extensions.
Report a bug

⁠16.1. Import Strategy Overview

The 'Portal Data' term referred to in this section can be classified into three types of object data:
  • Portal Configuration
  • Page Data
  • Navigation Data
Each type of object data has some differences in the import strategy.
The modes for the import strategy include the following:
  • CONSERVE
  • MERGE
  • INSERT
  • OVERWRITE
Each mode indicates how the portal data is imported. The import mode value is set whenever NewPortalConfigListener is initiated. If the mode is not set, the default value will be used. The default value is configurable as a UserPortalConfigService initial parameter. For example, the configuration below means that the default value is MERGE. 
​
​<component>
​  <key>org.exoplatform.portal.config.UserPortalConfigService</key>
​  <type>org.exoplatform.portal.config.UserPortalConfigService</type>
​  <component-plugins>
​  ............
​  </component-plugins>
​  <init-params>
​    <value-param>
​      <name>default.import.mode</name>
​      <value>merge</value>
​    </value-param>
​  </init-params>
​</component>
​
The way the import strategy works with the import mode will be clearly demonstrated in next sections for each type of data.
Report a bug

⁠16.1.1. Portal Configuration

PortalConfig defines the portal name, permission, layout and some properties of a site. These information are configured in the portal.xml, group.xml or user.xml, depending on the site type. The PortalConfig importer performs a strategy that is based on the mode defined in NewPortalConfigListener, including CONSERVE, INSERT, MERGE or OVERWRITE. Let's see how the import mode affects the process of portal data performance:
  • CONSERVE: There is nothing to be imported. The existing data will be kept without any changes.
  • INSERT: When the portal configuration does not exist, create the new portal defined by the portal configuration definition. Otherwise, do nothing.
  • MERGE and OVERWRITE have the same behavior. The new portal configuration will be created if it does not exist or update portal properties defined by the portal configuration definition.
Report a bug

⁠16.1.2. Page Data

The import mode affects the page data import as the same as PortalConfig.

Note

If the Import mode is CONSERVE or INSERT, the data import strategy acts as if in the MERGE mode in the first data initialization of the Portal.
Report a bug

⁠16.1.3. Navigation Data

The navigation data import strategy is processed at the import mode level as follows:

title

CONSERVE
If the navigation exists, leave it untouched. Otherwise, import data.
INSERT
Insert the missing description data, but add only new nodes. Other modifications remain untouched.
MERGE
Merge the description data, add missing nodes and update existing nodes.
OVERWRITE
Always destroy the previous data and recreate it.
In the portal navigation structure, each navigation can be referred to a tree which each node links to a page content. Each node contains some description data, such as label, icon, page reference, and more. Therefore, the portal provides a way to insert or merge new data to the initiated navigation tree or a subtree.
⁠
Diagram of the first data import strategy, with the foo, daa, and juu node labels branching off from the root node.

Figure 16.1. Data Import Strategy Navigation1

The merge strategy performs the recursive comparison of child nodes between the existing persistent nodes of a navigation and the transient nodes provided by a descriptor:
  1. Start with the root nodes (which is the effective root node or another node if the parent URI is specified).
  2. Compare the set of child nodes and insert the missing nodes in the persistent nodes.
  3. Proceed recursively for each child having the same name.
Let's see the example with two navigation nodes in each import mode. In this case, there are two navigation definitions: 
​<node-navigation>
​  <page-nodes>
​    <node>
​      <name>foo</name>
​      <icon>foo_icon_1</icon>
​      <node>
​        <name>juu</name>
​        <icon>juu_icon</icon>
​      </node>
​    </node>
​    <node>
​      <name>daa</name>
​      <icon>daa_icon</icon>
​    </node>
​  </page-nodes>
​</node-navigation>
​<node-navigation>
​  <page-nodes>
​    <node>
​      <name>foo</name>
​      <icon>foo_icon_2</icon>
​    </node>
​    <node>
​      <name>daa</name>
​      <icon>daa_icon</icon>
​    </node>
​  </page-nodes>
​</node-navigation>
⁠
Diagram of the second data import strategy, with the foo and daa node labels branching off from the root node.

Figure 16.2. Data Import Strategy Navigation2

For example, the navigation1 is loaded before navigation2. The Navigation Importer processes on two navigation definitions, depending on the Import Mode defined in portal configuration.
⁠

Import Mode Cases

Case 1: CONSERVE
With the CONSERVE mode, data are only imported when they do not exist. So, if the navigation has been created by the navigation1 definition, the navigation2 definition does not affect anything on it. We have the result as following
⁠
Diagram of the first data import strategy, with the foo, daa, and juu node labels branching off from the root node.

Figure 16.3. Data Import Strategy Navigation1

Case 2: INSERT
If a node does not exist, the importer will add new nodes to the navigation tree. You will see the following result:
⁠
Diagram of the insert data import strategy navigation, with the foo, daa, and juu node labels branching off from the root node. The bar node is added in this instance.

Figure 16.4. Data Import Strategy Navigation_Insert

Hereafter, the node 'bar' is added to the navigation tree, because it does not exist in the initiated data. Other nodes are kept in the import process.
Case 3: MERGE
The MERGE mode indicates that a new node is added to the navigation tree, and updates the node data (such node label and node icon in the example) if it exists.
⁠
Diagram of the insert data import strategy navigation, with the foo, daa, and juu node labels branching off from the root node. The bar node is added in this instance.

Figure 16.5. Data Import Strategy Navigation_Merge

Case 4: OVERWRITE
Everything will be destroyed and replaced with new data if the OVERWRITE mode is used.
⁠
Diagram of the second data import strategy, with the foo and daa node labels branching off from the root node.

Figure 16.6. Data Import Strategy Navigation_2

Report a bug