Procedure: Fast upgrade Unica Plan

Plan pre-upgrade

About this task

Note:

Existing customers who want to upgrade to JBoss + 12.1, must perform the following steps:
- Clear the recent items for all the users. Note: Administrator: Please communicate to all the users to clear their respective recent items prior to the migration to JBoss.
- Clear the directory <PLAN_HOME>/recentdata.
- Migrate to JBoss + 12.1.
No change is required to be done by new customers who are installing JBoss + 12.1. This is because recent items will not be present in their case.

For a Plan pre-upgrade, perform the following steps:

Procedure

Import the Plan system tables backup from the old version to the system tables schema used in a clean 12.1 environment.
Take a file system backup of the source and the destination of the following folders:
<PLAN_HOME>/accountattachments directory.

<PLAN_HOME>/approvalitems directory.

<PLAN_HOME>/assets directory.

<PLAN_HOME>/componentattachments directory.

<PLAN_HOME>/images directory.

<PLAN_HOME>/invoiceattachments directory.

<PLAN_HOME>/planattachments directory.

<PLAN_HOME>/programattachments directory.

<PLAN_HOME>/projectattachments directory.

<PLAN_HOME>/templates directory.
Copy or merge all files mentioned in step 2 in 12.1 from the source folders to the destination Plan respective folders.
In the source version, if you have customized the plan_log4j.xml file and plan_ehcache.xml file, copy the plan_log4j.xml file and plan_ehcache.xml file to Plan_HOME/conf folder of the destination environment.
Adhere to the following guidelines:
- For the plan_log4j.xml file, if the source version is earlier than 11.1.0, ensure that the plan_log4j.xml file follows log4j2 conventions. For more information, see the Unica Plan Installation Guide.
- For the plan_ehcache.xml file, ensure that you add the attribute-value pair name="PlanEhCacheManager", as shown in the following example, if it does not exist:
```
<ehcache updateCheck="false" name="PlanEhCacheManager">
```
Note: You can ignore Step 4 if you have not made any changes to the plan_log4j.xml file and plan_ehcache.xml file in the source version, and if you want to retain the target file without any modifications.
Rename ext folder to ext_data on the destination server at the <PLAN_HOME>/messages/com/hcl/umo/ path.
For Unica Plan version prior to 12.0, copy the ext folder from the source location <PLAN_HOME>/messages/com/ibm/umo/ and paste it to the destination location <PLAN_HOME>/messages/com/hcl/umo/. For Unical Plan version 12.0 and later, copy the ext folder from the source location <PLAN_HOME>/messages/com/hcl/umo/ and paste it to the destination location <PLAN_HOME>/messages/com/hcl/umo/.
If there are marketing objects in the source setup, copy the following files from the source location <PLAN_Home>/conf/en_US to the target location. mo_creatives_state.xml globalstates.xml sysmenu.xml sysmodules.xml

In <PLAN_HOME>/conf/xx_XX/sysmenu.xml (where xx_XX is the locale) change the value of <display> to Plan (see the following xml section).

<sysmenu>
     <menugroups>
        <default-startup-item>projectmanagement</default-startup-item>
             <menugroup id='projectmanagement'>
           <display>Plan</display>

In <PLAN_HOME>/conf/resourcebundles/com/unica/manager/configuration/plan*.properties files, if the version of existing Unica Plan installation is before 12.0, update the value of MARKETING_OPERATIONS_SETTINGS to Plan settings.
In <PLAN_HOME>/conf/en_US/sysmodules.xml (where en_US is the locale), change the value of <display> to Plan (see the following xml section).

Run the following commands at:
```
<sysmodules>
      <section>
           <module id='Analytics'>
                <display>Plan analytics</display>
```

Run the following command to register plan configuration:

./configTool.sh -vp -p "Affinium" -f“ <PLAN_HOME>/conf/plan_registration.xml

Ensure that the following JVM parameters are present. If not add them:
- For version 12.1.0, 12.1.0.1, 12.1.0.2, and 12.1.0.3, add the following parameters:
  - -Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector
  - -Dlog4j2.configurationFile=file:///<Plan_home>\conf\plan_log4j.xml (in case of fresh install of 12.1)
  - -Dlog4j.configurationFile=file:///<Plan_home>\conf\plan_log4j.xml (in case of fresh install of 12.1)
- For version 12.1.0.4, if you are installing, add the following parameters. If you are upgrading from version 12.1.0 or later, remove the parameters mentioned earlier, and add the following parameters:
  - -Dlog4j.configuration=file:///<Plan_home>\conf\plan_log4j_1x.xml
  - -Dplan.log4j.config=<Plan_home>\conf\plan_log4j.xml
  - -Dplan.log4j.async=true (If not set, deafults to true)
Note:
- In the Dlog4j2.configurationFile=file:///<PLAN_HOME>\conf\plan_log4j.xmlsetting, if you have customized the plan_log4j.xml and made some changes to suit your organization, then ensure that you make those settings in the plan_log4j.xml specified here as per the Dlog4j2.configurationFile that we have deployed to you now.
- Ensure that the xml file pointed by log4j2.configurationFile and log4j.configurationFile is the same and follows the log4j2 syntax. The file should contain the following two lines at the top:
```
<?xml version="1.0" encoding="UTF-8"?>
<Configuration packages="com.unica.afc.logger" monitorInterval="60">
```
- In Windows, the file path contains a back slash, whereas, in UNIX, it must contain a forward slash.
- Ensure that you restart the Plan application server and synchronize the menus.

Upgrading Unica Plan

Updating JDBC files

About this task

In case you do not want to reuse the Plan schema used in the 12.1 clean installation and rather want to use another user schema, follow the additional steps underneath:

Procedure

Take a back up of the jdbc.properties file from the 12.1 environment (Plan/tools/bin/umo_jdbc.properties). Update the username of the 12.1 Platform system database / schema name in the umo_jdbc.properties file.
Example of umo_jdbc.properties:
Name: umo_data_source.url
Description: URL reference for the Unica Plan system table database.
Example values for supported databases are:
SQL Server: jdbc:sqlserver://sqlserverHost:1433;databaseName=databaseName
IBM DB2: jdbc:db2://db2Host:50000/databaseName
Oracle: jdbc:oracle:thin:@oracleHost:1521:databaseName
umo_data_source.url=jdbc:oracle:thin:@<databaseHostName>:1521:<sid>
Name: umo_data_source.login
Description: Name of login for Unica Plan database-login account must have database administrative rights.
Name of login for Unica Plan database. login account must have database administrative rights.
umo_data_source.login=xmsp
Name: umo_data_source.password
Description: Password for Unica Plan database for login id provided in umo_data_source.login property
umo_data_source.password=ENC(+1Kd731xEuzqdDfqjQ9wnw==)

Note: If you have used the same user in the Platform and Plan, you can take the encrypted password from the Platform/tools/bin/jdbc.properties file.
Under <PLAN_HOME>/tools/bin, update the setenv.bat file with the correct DB driver path for the parameter DBDRIVER_CLASSPATH.

Upgrade to 12.1 config

About this task

Note: This procedure is not applicable to Fast Upgrade from version 12.0 to version 12.1.

Procedure

Add jBoss-logging-3.3.2.Final.jar and classmate-1.3.4.jar in CLASSPATH in setenv. These files are located in <Platform_HOME>/tools/lib.

For example: You can add like following in the classpath

${TOOLS_LIB}/../../../Platform/tools/lib/jboss-logging-3.3.2.Final.jar:${TOOLS_LIB}/../../../Platform/tools/lib/classmate-1.3.4.jar
Run the following commands at Platform_Home/tools/bin:

./configTool.sh -vp -p "Affinium|Plan|umoConfiguration" -f <PLAN_HOME>/conf/plan_approvals_settings_10.0.0.2.xml

./configTool.sh -vp -p "Affinium|Plan|umoConfiguration" -f <PLAN_HOME>/conf/plan_workflowservice_settings_10.0.0.2.xml
Run config_migration.sh in <PLAN_HOME>/tools/bin. Prerequisite: Set or update <UMO_HOME> in the config_migration.sh file.

./config_migration.sh -p -b 8.6.0.0 (Replace 8.6 with your existing source version.)
Run the following command to enable encodeCSV feature:

configTool -vp -p "Affinium|Plan|umoConfiguration" -f <PLAN_HOME>\conf\Plan_encodeProperty_11.1.xml

Note: Ensure that the jdbc.properties file within the <PLAN_HOME>/install location points to the appropriate Unica Platform database.

Upgrading Plan database

Procedure

Import the database with the source system tables of the VM containing the fresh installation of 12.1 Plan.
1. Run the umouilistupgrade utility from <PLAN_HOME>/tools/bin to merge the UMOConfigurationMessages_<locale>.properties and the UMOMktObjectConfigurationMessages_<locale>.properties of 8.6 and 12.1. This utility does not have any parameters: umouilistupgrade.bat.
2. Run the umodbsetup utility to upgrade the database to 12.1: umodbsetup.bat –t upgrade –m –b 8.6 –L en_US. Type the above command in the command prompt. Copying may give an error.
3. Execute the command: umodbsetup.bat –t upgrade –b 8.6 . If this does not work, you can execute the umo_upgrade_[8.6.0.0.0]_[12.1.0.0].sql file on the Plan database. This file is located at <PLAN_HOME>\tools\bin.
  
  Note: Replace 8.6 with your existing source version
If the version of the target system is 12.0.0 or later, execute the following query on Platform database to update the name of the Marketing Operations node to Plan, in Platform configurations:
```
UPDATE usm_configuration SET display_name='Plan' where internal_name='Plan' and display_name_key='Marketing Operations'
```

Unica Plan post-upgrade

Unica Plan Configuration changes

About this task

Deploy Unica Plan 12.1.0 war and run the Unica Plan Java Upgrade using the following procedure:

Note:

About log4j upgrade

Prior to 11.1, log4j1x API was used by the Plan source.

For 11.1 and later versions

The syntax of <PLAN_HOME>/conf/plan_log4j.xml has been changed to log4j2 format.
The configuration file contains the following lines at the top:
```
<?xml version="1.0" encoding="UTF-8"?>
<Configuration packages="com.unica.afc.logger" monitorInterval="60">
```
Prior to upgrade to 12.1, if you had upgraded Unica Plan version to 11.1, a file plan_log4j.11.1.0.0.xml is available in the <PLAN_HOME>/conf/ location, which contains the earlier mentioned syntax.
In this case, the syntax of plan_log4j.xml file in the <PLAN_HOME>/conf/ location would not be as per log4j2 format
In such a case the file plan_log4j.11.1.0.0.xml should be used in the following properties:
- -Dlog4j2.configurationFile
- -Dlog4j.configurationFile
Note:
In case of 12.1.0.4, plan_log4j.11.1.0.0.xml should be used in the following properties:
- -Dplan.log4j.config=<Plan_home>\conf\plan_log4j.11.1.0.0.xml
log4j2x API is used by Plan source.
log4j1x API is still used by unica_common.jar inside Plan JVM, because the Platform source (which results in unica_common) has not been changed to use log4j2x. For this reason, we provide the plan_log4j_1x.xml, which is as per the log4j1x syntax .This file is not used by the source code in Unica Plan (this is valid only till version 12.1.0.3 and not for later versions).

Procedure

Log in as an admin user.
In (Affinium|Plan|umoConfiguration) update the location for the nodes lised underneath:

templates

attachmentFolders

integrationServices
Update notifyPlanBaseURL in Affinium|Plan|umoConfiguration|notifications.
Update serverURL in Affinium|Plan|navigation.
If the new application URL is different than the old one, then you must connect to Plan database and access UAP_WS_ALERTS table. Records in this table may contain the pre upgrade application URL. You need to update this table and replace the old application URL by new one.
Restart the application server.
Go to Settings > Plan > Plan Upgrade.
Select all the checkboxes.
Click the “Upgrade" button.
Perform the following steps:
1. Access the file sysmenu.xml from the conf/locale location.
2. In the file, if you find conf/locale/<menugroup id="projectmanagement">, remove the <menugroup id="Operations"> section within it, and rename <menugroup id="projectmanagement"> as <menugroup id="Operations">.
3. Perform Step b for all locales.
4. Restart the Plan web application.
5. From the Unica Platform homepage, navigate to Settings > Plan Settings
  The Administrative settings page appears.
6. Inside System administration settings and within Restrcited options, select Synchronize menus.
Restart Unica Platform and Unica Plan.

Setting the Plan – Help About > Version

About this task

Change the plan version in the Unica Platform registration:

Procedure

Export the version configuration using the following command on clean 12.1 environment.
configTool.sh -x -p "Affinium|Plan|about" -f <PLATFORM_HOME>/conf/plan_about.xml

Edit the plan_about.xml file generated by the above command. Change the version to 12.1.0.0.GA_BUILD".

<property id="xxxxxx" name="releaseNumber" type="string_property" width="40"> 
<value>12.1.0.0.GA_BUILD</value>
</property>

Change display name as below:
 <property id="3214" name="displayName" type="string_property" width="40">
                <value>Unica Plan</value>
        </property>

Import this edited xml file using the following command:
configTool.sh -v -i -o -p "Affinium|Plan" -f <PLATFORM_HOME>/conf/plan_about.xml

Plan Post Upgrade Functional check

About this task

Perform UAT on the plan application. Ensure that all the Plans, Programs, Projects, Tasks, Approvals are opening and that the data is successfully imported. Ensure if all the configurations nodes are available.

Configure Unica Insights reports with Plan

Procedure

For Reports pack configurations, see the Unica Insights Reports Installation and Configuration guide.