How to Fast Upgrade from Unica V8.6x to V12.1

The thought of upgrading any type of computer software can be off-putting and make you ponder several bothersome questions… How long will the upgrade process take? Will it negatively impact my ability to meet current work demands? How long will it take to get accustomed to the updated platform? Is this upgrade really going to be worth my time? 

We have great news for our faithful Unicans who are still using previous iterations of our platform! Fast Upgrade is a feature that will allow you to quickly and seamlessly upgrade from any version of the Unica platform starting with version 8.6. 

Benefits of Fast Upgrade 

• Save Time – The traditional upgrade process can take approximately 2-3 days to complete. With Fast Upgrade, upgrades can be achieved in just a few hours. 
• Less Downtime – Fast Upgrade runs on a newly built clean environment. This means your current production environment will not be impacted and minimal downtime.  
• Direct Path to V12.1 – The traditional upgrade path would require users to jump from each version of Unica to the next (8.6.x–>10.0–>10.1–>11.1–>12.0à12.1) to access V12.1. In the case of Fast Upgrade, users can now upgrade from any version starting with V8.6 immediately to V12.1. 
• Cross Verification – If users would like to cross verify functionalities before and after the upgrade, this can easily be accomplished as both environments can be accessed in fast upgrade process. 
• Safety Net – In the event the upgrade failed with the traditional process, the time required to fix the environment was significant and may have impacted customer business. With Fast Upgrade, there is no roll back required as it’s ran on a completely separate environment.  

Prerequisite  

1. Before upgrading, make sure you have your based version (i.e. 8.6.x) up and fully functional. 
2. Fresh version of 12.1 is installed on different machine with same Database type as of source Unica version. 
3. Make sure fresh version 12.1 is fully configured and is up and running. 
4. Take a back of Platform, Campaign, Interact Design Time, Interact Runtime, Learning DB, Profile DB, Plan system DB of source version 8.6.x  
5. Restore database(schema) backup taken in step (d) above in the relevant database of the target environment. 

Unica Platform 

1. Run the following database script on Target Platform database (Schema). 

• <PLATFORM_HOME>/db/upgrade86to8601/insert_new_8601_locales.sql (do not execute this script if upgrading from 8.6.0.1 onwards) 
• <PLATFORM_HOME>/db/upgrade86to90/ManagerSchema_<DB>_90upg.sql  
• <PLATFORM_HOME>db/upgrade90to91/ManagerSchema_<DB>_91upg.sql  
• <PLATFORM_HOME>/db/upgrade91to911/ManagerSchema_<DB>_911upg.sql  
• <PLATFORM_HOME>/db/upgrade912to10/ManagerSchema_<DB>_10upg.sql  
• <PLATFORM_HOME>/db/upgrade912to10/<DB>_QRTZ_Scheduler_10_upgrade_Script.sql 
• <PLATFORM_HOME>/db/ upgrade10001to10002/ManagerSchema_<DB>_10002upg.sql  
• <PLATFORM_HOME>/ db/upgrade10002to101/ ManagerSchema_<DB>_101upg.sql  
• <PLATFORM_HOME>/ db/upgrade101to11/ ManagerSchema_<DB>_11upg.sql  
• <PLATFORM_HOME>/ db/upgrade1101to111/ ManagerSchema_<DB>_111upg.sql  
• <PLATFORM_HOME>/ db/upgrade111to11102/ ManagerSchema_<DB>_11102upg.sql  
• <PLATFORM_HOME>/ db/upgrade11102to12/ ManagerSchema_<DB>_12upg.sql 
• <PLATFORM_HOME>/ db/upgrade12to121/ ManagerSchema_<DB>_121upg.sql

Note :– If you are having DB2 database and you wanted to run the Unicode scripts, then please execute Unica scripts for DB2 e.g. ManagerSchema_DB2_91upg_unicode.sql.

If you are using new schema then navigate to <PLATFORM_HOME>/tools/bin and update the file jdbc.properties with below details. 

• Run the below command and copy the encrypted password in the jdbc.properties file ./encryptPasswords.sh –d <PLATFORM_DB_USER_PASSWORD> 
• Update the Platform user name in the User Name field. 

2. If you see ‘\’ character in the uasm.data_source then remove the additional ‘\’ character. 

3. In the application server, update the properties for UnicaPlatformDS JNDI such as schema / SID, Userid and password if you are using new schema

4. Execute the following command to upgrade Unica Platform configurations to 12.1.0. Navigate to <PLATFORM_HOME>/tools/bin location and execute below command. 

• ./configTool.sh –vp -p “Affinium” -f “<PLATFORM_HOME>/conf/Manager_config.xml”  
• ./populateDb.sh -n Manager 
• ./configTool.sh –vp -p “Affinium|suite|uiNavigation|mainMenu|Analytics” -f “<PLATFORM_HOME>/conf/watsonAssistant_navigation.xml” 
• ./alertConfigTool.sh –i -f “<PLATFORM_HOME>/conf/Platform_alerts_configuration.xml”  
• ./configTool.sh –vp -p “Affinium|Report|integrations” -f “<PLATFORM_HOME>/conf/upgrade101to11/cognos11_integration.xml”  
• ./upgrade86to90.sh (Only if you source version is 8.6) 
• ./upgrade90to91.sh (Only if you source version is either 8.6 or 9.0) 
• ./quartzjobtool.sh 
• ./configTool.sh –vp -p “Affinium” -f <Insights.xml directory_path>/Insights.xml (Insights.xml directory_path : /opt/HCL/Unica_12/Platform/Insights/conf) 
• ./configTool.sh –vp -p “Affinium|suite|security” -f “/<UNICA_PLATFORM_HOME>/conf/upgrade12to121/APISecurity.xml” 
• ./configTool.sh –vp -p “Affinium|suite|security|apiSecurity” -f “<UNICA_PLATFORM_HOME>/Platform/conf/upgrade12to121/APISecurity_Deliver.xml” 
• ./configTool.sh –vp -p “Affinium|suite|uiNavigation|settingsMenu” -f “<UNICA_PLATFORM_HOME>/conf/upgrade12to121/LicenseDetailsNavigation.xml” 
• ./configTool.sh -x -p “Affinium|Manager|about” -f “<PLATFORM_HOME> /conf/about.xml” 

Edit the about.xml file generated by the above command. Change the version and other details as below.

<property id=”xxxxxx” name=”releaseNumber” type=”string_property” width=”40″> <value>12.0.0.0.0.16</value> </property> 

Import the updated about.xml in the Platform configuration using below command. 

./configTool.sh -v –i -o -p “Affinium|Manager” -f <UNICA_PLATFORM_HOME>/Platform/conf/about.xml 

5. Change the application navigation URL from the USM_CONFIGURATION_VALUES table using below query. Take the back of USM_CONFIGURATION_VALUES table before running the query. 

UPDATE USM_CONFIGURATION_VALUES SET string_value = REPLACE(string_value, ‘<OLD HOSTNAME.DOMAIN>’, ‘<NEW_HOSTNAME.DOMAIN>’) WHERE string_value like ‘%http%’; 

6. The URL of the start page that appears when each user log in to HCL Unica products has to be changed manually from the USM_PERSONALIZATION table 

7. Check the following properties files from the source and destination Environment. Copy all the URLs mentioned in the respective properties files from source to destination files.   

• Platform_Admin_URL.properties  
• Platform_Admin_View_Priv.properties  
• Platform_Admin_URL.properties  
• Platform_Admin_Scheduler_Scripts.properties  
• Platform_Admin_Scheduler_API.properties 

Note :– For your non-production setup, keep the Java option -DENABLE_NON_PROD_MODE=true on your Platform server. For your production setup, set the Java option -DENABLE_NON_PROD_MODE=false or just remove it on your Platform server 

Unica Campaign 

1. Copy the entire CAMPAIGN_HOME/partition folder from based version to upgraded version. 

2. Navigate to CAMPAIGN_HOME /tools/upgrade/11.1+To12.1and edit the setenv.sh file for below mentioned attributes. 

• Edit the username if installation user is not root. 

• Update JAVA_HOME parameter to <UNICA_HOME>/jre location. 
• Update CAMPAIGN_HOME to actual Campaign directory. 
• Updates LOG_TEMP_DIR to <CAMPAIGN_HOME>/logs 
• Update JDBCDRIVER_CLASSPATH to your directory were driver is located. 
• Add the JVM Option JAVA_OPTIONS=”${JAVA_OPTIONS} -DFAST_UPGRADE_VERSION=8.6.x 

3. Navigate to <CAMPAIGN_HOME>/tools/upgrade/11.1+To12.1 and run the acUpgradeTool.sh. Before running the acUpgradeTool.sh file make sure that the jdbc.properties  under folder <CAMPAIGN_HOME>/install is updated with correct Platform schema name and password. 

4. Navigate to <PLATFORM_HOME/tools/bin location and run the below command: 

./configTool.sh -x -p “Affinium|Campaign|about” -f <PLATFORM_HOME>/conf/campaign_about.xml 

5. Edit the campaign_about.xml. Change the below properties in the campaign_about.xml file as highlighted. 

6. Navigate to <PLATFORM_HOME/tools/bin location and run the below command 

./configTool.sh -v –i -o -p “Affinium|Campaign” -f <PLATFORM_HOME>/conf/campaign_about.xml 

7. Execute below command in sequence 

./populateDb.sh -n Campaign 

./configTool.sh -v –i -p “Affinium|suite|security|apiSecurity|campaign” -f <CAMPAIGN_HOME>/conf/API_Filter.xml 

./configTool.sh -v –i -p “Affinium|suite|security|apiSecurity|campaign” -f <CAMPAIGN_HOME>/conf/API_V2_Filter.xml 

./configTool.sh -v –i -p “Affinium|suite|security|apiSecurity|campaign” -f <CAMPAIGN_HOME>/conf/API_V3_Filter.xml 

./configTool.sh –vp -p “Affinium|suite|security| apiSecurity|campaign” -f <CAMPAIGN_HOME>/conf/Engage_API_Filter.xml 

8. Navigate to <CAMPAIGN_HOME>/partitions/partition1/conf and delete the file unica_tblcache.mgr. 

9. Navigate to <PLATFORM_HOME/tools/bin location and run the below command 

./DBResourceBundle.sh -P Campaign -F <CAMPAIGN_HOME>/resourcebundles 

Unica Optimize 

1. Copy Optimize/partitions/partition1/reports content into Campaign/partitions/partition1/ reports directory. 

2. Copy Optimize/ partitions/partition1/logs content into Campaign/partitions/partition1/logs directory. 

3. Execute following script on Unica Campaign 12.0 system database. 

Oracle:  

ALTER TABLE UACO_OptSession MODIFY CustomSettingsXML VARCHAR(4000);  

SQL:  

ALTER TABLE UACO_OptSession MODIFY CustomSettingsXML VARCHAR(4000);  

DB2:  

ALTER TABLE UACO_OptSession ALTER COLUMN CustomSettingsXML SET DATA TYPE VARCHAR(4000); 

4. Run the below queries in sequence. 

ALTER TABLE UACO_OptSession ADD AgentChannelName VARCHAR(192);  

ALTER TABLE UACO_OptSession ADD AgentInfoTemplateTable VARCHAR(192);  

ALTER TABLE UACO_OptSession ADD AgentCustomerRelTemplateTable VARCHAR(192);  

ALTER TABLE UACO_OptSession ADD CustomSettingsFlag int; 

ALTER TABLE UACO_OptSession ADD CustomSettingsXML VARCHAR(4000); 

ALTER TABLE UACO_OptSession ADD LastRunType VARCHAR(192);  

UPDATE UACO_OptSession SET LastRunType = ‘Production Run’;  

Run Reorg table command for UACO_OptSession. Below is the example for DB2 re-org 

CALL SYSPROC.ADMIN_CMD (‘REORG TABLE UACO_OptSession‘);  

ALTER TABLE UACO_OptSession ADD AgentChannelName VARCHAR(192);  

ALTER TABLE UACO_OptSession ADD AgentInfoTemplateTable VARCHAR(192);  

ALTER TABLE UACO_OptSession ADD AgentCustomerRelTemplateTable VARCHAR(192);  

ALTER TABLE UACO_OptSession ADD LastRunType VARCHAR(192);  

UPDATE UACO_OptSession SET LastRunType = ‘Production Run’; 

 5. Navigate to <CAMPAIGN_HOME>/ddl and execute the script aco_extra_indexes_<db>.sql 

Before you execute the script verify if you have defined custom audience level and not using default audience level. If yes then you will get below error on executing the script aco_extra_indexes_<db>.sql 

Update the script aco_extra_indexes_<db>.sql with actual audience id that you are using before running the script. 

6. Login to the application and navigate to Settings–>Configuration–>Campaign–>unicaACOListener. Change the serverHost property to actual Host name of upgraded environment. 

7. To remap the system table, stop the listener. Remove “unica_tblcache.mgr” from <CAMPAIGN_HOME>/partitions/partition/conf. Start the listener and navigate to Unica Campaign–>settings–>Table mapping. 

Unica Interact 

1. Update the setenv.sh file under <Interact_Home>/interactDT/tools/upgrade and <Interact_Home>/tools/upgrade as below.  

• Change the user in the below line to installation user name 

• • if [ $whoami != “root” ] 

• JDBCDRIVER_CP :– Complete path to JDBC database driver. 
• JAVA_HOME :– ‘<Installation Path >/jre‘ 
• JDBCDRIVER_CLASS :– Change as per type of database. 

• • SQL Server: com.microsoft.sqlserver.jdbc.SQLServerDriver   
  • IBM DB2: com.ibm.db2.jcc.DB2Driver 
  • Oracle: oracle.jdbc.OracleDriver 

• JDBCDRIVER_URL:- Change as per type of database. 

• • SQL: jdbc:sqlserver://sqlserverHost:1433;databaseName=DBName 
  • IBM DB2: jdbc:db2://db2Host:50000/DBName 
  • Oracle: jdbc:oracle:thin:@oracleHost:1521:DBName 

2. Navigate to <Interact_Home>/interactDT/tools/upgrade/conf and update file ACIUpgradeTaskList.properties. Change the value of CHOICES_FOR_PREVIOUS_VERSIONS=8.6.x. 

3. Update jdbc.propertie files under following location. Set username and encrypted password for Platform database. 

• <Interact_Home>/install 
• <Interact_Home>/interactDT /tools/upgrade/conf 

4. Navigate to <Interact_Home>/interactDT/tools/upgrade and execute the script aciUpgradeTool.sh 

5. Navigate to <Interact_Home>/tools/upgrade/conf. Update the property CHOICES_FOR_PREVIOUS_VERSIONS=8.6.x,10.0.0,10.1.0,11.1.0 in all the below properties file. 

• ACIUpgradeTaskList_crhtab.properties 
• ACIUpgradeTaskList_usrtab.properties 
• ACIUpgradeTaskList_runtab.properties 
• ACIUpgradeTaskList_lrntab.properties 
• ACIILPBUpgradeTaskList_usrtab.properties 

6.Execute below scripts in sequence 

• aciUpgradeTool_crhtab.sh 
• aciUpgradeTool_runtab.sh 
• aciUpgradeTool_lrntab.sh 
• aciUpgradeTool_usrtab.sh 

7. Navigate to path <Installation_Directory>\Interact\tools\upgrade\conf and open ACIILPBUpgradeTaskList_usrtab.properties file.  

ILPB_TABLES_TO_UPDATE – Append the ILPB table (whitelist offers, default offers, offer by SQL) names which you want to migrate data from old columns to new predicate columns. 

8. Execute the script aciILPBUpgradeTool_usrtab.sh 

9. Undeploy the interactRT.war and do following changes. 

• Back up the interactRT.war file from the 12.0 environment  
• Unwar the interactRT.war file.  
• Copy the jdbc.properties file from Platform/tools/bin/ directory and paste it under interactRT.war/WEB-INF/classes.  
• Re-war the interactRT. 

10. Navigate to <PLATFORM_HOME>/tools/bin location and execute below commands. 

• ./configTool.sh –vp -p “Affinium|suite|security|apiSecurity|interact” -f <Interact_Home>/interactDT/conf/Interact_API_V2_Filter.xml 
• ./configTool.sh -x -p “Affinium|Interact|about” -f Interact_about.xml 
• Update the below highlighted variable in the Interact_about.xml 

• ./configTool.sh -v -o –i -p “Affinium|Interact” -f Interact_about.xml 
• ./configTool.sh –i -p “Affinium|Campaign|about|components” -f <Interact_Home>/interactDT/conf/interact_subcomponent_version.xml –o 
• ./configTool.sh -d -p “Affinium|suite|uiNavigation|mainMenu|Campaign|Interactive Channels” -o 
• ./configTool.sh –i -p “Affinium|suite|uiNavigation|mainMenu” -f <Interact_Home>/interactDT/conf/interact_navigation.xml 
• ./configTool.sh –i -p “Affinium|suite|uiNavigation|settingsMenu” -f <Interact_Home>/interactDT/conf/interact_setup_navigation.xml 

11. Navigate to <PLATFORM_HOME>/tools/bin and execute below command. 

./DBResourceBundle.sh -P interact –F <Interact_Home>/resourcebundles 

12. If you have added any custom entries in the ‘interact_log4j.xml’ file on source 10.x setup, then you must copy those custom entries into the target setup in the newly added ‘interact_log4j2.xml’ file. 

13. Deploy updated Interact RT WAR file. 

14. Update the configuration instanceURLs accordingly for your ServerGroup defined at Affinium|Campaign|partitions|partition1|Interact|serverGroups. 

The second Interact runtime 

1. Repeat the following steps for each Interact runtime if you have used a different server group and Platform.  
2. Install New Platform 12.1 with Interact RT.  
3. Perform the Platform upgrade and make the setup ready. (Refer the Platform Upgrade Guide.)  
4. Copy and restore the InteractRT database from the source to the target.  
5. Upgrade the database from source database to 12.1 by running the aciupgrade utility for RT.  
6. Create data sources on the target application server using the same JNDI names as the source setup.  
7. Deploy InteractRT.war. 

Unica Plan 

1. 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. 
• “Plan_HOME/conf/ plan_log4j.xml” file. 
• “Plan_HOME/conf/ plan_ehcache.xml” file.  

2. Replace all the above mentioned files and folders from the based server to the upgraded server. 

3. Rename ext folder to ext_data on the destination server at the <PLAN_HOME> \messages\com\hcl\umo 

4. In Plan_HOME/conf/xx_XX/sysmenu.xml (where xx_XX is the locale) change the value of <display> to Plan. 

5. In Plan_HOME/conf/resourcebundles/com/unica/manager/ configuration/plan*.properties files.  

Update the value of property Operations = with Plan.  

Update the value of property projectmanagement = with Plan 

6. In Plan_HOME/conf/en_US/sysmodules.xml (where en_US is the locale), change the value of <display> to Plan. 

7. In Plan_HOME\conf\resourcebundles\com\unica\manager\configuration \plan_en_US.properties files update the value of property analysis= with Plan analytics. 

8. Copy ext folder from source <PLAN_HOME>\messages\com\ibm\umo\ext to destination location. 

9. If there are marketing objects in the source setup, copy following files on 12.1 from <Plan_Home>/conf/en_US from source to 12.0. mo_creatives_state.xml globalstates.xml sysmenu.xml sysmodules.xml. 

10. Add following JVM arguments in the application server. 

• –Dlog4j2.contextSelector=org.apache.logging.log4j.core.async. AsyncLoggerContextSelector  
• -Dlog4j2.configurationFile=file:///<Plan_home>\conf\plan_log4j.xml  
• -Dlog4j.configuration=file:/// <Plan_home>\conf\plan_log4j_1x.xml 

11. Update the file umo_jdbc.properties under <Plan_Home>/tools/bin with details of Plan System database. 

12. Update the setenv.sh file under <Plan_HOME>/tools/bin with correct driver path in DBDRIVER_CLASSPATH. 

13. Run the utility under as below to encrypt the Plan database password under file umo_jdbc.properties. 

./umodbsetup.bat/sh –E 

14. 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 

 15. Copy the 8.6.x plan_registration.xml file from source to the respective destination UMO_HOME\conf folder. Replace 8.6.x with your existing source version. 

Change the serverURL, Release version, Copy Right information in the  

16. Navigate to <PLATFORM_HOME>/tools/bin location and run below commands. 

• ./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 

17. Navigate to <Plan_Home>/tools/bin and set <Plan_home> path in config_migration.sh file. 

Execute below command 

• ./config_migration.sh -p Plan_Home -b 8.6.0.0 
• ./configTool –vp -p “Affinium|Plan|umoConfiguration” -f <Plan_Home>/conf /Plan_encodeProperty_11.1.xml 
• ./umouilistupgrade.sh  

(This is to merge UMOConfigurationMessages_<locale>.properties and the UMOMktObjectConfigurationMessages_<locale>.properties of 8.6.x and 12.) 

 18. Plan Database upgrade. 

Run the below command 

./umodbsetup.sh –t upgrade –m –b 8.6 –L locale (example locale is en_US) 

19. Database script file will be created called umo_upgrade_[8.6.0.0.0]_[12.0.0.0.0].sql located under <Plan_Home>/tools. Execute this sql script directly under Plan system database. 

20. Now login to the application and navigate to SetingsàConfigurationàPlanàumoConfiguration. 

Update below locations. 

• templates  
• attachmentFolders  
• integrationServices 

21. Update to table UAP_WS_ALERT to replace all older URL’s to new URL. 

22. Restart the application server. 

23. Go to Settings -> Plan -> Plan Upgrade. Check all the checkboxes. Click the “Upgrade” button. 

24. Run the below command from <PLATFORM_HOME>/tools/bin location 

./configTool.sh -x -p “Affinium|Plan|about” -f <PLATFORM_HOME>/conf/plan_about.xml 

25. Edit the plan_about.xml file to update the version details, displayName and copy right information. 

26. Run the below command to import the plan_about.xml changes. 

./configTool.sh -v –i -o -p “Affinium|Plan“ -f <PLATFORM_HOME>/conf/plan_about.xml 

Trouble Shooting 

1. Issue :– While running the script aco_extra_indexes_<db>.sql you may encounter the below error if you have added the custom audience level.

Solution :– Update the aco_extra_indexes_<db>.sql script to include the audience id of the custom audience level replacing the default audience id. 

2. Issue :– After Interact upgrade the Interact Test client initialization fails. 

Make sure all the required Interact Runtime server properties has been added in the Platform configuration of the Interact runtime server. 

For example when you upgrade from 10.0.0.2 you may find below properties missing in the Platform configuration. 

Affinium|interact|general|centralizedLogger 

Affinium|interact|general|API 

Affinium|interact|profile|Audience Levels|<Audience Level>/ treatmentTable  

Solution :– Run the below command from the <PLATFORM_HOME>/tools/bin location 

./configTool.sh –vp -p “Affinium” -f <Interact_HOME>/conf/interact_configuration.xml 

3. Issue :– While running the umodbsetup.sh command to encrypt the ump password you may encounter below error. This error occurs if your password length is more than 8 characters. 

Solution :– Reset the Plan DB password to less than 8 characters and then run the script umodbsetup.sh to encrypt the password. 

4. Issue :– Not able to access platform page even changing all the URL’s to the target URL. This case can happen when the domain name of the source and target server is different. 

Solution :– Change the “Domain name” parameter under Configuration of Marketing Platform if it is pointing to the source domain. 

For additional questions or support, please visit our customer service portal.