Migrating document attachments to the IBM BPM document store

After migration, you must migrate your document attachments from the Process Server database to the IBM BPM document store. The migration of document attachments is a required post-migration task. The original versions of the document attachments will continue to reside in the database until all documents have been migrated. After the migration is complete, you can use either coaches or heritage coaches to work with IBM BPM documents in the IBM BPM document store.

Before you begin

Before you attempt to migrate your document attachments to the IBM BPM document store, review the topic "Limitations in administering the IBM BPM document store" to ensure that your system meets the requirements for document migration.

When document attachments are being migrated to the IBM BPM document store, they are temporarily stored twice in the Process Server database. For this reason, you should ensure that the Process Server database has sufficient storage to accommodate the twice-stored documents before you start the document migration.

Note: The IBM BPM document store must be used with a Federated Repositories user registry. If you migrate your documents to the IBM BPM document store and you later change to another form of user registry, such as a stand-alone LDAP registry or a custom registry, you lose access to your documents.

The IBM BPM document store restricts document size to 1 gigabyte or less. If the content of any document attachment in the Process Server database exceeds 1 gigabyte, you cannot migrate the document attachment to the IBM BPM document store. The document attachment will remain in the Process Server database and a reference to the document attachment will be created in the IBM BPM document store. You can access the content of the document attachment through APIs and Enterprise Content Management operations as if the document had been completely migrated.

If you are migrating documents from a pre-8.5.0.0 version to the current version, use the startDocumentStoreMigration command for your migration. This migration on IBM BPM will also set up the access control if the Basic Case Management feature is installed.

If you are migrating documents from an 8.5.0.x version to the current version and you are on IBM BPM with the Basic Case Management feature installed, access control migration will automatically start at the first start of the application cluster. The migration will run in the background. Messages in the SystemOut.log file will indicate the start and finish.

About this task

To migrate document attachments to the IBM BPM document store, complete the following steps:

Procedure

Run the getDocumentStoreStatus command. This wsadmin command returns the command syntax that can be used as well as the status of any document migration, as shown in the following sample:
AdminTask.getDocumentStoreStatus('[-deName myDeName]')

CWTDS2018I: The IBM BPM document migration has not yet started. '{0}' documents need to be migrated.

To pass more parameters for the command, you can use the following syntax:

install_root wsadmin -user my_user_name -password my_password -lang jython -c "print AdminTask.getDocumentStoreStatus('[-deName myDeName]')"

For example:

C:\8500PC\STANDARD\deploy2\AppServer\profiles\DmgrProfile\bin>wsadmin -user tw_admin -password tw_admin -lang jython -c "print AdminTask.getDocumentStoreStatus('[-deName De1]')"

For detailed information about the getDocumentStoreStatus command, see the "getDocumentStoreStatus command" topic.
Run the startDocumentStoreMigration command. This wsadmin command returns the command syntax that can be used, as shown in the following sample:
AdminTask.startDocumentStoreMigration('[-deName myDeName]')

To specify other parameters for the command, you can use the following syntax:

profile_root\bin\wsadmin -user my_user_name -password my_password -lang jython -c "print AdminTask.startDocumentStoreMigration('[-deName myDeName]')"

For example:

C:\8500PC\STANDARD\deploy2\AppServer\profiles\DmgrProfile\bin>wsadmin -user tw_admin -password tw_admin -lang jython -c "print AdminTask.startDocumentStoreMigration('[-deName De1]')"

For detailed information about the startDocumentStoreMigration command, see the "startDocumentStoreMigration command" topic.
Run the getDocumentStoreStatus command again to check the status of the document migration. If the migration is proceeding successfully or has completed successfully, the command will return one of the following messages:
CWTDS2019I: The IBM BPM document migration is running. '{0}' of '{1}' documents are already migrated.

CWTDS2020I: The IBM BPM document migration is running. '{0}' of '{1}' documents are already migrated. A cleanup is currently in progress.

CWTDS2021I: The IBM BPM document migration has finished. '{0}' documents were migrated.

If one or more documents fail to migrate successfully, the getDocumentStoreStatus command may return one of the following messages:

CWTDS2022I: The IBM BPM document migration has stopped with an error. '{0}' of '{1}' documents are already migrated. For '{2}' documents, the migration failed.

CWTDS2023I: The migration failed for document '{0}'. Details: '{1}'.
If a message indicates that one or more of the documents has failed to migrate successfully, complete one of the following steps:
- If all of the documents failed to migrate successfully, check the migration configuration and the logs for a general problem, such as a problem with the database connection.
- If the logs indicate an OutOfMemoryError condition, try increasing the heap size of the JVM for the period of time in which the migration will take place. Alternatively, try reducing the maximum number of documents that can be migrated in parallel to the IBM BPM document store, as described in the "Modifying configuration parameters" topic.
- If the logs indicate transaction timeouts, there may be very large documents that failed to migrate within one transaction. Try raising the transaction timeout temporarily by following the instructions in the topic "Transaction service settings." Alternatively, you can run the startDocumentStoreMigration command with the -keepFailedDocuments option as described below.
- If some of the documents failed to migrate successfully, you can choose to retain the content of these documents in the Process Server database and only create references for the documents in the IBM BPM document store. The legacy document APIs and ECM operations will continue to work with the documents in the Process Server database. To retain the content of the documents in the Process Server database and only create references for the documents in the IBM BPM document store, run the startDocumentStoreMigration command with the -keepFailedDocuments option, as shown in the following example:
  AdminTask.startDocumentStoreMigration('[-deName myDeName -keepFailedDocuments]')

What to do next

After the document migration has completed, the database tables LSW_BPD_INSTANCE_DOCUMENTS and LSW_BPD_INSTANCE_DOC_PROPS should be empty in the Process Server database. However, if the database contained documents larger than 1 gigabyte or if the -keepFailedDocuments option was used, the database might contain a few remaining rows. If you want, you can optionally reorganize the tables to release the disk space that was used by the deleted table rows. For example, for DB2 databases, you can reorganize the tables using the REORG and RUNSTATS commands.