{docbook}
<abstract>
<para>
The eXo Platform migration from 3.0 to 3.5 is performed automatically when the server is started. This chapter represents step-by-step instructions that allows you to migrate eXo Platform from 3.0 to 3.5 through the following topics:
</para>
<itemizedlist>
<listitem>
<para>
<link linkend="ADM.Migration.What_needs_to_be_migrated">What needs to be migrated?</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="ADM.Migration.Migrate_Transparent_Configuration">Migrate with transparent configuration</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="ADM.Migration.Upgrade_plugins_details">Upgrade plugins details</link>
</para>
</listitem>
</itemizedlist>
</abstract>
{docbook}

h1. What needs to be migrated? {anchor:id=ADM.Migration.What_needs_to_be_migrated}

There are many changes between eXo Platform 3.0 and eXo Platform 3.5, including data type structure (JCR node type), pre-defined data, templates and gadgets:

* Social data: model, and space templates.
* Knowledge data: data of Forums, Wiki and Answers.
* Collaboration data: data of Calendar.
* Content data structure: Document's vote, favorite, illustration, templates, pre-defined scripts and queries.
* Platform navigation.
* Content Re-import/Migration. At the first time when eXo Platform 3.0 was deployed, the XML contents file in webapps were imported into database. During the eXo Platform 3.0 runtime, the content might be updated/deleted. Now, there are the same content in eXo Platform 3.5 webapps, so you can re-import/override the old one of eXo Platform 3.0 by new one from the eXo Platform 3.5's XML content file.
* Many Gadgets.
* Users directories structure in JCR data.

All of changes above will be migrated automatically by the migration tools that are detailed as below.

h1. Migrate with transparent configuration {anchor:id=ADM.Migration.Migrate_Transparent_Configuration}

{note}
This section discusses how to migrate eXo Platform with only one server start-up.
Every configuration will be put in 2 files: 
* With Tomcat bundle, they are in _$PLATFORM\_TOMCAT\_HOME/gatein/conf/configuration.properties_ and _$PLATFORM\_TOMCAT\_HOME/gatein/conf/portal/portal/configuration.xml_
* With Jboss bundle, they are in _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.properties_ and _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/portal/portal/configuration.xml_
{note}

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Step 1. Prepare an environment.
</emphasis>
</citetitle>
</para>
{docbook}

*1.* Back up the eXo Platform 3.0 and its data.

*2.* Configure eXo Platform 3.5 to run with the eXo Platform 3.0 data as follows:

*i.* With Tomcat bundle, copy 2 folders "index" and "value" from _$PLATFORM\_TOMCAT\_HOME/gatein/data/jcr_ to _$PLATFORM\_TOMCAT\_HOME/gatein/data/jcr_. With Jboss bundle, copy 2 folders "index" and "value" from _$PLATFORM\_JBOSS\_HOME/gatein/jcr_ to _$PLATFORM\_JBOSS\_HOME/server/default/data/gatein/jcr_.

*ii.* With Tomcat bundle, configure the database connections in the _$PLATFORM\_TOMCAT\_HOME/conf/server.xml_ file to point to the eXo Platform 3.0 database.

For example, if your eXo Platform 3.0 runs on mySQL database, you need to configure the _server.xml_ file as below:

{code}<!-- eXo JCR Datasource for portal -->
	<Resource name="exo-jcr_portal" auth="Container" type="javax.sql.DataSource"
		maxActive="128" maxIdle="32" maxWait="10000"
		testWhileIdle="true" timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1"
		username="${db.username}" password="${db.password}" driverClassName="com.mysql.jdbc.Driver"
			url="jdbc:mysql://${db.host}:${db.port}/${db.jcr.name}"/>

<!-- eXo IDM Datasource for portal -->
	<Resource name="exo-idm_portal" auth="Container" type="javax.sql.DataSource"
	   maxActive="128" maxIdle="32" maxWait="10000"
	   testWhileIdle="true" timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1"
	   username="${db.username}" password="${db.password}" driverClassName="com.mysql.jdbc.Driver"
			url="jdbc:mysql://${db.host}:${db.port}/${db.idm.name}"/>{code}

With Jboss bundle, configure the _$PLATFORM\_JBOSS\_HOME/server/default/deploy/gatein-ds.xml_ file.

{code:xml}<!-- eXo IDM for portal -->
    <no-tx-datasource>
      <jndi-name>exo-idm_portal</jndi-name>
      <connection-url>jdbc:mysql://_$host_:3306/_$dbname-idm_</connection-url>
      <driver-class>com.mysql.jdbc.Driver</driver-class>
      <user-name>_$username_</user-name>
      <password>_$password_</password>
      <min-pool-size>5</min-pool-size>
      <max-pool-size>20</max-pool-size>
      <idle-timeout-minutes>0</idle-timeout-minutes>
      <prepared-statement-cache-size>32</prepared-statement-cache-size>
   </no-tx-datasource>
 
   <!-- eXo JCR Datasource for portal -->
   <no-tx-datasource>
      <jndi-name>exo-jcr_portal</jndi-name>
      <connection-url>jdbc:mysql://_$host_:3306/_$dbname-jcr_</connection-url>
      <driver-class>com.mysql.jdbc.Driver</driver-class>
      <user-name>_$username_</user-name>
      <password>_$password_</password>
      <min-pool-size>5</min-pool-size>
      <max-pool-size>20</max-pool-size>
      <idle-timeout-minutes>0</idle-timeout-minutes>
      <prepared-statement-cache-size>32</prepared-statement-cache-size>
   </no-tx-datasource>{code}

*iii.* Delete the _JCR\_CONFIG_ table in the JCR database: "jdbc\:mysql\://${{{ {db.host} }}}:${{{ {db.port} }}}/${{{ {db.jcr.name} }}}"


{docbook}
<para>
<citetitle>
<emphasis role="bold">
Step 2. Configure to migrate the eXo Platform data from 3.0 to 3.5.
</emphasis>
</citetitle>
</para>
{docbook}

*1.* Add the following code to the _$PLATFORM_\TOMCAT\_HOME/gatein/conf/configuration.properties_ or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.properties_ file.

{code}
############
# Upgrades #
############
# JCR user directories structure migration configuration
# This configuration is optional, if you do not want to run it, you set use-old-user-distribution=true and run-jcr-user-directories-migrate=false
use-old-user-distribution=false
run-jcr-user-directories-migrate=true

#This configuration for JCR session time-out. It is very important to run JCR user directories migration
#This configuration is example for a Platform with 1000 users
#Please see more detail in section
gatein.jcr.transaction.timeout=10000

### Commons upgrade plugins configuration
## indicates if upgrade plugins is enabled or not

#Gadget upgrade plugin, it is required
commons.upgrade.Upgrade-Gadgets.enable=true

#ECMS upgrade plugin, all are required
commons.upgrade.UpgradeVotingNodeTypePlugin.enable=true
commons.upgrade.FavoriteActionUpgradePlugin.enable=true
commons.upgrade.ThumbnailNodeTypeUpgradePlugin.enable=true

#ECMS template and script upgrade plugin, they are required
commons.upgrade.NodeTypeTemplateUpgradePlugin.enable=true
commons.upgrade.QueryUpgradePlugin.enable=true
commons.upgrade.ScriptUpgradePlugin.enable=true
commons.upgrade.SiteExplorerTemplateUpgradePlugin.enable=true
commons.upgrade.WCMTemplateUpgradePlugin.enable=true
commons.upgrade.UserViewUpgradePlugin.enable=true

#CS upgrade plugin, it is required
commons.upgrade.UpgradeCalendarPlugin.enable=true

#Social upgrade plugin, it is required
commons.upgrade.UpgradeToMOSPlugin.enable=true

#Social space template upgrade plugin, it is required
commons.upgrade.UpgradeTemplatePlugin.enable=true

#KS forums, all of them are required
commons.upgrade.UpgradeForumPlugin.enable=true
commons.upgrade.UpgradeWikiPlugin.enable=true
commons.upgrade.UpgradeAnswerPlugin.enable=true

#Portal navigation upgrade plugin
#This Configuration is optional. If you do not want to migrate your portal/groups navigation, set commons.upgrade.Upgrade-Navigations.enable=false
commons.upgrade.Upgrade-Navigations.enable=true

#Space home page template plugin, it is required
commons.upgrade.Upgrade-Spaces-Home-page.enable=true

##This Configuration is optional. If you do not want to re-import the contents, set commons.upgrade.Upgrade-WCM-Contents.enable=false
commons.upgrade.Upgrade-WCM-Contents.enable=true

## indicates the desired execution order (names of upgrade plugins separated with commas ",")
commons.upgrade.plugins.order=Spaces-Home-page,Upgrade-Gadgets,Upgrade-Navigations,Upgrade-WCM-Contents,UpgradeVotingNodeTypePlugin,FavoriteActionUpgradePlugin,ThumbnailNodeTypeUpgradePlugin,UpgradeToMOSPlugin,UpgradeTemplatePlugin,UpgradeAnswerPlugin,UpgradeWikiPlugin,UpgradeForumPlugin,UpgradeCalendarPlugin,NodeTypeTemplateUpgradePlugin,QueryUpgradePlugin,ScriptUpgradePlugin,SiteExplorerTemplateUpgradePlugin,WCMTemplateUpgradePlugin,UserViewUpgradePlugin 

## Proceed to the upgrade if it is the first time you run this service
commons.upgrade.proceedIfFirstRun=true{code}

*2.* Add the following code to the _$PLATFORM\_TOMCAT\_HOME/gatein/conf/portal/portal/configuration.xml_ or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.xml_ file.

{code:xml}<?xml version="1.0" encoding="UTF-8"?>
<configuration
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd http://www.exoplatform.org/xml/ns/kernel_1_2.xsd"
        xmlns="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd">

  <!--Configuration for migration JCR user directories structure-->
  <component>
    <key>org.exoplatform.services.jcr.ext.hierarchy.NodeHierarchyCreator</key>
    <type>org.exoplatform.services.jcr.ext.hierarchy.impl.NodeHierarchyCreatorImpl</type>
    <init-params>
      <value-param>
        <name>old-user-distribution</name>
        <value>${use-old-user-distribution:false}</value>
      </value-param>
      <value-param>
        <name>auto-migrate</name>
        <value>${run-jcr-user-directories-migrate:false}</value>
      </value-param>
    </init-params>
  </component>

  <!-- Configuration for migration Portal/groups navigation-->
  <!-- This Configuration is optional. If you do not want to migrate your portal/groups navigation, remove this session -->
  <!-- If there are some portals in your Platform, you need to configure for each portal-->
  <external-component-plugins>
    <!-- The full qualified name of the UserPortalConfigService -->
    <target-component>org.exoplatform.portal.config.UserPortalConfigService</target-component>
    <component-plugin>
      <!-- The name of the plugin -->
      <name>new.portal.config.user.listener</name>
      <!-- The name of the method to call on the UserPortalConfigService in order to register the NewPortalConfigs -->
      <set-method>initListener</set-method>
      <!-- The full qualified name of the NewPortalConfigListener -->
      <type>org.exoplatform.portal.config.NewPortalConfigListener</type>
      <description>this listener init the portal configuration</description>
      <init-params>
        <object-param>
          <name>portal.configuration</name>
          <description>description</description>
          <object type="org.exoplatform.portal.config.NewPortalConfig">
            <field name="predefinedOwner">
              <collection type="java.util.HashSet">
                <value>
                  <string>intranet</string>
                </value>
              </collection>
            </field>
            <field name="ownerType">
              <string>portal</string>
            </field>
            <field name="templateLocation">
              <string>war:/conf/office-extension/portal</string>
            </field>
            <field name="importMode">
              <string>merge</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>group.configuration</name>
          <description>description</description>
          <object type="org.exoplatform.portal.config.NewPortalConfig">
            <field name="predefinedOwner">
              <collection type="java.util.HashSet">
                <value>
                  <string>/developers</string>
                </value>
              </collection>
            </field>
            <field name="ownerType">
              <string>group</string>
            </field>
            <field name="templateLocation">
              <string>war:/conf/office-extension/portal</string>
            </field>
            <field name="importMode">
              <string>overwrite</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>portal.configuration</name>
          <description>description</description>
          <object type="org.exoplatform.portal.config.NewPortalConfig">
            <field name="predefinedOwner">
              <collection type="java.util.HashSet">
                <value>
                  <string>acme</string>
                </value>
              </collection>
            </field>
            <field name="ownerType">
              <string>portal</string>
            </field>
            <field name="templateLocation">
              <string>war:/conf/acme-portal/portal</string>
            </field>
            <field name="importMode">
              <string>overwrite</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>group.configuration</name>
          <description>description</description>
          <object type="org.exoplatform.portal.config.NewPortalConfig">
            <field name="predefinedOwner">
              <collection type="java.util.HashSet">
                <value>
                  <string>/platform/web-contributors</string>
                </value>
              </collection>
            </field>
            <field name="ownerType">
              <string>group</string>
            </field>
            <field name="templateLocation">
              <string>war:/conf/acme-portal/portal</string>
            </field>
            <field name="importMode">
              <string>overwrite</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>portal.configuration</name>
          <description>description</description>
          <object type="org.exoplatform.portal.config.NewPortalConfig">
            <field name="predefinedOwner">
              <collection type="java.util.HashSet">
                <value>
                  <string>default</string>
                </value>
              </collection>
            </field>
            <field name="ownerType">
              <string>portal</string>
            </field>
            <field name="templateLocation">
              <string>war:/conf/default-website/portal</string>
            </field>
            <field name="importMode">
              <string>overwrite</string>
            </field>
          </object>
        </object-param>
      </init-params>
    </component-plugin>
  </external-component-plugins>

  <!-- Configuration for re-import WCM content from webapp (.war files) file-->
  <!-- You can define the .war file that you want to re-import content-->
  <external-component-plugins>
    <target-component>org.exoplatform.commons.upgrade.UpgradeProductService</target-component>
    <!-- ECMS-Contents upgrade plugin-->
    <component-plugin>
      <name>Upgrade-WCM-Contents</name>
      <set-method>addUpgradePlugin</set-method>
      <type>org.exoplatform.platform.upgrade.plugins.UpgradeContentPlugin</type>
      <description>WCM Contents Upgrade Plugin</description>
      <init-params>
        <value-param>
          <name>product.group.id</name>
          <description>The groupId of the product</description>
          <value>org.exoplatform.platform</value>
        </value-param>
        <!--value-param>
            <name>plugin.execution.order</name>
            <description>The plugin execution order</description>
            <value>4</value>
        </value-param-->
        <values-param>
          <name>webapps-mames</name>
          <description>webapps to upgrade</description>
          <value>acme-intranet</value>
          <value>acme-intranet-portlet</value>
          <value>acme-website</value>
          <value>acme-websiteResources</value>
          <value>authoring-apps</value>
          <value>calendar</value>
          <value>chat</value>
          <value>chatbar</value>
          <value>cometd</value>
          <value>commons-extension</value>
          <value>CommonsResources</value>
          <value>contact</value>
          <value>content</value>
          <value>crash</value>
          <value>cs-extension</value>
          <value>csResources</value>
          <value>dashboard</value>
          <value>default-website</value>
          <value>ecm-wcm-core</value>
          <value>ecm-wcm-extension</value>
          <value>ecmadmin</value>
          <value>ecmbrowsecontent</value>
          <value>ecmexplorer</value>
          <value>ecmworkflow-extension</value>
          <value>exo-gadget-resources</value>
          <value>exoadmin</value>
          <value>eXoDMSGadgets</value>
          <value>eXoDMSResources</value>
          <value>eXoGadgets</value>
          <value>eXoGadgetServer</value>
          <value>eXoPlatformResources</value>
          <value>eXoResources</value>
          <value>eXoStaticResources</value>
          <value>eXoWCMResources</value>
          <value>eXoWorkflowResources</value>
          <value>faq</value>
          <value>fck</value>
          <value>formgenerator</value>
          <value>forum</value>
          <value>gadget-pack</value>
          <value>IDE</value>
          <value>intranet-gadget</value>
          <value>ks-extension</value>
          <value>ksResources</value>
          <value>mail</value>
          <value>newsletter</value>
          <value>platform-extension</value>
          <value>platformNavigation</value>
          <value>poll</value>
          <value>portal</value>
          <value>presentation</value>
          <value>rest</value>
          <value>searches</value>
          <value>seo</value>
          <value>SmartGWT</value>
          <value>social</value>
          <value>social-extension</value>
          <value>social-portlet</value>
          <value>social-resources</value>
          <value>web</value>
          <value>webos-ext</value>
          <value>webosadmin</value>
          <value>webosResources</value>
          <value>wiki</value>
          <value>workflow</value>
        </values-param>
      </init-params>
    </component-plugin>

    <!-- Configuration for Gadget upgrade plugin-->
    <!-- In can define "what are the gadget which you want to update" in this configuration-->
    <component-plugin>
      <name>Upgrade-Gadgets</name>
      <set-method>addUpgradePlugin</set-method>
      <type>org.exoplatform.platform.upgrade.plugins.UpgradeLocalGadgetsPlugin</type>
      <description>Gadgets Upgrade Plugin</description>
      <init-params>
        <value-param>
          <name>product.group.id</name>
          <description>The groupId of the product</description>
          <value>org.exoplatform.platform</value>
        </value-param>
        <!--value-param>
            <name>plugin.execution.order</name>
            <description>The plugin execution order</description>
            <value>1</value>
        </value-param-->
        <object-param>
          <name>eventslist</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>eventslist</string>
            </field>
            <field name="path">
              <string>war:/gadgets/events/Events.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>taskslist</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>taskslist</string>
            </field>
            <field name="path">
              <string>war:/gadgets/tasks/Tasks.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>messageslist</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>messageslist</string>
            </field>
            <field name="path">
              <string>war:/gadgets/messages/Messages.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>To-do</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>To-do</string>
            </field>
            <field name="path">
              <string>war:/gadgets/Todo/Todo.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>Calendar</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>Calendar</string>
            </field>
            <field name="path">
              <string>war:/gadgets/Calendar/Calendar.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>Calculator</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>Calculator</string>
            </field>
            <field name="path">
              <string>war:/gadgets/Calculator/Calculator.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>rssAggregator</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>rssAggregator</string>
            </field>
            <field name="path">
              <string>war:/gadgets/rssAggregator/rssAggregator.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>IDE</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>IDE</string>
            </field>
            <field name="path">
              <string>war:/ide.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>lastpost</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>lastpost</string>
            </field>
            <field name="path">
              <string>war:/gadgets/lastpost/Lastpost.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>pollslist</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>pollslist</string>
            </field>
            <field name="path">
              <string>war:/gadgets/polls/Polls.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>Activities</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>Activities</string>
            </field>
            <field name="path">
              <string>war:/gadgets/Activities/Activities.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>ViewerFriends</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>ViewerFriends</string>
            </field>
            <field name="path">
              <string>war:/gadgets/ViewerFriends/ViewerFriends.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>SocialRssReader</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>SocialRssReader</string>
            </field>
            <field name="path">
              <string>war:/gadgets/SocialRssReader/SocialRssReader.xml</string>
            </field>
          </object>
        </object-param>
        <object-param>
          <name>MySpaces</name>
          <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
            <field name="name">
              <string>MySpaces</string>
            </field>
            <field name="path">
              <string>war:/gadgets/MySpaces/MySpaces.xml</string>
            </field>
          </object>
        </object-param>
      </init-params>
    </component-plugin>
  </external-component-plugins>
</configuration>{code}

{note}
If this file has not been existing, you need to create it first.
{note}

*3.* Increase the JCR session time-out and JVM Xmx if you have a lot of data in eXo Platform 3.0. For example, in your current eXo Platform 3.0, there are about 200 users, 2 Gigabytes in the _gatein/data/jcr/values_ folder, and 1 Gigabyte in the _mySQL_ data, you will need to:

*i.* Configure the _$PLATFORM\_TOMCAT\_HOME/gatein/conf/configuration.properties_ or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.properties_ file by adding the following configuration.

{code}gatein.jcr.transaction.timeout=10000{code}

*ii.* Update JAVA\_OPTS Xmx: with Tomcat bundle, in _$PLATFORM\_TOMCAT\_HOME/bin/setenv.sh_ or .bat file, update JVM Xmx to 4G. With Jboss bundle, update JAVA\_OPTS Xmx in the _$PLATFORM\_JBOSS\_HOME/bin/run.conf_ file.

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Step 3. Perform the eXo Platform data migration from 3.0 to 3.5.
</emphasis>
</citetitle>
</para>
{docbook}

In this step, you only need to start server (Tomcat bundle or JBoss bundle), and the migration will be run automatically.

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Step 4. Finish your migration.
</emphasis>
</citetitle>
</para>
{docbook}

*1.* Stop server and remove the migration configurations through the following sub-steps:

*i.* Disable all migration plugins in the _$PLATFORM\_TOMCAT\_HOME/gatein/conf/configuration.properties_ file (or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.properties_):

{code}############
# Upgrades #
############
# JCR user directories structure migration configuration
use-old-user-distribution=false
run-jcr-user-directories-migrate=false
#gatein.jcr.transaction.timeout=10000

# Commons upgrade plugins configuration
## indicates if upgrade plugins is enabled or not
commons.upgrade.Upgrade-Gadgets.enable=false

#ECMS upgrade plugin
commons.upgrade.UpgradeVotingNodeTypePlugin.enable=false
commons.upgrade.FavoriteActionUpgradePlugin.enable=false
commons.upgrade.ThumbnailNodeTypeUpgradePlugin.enable=false

#ECMS template and script upgrade plugin
commons.upgrade.NodeTypeTemplateUpgradePlugin.enable=false
commons.upgrade.QueryUpgradePlugin.enable=false
commons.upgrade.ScriptUpgradePlugin.enable=false
commons.upgrade.SiteExplorerTemplateUpgradePlugin.enable=false
commons.upgrade.WCMTemplateUpgradePlugin.enable=false
commons.upgrade.UserViewUpgradePlugin.enable=false

#CS upgrade plugin
commons.upgrade.UpgradeCalendarPlugin.enable=false

#Social upgrade plugin
commons.upgrade.UpgradeToMOSPlugin.enable=false

#Social space template upgrade plugin
commons.upgrade.UpgradeTemplatePlugin.enable=false

#KS forums
commons.upgrade.UpgradeForumPlugin.enable=false
commons.upgrade.UpgradeWikiPlugin.enable=false
commons.upgrade.UpgradeAnswerPlugin.enable=false

#Portal navigation upgrade plugin
commons.upgrade.Upgrade-Navigations.enable=false

#Space home page template plugin
commons.upgrade.Upgrade-Spaces-Home-page.enable=false

#Re-import the contents
commons.upgrade.Upgrade-WCM-Contents.enable=false

## indicates the desired execution order (names of upgrade plugins separated with commas ",")
commons.upgrade.plugins.order=Upgrade-Spaces-Home-page,Upgrade-Gadgets,Upgrade-Navigations,Upgrade-WCM-Contents,UpgradeVotingNodeTypePlugin,FavoriteActionUpgradePlugin,ThumbnailNodeTypeUpgradePlugin,UpgradeToMOSPlugin,UpgradeTemplatePlugin,UpgradeAnswerPlugin,UpgradeWikiPlugin,UpgradeForumPlugin,UpgradeCalendarPlugin,NodeTypeTemplateUpgradePlugin,QueryUpgradePlugin,ScriptUpgradePlugin,SiteExplorerTemplateUpgradePlugin,WCMTemplateUpgradePlugin,UserViewUpgradePlugin

## Proceed to the upgrade if it's first time you run this service
commons.upgrade.proceedIfFirstRun=true{code}

*ii.* Delete configurations that were added before the migration in _$PLATFORM\_TOMCAT\_HOME/gatein/conf/portal/portal/configuration.xml_ or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.xml_ file.

If you do not run the JCR user directories structure migration, you need to keep the _$PLATFORM-3.5-TOMCAT\_HOME/gatein/conf/portal/portal/configuration.xml_ or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.xml_ file with the content as below:

{code:xml}<?xml version="1.0" encoding="UTF-8"?>
<configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd http://www.exoplatform.org/xml/ns/kernel_1_2.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd">
<component>
     <key>org.exoplatform.services.jcr.ext.hierarchy.NodeHierarchyCreator</key>
     <type>org.exoplatform.services.jcr.ext.hierarchy.impl.NodeHierarchyCreatorImpl</type>
     <init-params>
<value-param>
   <name>old-user-distribution</name>
   <value>true</value>
        </value-param>
     </init-params>
</component>
</configuration>{code}

*2.* Restart the server again. The migration process is done.

h1. Upgrade plugins details {anchor:id=ADM.Migration.Upgrade_plugins_details}

{note}
eXo Platform 3.5's Upgrade Framework is used to migrate existing data from eXo Platform 3.0 to 3.5.
{note}

A plugin is a _.jar_ file which is used for performing a specific task, especially for modifying the old data so that they are matched or compatible with the new structure. 

Plugins can be enabled/disabled via _$PLATFORM-3.5-TOMCAT\_HOME/gatein/conf/configuration.properties_. Meanwhile some of them are mandatory and must be always enabled; the others are optional and can be disabled. Also, plugins should also be disabled if you do not use certain features, such as Collaboration, Knowledge, Social, in your project.

To enable or disable a plugin, set the "enable" properties to "true" or "false" respectively, for example:

{code}commons.upgrade.UpgradeVotingNodeTypePlugin.enable=true{code}

When not specified, the plugins will be enabled by default.

This section shows a list of eXo Platform 3.5 upgrade plugins.

h2. Mandatory plugins {anchor:id=ADM.Migration.Upgrade_plugins_details.List_plugins.Mandatory_plugins}

These following plugins are required for upgrading to eXo Platform 3.5's new data structure, templates, skin and services.

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Content data tructure
</emphasis>
</citetitle>
</para>
{docbook}

* _commons.upgrade.UpgradeVotingNodeTypePlugin_: Ppgrade voting node type.
* _commons.upgrade.FavoriteActionUpgradePlugin_: Ppgrade favorite action.
* _commons.upgrade.ThumbnailNodeTypeUpgradePlugin_: Ppgrade thumbnail node type.


{docbook}
<para>
<citetitle>
<emphasis role="bold">
ECMS templates and scripts
</emphasis>
</citetitle>
</para>
{docbook}

They are: 
* _commons.upgrade.NodeTypeTemplateUpgradePlugin_
* _commons.upgrade.QueryUpgradePlugin_
* _commons.upgrade.ScriptUpgradePlugin_
* _commons.upgrade.SiteExplorerTemplateUpgradePlugin_
* _commons.upgrade.WCMTemplateUpgradePlugin_
* _commons.upgrade.UserViewUpgradePlugin_

{note}
By default, all the ECMS templates will be automatically migrated. In case you want to migrate a specific template manually, you need to specify your desired template in the _configuration.properties_ file.	
{note}

* With _commons.upgrade.NodeTypeTemplateUpgradePlugin_: Upgrade ecms node type template. 

Specify the node type templates which you do not want to upgrade with the following syntax:
{code}unchanged-nodetype-templates=<node name list>{code}
For example:
{code}unchanged-nodetype-templates=nt:file, exo:article{code}

* With _commons.upgrade.QueryUpgradePlugin_: Upgrade pre-defined queries.

Specify the pre-defined queries which you do not want to upgrade with the following syntax: 

{code}unchanged-queries=<query name list>{code}
For example:
{code}unchanged-queries=Created Documents{code}

* With _commons.upgrade.ScriptUpgradePlugin_: Upgrade pre-defined scripts.

Specify the pre-defined scripts which you do not want to upgrade with the following syntax:

{code}unchanged-scripts=<script name list>{code}

For example:

{code}unchanged-scripts=action/AddMetadataScript.groovy, action/AddTaxonomyActionScript.groovy{code}

* With _commons.upgrade.SiteExplorerTemplateUpgradePlugin_: Upgrade site-explorer-templates.

Specify templates of *Sites Explorer* with the following syntax:

{code}unchanged-site-explorer-templates=<templates name list>{code}
For example:
{code}unchanged-site-explorer-templates=ThumbnailsView, ContentView{code}


* With _commons.upgrade.UserViewUpgradePlugin_: Upgrade user view templates of *Sites Explorer*. 

Specify views of *Sites Explorer* with the following syntax:
{code}unchanged-site-explorer-views=<view name list>{code}
For example:
{code}unchanged-site-explorer-views=anonymous-view{code}


Use the following templates to specify the templates of the *Content List Viewer* and *Search* portlets:

{code}unchanged-clv-templates=<template name list>
unchanged-wcm-search-templates=<template name list>{code}

For example:

{code}unchanged-clv-templates=list/BigHotNewsTemplateCLV.gtmpl,navigation/CategoryList.gtmpl
unchanged-wcm-search-templates=search-form/UIDefaultSearchForm.gtmpl{code}


{docbook}
<para>
<citetitle>
<emphasis role="bold">
Collaboration
</emphasis>
</citetitle>
</para>
{docbook}

* _commons.upgrade.UpgradeCalendarPlugin_: upgrade Calendar.

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Knowledge
</emphasis>
</citetitle>
</para>
{docbook}

* _commons.upgrade.UpgradeForumPlugin_: upgrade Forum.
* _commons.upgrade.UpgradeWikiPlugin_: upgrade Wiki.
* _commons.upgrade.UpgradeAnswerPlugin_: upgrade Answers.

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Social
</emphasis>
</citetitle>
</para>
{docbook}

* _commons.upgrade.UpgradeToMOSPlugin_: upgrade Social Data Model.
* _commons.upgrade.UpgradeTemplatePlugin_: upgrade Social Template.
* _commons.upgrade.Upgrade-Spaces-Home-page_: upgrade spaces and homepage.

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Gadgets
</emphasis>
</citetitle>
</para>
{docbook}

* _commons.upgrade.Upgrade-Gadgets_: update gadgets with new skin and services. The list of gadgets to be updated is defined in the _$PLATFORM\_TOMCAT\_HOME/gatein/conf/portal/portal/configuration.xml_ or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.xml_ file, for example:

{code:xml}<component-plugin>
    <name>Upgrade-Gadgets</name>
    <set-method>addUpgradePlugin</set-method>
    <type>org.exoplatform.platform.upgrade.plugins.UpgradeLocalGadgetsPlugin</type>
    <description>Gadgets Upgrade Plugin</description>
    <init-params>
        <value-param>
            <name>product.group.id</name>
            <description>The groupId of the product</description>
            <value>org.exoplatform.platform</value>
        </value-param>
        <!--value-param>
            <name>plugin.execution.order</name>
            <description>The plugin execution order</description>
            <value>1</value>
        </value-param-->
        <object-param>
            <name>eventslist</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>eventslist</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/events/Events.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>taskslist</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>taskslist</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/tasks/Tasks.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>messageslist</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>messageslist</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/messages/Messages.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>To-do</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>To-do</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/Todo/Todo.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>Calendar</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>Calendar</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/Calendar/Calendar.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>Calculator</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>Calculator</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/Calculator/Calculator.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>rssAggregator</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>rssAggregator</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/rssAggregator/rssAggregator.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>IDE</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>IDE</string>
                </field>
                <field name="path">
                    <string>war:/ide.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>lastpost</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>lastpost</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/lastpost/Lastpost.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>pollslist</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>pollslist</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/polls/Polls.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>Activities</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>Activities</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/Activities/Activities.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>ViewerFriends</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>ViewerFriends</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/ViewerFriends/ViewerFriends.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>SocialRssReader</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>SocialRssReader</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/SocialRssReader/SocialRssReader.xml</string>
                </field>
            </object>
        </object-param>
        <object-param>
            <name>MySpaces</name>
            <object type="org.exoplatform.platform.upgrade.plugins.GadgetUpgrade">
                <field name="name">
                    <string>MySpaces</string>
                </field>
                <field name="path">
                    <string>war:/gadgets/MySpaces/MySpaces.xml</string>
                </field>
            </object>
        </object-param>
    </init-params>
</component-plugin>{code}


h2. Optional plugins {anchor:id=ADM.Migration.Upgrade_plugins_details.List_plugins.Optional_plugins}

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Portal navigation
</emphasis>
</citetitle>
</para>
{docbook}

* _commons.upgrade.Upgrade-Navigations_: upgrade navigations.

{docbook}
<para>
<citetitle>
<emphasis role="bold">
WCM contents
</emphasis>
</citetitle>
</para>
{docbook}

* _commons.upgrade.Upgrade-WCM-Contents_: Import new content of eXo Platform 3.5 from the XML content file in webapps. If the content has been existing in eXo Platform 3.0, they will be overwritten. The list of webapps containing the XML content to be overridden is defined in the _$PLATFORM\_TOMCAT\_HOME/gatein/conf/portal/portal/configuration.xml_ or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.xml_ file. For example:

{code:xml}<component-plugin>
    <name>Upgrade-WCM-Contents</name>
    <set-method>addUpgradePlugin</set-method>
    <type>org.exoplatform.platform.upgrade.plugins.UpgradeContentPlugin</type>
    <description>WCM Contents Upgrade Plugin</description>
    <init-params>
        <value-param>
            <name>product.group.id</name>
            <description>The groupId of the product</description>
            <value>org.exoplatform.platform</value>
        </value-param>
        <value-param>
            <name>plugin.execution.order</name>
            <description>The plugin execution order</description>
            <value>4</value>
        </value-param>
        <values-param>
            <name>webapps-mames</name>
            <description>webapps to upgrade</description>
            <value>acme-intranet</value>
            <value>acme-intranet-portlet</value>
            <value>acme-website</value>
            <value>acme-websiteResources</value>
            <value>authoring-apps</value>
            <value>calendar</value>
            <value>chat</value>
            <value>chatbar</value>
            <value>cometd</value>
            <value>commons-extension</value>
            <value>CommonsResources</value>
            <value>contact</value>
            <value>content</value>
            <value>crash</value>
            <value>cs-extension</value>
            <value>csResources</value>
            <value>dashboard</value>
            <value>default-website</value>
            <value>ecm-wcm-core</value>
            <value>ecm-wcm-extension</value>
            <value>ecmadmin</value>
            <value>ecmbrowsecontent</value>
            <value>ecmexplorer</value>
            <value>ecmworkflow-extension</value>
            <value>exo-gadget-resources</value>
            <value>exoadmin</value>
            <value>eXoDMSGadgets</value>
            <value>eXoDMSResources</value>
            <value>eXoGadgets</value>
            <value>eXoGadgetServer</value>
            <value>eXoPlatformResources</value>
            <value>eXoResources</value>
            <value>eXoStaticResources</value>
            <value>eXoWCMResources</value>
            <value>eXoWorkflowResources</value>
            <value>faq</value>
            <value>fck</value>
            <value>formgenerator</value>
            <value>forum</value>
            <value>gadget-pack</value>
            <value>IDE</value>
            <value>intranet-gadget</value>
            <value>ks-extension</value>
            <value>ksResources</value>
            <value>mail</value>
            <value>newsletter</value>
            <value>platform-extension</value>
            <value>platformNavigation</value>
            <value>poll</value>
            <value>portal</value>
            <value>presentation</value>
            <value>rest</value>
            <value>searches</value>
            <value>seo</value>
            <value>SmartGWT</value>
            <value>social</value>
            <value>social-extension</value>
            <value>social-portlet</value>
            <value>social-resources</value>
            <value>web</value>
            <value>webos-ext</value>
            <value>webosadmin</value>
            <value>webosResources</value>
            <value>wiki</value>
            <value>workflow</value>
        </values-param>
    </init-params>
</component-plugin>{code}

{docbook}
<para>
<citetitle>
<emphasis role="bold">
JCR user directory structure
</emphasis>
</citetitle>
</para>
{docbook}


This plugin is built-in in JCR that provides an option for migrating old JCR users directory structure to new JCR users directory structure. This allows you to improve performance when having a lot of users in database.

For example, the table below shows the difference in response time of eXo Platform 3.5 (new user directory structure) against eXo Platform 3.0 (old user directory structure) while performing some actions:

|| Number of users || Type Account & Login || Load Intranet Welcome Page || Load /portal/rest/jcr/repository/collaboration/Users || Load User Private JCR Folder ||
| 500 | 13.61% | \-20.83% | \-30.12% | 14.29% |
| 1000 | 8.82% | \-25.00% | \-86.06% | 8.96% |
| 2000 | 0.20% | \-29.63% | \-93.89% | \-1.37% |
| 5000 | \-4.30% | \-33.93% | \-95.45% | \-10.67% |

Formula: (_Platform 3.5 value_ - _Platform 3.0 value_) * 100 / _Platform 3.0 value_ (negative value means better).

It can be seen that with a larger number of users, the new user directory structure performs faster than the old one, especially when accessing the user directory directly.

To enable the migration, set these 2 flags in the _$PLATFORM\_TOMCAT\_HOME/gatein/conf/configuration.properties_ file (or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.properties_) as below:

{code}use-old-user-distribution=false
run-jcr-user-directories-migrate=true{code}

JCR user directory structure migration will take much time, so you need to increase the JCR session time-out.
Measure the amount of data in your current eXo Platform 3.0 and use a right session time-out. For example, if there are 1000 users in current eXo Platform 3.0, you should set configuration in the _$PLATFORM\_TOMCAT\_HOME/gatein/conf/configuration.properties_ (or _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein/configuration.properties_) file as below:

{code}gatein.jcr.transaction.timeout=10000{code}

The time you need to migrate the JCR user directories structure depends on the amount of eXo Platform user data and your system speed.
This migration also consumes memory, so you need to make sure to have enough resource on your server and configure enough memory to update the Xmx Java option (in the _$PLATFORM\_TOMCAT\_HOME/bin/setenv.sh or $PLATFORM\_JBOSS\_HOME/bin/run.conf_ file) before running.
For example, you can use 6 Gigabyte RAM to migrate 5000 users.