Step-by-step DMS Migration

The DMS migration is a wizard-driven process. The DMS Migration wizard walks you step-by-step through the entire migration process, including the following stages:

  • Select target DMS

  • Configure target DMS

  • DMS migration in progress

  • Start DMS Transition

  • DMS Transition in progress

  • Commit the migration

To migrate a DMS,

  1. Log in to PPM and launch the Administration Console.

  2. From the Administration Console Actions pane of the Administration Console window, click Administration Task > DMS Configuration.

  3. On the DMS Configuration page, click Migrate.

    The wizard displays the "Select target DMS" page.

  4. From the Target DMS drop-down list, select a target DMS.

    The available options vary with your current DMS. For example, if you migrate from PPM File System, the available options for Target DMS include:

    • PPM Database DMS

    • External Database (JDBC) DMS Driver

    • External Database (JNDI Datasource) DMS Driver

    Note: The latter two options are two ways of defining the external database for the PPM External Database DMS solution. For more information, see Configuring PPM External Database DMS Solution.

    Note: If you migrate your current DMS (Documentum or PPM Database DMS) to PPM File System, a warning message shows up stating that some document information might not be preserved due to unsupported functionalities by the target DMS.

  5. Click Next.

    The wizard displays the "Configure target DMS" page.

  6. On the "Configure target DMS" page, provide values for all required fields.

    • If you selected PPM Database DMS as the target DMS, there are no empty fields on this page. Proceed to next step.

    • If you selected External Database (JDBC) DMS Driver as the target DMS, provide values as described in the table below.

      Field (*required)

      Description, Sample Value

      dms.database.JDBC.ServerAddress

      Address (IP address or machine host name) of the DB Server where to you plan to store DMS documents.

      dms.database.JDBC.ServerPort

      Port of the DB Server where you plan to store DMS Documents.

      *dms.database.JDBC.DB_SID

      SID of the DB server where you plan to store DMS documents.

      dms.database.JDBC.Username

      Username of the DB server where you plan to store DMS documents

      dms.database.JDBC.Password

      Password of the DB server where you plan to store DMS documents

    • If you selected External Database (JNDI Datasource) DMS Driver as the target DMS, make sure you have created your JNDI datasource, then provide values as described in the table below.

      For information about how to create JNDI datasource, see Creating JNDI Datasource.

      Field (*required)

      Description, Sample Value

      *dms.database.JNDI.Datasource

      Specify the JNDI name of the datasource used to store documents.

      Note: Make sure you prefix your value with "java:". For example, java:dms, or java:/dms.

      dms.database.JNDI.Username

      Specify the username you use to connect to the JDNI datasource. Leave it blank if username and password are already defined in the datasource definition.

      dms.database.JNDI.Password

      Specify the password you use to connect to the JDNI datasource. Leave it blank if username and password are already defined in the datasource definition.

  7. Click Next.

    Clicking Next tests your configuration right away and proceeds to the next page when the configuration is valid, and the new page summarizes the target DMS configuration.

    As part of the validation, it tries to create and delete some temporary documents on your new DMS environment.

  8. Click Start Migration if you are sure you want to migrate the current DMS to the specified target DMS.

    Upon migration start, the DMS Migration Engine Service is enabled and the documents are migrated in batches.

    Note: There can be a delay of less than one minute between clicking Start Migration and the moment where the document starts to be actually migrated; this is due to the default scheduling of the DMS Migration service, which starts every 30 seconds.

  9. After clicking Start Migration, the wizard displays the "DMS migration is IN PROGRESS" page.

    While the DMS Migration is in progress, the DMS Migration Engine Service is running in the background to migrate the documents. If a PPM User checks in new documents or edits the existing documents, these documents are also migrated.

    The DMS Migration Engine Service has no impact on the working of the current DMS system. When PPM Users perform DMS actions, such as checking in or out documents, they are working with the current DMS system.

  10. Click Refresh to update the migration progress status.

    Note: The progress bar is not updated automatically. You need to click Refresh to update the migration progress status.

    The migration status contains the following information:

    Item

    Description

    Status

    Status of the migration, shown by a progress bar reflecting the percentage of Files processed.

    Start time

    The migration start time, it is recorded when you click Start Migration.

    Files processed

    The number of the files that have been processed. It represents the number of both Successful and Failed documents.

    Successful

    The number of documents that have been migrated successfully.

    Failed

    The number of documents which migration failed. You can click Retry failed files to retry migrating them again once the migration completes.

    Files total

    The total number of documents in the system.

  11. You can also perform the following actions on this page:

    • Retry failed files: Once the migration is completed, if there are any files that failed to be migrated, you can click this button to retry to migrate them until they succeed. All failed files are re-migrated.

      Note:  

      • If there are some failed documents, you need either retry to migrate them until they succeed, or delete them from the system. These failed documents are not migrated if you go to the next step, and should be considered lost documents once you move to transition period, even if you cancel migration during the transition period.

      • The migration log (<PPM_Home>/server/<PPM_Instance>/log/dms.log) contains detailed information about migration operations, activities, status, and issues.

        The com.kintana.dms parameter in logging.conf specifies logging these information by default. However, you can modify the logging level if needed

    • View failed files logs: View the migration log for a list of failed files. If a file fails to be migrated, the whole exception details are included in the logs. You can search migration logs based on the time the error occurred.

    • Pause | Resume: When migration is under way, you can pause it. If migration is paused, you can resume it.

    • Cancel Migration: Clicking this button cancels the migration immediately and brings you back to the current DMS Configuration screen. The target DMS environment is left as-is. Documents already migrated to the target DMS system remain there unless manually removed.

  12. When the progress state reaches 100%, click Refresh.

    The wizard displays the "DMS Migration is COMPLETED" message.

    Note: Once you see the message, make sure that no document is in Failed state, as failed documents are not available once you start using the new DMS.

    Before moving to the next step (Transition Period), this is a good time to enable full-text search if you plan to use the feature.

    If you move to Transition Period without enabling full-text search, the full-text search feature is not be available to PPM users and they cannot search documents by Document Key Words.

    To enable full-text search in PPM Database DMS:

    1. Create TEXT indexes, as described in Create and maintain Oracle TEXT indexes.

      Note that this step can take a long time (over 1 hour per 5 GB of documents to index).

    2. In PPM Administration Console, go to Application Configuration, set the parameter DMS_DB_ENABLE_FULLTEXT_SEARCH to true, and then save the change.

    Once the migration is completed, you can move to "Transition Period", during which PPM Database DMS becomes active, but your old DMS solution (File System or Documentum) is still active in the background and save copies of newly created documents. This way, you can try PPM Database DMS for some time. If you find that the new DMS solution does not meet your requirements, or if you encounter any issue with the new DMS solution, you can always switch back to the previous DMS solution without causing loss of any documents to PPM users.

  13. Click Start Transition.

    Starting the transition replaces the current DMS solution with the new target DMS solution. It takes a few seconds to a few minutes to complete this switching action, during which the wizard displays a temporary page.

    During the transition, the PPM DMS system becomes read-only for a few seconds while the DMS Driver is reloaded on all PPM Server nodes. If PPM users try to add a new document or check in a new version while the system is locked, they receive a message similar to the follows: 

    PPM Document Management System is currently under maintenance. Please try again later.

    For this reason, and to minimize the potential impact on PPM Users, it is recommended to move to transition while the PPM Server system is not under heavy load.

  14. The wizard displays the "Transition" page.

    In the transition stage, your DMS system is already switched to the target DMS system, and all documents in the legacy DMS System were already migrated.

    The DMS Transition period allows you to start using the new DMS solution while the old DMS is still available. PPM Users are performing DMS actions on the target DMS solution, such as check in, check out, and save documents. Meanwhile, any new documents added or modified documents checked in to the new DMS system by PPM users are synchronized back to the old DMS system as well. This way, if you choose to cancel the migration and move back to the legacy DMS solution for any reason, you are not losing any documents changes occurred during in the transition process.

  15. Click Refresh to update transition synchronization status.

    The transition status information includes:

    • Transition status

      • Number of Failed documents

    • Documents Migration Summary

      • Start time

      • File processed

      • End time

  16. You can perform some other actions on this page:

    • Retry failed files: Just like during the migration, some files may fail to be synchronized back to the legacy DMS solution. This has no impact if you choose to continue with the new DMS system, but make sure that these documents are synchronized successfully back to the legacy DMS system if you plan to cancel the migration.

    • View failed files logs: Errors occurred during synchronization of documents changes are logged along with exception details. Click this button to view detailed log.

    • Cancel Migration: Clicking this button during the transition period results in synchronizing any new documents or new versions of documents added or checked in to the new system but not yet synchronized back to the legacy system, and then switching back to the legacy system.

      Note: If PPM Users create and save new entities with attachments in the time lapse between a PPM administrator clicking Cancel Migration and the completion of the cancellation process, these entities might fail to be created as the DMS is locked during that time window. This is similar to what might happen after the transition period starts.

  17. Click Commit.

    By clicking Commit, you stop synchronizing new documents to the old DMS. Once you click Commit, the DMS Migration Engine Service stops, you are officially moved to the PPM Database DMS, and the old DMS is retired.

    Note:  

    • You can stay in Transition period for as long as you feel necessary to ascertain the stability and performance of the new DMS system.

    • All error log for failed documents are cleaned once you click Commit.

    • The DMS Migration Engine Service is disabled automatically after you click Commit. Do NOT try to start it manually.

    • PPM does not delete any of your documents from the old DMS solution (Documentum or File System) after a DMS Migration, you need to manually remove them once the migration is committed.