IBM Connections Side by Side/ In Place migration 5.5 / 6.0 David McCarthy

Agenda In Place Upgrade Side By Side Migration Troubleshooting Guide References

In Place Upgrade Customers almost NEVER do it this way. There is no way to back out once you start. When they do use this method, it tends to be only for TEST/DEV type environments. Here is a great article with steps: https://milanmatejic.wordpress.com/2016/01/18/ibm-connections-5-to-5-5- in-place-migration/ I won’t spend long on the link, since most of those same steps are covered later on.

Side by Side Migration - Steps 1. Install “Target” Connections version (i.e. version you are upgrading to, e.g. IC 5.5 CR2 or IC 6.0) on separate HW 2. Backup customizations on “Source” environment (i.e. version you are upgrading from) 3. Export artifacts from Source using Migration Tool 4. Migrate the “Source” databases to “Target” DB server environment 5. Upgrade the SQL schema for “Target” databases 6. Migrate the content stores 7. Import artifacts using Migration Tool 8. Post Migration Tasks Talk a bit about “Source” and “Target” -> very important concept. Almost all the PMRs are for either Step 4 or Step 5.

Side by Side Migration – Step 1 Install “Target” Connections version (i.e. version you are upgrading to, e.g. IC 5.5 + latest CR or IC 6.0 + latest CR) on separate HW For 6.0: https://www.ibm.com/support/knowledgecenter/SSYGQH_6.0.0/admin/install/ t_install_cluster-N.html The steps in Knowledge Center have not changed for 6.0, apart from tweaks / edits.

Side by Side Migration – Step 1 Not quite the right order, but just added it for illustrative purposes

Side by Side Migration – Step 2 Backup Customizations 6.0: https://www.ibm.com/support/knowledgecenter/SSYGQH_6.0.0/admin/migrat e/c_configuration_changes_after_update.html Complicated looking procedure, but then again, we’ve never had any PMRs for it.

Side by Side Migration – Step 3 Export artifacts from “source” environment (i.e. version you are upgrading from) 6.0: https://www.ibm.com/support/knowledgecenter/SSYGQH_6.0.0/admin/migrat e/t_migrate_network_export.html What are “artifacts” anyway? Simple answer = the config files. (Data files are kept in content stores, which will be migrated later.) Anecdotally, a lot of customers seem to not do this step! Instead, they take the config files for the “Target” version and manually update them with the changes they had made to config files on their “Source”. From our experience, we’ve found that customers tend not to do this step. Instead, they take the config files on “Target” and just make the same changes they had done to “Source”. How we know is when we see their config files are not the correct versions. So, should we be worried? Not if the customers are careful .

Side by Side Migration – Step 4 Migrate the “Source” databases to “Target” DB server environment 6.0: https://www.ibm.com/support/knowledgecenter/SSYGQH_6.0.0/admin/migrat e/t_update_databases_side-by-side.html Overview: Create empty DBs on Target DB server for exact same version as Source (e.g. 5.5 + CR2). Remove constraints Transfer the data from Source to Target Re-apply constraints Run some SQL to update the database sequence

Side by Side Migration – Step 4 contd There are two supported methods for this part of the process: Use DBT.jar tool to transfer the data (i.e. the method described on previous slide) OR: Use native DB tools to create backup of Source DBs and restore them to Target DB server (NOT in Knowledge Center documentation) DBT.jar method is the one most recommended: http://techblog.gis-ag.info/2016/07/27/why-you-should-always-use-dbt-for- transferring-ic-databases/

Side by Side Migration – Step 4 contd Q: What are the “constraints”? A: Rules that prevent tables from having certain types of duplicate data. Q: If that’s the case, why do we remove them? A: Source DBs might contain “old” data that violate the constraints. If we didn’t remove them, then the transfer process would be unable to add this data to the Target DB. Also, these scripts will remove data that is not necessary in the new Target environment. Demo: IBM\Connections\xkit\connections.sql\homepage\db2\predbxfer55CR1.sql Emphasise the Search tables: DELETE FROM HOMEPAGE.SR_INDEX_MANAGEMENT@

Side by Side Migration – Step 4 Troubleshooting Ensure customers use latest version of the dbt.jar file (the one from “\IBM\Connections\xkit\migration” on the Target server. Ensure Target & Source DBs are at the exact same schema version. Useful queries: select DBSCHEMAVER as "Activities" from ACTIVITIES.OA_SCHEMA; select value as "Blogs" from BLOGS.roller_properties where name='database.schema.version'; select DBSCHEMAVER as "Dogear" from DOGEAR.DOGEAR_SCHEMA; select DBSCHEMAVER as "Communities" from SNCOMM.SNCOMM_SCHEMA; select DBSCHEMAVER as "Calendar" from CALENDAR.CA_SCHEMA; select SCHEMA_VERSION as "Files" from "FILES"."PRODUCT"; select DBSCHEMAVER as "Forums" from FORUM.DF_SCHEMA; select VALUE as "Mobile" from MOBILE.ROLLER_PROPERTIES where NAME='database.schema.version'; select DBSCHEMAVER as "Profiles" from EMPINST.SNPROF_SCHEMA; select SCHEMA_VERSION as "Wikis" from "WIKIS"."PRODUCT"; select DBSCHEMAVER as "Homepage" from HOMEPAGE.HOMEPAGE_SCHEMA; select SCHEMA_VERSION as "Metrics" from "METRICS"."PRODUCT"; SELECT SCHEMA_VERSION FROM PNS.PRODUCT where ID = 'pushnotification'; The queries are only useful if troubleshooting the Data transfer step. When Target DBs are upgraded, then the schema versions will no longer match.

Side by Side Migration – Step 4 Troubleshooting One common type of issue: Customer had modified something in the default schema in the Source environment, e.g. increased the max column length for Country column in EMPLOYEE table. By default, it’s only 3 By increasing this limit in Source, likely they will have data in this column >3. DBT.jar step fails with SQL ERRORCODE=-4229. This usually means the value (in Source) is too long for the defined column in Target. To resolve this, customer has to drop the Target DB, make same change to same column in the Target DB and re-do the transfer.

Side by Side Migration – Step 4 Troubleshooting Q: What if the customer did not use DBT.jar method to migrate the data? A: Still supported. However, we have seen PMRs whereby customers had problems with Search indexing afterwards. In order to prevent those issues, follow these steps to check the names of Search indexing nodes in your deployment: https://www.ibm.com/support/knowledgecenter/SSYGQH_5.0.0/admin/admin/t_admin_sea rch_list_nodes.html So, for example, if you find that the result from the SearchService.listIndexingNodes() command contains the name of the node(s) from the previous Connections 5.0 environment, then follow the steps in this document to remove them: https://www.ibm.com/support/knowledgecenter/SSYGQH_5.0.0/admin/admin/t_admin_sea rch_remove_node.html

Side by Side Migration – Step 4 Collecting Data Get the entire DBT_HOME directory on the target database server. Logs are here: DBT_HOME\logs Get the versions & DB type for the Source & Target DB servers.

Side by Side Migration – Step 5 Upgrade the SQL schema for “Target” databases Always use the manual SQL scripts instead of the DBWizard. (Most customers do, Also, the doc recommends this for HOMEPAGE especially). 6.0: https://www.ibm.com/support/knowledgecenter/SSYGQH_6.0.0/admin/migr ate/t_update_databases-manual.html Tip: After data has been migrated from Source to Target, really good idea to create DB backups before upgrading Target Tip: When running the scripts, add >>filename to the end of each command to pipe the output to a log file.

Side by Side Migration – Step 5 contd DEMO THE SQL UPGRADE SCRIPT PROCESS Unless you are upgrading from 5.0 to 5.5 or 6.0, then in addition to the SQL upgrade script, for HOMEPAGE, it’s also necessary to do Java Migration step: http://www.ibm.com/support/docview.wss?uid=swg21991138 This step is NOT needed if going from 5.5 to 6.0 In order to do this yourself, it’s pretty easy. You just need: A vm running a Source version. (Take a snapshot first!) Stop Connections. Copy over the connections.sql folder for the Target version. Start a DB2 command prompt. Run through the steps in the doc and run the SQL scripts. Output the results to log files. Now, you have a “working” set of SQL upgrade log files to use for reference.

Side by Side Migration – Step 6 Migrate the content stores 6.0 : https://www.ibm.com/support/knowledgecenter/SSYGQH_6.0.0/admin/migr ate/c_content-store_migration.html

Side by Side Migration – Step 7 Import artifacts 6.0 : https://www.ibm.com/support/knowledgecenter/SSYGQH_6.0.0/admin/migr ate/t_migrate_network_import.html

Side by Side Migration – Step 8 Post Migration Tasks 6.0 : https://www.ibm.com/support/knowledgecenter/SSYGQH_6.0.0/admin/migr ate/t_post-migration_tasks.html Note that clearing scheduled tasks is now mandatory for side-by-side migration

General Troubleshooting Guide This sounds obvious, but it’s really important to understand WHERE in the overall process the customer is having the issue. e.g. Customer will say “I’m doing a side-by-side migration and I have X error” We should establish is this a problem during data transfer or re-applying constraints or upgrading DB, etc.? The entire side-by-side process has not really changed since version 2.0! So, chances are the SQL error code has come up before. (WellSpring is your friend!  )

General Troubleshooting Guide – Collecting Data If issue is for data migration step, get the entire DBT_HOME directory on the target database server. Logs are here: DBT_HOME\logs If it’s an issue for importing / exporting artifacts using Migration Tool: Export log is “migrate.latest.log” in the IC_HOME/migration/work directory after running the export command; Import log is in the same directory If it’s an issue for upgrading the databases, then get logs: If they used the DB Wizard, then get: Database wizard runtime log --- Windows 2008: C:\Users\db2inst1\lcWizard\log Linux/AIX: /home/db2inst1/lcwizard/log (db2inst1 stands for the database user name) Sql scripts execution log generated by database wizard Windows 2008: C:\Users\db2inst1\lcWizard\log\dbwizard Linux/AIX: /home/db2inst1/lcwizard/log/dbwizard (db2inst1 stands for the database user name) If they used manual scripts, then they should have used >>filename to output the SQL command results to logs Get the versions & DB type for the Source & Target DB servers. db2diag.log for DB2 is very useful

References Nice checklist created by Business Partner: https://turtleblog.info/2014/09/30/my-connections-migration-checklist/ Another Blog post with useful info: https://www.urspringer.de/2017/01/12/issues-migration-ibm-connections-5-0-5-5/ Internal step by step guide with screenshots: https://w3-connections.ibm.com/files/app#/file/fe2c1b27-d2ae-40e5-93e1-c97707bd0014 DB Schema version queries https://w3-connections.ibm.com/wikis/home?lang=en- us#!/wiki/W1eb8bb82f523_4cc3_a250_2809a6830a27/page/Handy%20SQL%20queries%20to %20show%20the%20DB%20schema%20values%20for%20IBM%20Connections%20databases New Way To Learn 2017 Presentation by Charles Price (will be available from 2nd May 2017): https://apps.na.collabserv.com/wikis/home?lang=en- us#!/wiki/Wce4f52b1fb71_4fc2_bffd_3317cad38c4b/page/3- 009%20Upgrading%20Connections%205.5%20to%206