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.
The startDocumentStoreMigration and getDocumentStoreStatus commands
are used to perform many of the tasks in this topic. The commands
are run using the AdminTask object of the wsadmin scripting client.
To run the commands, the following conditions must be met:
- The commands must be run on the deployment manager node.
- One or more application cluster members must be running.
- Run the commands in connected mode. Do not specify the wsadmin
-conntype none option.
- You must connect to the deployment manager with a user ID that
has WebSphere Application Server operator privileges.
Start the wsadmin scripting client from the profile_root/bin directory
of the deployment manager profile (or the stand-alone server profile
of IBM BPM Express). The commands do not write to a log file, but
the wsadmin scripting client always writes a profile_root/logs/wsadmin.traceout log
file where you will find exception stack traces and other information.
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:
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.