Migrating document attachments to the IBM BPM document store

The startDocumentStoreMigration command is used to migrate document attachments from the IBM BPM database to the IBM BPM document store. The migration of document attachments to the IBM BPM document store is considered to be a required IBM BPM post-migration task and it should be done after the database migration has been completed. The original versions of the document attachments will continue to reside in the IBM BPM database until all documents have been migrated. After the migration is complete, you can use either coaches or heritage coaches to work with BPM documents in the IBM BPM document store.

1. 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:

   profile_root\bin\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.

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

3. 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}'.

4. 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 IBM BPM 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 IBM BPM database. To retain the content of the documents in the IBM BPM 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]')