Migration Manager Best Practices

1. Migration ManagerBest Practices Sampath Sriramadhesikan August 25, 2009

2. Agenda • Introduction • Content Practices • Package Practices

3. Introduction • Factors influence successful use of Migration Manager • Know your content • Knowledge of configurations • Integrity of configurations • Knowledge of configuration applications • Limitations of Migration Manager • Know Migration Manager functionality • Organizing migration groups • Organizing packages • Using change packages • Using snapshot package actions

4. Source Maximo instance Target Maximo instance Define Create Distribute Deploy Recap – migration steps • Migration Manager incorporates four key steps • In source environment, the key step is package definition • Package definition determines the content • In target environment, the key step is package deployment • Package deployment imports content into the target database • Package deployment errors can reveal: • Bad data in the source environment • Configuration dependency issues

5. Planning for migration • Pre-requisite to all migration steps • Planning is act of identifying: • All configuration artifacts that must be migrated • All the necessary migration artifacts that must be created and managed to migrate configuration artifacts • Planning is essentially data gathering • From project managers • Which application must go live? When? • From development team members • Which configurations are needed for a particular application go live? • Result of planning activity is usually a document or spreadsheet

6. Migration planning spreadsheet

7. Recommendation • Include migration planning in project schedules • Collaborate with development team to keep track of configurations • Ensure a migration planning document is output • Should provide package-level details • Which package migrates which configuration? • Outline migration procedure: • Manual tasks • Migration Manager tasks • Tasks using other tools (Integration Framework data import) Benefits • Systematic approach to migration, increase stakeholder awareness • Smoothen migration tasks; avoid ad hoc migrations

8. Deploying Content • Configuration content deployed using Migration Manager is subject to business rules and validations Process manifest (MANIFEST) - determine product compatibility Process data dictionary data (DDMETADATA) Validations Process package metadata (PKGMETADATA) Configure the database-structural changes are applied Validations Validations Process compiled sources (CMPSRC) Process all other configurations (CFGDATA) Validations

9. Bad data • Bad data is data that does not obey business rules and validations • Bad data in a migration package can lead to deployment errors • Bad data impacts application functionality, availability and stability • Bad data is predominantly introduced through SQL scripts/statements • Directly inserting/updating/deleting records in the database • No business rules or validations • Examples: • Maxvars have no matching Maxvartype • Workflow process references action, but no action record is present • Domain values exceed domain length • Attribute length less than domain length • Domain type and values do not match • Table is text search enabled but no attribute is enabled for search type TEXT • More than one clustered index has been set up for a table

10. Data integrity tools • Primary tool is Integrity Checker • Verifies the integrity of key configurations of the underlying Maximo database • Critical to identify bad data in the database • Integrity Checker should be run in both source and target environment • Run periodically, prior to and after migration • Integrity Checker bundled with Maximo • Location: /tools/maximo/integrityui.bat • Integrity Checker log files location: /tools/maximo/log • Log file name: Integrity<datetime stamp>.log • Integrity Checker documentation currently part of Maximo 6->7 upgrade • Upgrade guide downloadable from IBM support • Most data dictionary discrepancies can be fixed by running Integrity Checker in ‘repair’ mode

11. Integrity Checker spreadsheet • Incorporate integrity checker prior to migration activity • Prepare an assessment spreadsheet: Identify fix before migration can begin Determine if error impacts migration Identify cause of error from product documentation Error message from Integrity Checker log

12. Recommendation • Before migration begins, determine the impact of Integrity Checker errors upon migration • Review integrity checker errors with development and IBM support and/or services team • Correct the errors and warnings following instructions in the Integrity Checker documentation or with assistance from IBM support and/or services team Benefits • Successful integrity checking lowers chances of migration errors • Smoothen migration tasks; avoid costly recovery from migration errors

13. Comm Templates Roles Workflow Database Configurations Application Presentations Domains Condition Expressions Sig Options Security Groups Users Object Structures Publish Channels External Systems End Points Database Configurations Understanding and organizing migration groups and objects • Migration Groups and Object Structures applications are used to organize content • These applications can be exploited when there is greater understanding of relationships among various configurations • Each application being prepared for production may require a number of underlying configurations to be migrated: Purchasing applications Asset applications

14. Defining new migration groups • It may not always be appropriate to utilize out of the box migration groups • You can create custom migration groups to reorganize content to suit your specific migration scenario BPM XYZWF DMROLE DMESCALATION DMACTION DMROLE DMACTION DMCOMMTEMPLATE DMCOMMTEMPLATE DMWFPROCESS DMWFPROCESS DATA DICTIONARY XYZWFPERSON DOCUMENT LIBRARY DMPERSON SYSTEM FUNCTIONAL APPLICATION Customer specific groups to migrate workflows only (5 object structures) RESOURCES Out of the box BPM group (50+ object structures)

15. Defining new object structure • An object structure is an assembly of related business objects • Each out of the box object structure for Migration Manager has been verified for end-to-end migration • Each object structure may be associated with Java processing class: • Outbound class (during export; rarely required) • Inbound class (during import; may be required to adhere to business rules and validations) • If an object structure is not available out of the box, it can be designed on the field • Testing a newly defined object structure will reveal need for Java processing • IBM services or business partners can create these as needed

16. Approach for new object structures and migration groups Start Determine if you have requirements to support production rollout (Content created in development, promoted to test/production) Define the object structure(s) that groups together chosen MBOs Set up source and target product environments and prepare an appropriate seed database Determine whether there are MBO business rules that require extra processing Code object structure processing class (outbound, inbound) Define a package that includes your migration group, create, distribute and deploy Identify the application you need to enable If errors occur, adjust your object structure definition and/or processing code; re-test Identify the relevant MBOs of the application whose content should be migrated Define a migration group to group and order the object structures; set up dependencies Finish Test content migration Identify content Enable content

17. Review object structure limitations • Limitations are documented in Migration Manager guide and Tech Notes • Some object structures may support certain migration scenarios • Data not migrated: • Data may be environment specific (example: passwords, ports) • Data may depend upon other transactional objects • Data may be generated by business objects directly • Data migrated but has dependency: • Other data migrated prior to current object structure • Organization, site, etc

18. Review object structure limitations - examples • Users migrated with DMMAXUSER object structure • Example limitation: • Data in the LOGINTRACKING tables is not migrated (considered specific to an environment) • Ticket Templates migrated with DMTKTEMPLATE object structure • Example limitation: • Organization, site, person, person group, classification must all be migrated prior to ticket template migration • Workflows migrated with DMWFPROCESS object structure • Example limitation: • Data in the WFINSTANCE and WFTRANSACTION tables is not migrated (considered specific to an environment) • Data for workflow actions should be migrated prior to workflow migration using DMACTIONGROUP and DMACTION object structures

19. Recommendation • Review configurations with your development team • Map configurations to the appropriate migration groups and object structures • Assess if new migration groups and/or object structures are required • Create new migration groups if necessary to reduce the volume of data to be migrated • Create new object structures if necessary and you want to migrate data using Migration Manager functionality Benefits • Tailor migration effort to your requirement • Simplify the migration effort to only the configurations that need migration

20. Defining Packages • Migration Manager is used to define two types of packages: • Snapshot • Change • Snapshot packages are easy to define and manage • Snapshots can be created at any time • Change packages require planning and preparation • Change packages must be defined and activated ahead of the configuration activity • Choice of the type of package depends upon: • Level of change management in development • Migration strategy

21. Snapshot packages • There are two key features in snapshot packages: • SQL criteria • XML processing actions • SQL criteria may be associated with each object structure included in the package definition • Criteria are in the form of standard SQL where conditions • Can use SQL constructs like ‘1=2’ to avoid selection of any records for an object structure • Criteria can be modified at any time (even after package definition approval) • Example: migrate a specific set of domains- • domainid in ('XYZCHANGETYPE', 'XYZBANK','XYZTICKSOURCE','XYZPROTICKSOURCE', 'XYZWRTICKSSOURCE', 'XYZEMERPATH', 'XYZCHANGEPATH','XYZWRTKSSOC','PMSTATUS', 'PRSTATUS','WOSTATUS', 'SRSTATUS','INCIDENTSTATUS','PROBLEMSTATUS') • Example: migrate a specific set of PERSON records- • personid in (select personid from maxuser where userid in (select userid from groupuser where groupname in (‘MXDEV', ‘MXREF')))

22. Snapshot packages – XML processing actions • Processing action can be associated with each snapshot package • Action is specified during package definition or before package creation • Action is applied to each XML document within the package • Action can be: • Replace • AddChange • Replace rule: • If the main record exists, it will be updated; if not, it will be inserted • If the sub-record exists, it will be updated; if not, it will be inserted • If a sub-record is not present in the XML document, but present in the target database, that sub-record will be removed from database • Summary: The target configuration will match the configuration expressed in the XML document • AddChange rule: • If the main record exists, it will be updated; if not, it will be inserted • If the sub-record exists, it will be updated; if not, it will be inserted • Any other sub-records in the target database not present in the XML document, will be left untouched

23. Stage/Production Environment ESC 1001 XML processing example ESCPOINT 1 ACTION 1 Development Environment ESC 1001 1 ESCPOINT 2 ESCPOINT 1 ESC 1001 Initial Migration ACTION 2 ESCPOINT 1 ACTION 1 New point added directly in stage/prod ACTION 1 2 ESCPOINT 2 ESCPOINT 2 ACTION 2 ACTION 2 ESCPOINT 3 Development changes ESC 1001 ACTION 3 ESCPOINT 1 ACTION 1 ESCPOINT 2 3a ESC 1001 ACTION 2 Second Migration (action=Replace) ESCPOINT 3 ESCPOINT 1 deleted ACTION 3 ACTION 1 ESCPOINT 4 ESC 1001 ESCPOINT 2 ACTION 4 ESCPOINT 1 ACTION 1 ACTION 2 3b ESCPOINT 2 ESCPOINT 4 ACTION 2 Second Migration (action=AddChange) ACTION 4 ESCPOINT 3 ACTION 3 ESCPOINT 4 ACTION 4

24. Change packages • Change packages must be defined and activated ahead of time • They must capture database events as configurations are built • Change tracking records are stored and accumulated over time for each change package • Change tracking records can be viewed in Migration Manager application • Tracking records may be deleted prior to package creation • To avoid re-sending accumulated tracking events, use Reset Event Tracking action to move accumulated tracking events to history table • User-specific change tracking should be exploited in multi-user environment where some users alone are authorized to change configurations

25. Viewing tracked changes Primary keys of affected object User that caused the event Object affected by change Event date Database event • Prevent unauthorized changes from being migrated • Review each tracking record • Delete a tracking record if corresponding configuration should not be migrated

26. Other package features • Package can deployed back to the originating environment • Useful in development environments to save work in progress • Periodic refresh of development environment requires developers to save their work and restore • Package manifest information • Determine size and scope of the package • Object structures included in the package • Main record counts for each object structure • Determine compatibility of target environments with package content • Product and version information of originating environment • Older package (example, Maximo 7.1 version) can be deployed to newer targets (example, Maximo 7.1.1.4) • Share package of package definitions • Well defined or best practice package definitions can be packaged and shared among development team members

27. Recommendation • Packages offer a very flexible construct to hold configuration content • Package definition drives all subsequent migration steps including deployment • Care should be taken to define the migration groups, SQL criteria of the package definition • Review definitions with development team members prior to creating packages • Depending upon development methodology, snapshots or change or a mix of packages may help achieve migration goals • Adopt a package definition naming convention that reflects content, project milestone or owning development team Benefits • Flexible package functionality can be adopted to development methodology • Consistent packaging conventions ensure traceability and repeatability during migration activity

28. Database backups • Treat migration on par with patches, upgrades, installs • Database backups prior to package deployments are strongly recommended • Most customers have daily/maintenance window database backup policies in effect • Migration Manager itself does not contain any rollback or restore capability

29. Migration logs • Detailed debug logs can be generated for migration tasks, especially deployment • Faster isolation of errors and corrective action • Have entire package processed to capture all data validation errors • Turn on system property mxe.dm.continueonerror • Configure logging for ‘dm’, ‘integration’ and ‘sql’ loggers • Direct Migration Manager logs to dedicated migration log file • Ensure ‘DEBUG’ level is specified for ‘integration’ and ‘dm’ loggers • Ensure ‘INFO’ level is specified for SQL logger

30. Migration logs Name of the package being deployed Type of the XML being processed Name of the object Primary keys of the record being processed Database operation being performed with the data Which XML failed to be processed? Validation error message