Migrating Quickr for Portal places to Connections Content Manager libraries

Use the IBM® Connections Migration Tool for Lotus® Quickr® for WebSphere® Portal to migrate contents from Lotus Quickr for WebSphere Portal 8.5 to IBM Connections Content Manager.

Before you begin

The following conditions apply to be able to migrate Lotus Quickr content into Connections:

The migration tool is based on IBM Connections 5.0 CR2 and IBM FileNet® Collaboration Services 2.0.0.1 Interim Fix 2 (IF002). For more information about requirements, see system requirements.
The migration tool does not support migrating the multiple selection property from Quickr.
After migration, the time stamp and creator of new communities in Connections will be the current time and the admin account who runs the migration. The actual content that is migrated preserves the time stamp and updater information from Quickr.
Submit all the completed draft documents before migration.
FileNet and Quickr for Portal need to be configured with the same user directory (LDAP) for the user IDs to map correctly.
If a team place was created before you planned to run the migration tool, then the place would not have statistics because statistics-scheduled jobs run once every day at 1:30 AM by default. To change the time that the statistics job runs before you run migration tool, access the Quickr server's WebSphere Application Server Integrated Solutions Console. Then, navigate to Resource environment providers > QuickrAdminConsole > Custom properties to change the schedule.tasks.saveSystemStatistics.starttime value to the time the statistics task is executed. Restart the Quickr server.
Only Quickr linked libraries that are configured by using a POC link can be converted to a FileNet linked library.

The IBM Connections Migration Tool for Lotus Quickr for WebSphere Portal needs to migrate membership from Quickr to a Connections Community, however, Connections Community API requires a unique ID when it adds a member. The migration tool uses IBM Security Directory Integrator to generate a flat file to map the DN to unique ID. When you generate the files successfully, you can copy them to the Quickr server and perform more configuration. Make sure that you create the correct mapping for every external user in Quickr; otherwise, errors are reported during migration.

A group member who was a place manager is downgraded to be a simple member in a community after migration.

The migration tool does not support migrating to subcommunities because subcommunity owners and members must be from the parent community.

To run multiple instances of the migration tool, copy the migration tool to a different location and then run the migration from there. Be sure not to run multiple instances within the same directory.

CAUTION: After migration all community members have read permission to content that migrated from the Quickr place by default. This permission is granted even if members were restricted from accessing certain documents or folders before migration as Quickr users of the place.

About this task

Libraries in Quickr places, including folders, documents, history versions, and comments can be migrated to IBM Connections Communities. Existing Lotus Quickr Linked Libraries and Libraries that are integrated with IBM Connections also can be migrated.

Note: Quickr blogs, wikis, and components other than libraries cannot be migrated.

Note: If the Quickr server is running on a 32-bit server, JVM heap size and supported migration instances must be carefully tuned. Consider the following JVM heap size settings as a guide:

For the Quickr for Portal server use 1280 MB heap to support eight to 10 instances of parallel migration.
For the Connections Content Manager server use 3072 MB heap to support eight to 10 instances of parallel migration.

You can modify the execution script file (run.bat/run.sh) to set up the JVM heap size. Using the text editor, edit the execution script file as follows:

On Windows™, modify the setting in the run.bat file as follows:

@REM Please specify the directory where Java is installed
@REM c:\java\bin\java -jar migration4quickrj.jar %1
java -Xms1024M -Xmx1024M -jar migration4quickrj.jar %1

On Linux™, modify the following setting in the run.sh file:

# Please specify the directory where Java is installed
# /usr/java/bin/java -jar migration4quickrj.jar $1
java -Xms1024M -Xmx1024M -jar migration4quickrj.jar $1

Approximately 90 thousand documents per one migration tool process with a heap size of 1 GB is should be used.

Procedure

Run the Quickr for Portal Cleanup Users task and the User Transformation tool before migration to avoid generating exceptions during migration.
To complete migration of places to Connections communities, you need to disable Activity Stream generation before migration and then re-enable after migration completes. To disable Activity Stream generation before migration:
1. Open the Administration Console for Content Platform Engine (ACCE) on the FileNet system. Log in with the administrator's user name and password by accessing the following URL: http://server:port/acce
  Where server is the name of the application, by default: FileNetEngine; port is the port number the server is listening on. For example:
```
 http://cpe.example.com:9080/acce
```
  Note: The Administration Console for Content Platform Engine (ACCE) supports a subset of the browsers that are supported by Connections. While some operations in Administration Console for Content Platform Engine might work with other browsers, if an error is encountered, ensure that you are running a supported browser. See the system requirements for supported software for FileNet Content Engine. Click Administrative Console for Content Engine in the By component column, then view Prerequisites and check Web Browser support.
2. Expand the Object Stores node in the navigation tree, right-click the existing object store that you want to configure, and then click Open.
  If the createObjectStore.sh|.bat tool was used to create the object store, its name is ICObjectStore.
3. Once the object store is open, click Search to open the Search page.
4. On the Simple Search tab page, select Collaboration Configuration from the Select From Table dropdown.
5. From the Select Columns list, select the asterisk (*). Use the move button to place "*" into the Selected pane, and then click Search.
6. Click OK on the Message window.
  A single row is returned.
7. Click the result link in the ID column to open it for viewing and editing.
8. In the results view tab, click the Properties inner tab.
9. Scroll to the property Activity Stream Generation Enabled and change its value to false to disable Activity Stream generation.
10. After migration completes, repeat this procedure except reset the Activity Stream Generation Enabled property to true to enable it.
You need to disable three User Identity actions before migration and then re-enable them after migration completes.
1. Open the ACCE on the FileNet system as in step 1.a.
2. Expand the Object Stores node in the navigation tree as in step 1.b
3. Click Event,Actions,Processes to access the Change Preprocessor Actions folder, and then click it to open a new tab.
  There are three add-ons on this tab: User Identity Document Change Preprocessor Action, User Identity Folder Change Preprocessor Action, User Identity Task Change Preprocessor Action.
4. Click any of the add-on names to open a new tab that describes the add-on.
  1. On this tab, set the isEnable property to false.
  2. Click Save and then Refresh to disable the add-on.
  3. Repeat this process to disable the other two add-ons temporarily.
5. Restart FileNetEngine from WebSphere Application Server Integrated Solutions Console.
6. After migration completes, repeat this procedure except reset the three add-ons to true to re-enable them.
Optional: If Lotus Quickr is integrated with IBM Connections by using a widget before the migration, you need to disable the widgets from Connections after migration. Disable the Communities widgets by editing the Connections widgets-config.xml file to comment out or remove the widget definition.
1. Open the widgets-config.xml file under <was_home>\AppServer\profiles\<app_name>\config\cells\<cell_name>\LotusConnections-config.
2. Search for primaryWidget settings and then either comment them out or disable them similar to the following by setting them to false, for example:
```
<widgetDef bundleRefId="quickrCommunityLibrary_res" defId="LinkedQuickrCommunityLib" description="LinkedQuickrCommunityLibDesc" primaryWidget="false"
```
Generate mapping between DN to Connections unique ID.
Before performing this task, review how to populate the Profiles database and know where your Connections unique ID comes from. You can get the wizard for populating Profiles databases from the Connections installation package. All IBM Security Directory Integrator-related files are in the Wizards\TDIPopulation directory.
- The Unique ID might be directly from an LDAP attribute, no conversion isneeded, for example from ibm-entryUuid for IBM® Security Access Manager LDAP by default.
- The Unique ID also might be converted from an LDAP attribute by calling existing IBM Security Directory Integrator JavaScript™ functions. Copy them from Wizards\TDIPopulation\win\TDI\profiles_functions.js, for example, call function_map_from_objectGUID to convert from objectGUID for AD LDAP by default, call function_map_from_dominoUNID to convert from dominoUNID for Domino® LDAP by default.
Note: Make sure to save the DN:unique ID mapping file character set as "utf-8".
The following procedure uses an Active Directory LDAP as an example. If you are using IBM Security Access Manager LDAP, add ibm-entryUuid instead of objectGUID in step e, and then choose CSV Parser instead of Script Parser in step f. If you do not use the default LDAP attribute as the Connections unique ID, you should refer these steps and change them to suit your Connections implementation. You should generate two files for user and group respectively. You can specify the LDAP search filter for user and group respectively in step g.
1. Set up your IBM Security Directory Integrator development environment as described in Setting up your development environment.
2. Import the Connections IBM Security Directory Integrator project to the IBM Security Directory Integrator configuration editor. The configuration file is WizardsCopy\TDIPopulation\win\TDI\profiles_tdi.xml. You can make a copy of the Wizards directory and work on this copy.
3. Create collect_dns_uid_For_AD and collect_dns_uid_flow_For_AD by copying and pasting the existing collect_dns and collect_dns_flow.
4. Change collect_dns_uid_For_AD to call collect_dns_uid_flow_For_AD as follows:
  1. Select collect_dns_uid_For_AD Assemblyline.
  2. Expand the Data Flow folder.
  3. Select the Call_collectFlow of that Assemblyline.
  4. Open the Connection tab.
  5. Click Query for the AssemblyLine field and then select collect_dns_uid_flow_For_AD.
5. In collect_dns_uid_flow_For_AD, add a mapping by clicking Add then entering objectGUID as name.
6. On the Parser tab:
  1. Select Script Parser, click Edit Script, and then copy the function function_map_from_objectGUID from profiles_functions.js.
  2. Change work.getAttribute("objectGUID") to entry.getAttribute("objectGUID").
  3. Change the function writeEntry() as follows:
    function writeEntry () { out.write (entry.getString("$dn")); out.write (";"); out.write (function_map_from_objectGUID()); out.newLine(); }
7. Click Advanced and set Character Encoding to UTF8. If the directory is Domino Native, and IBM Connections also connects to the same directory, then the writeEntry function should be similar to the following to convert "," to "/" for person dn and trim "CN=" from group dn. Also, add an attribute in Output Map named "objectclass".
```
function writeEntry ()
{
var type = entry.getString("objectclass");
if(type == "dominoPerson")
{
var person_dn = entry.getString("$dn");
var index = person_dn.indexOf(",");
if(index != -1)
{
person_dn = person_dn.replace(/,/g, "/");
}
out.write (person_dn);
out.write (";");
out.write (function_map_from_dominoUNID());
out.newLine();
}
if(type == "dominoGroup")
{
var group_dn = entry.getString("$dn");
var index = group_dn.indexOf("CN=");
if(index == 0)
{
group_dn = group_dn.substring(3);
}
out.write (group_dn);
out.write (";");
out.write (function_map_from_dominoUNID());
out.newLine();
}
}
```
8. Configure Wzards\TDIPopulation\win\TDI\profiles_tdi.properties with the LDAP server information, such as source_ldap_url, source_ldap_user_login, source_ldap_user_password, source_ldap_search_base, source_ldap_search_filter.
9. Create Wzards\TDIPopulation\win\TDI\collect_dns_uid_For_AD.bat by copying from Wzards\TDIPopulation\win\TDI\collect_dns.bat, and then change it to call the new assembly line collect_dns_uid_For_AD.
10. Run collect_dns_uid_For_AD.bat in the command console. Then, the generated collect.dn includes the mapping from DN to uniqueID as the following example shows. You can rename it as you want.
```
CN=John Smith1,OU=Users,OU=region,OU=yourcompany,O=Sales Group,DC=company,DC=sales,DC=companyname,DC=com;05A7B8F2-1E24-4F0D-B02F-BDB223613EE5
CN=John Smith1,OU=Users,OU=region,OU=yourcompany,O=Sales Group,DC=company,DC=sales,DC=companyname,DC=com;CEABB8F9-D2A0-4754-B9FD-E2DA162D705B
......
```
11. Add "DN;UniqueID" at the beginning of the mapping file.
Select the Connections Communities administrative user
Connections Communities administrative user account is used during the migration. To find out which account is the administrative user, open the IBM WebSphere Application Server Integrated Solutions Console on the Connections server and navigate to Applications > Application Types > WebSphere enterprise applications > Communities > Security role to user/group mapping > admin to see all Communities administrative users that are listed in the Mapped users column.
Give the FileNet administrator role the privilege for the file content migration as follows:
1. Access FileNet ACCE by using http://yourfilenet:port/acce
2. Click the ICObjectStore tab. ICObjectStore is created by Connections.
3. Click the Security tab and select an administrative user, for example wasadmin, and then click Edit to set the permissions for the selected administrative user.
4. Select This object and All children instead of the default value This object only from the Apply to drop down.
5. Select Modify certain system properties, and then click OK and Save.
Put the migration tool migration4quickrj.zip on the Connections Content Manager server or Quickr server.
When you extracte the files, you will see the properties/execution script files/migration tool with libraries that the migration tool depends on. Put the appropriate database JDBC driver into the directory where you extracted the files as follows:
- db2jcc.jar for DB2®
- ojdbc.jar for Oracle
- sqljdbc.jar for SQL Server

You can edit the migration.properties file.

Here are the system properties that can be modified:

isMigrationVersionsForDoc if you want to migrate all historical versions of a document, set this property to true; if not, set it to false.
IntegratedIDsFileName for the Quickr places-to-Connections communities ID mapping file to support -m migration.
placeIDsFileName Quickr places ID file to support -s migration.
isGenerateMappingTableForInsertedLinks=true|false If set to true, then the mapping table for inserted links that exist in migrated documents are generated. If set to false or not set at all, then the mapping table is not generated.

Quickr, FileNet, and Connections server details and Connections database details where Quickr for Portal already has been integrated with Connections, for example:

#Quickr server information
quickrHost=quickr.mycompany.com
quickrPort=10040
quickrAdmin=wpsadmin
quickrPassword=password
PlacePageSize=30
LibrariesPageSize=100
FolderAndDocPageSize=100

#FileNet server information
filenetHost=filenet.mycompany.com
filenetPort=9081
filenetAdmin=wasadmin
filenetPassword=password
filenetObjName=ICObjectStore

#Connections server information
ConectionsHost=connections.mycompany.com
ConectionsPort=9444
ConectionsAdmin=wasadmin
ConectionsPassword=password

#Connections database server information
#ConnectionsDBHost=connectionsdb.mycompany.com
#ConnectionsDBPort=50000
#ConnectionsDBAdmin=LCUSER
#ConnectionsDBPassword=password
#Please select your Connections database type
#ConnectionsDBBrand=DB2
#ConnectionsDBBrand=Oracle
#ConnectionsDBBrand=SQLServer
#if database type is Oracle please add this property, and ignore others
#ConnectionsDBOraSID=OracleSID
#if database type is Oracle please add this property, and ignore others
#ConnectionsDBSchemaCommunityName=SNCOMM

#Quickr database server information
#Please specify your database server information for schema community
QuickrDBSchemaCommunityHost=quickrdb.schema_community.mycompany.com
QuickrDBSchemaCommunityPort=50000
QuickrDBSchemaCommunityAdmin=db2admin
QuickrDBSchemaCommunityPassword=password
QuickrDBSchemaCommunityName=schema_community_database_name
#Please specify your database server information for schema jcr
QuickrDBSchemaJCRHost=quickrdb.schema_jcr.mycompany.com
QuickrDBSchemaJCRPort=50000
QuickrDBSchemaJCRAdmin=db2admin
QuickrDBSchemaJCRPassword=password
QuickrDBSchemaJCRName=schema_jcr_database_name
#Please specify your database server information for schema release
QuickrDBSchemaRELEASEHost=quickrdb.schema_release.mycompany.com
QuickrDBSchemaRELEASEPort=50000
QuickrDBSchemaRELEASEAdmin=db2admin
QuickrDBSchemaRELEASEPassword=password
QuickrDBSchemaRELEASEName=schema_release_database_name
#Please select your Connections database type
QuickrDBBrand=DB2
#QuickrDBBrand=Oracle

#Community context root, by default is "/communities"
ConnectionsCommunitiesContextRoot=communities
By default, community context root is "/communities", so this property value should be "communities", please ignore "/"

Note: You can add the isDebug=true property to the migration.properties file to enable the debug option to trace more details for help in resolving migration issues.

DocTypePropMappingSubClassProp You can provide document types/properties mapping (save as documentType_properties_mapping.xml) to customize how those values can be mapped for during migration, for example:

<?xml version="1.0" encoding="UTF-8"?>
<doctypes>
	<doctype QJName ="docType1" FNName="docType1">
		<property QJName='New Text' QJType='text' FNName='New_Text' FNType='String'/>
		<property QJName='New Multi-line Text' QJType='String' FNName='New_Multi_line_Text' FNType='String'/>
		<property QJName='New Number' QJType='double' FNName='New_Number' FNType='Float'/>
		<property QJName='New Person' QJType='string' FNName='New_Person' FNType='String'/>
		<property QJName='New Single Selection' QJType='string' FNName='New_Single_Selection' FNType='String'/>
		<property QJName='New Date' QJType='dateTime' FNName='New_Date' FNType='DateTime'/>
		<property QJName='New Time' QJType='long' FNName='New_Time' FNType='DateTime'/>
		<property QJName='New Date and Time' QJType='dateTime' FNName='New_Date_and_Time' FNType='DateTime'/>
		<property QJName='New URL' QJType='string' FNName='New_URL' FNType='String'/>
	</doctype>
	<doctype QJName ="docType2" FNName="docType2">
		<property QJName='New Text' QJType='text' FNName='New_Text' FNType='String'/>
		<property QJName='New Multi-line Text' QJType='String' FNName='New_Multi_line_Text' FNType='String'/>
		<property QJName='New Number' QJType='double' FNName='New_Number' FNType='Float'/>
		<property QJName='New Person' QJType='string' FNName='New_Person' FNType='String'/>
	</doctype>
</doctypes>

Note: If the document type or propertysheet type name is not English, migrate the document type and propertysheet type by using the documentType_properties_mapping.xml file. Otherwise, the migration tool returns an error when it tries to create a document type/propertysheet type that contains the native words.

To start the migration:
- On Windows click the Start menu, click Run, navigate to the directory where you unzipped the migration4quickrj.zip and enter run.bat -option
- On Linux/AIX® navigate to the directory where you extracted migration4quickrj.zip and enter ./run.sh -option
Where -option is one of the following commands:
- -a retrieves all places from Quickr with place ID and name, and saves to the not_integrated_place_IDs.properties file.
  Note: Use option -a to retrieve place IDs and then perform a batch migration by using the option -s. Consider running parallel migrations by making multiple copies of the migration tool to perform batch migration according to different place IDs.
- -i retrieves Quickr places that have are integrated with Connections using the Quickr widget, lists Connections communities ID, places ID, and name and saves to integrated_place_and_community_IDs.properties file.
- -r migrates all places. If no integration exists between Lotus Quickr and IBM Connections using the Quickr widget, this command migrates all places into IBM Connections as new communities. If integration does exist between Lotus Quickr and IBM Connections using the Quickr widget, the command migrates places that are not integrated with IBM Connections as new communities.
- -e migrates all places into an existing community. If no integration exists between Lotus Quickr and IBM Connections using the Quickr widget, this command migrates all places into IBM Connections existing communities by specifying the source places ID and target communities ID from configuration file; If integration does exist between Lotus Quickr and IBM Connections with the Quickr widget, the command migrates places that are not integrated with IBM Connections as new communities by specifying the source places ID and target communities ID from configuration file.
- -s migrates places not integrated with Connections by place ID. Place By default place IDs are stored in the not_integrated_place_IDs.properties configuration file.
- -m migrates places that are integrated with Connections into existing Connections communities by place ID and community ID. By default place IDs are stored in the integrated_place_and_community_IDs.properties configuration file.
  Note: Migrate linked libraries that are previously integrated with Connections by using a library widget first. If a place has a Quickr linked library widget only, it can be migrated also by leaving the place ID blank and specifying the community ID in integrated_place_and_community_IDs.properties file.

Results

Check that places, libraries, documents, folders, document versions, members, and comments are migrated as expected.

Migration tool log output is collected in the info.log and error.log files. The phrase "Fetch *****" in info.log means that fetching is occurring currently. Phrasing similar to "Retrieve ACLs of document & folder took 0.04346666666666667 minutes!" means that the fetch completed, and "Import of document aaa.xml into /ClbTeamspaces/multiple_or_single_0_1" means that the activity of importing documents has started.

If a folder migration fails, then all subfolders and documents under the folder fails also.

After migration completes, the failedDocuments.log contains any failed documents in the format DocumentName=******* DocumentPath=*********. The failedFolders.log file contains any failed folders in the format FolderName=******* FolderPath=*********. To validate the migration, see Post-migration tasks.

See also Frequently Asked questions for answers to issues that might occur when using the migration tool.