DOCUMENTUM® D2 4.6 CONFIG OBJECT
MODEL CHANGE AND MIGRATION
ABSTRACT
This white paper explains how to use the migration utility to upgrade the object
model and config objects from version 4.5 to 4.6 in your EMC® Documentum® D2
applications.
March, 2016
WHITE PAPER
To learn more about how EMC products, services, and solutions can help solve your business and IT challenges, contact your
local representative or authorized reseller, visit www.emc.com, or explore and compare products in the EMC Store
Copyright © 2014 EMC Corporation. All Rights Reserved.
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change
without notice.
The information in this publication is provided “as is.” EMC Corporation makes no representations or warranties of any kind with
respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a
particular purpose.
Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com.
Part Number H15001
2
TABLE OF CONTENTS
EXECUTIVE SUMMARY .............................................................................. 4
AUDIENCE ....................................................................................................... 4
D2 CONFIG OBJECT MODEL CHANGE ......................................................... 5
PREREQUISITES FOR MIGRATION ............................................................ 5
MIGRATION UTILITY ................................................................................ 6
RUNNING THE UTILITY ............................................................................. 7
MIGRATION PHASES ................................................................................. 8
TYPES MIGRATED ................................................................................... 10
CUSTOMIZATION IMPACT ....................................................................... 11
TROUBLESHOOTING ............................................................................... 12
3
EXECUTIVE SUMMARY
This white paper explains how to use the migration utility to perform a one-time migration while upgrading from EMC®
Documentum® D2 4.5 to 4.6.
The D2 Config object types were upgraded in version 4.6 to extend from dm_sysobject which allows them to be protected by
ACLs. Migration of types in an existing D2 environment along with corresponding object instances requires a one-time
transformation be performed on the docbase. This is a mandatory step to upgrade from D2 4.5 to 4.6.
AUDIENCE
This white paper is intended for support professionals and customers. It contains steps to perform migration to upgrade to
Documentum D2 4.6
4
D2 CONFIG OBJECT MODEL CHANGE
D2 Config provides many configuration types, instances of which represent application configuration and are stored in a
Documentum repository. Prior to D2 4.6, instances of many of these configuration types were just persistent objects with no
ACLs. In D2 4.6, these types have been promoted to extend dm_sysobject, which means that all instances of these types can be
protected by ACLs which grant appropriate privileges to designated users and groups.
For a fresh installation of D2 4.6, the DAR files that are deployed to the repository will have the upgraded types, and thus no
migration is required. However, for an existing D2 4.5 environment, these types need to be redefined and their corresponding
object instances migrated before D2 can be upgraded. Since the config objects are dropped and recreated as part of migration,
the object ID of such objects will change and hence any dm_relations which refer to these objects also need to be recreated.
As such, migration involves deletion and recreation of data in the repository. This process is irreversible and hence it is strongly
recommended to snapshot or backup the content server and database machines before migrating. Migration is only supported
from D2 4.5 to D2 4.6, and hence customers using prior versions of D2 will have to upgrade to D2 4.5 first, perform migration,
and then upgrade to D2 4.6.
PREREQUISITES FOR MIGRATION
•
An existing D2 4.5 environment
•
The standalone migration utility zip file
•
Java 1.7 or later on the CS machine where the utility runs
•
DM_HOME environment in CS machine (Set by default)
•
Application servers and JMS shutdown before migration
•
Admin user to run the migration
•
A snapshot of the Content Server and DB machines before running the migration utility is highly recommended
•
The dfc.properties file bundled in the migration zip merely includes C:/Documentum/config/dfc.properties. For non-Windows
machines or if the effective dfc.properties file is in a different location, update the path of this included dfc.properties file
accordingly.
5
MIGRATION UTILITY
The migration utility is a standalone command line utility. It is shipped as a zip file which needs to be extracted to the content
server machine and invoked. It is a multi-threaded program that performs dumping and recreation of objects in a phased
manner. The phases of migration can be individually skipped by passing extra arguments during invocation.
The utility needs to be run as super user in order to ensure sufficient privileges to drop objects and types. The migration utility
takes roughly an hour to migrate 7000 config objects 70000 relations along with the re-installation of DARs. The utility is reentrant and can be re-run if the migration fails at any point of time.
The migration utility will contain the following subfolders and files:
•
composer/ - Contains the D2 4.6 DARs that will be used by headless composer during migration.
•
dump/<docbase>/configs/ - Contains all config instances dumped.
•
dump/<docbase>/relations/ - Contains all relation instances dumped.
•
dump/<docbase>/types/ - Contains all config types dumped.
•
lib/ - All java jar libraries packaged with the migration utility
•
logs/ - Contains Migration.log, composer-out.log, composer-err.log
•
D2-Config-Migrator.jar - The migration utility jar
•
dfc.properties
Figure 1.
6
RUNNING THE UTILITY
After extracting the migration zip file to CS machine, use the below command to perform migration.
java -jar D2-Config-Migrator.jar <docbase> <admin-user> <password>
The utility can also take any of the below optional arguments to skip a particular phase of migration.
Note: These arguments should not be used under normal circumstances and must be used only with the guidance of D2
engineering/support after reviewing the current state of docbase.
ARGUMENT
skipCreateConfigFolders
skipDumpConfigs
skipDumpRelations
skipDumpTypes
skipScanDumpedConfigs
skipScanDumpedRelations
skipDeleteConfigs
skipDeleteTypes
skipInstallDars
skipCreateConfigs
skipCreateRelations
skipUpdateRelationDescriptions
forceMigrate
help
DESCRIPTION
Skip creating folders under /System/D2/Data in repository
Skip dumping D2 config objects
Skip dumping dm_relations related to these configs
Skip dumping dm_type that are migrated
Skip scanning dumped config xml files to determine objects already
migrated in previous run
Skip scanning dumped relation xml files to determine relations already
migrated in previous run
Skip deleting config objects from repository
Skip dropping types from repository
Skip headless composer dar upgradation
Skip recreation of configs from dump files
Skip recreation of relations from dump files
Skip updating object id references in dm_relation objects
Force migration on the repo. Dump config, dar installation and delete
types phases will be forced irrespective of args
Lists out all possible args for the command
Example usages of optional args:
skipInstallDars:
The headless composer dar installation fails repeatedly during migration and the program terminates. Use GUI composer to
manually install the 4.6 dars to docbase. Re-run migration utility with this arg since dar installation was already done and needs
to be skipped.
skipDumpConfigs:
The configs were already dumped during a previous run of migration which did not complete successfully. If the same dump
needs to be used during recreation of objects, append this arg and re-run utility to skip dumping of objects again from docbase.
forceMigrate:
Tell the migration utility to force dump configs. This has been provided to force dump/migrate objects in the repository even
though they were already migrated and are sysobjects. This is a provision to push bug fixes to migration utility and force remigration.
7
MIGRATION PHASES
The below diagram indicates the various stages of migration.
Figure 2.
Prepare
•
The utility checks if the command and args passed are valid
•
Checks if the passed in user is a superuser in the repository, if not terminates with error
•
Validates if DM_HOME is set in CS machine where migration is performed.
•
Checks for all the plugins that were installed prior to migration. This ensures that only those DARs are re-installed as part of
migration.
Dump
•
The dump folder is where all the objects being migrated are dumped. This includes configs, types, and dm_relation objects.
•
For every repository that is migrated, there will be a sub-folder under this dump folder with the repository name. Under this
repository sub-folder, there will be sub-folders for configs, relations and types.
•
The dump folder will not be deleted by the migration utility. It needs to be manually deleted after a successful migration.
•
Each dump file is an XML file which stores the properties of the object being migrated.
•
The scan phase runs through all the dumped XML files and identifies whether an XML file has already been migrated during a
previous run or if it has yet to be migrated.
8
A sample dump file for a config object looks like:
Figure 3.
Upgrade
•
Once the objects are dumped, the utility starts deleting them from the repository.
•
The corresponding types are dropped from the repository.
•
The utility invokes headless composer bundled within the CS to reinstall the DARs to the repository.
•
Plugin DARs are reinstalled only if they were previously installed to the repository prior to migration.
•
If the DAR installment is not successful, the utility terminates and needs to be re-run.
Create
•
If DAR installation was successful, the utility starts reading the dump files and recreates the corresponding objects in the
repository.
•
All references to the old object ids are replaced with the object ids of newly created objects.
Validate
•
Finally the utility prints the number of objects and relations that were dumped and migrated during the current run. It also
prints the status of the headless composer DAR installation phase.
9
TYPES MIGRATED
There are a total 71 types to be migrated. Out of these types, objects of type d2c_admin_ticket or c6_method_return are not
recreated in the repository since they are transient in nature. Plugin types, if not present prior to migration, will not be installed
or migrated.
All objects are placed under respective folders inside the /System/D2/Data/ folder in the repository. Objects of type
d2c_preferences are placed in the corresponding user’s home cabinet, and the default preference objects are placed under the
/System/D2/Data/d2c_preferences/ folder.
The following is a list of all types that will be migrated:
d2c_admin_ticket
c6_method_return
d2_dictionary
d2_dictionary_value
d2_taxonomy
d2_options
d2_persistent_config
d2_application
d2_attribute_mapping_config
d2_default_value_config
d2_mail_attachment_config
d2_register_config
d2_user_config
d2_relation_config
d2_query_config
d2_dctmaudit_config
d2_specifications
d2c_preferences
d2_module_config
d2_acl_config
d2_audit_config
d2_bocs_precache_config
d2_checkin_config
d2_checkout_config
d2_convert_config
d2_extended_create_config
d2_filter_config
d2_inheritance_config
d2_link_config
d2_linked_document_config
d2_mass_update_config
d2_menus_config
d2_naming_config
d2_pdfrender_config
d2_plugin_config
d2_portalmenus_config
d2_search_config
d2_skin_config
d2_structure_config
d2_template_config
d2_toolbars_config
d2_treeview_config
d2_uniqueness_config
d2_user_preferences_config
d2_vdtemplate_config
o2_attribute_config
x3_graphic_config
x3_skin_config
x3_space_config
x3_widget_config
d2_link
d2_link_checkout
d2_naming_counter
d2c_cancelcheckout
d2c_delegation
d2c_followup_task_audit
d2c_mailing_audit
d2c_mass_create_queue
d2c_subscription
d2c_subscription_audit
10
d2c_subscription_queue
d2c_wf_pop_history
x3_options
c2_options
o2_options
p2_options
d2_bin_options
d2_create_config
d2_create_value_config
d2_documentset
d2_documentset_switch
Config objects of most of these types will get d2_acl_config as the default ACL, thereby granting dm_world RELATE permit. For
certain types like d2_dictionary or d2_taxonomy where a security group can be defined, a separate ACL per object is created and
assigned accordingly.
CUSTOMIZATION IMPACT
Since the above types have been migrated to extend from dm_sysobject, if any custom types were created by extending these
types, they need to be handled specially.
•
If the custom types extend d2_module_config or d2_persistent_config, they will be migrated automatically.
•
If the custom types extend any other types in the above table, the types and objects will have to be migrated manually.
Also if there are any custom attributes on these custom types that conflict with a dm_sysobject attribute, then the custom
attribute needs to be renamed by changing the type definition and objects migrated accordingly. Any custom code written
involving types inheriting from the above types should be written with this object model change in mind.
11
TROUBLESHOOTING
1.
“Please set DM_HOME environment variable and re-run migration utility” error
2. Verify that the DM_HOME env variable is set in the CS machine. This is usually set by default.
3. “Unable to obtain session, exiting migration utility.” error
4. Verify that the dfc.properties within migration folder includes the dfc.properties in CS machine correctly
5. “Error retrieving object by Object Id. This may happen if an object previously installed by Composer was deleted” and
“DM_TYPE_MGR_E_CANT_FIND_TYPE_HANDLE” in composer logs.
6. This does not impact the migration in any manner and can be safely ignored. It was fixed as CMPSR-4474 in 7.1P21, 7.2 P05
versions of headless composer.
7. “java.io.FileNotFoundException: .\logs\composer-out.log (The system cannot find the path specified)” error
8. If using Windows server 2012, if the machine login account being used is not Administrator, the migration utility should be
run in a cmd shell which in turn is started using “run as Administrator” in order to have sufficient privilege to create files.
9. “[emc.installer] Caused by: org.eclipse.core.internal.resources.ResourceException: A resource already exists on disk '<D2Config-Migrator>\composer\Install_workspace\D2-DAR\bin\content\69” error in composer logs
10. Rename or delete the ”/composer/Install_workspace" folder and re-run migration utility
11. “[DM_TYPE_MGR_E_CANT_FIND_TYPE_HANDLE] “error during creating configs
12. Verify if the type was re-installed successfully by migrator
12