Installing and configuring
This article provides detailed installation and configuration information, which supplements the Preparing to migrate Quickr for Domino places to Connections Content Manager
- DETERMINE THE USER FOR THE MIGRATION
Before using the migration tool, ensure that CCM is installed successfully. You must also determine which user to use for migration. The user must be from LDAP and can access both Connections and FileNet successfully. The user must also be a FileNet administrator.
- GENERATE THE DN MAPPING FILE FOR THE CASE OF DIFFERENT LDAP SERVERS FOR Q-D AND IBM CONNECTIONS
If Quickr Domino and IBM Connections connect to the different LDAP servers, you must generate the DN mapping files and populate them to qpconfig.xml. For example, suppose Quickr Domino connects to a Domino LDAP server or Domino Native, but IBM Connections connects to IDS LDAP servers. You must get the DN mapping from the Domino LDAP/Native to IDS for each user and group in Quickr Domino.
The DN mapping file is a CSV file. Each line has two fields, separator is “;”. The first field is the user or group DN in the LDAP server, which Quickr Domino uses. The second field is the user or group DN in the LDAP server, which IBM Connections uses. The migration tool does the mapping based on the mapping files.
User DN mapping file when Quickr connects to Domino Native:
CN=John Smith/O=ibm;CN=John Smith,OU=Users,OU=Westford,OU=Lotus,O=Software Group,DC=lotus,DC=notesdev,DC=ibm,DC=com
CN=Susan Adams/O=ibm;CN=Susan Adams,OU=Users,OU=Westford,OU=Lotus,O=Software Group,DC=lotus,DC=notesdev,DC=ibm,DC=com
Group DN mapping file when Quickr connects to Domino Native:
User DN mapping file when Quickr connects to Domino LDAP:
CN=John Smith,O=ibm;CN=John Smith,OU=Users,OU=Westford,OU=Lotus,O=Software Group,DC=lotus,DC=notesdev,DC=ibm,DC=com
CN=Susan Adams,O=ibm;CN=Susan Adams,OU=Users,OU=Westford,OU=Lotus,O=Software Group,DC=lotus,DC=notesdev,DC=ibm,DC=com
Group DN mapping file when Quickr connects to Domino LDAP:
Performing the migration
The following information describes how to perform the migration.
- GETTING THE RESTRICTED RESOURCE LIST
In the current implementation of the migration tool, the room/folder/document reader ACL setting is not reserved after Q-D migration. All community members are granted reader access to the content contained in the community, no matter whether the user is allowed based on the original Q-D ACL setting.
To facilitate the client to check which restricted room/document is brought into public, the qptool provides a sub-command getrestrictedresourcelist to list all restricted room/document contained in the place specified in the command line.
This section provides the command usage and gives a brief description explaining the meaning of the generated restricted resource list.
- To run the qptool getrestrictedresourcelist command:
getrestrictedresourcelist: Gets the restricted resource list from the specified place input list.
qptool getrestrictedresourcelist [–?] (–a | –p <place list> | –i <file>) [–o <file>]
–? Prints out this usage message.
–a Generates the restricted resource list for all places on the server.
–p <name> <name> Space-separated list of places to generate the restricted resource list for.
–i <file> Input file specifying places to generate the restricted resource list for.
–o <file> Specifies the output file. (Default: qptool.getrestrictedresourcelist.xml)
In this example, the user specified to generate the restricted resource list contained in place place_0702 to output file E:\resourcelist.xml, with the log redirected to E:\log.txt.
- Specification for the generated restricted resource list:
The generated restricted resource list for each place contains all inner rooms expanded in flat form, rather than in nested form. The following section provides a brief description for each element appearing in the generated list.
▪ <room> element:
Indicates a room, which has identical room members as place members. This means that all place members are also a member of this room. Therefore, all pages contained in the room are viewable to all place members, as long as it does not specify its own ACL, or is contained in an ACL folder.
For a room element, the "name" attribute specifies the room name, and the "nsf" attribute specifies the corresponding nsf file.
▪ <restricted_room> element:
Indicates a room whose room members are different from the place members. This means that not all place members can access the inner room. After Q-D migration, all community members are allowed to view the content contained in the restricted room. Therefore, all documents contained in the restricted room should be regarded as restricted resources, no matter whether it is listed in the generated list or not. The listed, restricted document only means the document has its own ACL setting, either explicit ACL or implicit ACL inherited from ACL folder; thus, it is not viewable to all room member.
For a restricted room element, the "name" attribute specifies the room name, the "nsf" attribute specifies the corresponding nsf file, and the "room_owners" specifies the room owners of this room.
▪ <restricted_document> element:
Indicates a document, which has its own ACL setting, either due to explicitly being a set ACL for this individual document, or implicitly being inherited from a contained ACL folder. This document is not viewable to all room members of the contained room.
For a restricted document, the "name" attribute specifies the name of the document, the "unid" attribute specifies the document unid in the notes db, the "location" attribute specifies the document location relative to the contained room, and the "document_authors" attribute specifies the document authors.
Note: For a <restricted_document> element, if the name contains sensitive information, which is not allowed to be shown in the generated list, there is a hide_restricted_document_name configuration option in qpconfig.xml specifically designed for this purpose. For more information about the <hide_restricted_document_name> option, see Preparing to migrate Quickr for Domino places to Connections Content Manager.
- MIGRATE A QUICKR DOMINO SIMPLE CUSTOMIZED FORM
If you want to migrate documents based on Quickr Domino customized forms, you must also migrate the corresponding customized forms. The Quickr Domino customized forms are migrated to FileNet as document classes. Note, however, that the design and implementation of a customized form in Quickr Domino and a document class in FileNet are different. In Quickr Domino, a customized form is at place level. In FileNet, the document type is at global level. Document classes created for customized forms in all places are placed together as the subclass of the Lotus Quickr Page document class.
Due to the maximum row length limitation of the underlying databases for Filenet (described later in this article), you may not be able to migrate all of custom forms in Quickr Domino to FileNet. The migration tool provides a filter mechanism for you to select the most important customized forms to be migrated.
This section provides a detailed description about how to select and migrate these customized forms and also provides error handing information.
- Get all customized forms from interested Q-D places and select the customized forms to be migrated. To do so:
◦ Run the qptool getcustomizedforms command:
getcustomizedforms: Gets a customized forms list from the specified place.
qptool getcustomized forms [–?] (–a | –p <place list> | –i <file>) [–o <file>]
–? Prints out this usage message.
–a Gets customized forms from all places on the server.
–p <name> <name> Space-separated list of places to get customized forms from.
–i <file> Input file specifying places to get customized forms from.
–o <file> Specifies the output file. (Default: qptool.getcustomizedforms.xml)
In this example, the user specified to generate the customized forms list contained in place place_0328 to output file d:\output.xml.
◦ Select the customized forms in the generated output XML file.
In the generated XML containing customized forms list, select the customized forms to be migrated. Notice in the following output file that the customized forms migration setting contains two level: room level and form level. The default setting is false for all room level settings and form level settings. The room level migration setting has a higher priority than a form level setting. For customized forms to be migrated, you must set the value of its migration setting to true. You must also set the migration setting of the surrounded room element to true.
For example, if you want to migrate customized form Form1 included in the Main room, you must first enable the migration setting on the Main room and then enable the migration setting on Form1. If the room level setting is false, all forms in the room will not be migrated, even if its own migration setting is true.
- Migrate the selected customized forms.
◦ Run the qptool migratecustomizedforms command:
migratecustomizedforms: Migrate a customized forms list from the specified place input list.
qptool migratecustomizedforms [–?] -u <user> -pw <password> -i <file> [-o <file>]
–? Prints out this usage message.
–u <user> Specifies the user name of the privileged account to run the migration.
–pw password Specifies the password of the privileged account to run the migration.
–i <file> Input file specifying places to be migrated.
–o <file> Specifies the output file. (Default: qptool.migration.xml)
The user must provide the selected customized forms list as an input parameter to this command. The console output displays which customized form was migrated successfully and how many customized forms are migrated for each room and place.
Note: Because migratecustomizedforms saves the mapping relationship between Q-D customized forms and the Document class in the local cache files during customized forms migration, it does not support multiple qptool instances running simultaneously, which can destroy the consistency of the local cache file.
- Best practice for migrating customized forms.
According to the current design and implementation of the document class in Filenet, all property templates contained in document class are maintained in the DocVersion table. That is to say, each time you create a new document class, the DocVersion table is altered to add the columns corresponding to the property template contained in the new document class.
The underlying database has a row length limitation, which restricts the maximum byte length of each row in table. Since each column created for the property template uses some byte space to store data, eventually the row length limitation of the DocVersion table is exceeded, resulting in failure of the document class creation operation.
When running the qptool migratecustomized forms command, if you notice a runtime exception reporting, “The row length limitation of the underlying database has been exceeded, incapable of creating document class any further,” it means you are not able to migrate customized forms any further.
Since the row length limitation is a unavoidable restriction, there is no way to migrate all user-selected customized forms if you select too many customized forms to migrate. And, it is also possible that the customized forms considered "important" are still not migrated when the exception is thrown.
Therefore, it is strongly recommended that customized forms be prioritized from most significant to least significant, so as to avoid or minimize the need for performing manual cleanup, which is necessary for restoring the DocVersion table to its initial status for preparing to re-migrate customized forms.
Only when the most important forms are migrated successfully, should you migrate less important forms. In other words, migration of customized forms is an incremental operation; not an all-in-one operation. Run this command multiple times, gradually increasing the customized forms to migrate. In this way, you can be assured that the most importance customized forms are successfully migrated to CCM if the row length limitation exception is thrown.
For example, suppose that there are three different customized forms, formA, formB and formC, sorted according to their relative significance. The migration order should be formA, then formB, and, lastly, formC. In this case, you should run the migratecustomizedforms command three times.
▪ For the first time, only select formA to be migrated.
The console displays a message if formA is successfully migrated to CCM.
▪ For the second time, select formA and formB to be migrated.
Again, the console displays a message if formB is successfully migrated to CCM.
▪ For the third time, select formA, formB and formC to be migrated.
If formC is successfully migrated to CCM, another message is shown.
▪ You must examine the command output to check that the selected customized forms were successfully migrated. After the row length limitation exception is thrown, there is no need to proceed to next step, since the DocVersion table is not able to hold any more document classes.
Nevertheless, a manual clean-up operation is necessary in case you change your mind about the significance of the customized forms and want to re-migrate these forms again. For more information about how to perform this clean-up operation, refer to the "Error handing when the row length limitation is exceeded" section in this article.
- Check the current low length for the DocVersion table.
If you are curious if the DocVersion table can hold any more document classes, and want to check the current row length of the table, here are some tips. Take DB2 for example. You can run the following command to check the current row length of the DocVersion table, which is the main restriction for customized form migration.
▪ Connect to FNOS database using LCUSER account:
▪ Get the database page size setting, which corresponds to the row length limitation:
▪ Run the db2 describe table DocVersion command, and redirect the output to a file:
▪ Examine the output file to calculate the current row length of DocVersion table. You must sum up all the values in the “Column Length” column as shown.
Note: For data type BLOB and DBCLOB, the sizes shown in the output table (1073741824 and 536870912 respectively) are not the actual byte space taken up by the column. Use 300 as an approximation for the size instead of the number shown in the output file.
For a more formal way to determine the table row length, see information about determining database row size in the FileNet information center. You can then compare the row length limitation with the table row size to get a feel for how much byte space remains to create document classes.
- Error handing when the row length limitation is exceeded.
This section describes how to run the cleanup operation to prepare for re-migrating customized forms. Because this process involves multiple manual operations, it is recommended that you decide the significance of these customized forms.
▪ Delete all serilization files. During the customized forms migration process, several serilization files are going to be generated, saving the migrated customized fields information and customized forms information.
This file, located in the <domino_installation>\data\LotusQuickr directory, contains the mapping relation from Q-D customized fields to the Filenet property template (<field_type, field_name, choice_list> ------> property template unid). This file is shared by all Q-D places in the Domino server.
2. Main.ser and PageLibraryXXXXXX.ser
These files are located in the place directory for each place, with each file corresponding to one room. They contain the mapping relationship between successfully migrated customized forms and the Filenet document class (customized forms unid and other important information ------> document class unid). These files also contain the migration setting configuration, which determines if the Q-D pages created based on the customized forms need to be migrated when running the Q-D migration command. These files are also used when migrating Q-D files based on customized forms to get the metadata describing the customized forms, such as the customized property list.
Generally, there is no need to delete these serialization files unless you want to run the clean-up process and then re-migrate customized forms. You must delete these serialization files to remove all cached mapping relationships between Q-D customized forms and the Filenet document class, since the document class corresponding to Q-D customized forms is deleted after the cleanup process, and then generated again.
▪ Delete all document classes corresponding to the migrated customized forms.
▪ All document classes corresponding to the migrated customized forms are subclass of “Lotus Quickr Page” document class. You must delete all the document classes located under “Lotus Quickr Page”.
▪ Delete the Property Templates contained in the document classes that were just deleted.
▪ A property template is the Filenet equivalent of a Q-D customized field. Each customized field contained in a customized form must match a property definition in the corresponding Filenet document class. That is to say, a Document Class consists of a Property Definition, which is an instance based on a Property Template. To run the clean-up operation, you must delete all the property templates created for migrated customized forms.
▪ You can locate a Property Template using the Created Date and Category columns as shown. All Property Templates created for customized forms are categorized as “Lotus Quickr,” but not all Property Template categorized as “Lotus Quickr” are created for customized forms. Some are created by Quickr product add-ons, which must not be deleted. So to identify the Property Template that needs to be deleted, you must use a combination of Created Date and Category to locate them.
▪ Delete Choice List corresponding to Q-D customized field of Text Popup type.
▪ To migrate a Q-D customized field of Text Popup type, a choice list needs to be created to store the choice items, besides the property template.
▪ To completely clean up the Filenet server with regards to customized forms migration, remove choice list objects created for Q-D Text Popup fields (display names start with “h_TextPopup) from the Filenet server.
▪ Remove the database column associated with a deleted property. To do so:
1. Stop the Content Engine (CE) application to ensure there is no user activity on the object store. The object store database is altered by this procedure and it is important that no users are accessing the database at this time.
2. Use the following query in the appropriate database tool to obtain all the columns that the CE knows about the DocVersion table.
select column_name from ColumnDefinition where lower(dbg_table_name) = lower('DocVersion')
Take DB2 for example. The following command saves the result of querying the valid columns of the DocVersion table that CE cares about to a file.
3. Drop unused columns from the DocVersion table that are not present in the CE's ColumnDefinition table.
Take DB2 as an example. With the IBM Data Studio, you can use the GUI to alter the table. The Alter screen gives the "Drop" option, which allows you to choose the columns for removal. Consult the DB2 documentation for details on drop column support in the Control Center. This procedure can be time consuming if the table has many rows, and preparations for logging and disk space must be made.
After deleting all document classes from the CE console, the columns marked with a red, rounded rectangle represent unused columns. After dropping the column definition, the byte space occupied by these unused columns can be released.
4. Restart the Content Engine application.
- MIGRATE QUICKR DOMINO PLACES
Run the qptool migratecustomizedforms command:
migratecustomizedforms: Migrate a customized forms list from the specified place input list.
load qptool migration [-p (place list)] [-a] [-i input.xml] -u username -pw password
–p Specifies a single place or a list of places to migrate.
–a Migrates all places.
–i input.xml Specifies the places list in the xml file.
–u <username> Specifies the administrator account used for migration.
–pw <password> Specifies the administrator account password.
- STATISTICAL INFORMATION
After each place is successfully migrated to CCM, the following statistic information is generated.
A detailed explanation for each counter is as follows:
- Migrated Room Count: The number of sub-rooms successfully migrated for this place.
- Migrated Folder Count: The number of folders successfully migrated for this place.
- Migrated Document Count: The number of Q-D documents successfully migrated for this place.
- Migrated Document Version Count: The number of Q-D documents taking version into account successfully migrated for this place.
- Migrated Attachment Count: The number of attachments successfully migrated for this place.
- The difference between Migrated Document Count and Migrated Document Version Count is that Version Count takes version into account. For example, if a Q-D page with two versions is migrated to CCM, the Migrated Document Count is increased by 1, but Migrated Document Version Count is increased by 2, since there are two versions associated with this Q-D page.
- A Q-D page with a Upload/Imported type is counted in the Migrated Document Count, but not in the Migrated Attachment Count. The Migrated Attachment Count only counts the attachments attached to a Q-D normal page and uploaded image inserted into the page content.
- The sum of the Migrated Document Version Count and Migrated Attachment Count values should be identical with the "File count" obtained from ACCE. The "File count" actually counts the number of Content Elements added to the Filenet Document object. Also, since both the HTML rich text for each Q-D document version and the attachments attached to Q-D page are treated as Content Elements of the Document object associated with the Q-D page:
File count = "Migrated Document Version Count" + "Migrated Attachment Count"