Remedy Migra Tor

BMC Remedy Migrator 7.6.
04
BMC Remedy Migrator Guide
January 2011
www.bmc.com
Contacting BMC Software

You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada

Address BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000
Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000
If you have comments or suggestions about this documentation, contact Information Design and Development by email at doc_feedback@bmc.com.
Copyright 20012011 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. The information included in this documentation is the proprietary and confidential information of BMC Software, Inc., its affiliates, or licensors. Your use of this information is subject to the terms and conditions of the applicable End User License agreement for the product and to the proprietary and restricted rights notices included in the product documentation.
Restricted rights legend

U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.
Customer Support
You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer Support by telephone or email. To expedite your inquiry, please see Before Contacting BMC Software.
Support website
You can obtain technical support from BMC Software 24 hours a day, 7 days a week at http://www.bmc.com/support. From this website, you can:
s s s s s s s
Read overviews about support services and programs that BMC Software offers. Find the most current information about BMC Software products. Search a database for problems similar to yours and possible solutions. Order or download product documentation. Report a problem or ask a question. Subscribe to receive email notices when new product versions are released. Find worldwide BMC Software support center locations and contact information, including email addresses, fax numbers, and telephone numbers.
Support by telephone or email

In the United States and Canada, if you need technical support and do not have access to the Web, call 800 537 1813 or send an email message to customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) Outside the United States and Canada, contact your local support center for assistance.
Before contacting BMC Software

Have the following information available so that Customer Support can begin working on your issue immediately:
s
Product information Product name Product version (release number) License number and password (trial or permanent)
Operating system and environment information Machine type Operating system type, version, and service pack System hardware configuration Serial numbers Related software (database, application, and communication) including type, version, and service pack or maintenance level
s s s
Sequence of events leading to the problem Commands and options that you used Messages received (and the time and date that you received them) Product error messages Messages from the operating system, such as file system full Messages from related software
License key and password information

If you have a question about your license key or password, contact Customer Support through one of the following methods:
s
E-mail customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) In the United States and Canada, call 800 537 1813. Outside the United States and Canada, contact your local support center for assistance. Submit a new issue at http://www.bmc.com/support.
Contents
Preface 11
Migrator documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 AR System documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Chapter 1 Overview of BMC Remedy Migrator 15 16 17 17 17 18 20 23 24 24 25 26 26 27 28 28 30 30 31 32 32 33 33 35 36 36 37 38
How Migrator works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Migrator migrates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source and destination servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The migration process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sequencing objects during a migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System object and field migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Installing and starting Migrator
Memory usage and disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uninstalling Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3 Licensing and logging on to Migrator
Migrator licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding and managing server accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Licensing and managing servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a licensed AR System server in Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . Managing existing Migrator licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging in to an AR System server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preference servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging on and opening a server window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 4 Navigating in Migrator
Navigating in Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The main Migrator window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing information in Migrator windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing synchronization within windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Using the migration status pane and tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Migration status pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Migration status tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Customizing Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Customizing the main menu and toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Rearranging window columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Working with server windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Opening a server window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Displaying objects in a server window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Types of object details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Deleting objects from servers or files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 File types used in migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Exporting object definitions on a server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Converting definition files to .migrator format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Chapter 5 Migration options 59
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 General options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Migration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Multiple-thread options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Required Object options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Backup options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Object Removal options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Change History options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Group options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Data options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Retry options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Ignore Prefix option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Migration mask options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Directory options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Viewing backup, script, and results files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Chapter 6 Preparing to migrate 79
Defining migration modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Migration mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Scripting mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Copy/Prefix migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Migration checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Monitoring migrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Controlling migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Viewing migration results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Resolving reported failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 How objects are migrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Form migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Managing embedded server names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Chapter 7 Performing migrations 87
Performing migrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6 BMC Remedy Migrator Guide
Migrating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Migrating applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Migrating an application as a selected object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Deploying an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Migrating a form view and its associated fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Migrating fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Migrating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Migrating individual entries in a form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Migrating data entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Creating a data search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Using field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Performing Copy/Prefix migrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Chapter 8 Working with migration scripts 105 106 107 107 108 109 110 111 111 112 113 114 114 115 117 118 120 120 121 121 121 122 122 125 126 126 127 129 130 131 131 132 132
7
Scripting overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating, running, and saving migration scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and saving migration scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening and running migration scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying migration scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing object elements in a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding or removing a server in a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing server options for a script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying and removing objects in a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Before or After commands and descriptions . . . . . . . . . . . . . . . . . . . . . . Scheduling scripted migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scheduling migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing an existing migration schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 9 Dependency reports
Overview of Dependency reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Dependency reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and using Dependency reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing a Dependency report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving a Dependency report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing a Dependency report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migrating dependent objects from a Dependency report . . . . . . . . . . . . . . . . . . . Customizing a Dependency report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 10 Differences reports
Overview of Differences reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparison view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Details view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Differences reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and using Differences reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing a Differences report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving a Differences report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing a Differences report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migrating differing objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Customizing a Differences report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Differences display options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Differences color options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Mask options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Chapter 11 Migration Result reports 137
Overview of Migration Result reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Working with Migration Result reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Viewing a Migration Result report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Saving or removing a Migration Result report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Printing a Migration Result report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Customizing a Migration Result report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Result display options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Result color options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Chapter 12 Source Control 145
Overview of Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Starting SC in Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Working with SC in Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Chapter 13 Support for overlays and custom objects 151
Operations on overlays and custom objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Comparing objects at the same location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Migration of overlays and custom objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Migrating overlays that exist at the destination . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Migrating overlays that do not exist at the destination . . . . . . . . . . . . . . . . . . . . . 155 Migrating overlays when corresponding overlaid objects do not exist at destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Migrating origin objects for which overlays exist at the destination . . . . . . . . . . 156 Migrating objects from pre-7.6.04 AR System servers . . . . . . . . . . . . . . . . . . . . . . 156 Migrating objects from AR System server 7.6.04. . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Appendix A Migrator command-line interface 159
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 XML files for processing commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Command line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Metadata mappings and CMDB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Mapping files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Mapping types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Metadata XML document structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Metadata mappings and BMC Remedy ITSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 XML mapping documents for BMC Remedy ITSM . . . . . . . . . . . . . . . . . . . . . . . . 170 Mapping to a foreign entry ID field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Injecting data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Form mapping data options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Examples of CLI migration commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Specified form migration/comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . All Form migration/comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specified form and all filters migration/comparison . . . . . . . . . . . . . . . . . . . . . . Specified CMDB migration/comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . All CMDB migration/comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . All object migration/comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployable applications instruction file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CMDB instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data instruction file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multiple migrations or comparisons using one instruction file . . . . . . . . . . . . . . Package file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Differences report as input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix B Menus and shortcut keys
174 174 174 174 175 175 175 176 176 177 178 178 181 182 182 183 183 184 185 185 187 188 188 189 189 191 193
Main menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edit menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . View menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Servers menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Objects menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migrate menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Script menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tools menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Window menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shortcut keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migrator Glossary Index
Contents
10
Preface
IMPORTANT
The compatibility information listed in the product documentation is subject to change. See the compatibility matrix at http://www.bmc.com/support for the latest, most complete information about what is officially supported. Carefully read the system requirements for your operating system, especially the patch requirements. Welcome to BMC Remedy Migrator, version 7.6.04, the tool that helps you synchronize your BMC Remedy Action Request System (AR System) development and production servers. This administrators guide describes the tasks involved in installing and using Migrator.
Migrator documents
This guide includes provides instructions for installing and using Migrator with AR System. Unless otherwise noted, online documentation in Adobe Acrobat (PDF) format is available on the Migrator product installation DVD and on the Customer Support site (http://www.bmc.com/support). You can access online help for Migrator through the Migrator Help menu. The BMC Remedy Migrator Release Notes provide information about compatibility, how to contact Customer Support, and descriptions of open issues.
AR System documents
The following table lists documentation available for AR System 7.6.04. Unless otherwise noted, online documentation in Adobe Acrobat (PDF) format is available on AR System product installation DVDs, on the Customer Support website (http://www.bmc.com/support), or both.
Preface 11
BMC Remedy Migrator 7.6.04
You can access product help through each products Help menu or by clicking Help links.
NOTE
The AR System product help has not been updated for version 7.6.04. The help topics still apply to version 7.6.03. For the most recent content, refer to the PDF documentation.
Title Concepts Guide1 Description Audience
Overview of AR System architecture and features; includes Everyone information about add-on products that extend AR System functionality and a comprehensive glossary for the entire AR System documentation set. Instructions for installing AR System. Information about the development of AR System applications, including an introduction to using BMC Remedy Administrator. Administrators Developers2
Installation Guide Introduction to Application Development with BMC Remedy Developer Studio
Form and Application Objects Information about AR System applications and their user Guide interface components, including forms, fields, views, menus, and images. Workflow Objects Guide
Developers
Information about the AR System workflow objects (active Developers links, filters, and escalations) and how to use them to create processes that enforce business rules. Information about configuring AR System servers and clients, localizing, importing and exporting data, and archiving data. Administrators
Configuration Guide
BMC Remedy Mid Tier Guide Information about configuring the mid tier, setting up applications for the mid tier, and using applications in browsers. Integration Guide
Administrators
Instructions for integrating AR System with external Administrators/ systems by using web services, plug-ins, and other products, Developers/ including LDAP, OLE, and ARDBC. Programmers3 Information about monitoring and maintaining AR System Administrators/ and AR System applications to optimize performance and Developers/ solve problems. Programmers Database administration topics and rules related to how AR System interacts with specific databases; includes an overview of the data dictionary tables. Information about implementing a distributed AR System server environment with BMC Remedy Distributed Server Option (DSO). Administrators/ Developers/ Programmers Administrators
Optimizing and Troubleshooting Guide Database Reference
BMC Remedy Distributed Server Option Guide BMC Remedy Flashboards Guide C API Reference C API Quick Reference
Instructions for creating, modifying, and administering Administrators/ flashboards to display and monitor AR System information. Developers Information about AR System data structures, C API function calls, and OLE support. Quick reference to C API function calls. Programmers Programmers
12
AR System documents
Title Java API
Description
Audience
Information about Oracle Java classes, methods, and Programmers variables that integrate with AR System. For the location of the JAR file containing this online documentation, see the information about the Java API in the Integration Guide. Information about Java classes, methods, and variables used Programmers to write plug-ins for AR System. For the location of the JAR file containing this online documentation, see the information about plug-ins in the Integration Guide. Instructions for configuring and using BMC Remedy Email Administrators Engine. Descriptions of AR System error messages. Administrators/ Developers/ Programmers Everyone Administrators
Java Plug-in API
BMC Remedy Email Engine Guide Error Messages Guide
Master Index BMC Remedy Approval Server Guide Release Notes Release Notes with Known Issues BMC Remedy User Help BMC Remedy Administrator Help
Combined index of all books. Instructions for using BMC Remedy Approval Server to automate approval and signature processes in your organization. Information about new features, compatibility, and international issues.
Everyone
Information about new features, compatibility, international Everyone issues, installation planning, and open issues. Instructions for using BMC Remedy User. Instructions for using BMC Remedy Administrator to develop AR System forms, workflow objects, and applications. Instructions for using BMC Remedy Alert. Instructions for configuring BMC Remedy Mid Tier. Instructions for using AR System forms in browsers. Everyone Developers
BMC Remedy Import Help Instructions for using BMC Remedy Import. BMC Remedy Alert Help BMC Remedy Mid Tier Configuration Tool Help BMC Remedy Browser Help
Administrators Everyone Administrators Everyone Administrators / Developers Administrators / Developers
BMC Remedy Migrator 7.6.04 Outlines procedures for installing BMC Remedy Migrator, BMC Remedy Migrator Guide setting options, and performing migration tasks. BMC Remedy Migrator online help Procedures for setting BMC Remedy Migrator options and performing migration tasks.
BMC Remedy Encryption Provides an overview of the BMC Remedy Encryption Administrators Security 7.6.04 BMC Remedy Security products and explains how to install and configure Encryption Security Guide them. The full title of each guide includes BMC Remedy Migrator 7.6.04 (for example, BMC Remedy Migrator 7.6.04 Concepts Guide), except the BMC Remedy Migrator Guide and BMC Remedy Encryption Security Guide. 2 Application developers who use BMC Remedy Administrator. 3 C and Java programmers who write plug-ins and clients for AR System.
1
Preface 13
14
Chapter
Overview of BMC Remedy Migrator

This section provides an overview of BMC Remedy Migrator and the migration process. The following topics are provided: How Migrator works (page 16) How Migrator migrates (page 17)
Chapter 1
15
How Migrator works

If you have two or more servers in your AR System environment, you might need to transfer or synchronize definitions or data between servers. Migrator automates the process of transferring objects and data from one source (server or file) to another. For example, you can develop workflow applications on a development server (source) and use Migrator to transfer them to a production server (destination), ensuring the integrity of all migrated changes. Before Migrator, you had to remap objects and wait for the export of data to move objects or data between servers or files. No clients could connect while these changes were being made. With Migrator, you can migrate objects and data to and from servers quickly, while still having all clients connected and running. Migrator checks for the integrity of objects, such as groups, active links, forms, and so on. It migrates only those objects that have changed after the initial migration. Migrator can migrate AR System objects and data to and from the same server, from one server to another, or to many servers. It can also migrate from a server to a file, from a file to a server, or a file to a file, and can migrate data from one form to another as well as to a file. Migrator integrates with AR System through existing application programming interfaces (APIs) and requires no additional integration work. You can install Migrator on a client workstation and run it independently of AR System. The APIs handle all communication between Migrator and AR System servers.
Figure 1-1: Migrator and AR System server integration
In addition to server objects, Migrator can transfer data entries from one or more AR System forms. You can select single, multiple, or searched sets of data. You can migrate data immediately or save your migration in a script to be run later.
16
How Migrator migrates

You can perform migrations using either of two methods: immediate migrations or scripted migrations. These migrations are discussed in detail in Chapter 6, Preparing to migrate. Immediate migrations run in Migration mode. Scripted migrations run in Scripting mode. In this mode, you create scripts that you can save, schedule, and reuse. You can also use the Before and After commands to run a program before or after the script executes.
Source and destination servers

With Migrator, you connect to one or more AR System servers and then choose a source and destination for the objects, fields, or data you are migrating. This guide refers to two server types: A source server, where you modify or update your applications that are in development. A destination server, where users work with the current versions of your applications that are in production.
NOTE
During a migration, the source server should show no impact in performance. Impact to the destination server can vary from minimal to heavy, depending on the number of changes being made, the size of the objects, server speed, network bandwidth, and traffic.
The migration process

To migrate objects, you select the objects you want to migrate and start the migration using menu commands or by dragging the objects to the destination server. A migration consists of the following steps:
Step 1 Migrator packages the selected objects. Step 2 Migrator expands the package and looks for join forms, table fields in forms,
related objects, and required menus.

Step 3 Migrator produces a migration results file. Step 4 The migration begins.
Migrator migrates the objects in a specific sequence (see Sequencing objects during a migration on page 18), and then generates a migration result report.
Chapter 1
17
Figure 1-2: Migration process

Start
Retrieve Object to be Migrated from Result File
Compare Source and Destination
Destination
Different or Missing? No Is Source Missing? No Update Result File
Is
Yes
Migrate Object 1. Create if missing 2. Update if different
Yes
Mark for Deletion/Disable
Yes
Are there more Objects to Migrate?
No
Deletion/Disable Marked Objects
Stop
When a migration begins, Migrator retrieves the next object from the results file and compares the source object to the destination object, if any. Based on the results, Migrator performs the following actions: Creates the object, if it is missing, on the destination server. Modifies the destination server if the object is different from what is on the source server. For Form and Related migrations, Migrator performs the following actions: Marks the objects to delete or disable if they are not in the source server. Deletes or disables all marked objects (active links, filters, or escalations) that are on the destination server.
Sequencing objects during a migration

Migrator uses a predefined sequence for migrating objects. For Regular, Join, Display-only, View, and Vendor forms, Migrator looks for the views, then the fields, for each form, repeating the process if necessary before it moves on to the next object type in the sequence. Table 1-1 on page 19 outlines the sequence of object migrations.
18
Table 1-1: Object migration sequence Sequence 1 2 3 Object Groups Roles Regular forms: 3a Views 3b Fields 4 Join forms: 4a Views 4b Fields 5 Display-only forms: 5a Views 5b Fields 6 View forms: 6a Views 6b Fields 7 Vendor forms: 7a Views 7b Fields 8 9 10 11 12 13 14 Fields Views Images Menus Active Links Filters Escalations 22 23 24 25 26 27 28 Filter guides Web Services Packing lists Applications Plug-in modules Plug-in definitions Data 21 Flashboards alarms 20 Flashboards 19 Flashboards data sources 18 Sequence 15 16 17 Object Active link guides Distributed Server Options: DSO maps Distributed Server Options: DSO pools Flashboards variables
Chapter 1
19
AR System object and field migrations

Migrator migrates the following AR System objects and fields.
Objects
AR System objects that you can migrate include: Forms (including different views of forms) Workflow objects (active links, filters, escalations, active link and filter guides), including locked objects Applications, including deployable applications Packing lists Web services Menus Groups Roles Distributed maps Distributed pools Data Views Flashboards (variables, data sources, Flashboards, and Flashboards alarms)
System objects
Plug-in definitions Plug-in modules
20
Fields
AR System fields that you can migrate include: Data fields (character, diary, integer, real, selection, date/time, date, time, decimal, attachment, attachment pool, currency) Control fields (buttons, menus, toolbar icons) Trim fields (lines, boxes, text) Table fields (client side or server side), including tree view and table views Page fields Flashboards fields Alert List fields Application List fields View fields Result List fields Data visualization fields
Chapter 1
21
22
Chapter
Installing and starting Migrator

This section describes how to install, start, and uninstall Migrator. The following topics are provided: Memory usage and disk space requirements (page 24) Considerations for installation (page 24) Installing Migrator (page 25) Starting Migrator (page 26) Uninstalling Migrator (page 26)
Chapter 2
23
Memory usage and disk space requirements

Before installing Migrator, make sure that your computer has the following memory and disk space: Memory512 MB minimum; 1 GB recommended. Disk spaceAt least 1 GB free space, 5 GB recommended. If the option to delete database and dependency files is disabled (which means that these files are retained), you might need more disk space (between 5 GB and 10 GB), depending on the size of the files you are using.
Considerations for installation

Follow these guidelines when installing Migrator: You must have administrator privileges for the machine on which you want to install Migrator. You cannot install two different versions of Migrator under the same user name. If you need to install different versions on the same server, install each version under a different user name and in a separate directory to avoid compatibility problems between versions. When you are installing a new version of Migrator, do the following: Back up your existing installation files. Uninstall the existing version of Migrator. Install the new version. If you want to install an older version of Migrator after having installed and uninstalled version 7.6.04, you must manually delete the directories and files for the previous installation. If you are installing Migrator on the Windows Vista platform, have Migrator create the directories for backup, cache, result, and script files under the User (Home) directory, or update the permissions for these folders so that the files can be accessed by your users when running Migrator.
24
Installing Migrator
Installing Migrator
Use the following procedure to install Migrator.
NOTE
You must have administrator privileges for the machine on which you are installing Migrator.
To install Migrator
1 Shut down all other running applications before you start. 2 Insert the Migrator DVD into your DVD drive.
If the Migrator setup program starts a few seconds after inserting the disk, skip to step 4 or follow the on-screen instructions.
3 From your DVD drive, double-click migrator.exe.
A progress bar appears as the files are extracted.

4 Click Next when you see the Welcome screen. 5 In the License Information dialog box, read the license agreement, and click Agree.
For more information about licensing for Migrator or for your AR System installation, see the BMC Remedy Migrator 7.6.04 Release Notes.
6 Perform either of the following actions:
Click Next to accept the default installation directory. Click Browse to select another installation directory.
7 Click Next. 8 Click the check box to place the Migrator program icon on your desktop, and click
Next.
9 Review the installation options you selected; if they are correct, click Install to
begin the installation.
NOTE
You might see validation warnings related to the mfc71.dll, mfc71u.dll, and msv1_0.dll2 files. These warnings can be ignored because they do not affect the ability of Migrator to be installed.
10 When installation is complete, click Done. (Optionally, you can click View Log
display the installation log.) To begin using Migrator, you must restart your computer.
Chapter 2
25
Starting Migrator
After you have installed Migrator, the Windows Start menu displays the Migrator icon in the program folder that you selected during the installation process.
To start Migrator
1 If you created a shortcut on your desktop during installation, double-click the
Migrator icon. Or, select Migrator from the Start menu.

2 Obtain a license from BMC Customer Support.
You will need a license for the AR System server if you do not already have one. For information about contacting BMC Customer Support, see the BMC Remedy Migrator 7.6.04 Release Notes.
Uninstalling Migrator
Uninstall Migrator from the Control Panel on Windows.
To uninstall Migrator
1 Close Migrator. 2 Choose Start > Settings > Control Panel. 3 From the Control Panel, select Add/Remove Programs. 4 From the Currently Installed Programs list, select BMC Remedy Migrator 7.6.04,
and click Remove.

5 In response to the prompt, click Yes to begin the uninstall process. 6 When the uninstallation is done, click OK to close the confirmation message box.
26
Chapter
Licensing and logging on to Migrator

This section provides an overview and instructions for licensing and logging on to BMC Remedy Migrator. It describes how to add and manage server accounts, license those accounts, and use the licensed accounts to log in to a server. The following topics are provided: Migrator licenses (page 28) Adding and managing server accounts (page 28) Licensing and managing servers (page 30) Logging in to an AR System server (page 32)
Chapter 3 Licensing and logging on to Migrator
27
Migrator licenses
You must obtain a separate license key for each AR System server that you want to access with Migrator. Migrator does not function on a server that is not licensed. For information about licensing AR System servers, see the Configuration Guide. After you start Migrator, open the Login dialog box. During the login process, you have two choices to make: Do you need to add a server? If you do, you must add the server from the Accounts dialog box. Choose Tools > Accounts to open the Accounts dialog box. If the server is not listed, you must add it to the list. For information about adding a server, see Adding and managing server accounts. If the server is listed, you can continue the login process. Is the AR System server you want to use licensed? If a listed server is not licensed, you must license it. For more information about licensing AR System servers, see the Configuration Guide. If a listed server is already licensed, you can select it and log in.
NOTE
If you need to add a server or a license, the Login dialog box appears for the first session. After the first session, if Migrator finds the correct user information, the Select Server dialog box appears instead of the Login dialog box.
Adding and managing server accounts

Using the Accounts dialog box, you can add, modify, or delete users and limit access to users from the available servers. Any changes you make in the Accounts dialog box apply simultaneously in Migrator, BMC Remedy Alert, and BMC Remedy User. After you log in to Migrator and open the Accounts dialog box, either a check mark or an X appears next to each server name. A green check mark indicates you can connect to the server. A red X indicates you cannot connect to the server, even if the server has been licensed. The following steps show how to manage your server accounts as an administrator.
28
Adding and managing server accounts
To add and manage server accounts

1 Choose Tools > Accounts to open the Account dialog box, which shows the servers
that have been added. If the Accounts menu selection is unavailable, you must provide login information before proceeding.
Figure 3-1: Accounts dialog box
2 In the Account dialog box, perform any of the tasks outlined in Table 3-1: Table 3-1: Adding and modifying server information To Add a new server Do this Click Add, and enter a server name. If the server you are adding is a preference server, enter the appropriate port numbers in the slide-out dialog box that appears at the right. Select the server, click Modify, and make the appropriate changes. Select the server, and click Delete. Click User Manager. Click Add to add a new user, or select a name in the Users list and click Modify to modify the user account.
Note: For each user to have their own server list, you
Modify an existing server Delete a server Add or modify the Users list
must include a specific home directory for that user in the directory path. View port columns for firewall Select Advanced Server Properties. Select a server and support click a column and type a port number or private server number: AR TCP Port represents the port number of the AR System server. AR RPC # represents the program number of the specified AR System server. This number allows you to connect to a private server behind the firewall.
Chapter 3 Licensing and logging on to Migrator
29
WARNING
You can set different TCP ports for each server, but if the ARTCPPORT environment variable is defined, Migrator uses the port defined by the variable for all servers while ignoring the settings in the Accounts dialog box.
3 Click OK.
The new login information is not applied to your current session. You must log in again before your changes take effect, or proceed to one of the following actions: If the server you added needs a license, or does not yet exist in the Server Licenses dialog box, see the Configuration Guide for licensing information. If the server you added has already been licensed, and has been added to the Server Licenses dialog box, continue to Logging in to an AR System server on page 32.
Licensing and managing servers

One AR System server license is issued for each AR System server you want to work with using Migrator. There is no limit to the number of clients on which you can install Migrator. For more information about licensing AR System servers for use with Migrator, see the Configuration Guide.
Adding a licensed AR System server in Migrator

When you have logged into Migrator, you can add a licensed AR System server.
To add a licensed AR System server in Migrator

1 In Migrator, choose Tools > Licenses to open the Server Licenses dialog box. Figure 3-2: Server Licenses dialog box in Migrator
2 Click Add.
30
Licensing and managing servers
3 Select a server from the list, and click OK.
If the server is properly licensed, it is added to the list in the New Licenses section of the Server Licenses dialog box.
4 Click Done.
Continue to Logging in to an AR System server on page 32 for procedures on how to log in to a server. For information about removing, importing, purging, or viewing the license, see Managing existing Migrator licenses.
Managing existing Migrator licenses

The following sections explain how to work with existing Migrator licenses.
Transferring licenses to other AR System servers

Each AR System server must have its own Migrator license. If you transfer an AR System server license from one server to another, you must remove the Migrator license from view in the old server, and add it to the new server. Information about server licenses is stored in the AR System Licenses form, which can be accessed from BMC Remedy User. For more information about transferring AR System licenses to other servers, see the Configuration Guide. For information about removing a deleted AR System server from view in Migrator, see Removing an AR System server and its Migrator license from view. For information about adding a licensed server in Migrator, see Adding a licensed AR System server in Migrator on page 30.
Viewing Migrator license details

To view Migrator license details for a server, choose Tools > Licenses.
Removing an AR System server and its Migrator license from view

Removing a server and its Migrator license from the servers list makes the server inaccessible to Migrator, but it does not remove the license from the server (or from the local Migrator license file if the server is version 4.5.2 or older). It only removes the server from the local machine and it can no longer be viewed.
To remove a server from view

1 In Migrator, choose Tools > Licenses. 2 In the Server Licenses dialog box, select a server, and click Remove. 3 In the message box, click Yes to confirm the license removal, or No to keep the
license in view.
4 After confirming the server removal, indicate whether you want to remove the
server from the local cache.

Chapter 3 Licensing and logging on to Migrator 31
By doing this, you can remove servers from the Server Licenses list, but still keep some or all of the servers cached.
NOTE
If you add a removed server back to the servers list later, the definitions are retrieved the first time you log in to the server.
Logging in to an AR System server

The first time you log in to an AR System server, Migrator retrieves all object definitions from that server. This retrieval builds a cache on the client machine in the Migrator directory. The first retrieval can take some time, but makes it faster and easier to access those definitions in the future.
NOTE
By default, caching is disabled. See Cache file management on page 42 for information about managing the cache process.
Preference servers
You can log in to a preference server, which sets the behavior and display characteristics of each client. These preferences can be stored locally on the client machine, or centrally on a designated preference server. Centralized preferences make the same settings and customizations available when logging in to multiple machines. Local preferences can be used when no preference server is designated or available. Regardless of whether centralized or local preferences are used, multiple users can use the same client machine with individual preferences and customizations. Only AR System 5.0 or higher servers can be used as preference servers. If no preference forms are found on your AR System server, a text box appears asking if you want to create the preference server forms. The Migrator Preference form is then created to set up a preference server. For more information about preference servers, see the Configuration Guide and BMC Remedy User help.
NOTE
If you are logged in to two computers simultaneously and make a change on one by changing an option or licensing a server, you do not automatically see the new options or licenses on the other computer. You must log in again to the preference server to view the new changes.
32
Logging in to an AR System server
Authentication
Administrators can have greater control by verifying user authentication using an authentication server. With an authentication server, Migrator checks to see if a user is a registered user. If a match is found, the user definition and permissions specified in the matching user record are used. If no match is found, the authentication is stopped and the user is treated as a guest user. If authentication is not enabled in AR System, Migrator cannot authenticate a user. See the Configuration Guide.
Logging on and opening a server window

Migrator provides two methods by which you can log in. The following procedures outline each method. For information about setting login options, see Overview on page 60.
To log in to Migrator
1 Perform either of the following actions:
If you are not already logged in, choose File > New Server Window to display the Login dialog box and open a new server window. To log in to Migrator without opening a server, choose Tools > Login. For example, you must be logged in to Migrator to refresh a previously saved differences report or to add licensed servers.
NOTE
Make sure that the server you want to log in to is licensed. For See Adding and managing server accounts on page 28 and Licensing and managing servers on page 30.
2 In the Login dialog box, enter your AR System user name and password for that
server, and click OK. By default, the Migrator login window shows the User Name and Password fields only. By clicking the Options button, you can also display the Preference Server and Authentication fields. The first time you use Migrator, both the User Name and Password fields are empty. The next time you log in, Migrator remembers the last user name and tries that information first (unless it has been changed) when logging on to a server.
3 (optional) To log in to a preference server, click the Options button to display the
Preference Server field. Then, enter or select the preference server name.
4 If required, type your authentication server in the Authentication text box. 5 To add, modify, or delete an existing server or manage usage of a server, click the
Accounts button. For information about the Accounts dialog box, see Adding and managing server accounts on page 28.
Chapter 3 Licensing and logging on to Migrator 33
6 Click OK. 7 In the Select Server dialog box, select the server you want to use, and click OK.
The server window appears, showing the AR System objects residing on the server you logged in to. Then, the Retrieving Objects window appears and lists the objects that Migrator is opening for the server.
NOTE
Depending on the number of objects the server has stored, opening a server can take some time while objects are being retrieved and cached. You can cancel the cache process by clicking the Cancel button in the Retrieving Objects window.
8 (optional) To open another server window, repeat this procedure.
By logging on to each server individually, you can specify a different user name and password for each server.
34
Chapter
Navigating in Migrator
This section describes viewing and using windows, and synchronizing views in BMC Remedy Migrator. It explains how to use the migration status pane and how to customize menus, toolbars, and columns. It also describes how server windows work, how to display or remove objects and forms in server windows, and how to export and convert definition and XML files. The following topics are provided: Navigating in Migrator (page 36) Using the migration status pane and tabs (page 38) Customizing Migrator (page 39) Working with server windows (page 41) File types used in migrations (page 56)
Chapter 4
35
The main Migrator window displays tools and information that control viewing server or report information and viewing synchronized objects across views. You can navigate in Migrator using the mouse or shortcut keys, or by customizing the main menu or toolbars. For information about menus, toolbars, and shortcut keys, see Customizing Migrator on page 39.
The main Migrator window

When you open Migrator without logging on to a specific server, the main window is empty. When you open a server window, you can display object details, migration status details, reports, files, and scripts.
NOTE
Not all menu items or toolbar buttons are accessible until you log in to a server and open a file.
Figure 4-1: Migrator main window
36
The Migrator main window includes the following areas: Title barDisplays the currently open server. Main menu bar and toolbarsAppears at the top of the window. For information about customizing the main menu bar and toolbars, see Customizing Migrator on page 39. For a detailed description of the main menu bar and toolbars, see Appendix B, Menus and shortcut keys. Left pane (navigation pane)Displays lists of objects available for the currently open server. Object lists can be displayed in two formats: Object type tabgroups objects in folders by how they are named. See Displaying objects in the Object Type view on page 43. Prefix tabLists objects by folders named according to how they are organized, for example, a packing list. Some objects might be grouped under folders with labels using initials. See Displaying objects in the Prefix view on page 44. Right pane (object list view)Displays the server and report windows, with details for the currently selected object or report. See Types of object details on page 48. Status barAppears at the bottom of the main Migrator window. It displays the following information: Messages about the status of Migrator tasks The name of the user currently logged in to Migrator Help for menu commands and toolbar buttons To show or hide the status bar, choose View > Status Bar. In addition, a migration status pane can be displayed at the bottom of the window when you choose View > Migration Status. This area displays migration in progress and enables you to control, monitor, and store migrations. The status pane is described in Using the migration status pane and tabs on page 38.
Viewing information in Migrator windows

In the left pane of the server window, you can use either the Object Type or Prefix tab to select Backup files, Script files, and Migration Report Result files. To view these files, save them in the directories specified in Migrator options. See Directory options on page 77. To locate a file in a different directory, choose Tools > Options > Directories. To display the contents of a file, select that file in the right pane. Object lists appear within windows in ascending order by name when you open a secondary window or when you select a new object type.
NOTE
Nonalphabetical characters are sorted individually before alphabetical characters. For example, a dash (-) is sorted before a colon (:).
Chapter 4
37
Viewing synchronization within windows

To synchronize the window views, select an object in any open server or report window and choose View > Synchronize Views. If that object is located in the server or report, every open view displays the selected object.
Using the migration status pane and tabs

You can use the migration status pane and status tabs to view and control migrations. From the status pane, you can watch the progress of a migration and use the status tabs to monitor a migrations status. You can also control active migrations and view information about active, completed, and scripted migrations.
Migration status pane

The migration status pane at the bottom of the Migrator window displays an instant view for monitoring all your migration activity (see also Monitoring migrations on page 81).
To show or hide the migration status pane

Choose View > Migration Status.
Figure 4-2: Migration status pane
To undock and relocate the migration status pane

Select the outer edge of the pane and drag it to another location. The following table outlines the information you can view in the migration status pane:
Table 4-1: Information in migration status pane (Sheet 1 of 2) Field Name Status What it does Lists the script name or migration name. Shows the status of an interrupted or completed migration, and how many passes of this migration have occurred. For example, if this is the first instance of this migration, a migration is being repeated once, the message Migrating pass 1. This enables you to see how many times a specific migration occurred.
38
Customizing Migrator
Table 4-1: Information in migration status pane (Sheet 2 of 2) Field Type Progress Start Time End Time Source Destination Description What it does Designates a scheduled or immediate migration. Indicates the completion percentage for a migration. Indicates the actual start time for a migration. Indicates the actual end time for a migration. Lists the name of the source server. Lists the name of the destination server. Displays a brief description of the migration.
Migration status tabs

The migration status tabs show you an instant view of all your migration activity. You can view immediate, scheduled, or completed migrations, depending on which status tab you select. Click each tab to show the status of the following types of migrations: AllShows all immediate and scheduled migrations in progress. ImmediateShows all immediate migrations that are in progress, queued, or interrupted. ScheduledShows all scheduled migrations, as indicated by migration scripts. CompletedShows all completed migrations. To display the migration statistics in a migration result report, click the Completed tab and then doubleclick a migration listing.
Customizing Migrator
You can customize the Migrator main menu, toolbars, and columns in windows.
Customizing the main menu and toolbars

To rearrange the items on the main menu, drag the menu items to a new location on the menu. To remove toolbar buttons from the main toolbar, drag the buttons down into the main window. To change the look of the toolbars, create a new toolbar, or to change Migrators default toolbars and main menu, use the following procedure:
Chapter 4
39
To customize the main menu and toolbars

1 Choose Tools > Customize. 2 In the Customize dialog box, perform any of the following actions in the Toolbars
tab (Figure 4-3 on page 40): Click a toolbar name to select or clear that toolbar. Click Show Tooltips to select or clear the help text that is displayed when you point to a toolbar button. Click Cool Look to select or clear the shadow effect around the toolbar buttons. Click Reset to restore Migrators default toolbars and main menu. Click New to create a new user-defined toolbar. Then, type in the new toolbar name and click OK, making sure to select the Toolbars tab. The new toolbar appears on your screen empty.
Figure 4-3: Customize dialog boxToolbars tab
3 To add toolbar buttons or menu commands to the default view of the main
window, click the Command tab (Figure 4-4) and select a category, and then drag the toolbar buttons or menu items to your new toolbar.
40
Working with server windows
Figure 4-4: Customize dialog boxCommand tab
4 When you have finished making changes, click OK.
Rearranging window columns

You can rearrange the column order in a server window, a Form Detail view, and a Script view for a chosen tree item.
To rearrange column order in a window

1 Select an object in the left pane of the server window. 2 Drag and drop the columns to a new location.
The next time you open the server window, Migrator remembers your changes and displays the columns in their new locations. You can also rearrange the columns in the migration status pane.

Use server windows to perform most migration tasks. When you open a server window, functions in the main menu applicable to the task you are performing are available. Unavailable functions are either not necessary for the task, or you have not selected the items that activate them. You can have multiple server windows open in the Migrator main window.
Chapter 4
41
Opening a server window

To open a server window
1 Choose File > New Server window. 2 From the list, select a server. Figure 4-5: Opening a new server window
List of licensed servers
Migrator performs the following actions: Creates cache files by retrieving objects for the server and copying them to your computer. A cache progress window shows the objects that are being retrieved. You can cancel the cache by clicking the Cancel button. Lists server objects in the left pane of the server window. You can select how objects are viewed by clicking either the Object View or Prefix tabs. Displays details for a selected object or report. You can view objects by form, by application, or by workspace. See Displaying objects in a server window on page 43.
Cache file management

When you open a server window for the first time, Migrator generates the following cache files in the Migrator directory on your hard drive: A server cache, where workflow support files are located. A database information cache for the server, which lists all the required AR System object information. This information is used by the list views for both the server windows and the form detail windows. A dependency file cache for the server, which is used to generate upward and downward dependency information. You can specify the directory in which to store cache files. See Directory options on page 77.
42
Although initial caching takes time because Migrator copies all the objects from the server to your computer and builds the database, cache files ultimately save time and lessen the load on the server.
Refreshing and updating cached objects

To recache your computer after the initial caching, choose View > Refresh (or press F5). Whenever you reopen a server window, Migrator updates cache files, taking less time because only changed objects are cached. Migrator also updates the object type cache when you switch object types in the left pane of the server window. For example, when you go from Forms and click Filters, Migrator updates filters. When you go from Filters and click Forms, Migrator updates forms. Migrator also updates the cache file during a migration. To view the changes in the cache after a migration, refresh your display by pressing F5. You can turn automatic caching on or off. To do so, choose Tools > Options, and then click General in the left pane to display the caching options (see Overview on page 60).
NOTE
Migrator provides an option to keep or delete the database and dependency files generated with .migrator files. See Overview on page 60.
Space limitations on caching

During a cache process, Migrator warns you when less than 10 MB of space is available on your computer. When you see this warning, stop the caching process, create more hard drive space, and then cache again.
WARNING
If you rename any object on a server where the cache is enabled, you must open that server in Migrator and update the cache before making any more changes to that object. This is required for the cache to recognize the object changes.
Displaying objects in a server window

When you log in to a server, the objects for that server are displayed in a server window.
Displaying objects in the Object Type view

The Object Type view lists objects by their type. It also lists backup, script, and result files. If no objects exist on the server for an object type, that object type is not listed.
Chapter 4
43
Figure 4-6: Object Type view
To view objects by type, click the Object Type tab in the left pane of the Migrator main window. To display all objects of a specific type, select the type from the list. The objects of that type are listed in the right pane.
Displaying objects in the Prefix view

The Prefix view groups objects into folders, based on categories or on naming conventions you define using colon (:) delimiters. For example, all objects named MB objectName appear in a folder called MB. Objects named MB:Sub1:objectName appear in a Sub1 folder under the MB folder. In the Name column, only the objectName portion of the object name is displayed.
Figure 4-7: Prefix view
To view objects by prefix, click the Prefix tab in the left pane of the Migrator main window. To view a set of objects, click the folder for the objects you want to view.
44
Viewing objects by form

You can view the list of objects associated with each form.
Figure 4-8: Viewing objects by form
To display objects by form

1 Choose View > By Form.
The By Forms dialog box appears. By default, All Forms is the selected view option, and the list of available forms is disabled.
2 In the View Option area, click the option button for the types of forms you want to
view, and click OK. If you select Forms with Prefix, the Prefix field becomes enabled. Enter a prefix. If you select Selected Forms, use the Add, Remove, Add All, or Remove All buttons to create a list of the forms you want to view. To select more than one form, hold down the Ctrl or Shift key as you make your selections.
3 In the left pane of the server window, click Forms to display the forms you
selected. Migrator displays the forms according to the view options, and all the objects related to those forms.
Viewing form details

You can double-click a form to view its details (or click once and press Enter). In addition, you can view the details of forms (fields, views, and data) by rightclicking a form in the right pane and then choosing Form Details. This action displays the Form Detail tree view.
Chapter 4
45
Figure 4-9: Form detail list showing field details
To display the details of a selected form

1 In the left pane of the server window, under AR System Objects, click Forms. 2 In the right pane of the server window, select a form. 3 Choose View > Form Details.
The details for the selected form appear in the right pane of the Migrator window. The header bar shows the name of the form and the number of objects being viewed for that form. From the Form Detail window, you can migrate fields, views, data, and other objects related to that form.
NOTE
When dragging an active link, filter, escalation, and so on from a Form Detail window to another Form Detail window, the name of the form to which the object is linked is not changed to the destination form name. Only fields and views are created on the destination form. Also, data with fields and views are the only objects migrated to the destination Form Detail view.
46
Viewing objects by application

You can view the list of objects pertaining to an application.
To view objects by application

1 Choose View > View by Application. Figure 4-10: View by Applications dialog box
2 In the By Application dialog box, select a local or deployable application.
For more information about local and deployable applications, see the Form and Application Objects Guide. The objects for the selected application are listed in the right pane of the server window.
Viewing objects by workspace

A workspace allows you to limit the objects displayed in a window to only those objects that are associated with a particular packing list or application. When you create new objects in the context of the workspace, the objects are added to the packing list or application. For more information about workspaces, see the Form and Application Objects Guide.
To view objects by workspace

1 Click in the server or file window whose workspace objects you want to display.
Make sure that the All Forms option is selected in the By Form dialog box; otherwise, the menu option is disabled. See Viewing objects by form on page 45.
2 Choose View > By Workspace.
The By Workspace dialog box appears. If no workspace has been created on this server, the message No current record appears.
3 Select an application or packing list from the list, and click OK.
Chapter 4
47
In the server window, the object category reflects the options selected in the By Workspace dialog box. For more information about applications, see the Form and Application Objects Guide.
Types of object details

The right pane of the server or file window (Figure 4-11) displays columns of objects and details about each object listed. The following sections list the items listed for each object type.
Figure 4-11: Details for selected objects
Forms
Table 4-2: Items listed for forms (Sheet 1 of 2) Item Form Name Type Access Point Description The name of the object. For forms, the type of form, such as Join or Regular. Whether an access point is available for the object. You can identify specific forms and guides in deployable applications as access points, or points of integration, for use with other deployable applications. For more information about deployable applications, see the Form and Application Objects Guide. Whether any new entry points are available for the object. A new entry point can be clicked to start a task, such as creating a request. Entry points are listed in the Application List field on the home page. For more information about home pages, see the Form and Application Objects Guide. Search Entry Point Owner Whether any search entry points are available for the object. A search entry point can be clicked to start a search. The name of the user who created the object.
New Entry Point
48
Table 4-2: Items listed for forms (Sheet 2 of 2) Item Timestamp Last Changed Lock State Description The date and time on which the object was created or changed. The name of the user who last updated the object. The locked state of the object. Locking allows application developers to protect workflow objects that are not designed for or intended to be customized, by preventing them from being modified or even viewed. An object can have one of the following locked states: NoneAllows users to view and modify the object. Read-onlyPrevents users from modifying the object, but allows them to view its details. HiddenMore restrictive lock that prevents users from viewing details of a locked object, including in Migrator differences and dependency reports. For more information about locked objects, see the Form and Application Objects Guide. Archive Whether archiving is enabled or disabled for a form. You can use the data archiving feature in AR System to set up options for backing up of data in forms. Archive forms can be migrated if they exist on the destination. For more information about data archiving, see the Configuration Guide. Views, Fields, Data Fields, Trim Fields, Control Fields, Page Fields, Table Fields Member A, Member B, and so on The number of fields of each type included in the form.
If this is a join form, the names of the member forms.
Active links, filters, and escalations

Table 4-3: Items listed for active links, filters, and escalations (Sheet 1 of 2) Item Name Primary Form Forms Referenced Enabled Order Execute On If Actions Else Actions Owner Timestamp Description The name of the active link, filter, or escalation. The name of the form that appears in BMC Remedy User when the application opens. The number of forms referenced. Whether this object is enabled. The execution order for this object. The action on which this object executes. The number of if actions included. The number of else actions included. The name of the user who created this object. The date and time on which this object was last changed.
Chapter 4
49
Table 4-3: Items listed for active links, filters, and escalations (Sheet 2 of 2) Item Last Changed Lock State Description The name of the user who last changed this object. The locked state of the object. Locking allows application developers to protect workflow objects that are not designed for or intended to be customized, by preventing them from being modified or even viewed. An object can have one of the following locked states: NoneAllows users to view and modify the object. Read-onlyPrevents users from modifying the object, but allows them to view its details. For more information about locked objects, see the Form and Application Objects Guide. Control Field (active links only) Focus Field (active links only) Qualification Typically a menu field or a button, which fires an active link when selected. A field on which an active link fires when the field gains focus. The text of any qualification created for this object.
Active link guides and filter guides

Table 4-4: Items listed for active link guides and filter guides (Sheet 1 of 2) Item Name Description The name of the active link guide or filter guide that appears in the server window the BMC Remedy System Administration Console. The name of the form to which the guide applies. The type of form to which the guide applies, for example, a regular form. The name of the guide that appears in the Open dialog box in Remedy User. The name of the user who created the guide. The date and time on which the guide was last changed. The name of the user who last changed the guide.
Form Name Type Label Owner Timestamp Last Changed
50
Table 4-4: Items listed for active link guides and filter guides (Sheet 2 of 2) Item Lock State Description The locked state of the object. Locking allows application developers to protect workflow objects that are not designed for or intended to be customized, by preventing them from being modified or even viewed. An object can have one of the following locked states: NoneAllows users to view and modify the object. Read-onlyPrevents users from modifying the object, but allows them to view its details. HiddenMore restrictive lock that prevents users from viewing details of a locked object, including in Migrator differences and dependency reports. For more information about locked objects, see the Form and Application Objects Guide. Description A description of the guides function.
Applications
Table 4-5: Items listed for applications (Sheet 1 of 2) Item Application Name Application Label Primary Form Primary View Owner Timestamp Last Changed Lock State Description The name for the application. The name for the application that appears in the Open dialog box in BMC Remedy User, and in the application title bar. The form that appears when the application is opened in BMC Remedy User. The view of the form that appears when the form is opened. The name of the user who created the application. The date and time on which the application was last changed. The name of the user who last changed the application. The locked state of the object. Locking allows application developers to protect workflow objects that are not designed for or intended to be customized, by preventing them from being modified or even viewed. An object can have one of the following locked states: NoneAllows users to view and modify the object. Read-onlyPrevents users from modifying the object, but allows them to view its details. For more information about locked objects, see the Form and Application Objects Guide. Application State The current production state of the application, for example, Maintenance or Test.
Chapter 4
51
Table 4-5: Items listed for applications (Sheet 2 of 2) Item Type Description The type of application, either local or deployable. Deployable applications use permissions based on roles that are specific to the application, rather than groups that are specific to the server. A description of what the application does or other pertinent information.
Description
Packing lists
Table 4-6: Items listed for packing lists Item Packing List Name Packing List Label Owner Timestamp Last Changed Lock State Description The name of the packing list. The label used, if any, for the packing list. The name of the user who created the packing list. The date and time on which the packing list was last changed. The name of the user who last changed the packing list. The locked state of the object. Locking allows application developers to protect workflow objects that are not designed for or intended to be customized, by preventing them from being modified or even viewed. An object can have one of the following locked states: NoneAllows users to view and modify the object. Read-onlyPrevents users from modifying the object, but allows them to view its details. For more information about locked objects, see the Form and Application Objects Guide. Description A description of the packing lists function.
Web Services
Table 4-7: Items listed for web services (Sheet 1 of 2) Item Web Services Name Form Name Web Services Label Owner Timestamp Last Changed Description The name of the web service. The form used as the access for the web service. The name that is displayed to users. The name of the user who created the web service. The date and time on which the web service was last changed. The name of the user who last changed the web service.
52
Table 4-7: Items listed for web services (Sheet 2 of 2) Item Lock State Description The locked state of the object. Locking allows application developers to protect workflow objects that are not designed for or intended to be customized, by preventing them from being modified or even viewed. An object can have one of the following locked states: NoneAllows users to view and modify the object. Read-onlyPrevents users from modifying the object, but allows them to view its details. For more information about locked objects, see the Form and Application Objects Guide. Description A description of the web services function.
Menus
Table 4-8: Items listed for menus Item Menu Name Type Refresh Timestamp Owner Last Changed Lock State Description The name of the menu. The type of menu, either Character, File, Search, SQL, or Data Dictionary. The condition on which the menu is refreshed, either On Connect, On Open, or on 15 Minute Interval. The date and time on which the menu was last changed. The name of the user who created the menu. The date and time on which the menu was last changed. The locked state of the object. Locking allows application developers to protect workflow objects that are not designed for or intended to be customized, by preventing them from being modified or even viewed. An object can have one of the following locked states: NoneAllows users to view and modify the object. Read-onlyPrevents users from modifying the object, but allows them to view its details. For more information about locked objects, see the Form and Application Objects Guide.
Groups
Table 4-9: Items listed for groups (Sheet 1 of 2) Item Group ID Group Name Description The unique ID for the group The name of the group.
Chapter 4
53
Table 4-9: Items listed for groups (Sheet 2 of 2) Item Group Type Category Description The permission type for the group, either None, View, or Change. The category of group, either Regular, Computed, or Dynamic. Regular groups are explicit groups that you create and to which you assign a specific list of users. Computed groups are explicit groups that you create and to which users are assigned based on a comparison of users belonging to other explicit groups. For example, you can create a computed group that includes the list of users who are members of both groups A and B, or members of group C, but not members of group D. Dynamic groups use the contents of special fields to determine group membership. For more information about groups, see the Form and Application Objects Guide.
Flashboards
Table 4-10: Items listed for Flashboards Item Flashboards Flashboards alarms Description A tool for representing data visually from AR System forms. Tools that enable sending of notifications to specific users based on a threshold value.
Flashboards variables Specify the information you want to monitor from a single form. In Flashboards, a variable represents data, such as a slice of a pie graph, a bar in a bar graph, or a line in a line graph.
Plug-ins
Table 4-11: Items listed for plug-ins Item Plug-in modules Description The names of plug-in modules. Plug-in modules are used with the arplugin process, which is a companion process to the AR System server. It loads configured plus-in modules to interface with external data. Definitions for selected plug-ins.
Plug-in definitions
Roles
Table 4-12: Items listed for roles Item Role ID Role Name Application Description The unique identifier for this role. The name of the role. The application to which this role belongs.
54
Deleting objects from servers or files

Although you typically delete objects from within BMC Remedy Developer Studio before you migrate, you can delete objects, including locked objects, from servers or files using Migrator. To make sure that nothing is affected by the deletion, Migrator runs a check on the object that you want to delete.
NOTE
Locked objects can be deleted only in blocks. Deleting one object that belongs to a locked group deletes the entire group. Deleting a locked form that is part of a join deletes the join form.
To delete objects
1 In the right pane of the server or file window, select the objects you want to delete.
Migrator cannot delete DSO (distributed server option) Map-related forms, User and Group forms, and AR System-specific forms, such as the User Preference form. Also, Migrator does not support deletion of data in .migrator forms.
2 Choose Edit > Delete.
If other objects are affected by the deletion, those objects are listed. If no other objects are affected, a confirmation message appears.
Figure 4-12: Deleting objectsimpact warning message
Objects affected by deletion
3 Confirm that you want to delete the objects:
Click Yes to delete the specified selection and continue to the next object. Click No to skip the specified selection. Click Yes to All to delete all the selected objects. Click No to All to stop the deletion.
Chapter 4
55
WARNING
If you select Yes to All, Migrator deletes every object without checking the impact of the deletion on the links to other objects.
File types used in migrations

You can work with definition files (.def), and XML (.xml) files, and Migrator files (.migrator). AR System .def and .xml files are text-based and the .migrator file is binarybased. All three types of files contain one or more AR System object definitions. Similar to the .def and .xml file, the .migrator file stores the actual support file, along with the object definitions. You can work with object definitions in the following ways: Export object definitions to AR System .def and .xml formats, which Migrator exports as server independent. Convert .def and .xml files to the .migrator format, which can be launched independently. The files are displayed in their own server windows. Migrate objects from a server to a .migrator file, a .migrator file to a server, or between .migrator files.
NOTE
When converting a .def or .xml file to a .migrator file, the original .def or .xml file remains intact. The newly converted .migrator file is stored within the same directory where the .def or .xml file is stored.
Exporting object definitions on a server

Use the following procedures to export objects on a server (including locked objects) to .def or .xml files. These procedures are useful if you want to generate AR System definition or XML files from within Migrator.
To export objects to .def or .xml files

1 In the left pane of the server window, under AR System Objects, click an object
type.
2 In the right pane, select the objects you want to export. 3 Choose Tools > Export Definitions. 4 In the Save As dialog box, enter a file name, including the .def or .xml extension,
and click Save. If the definition file already exists, you can append the existing file.
56
File types used in migrations
To export locked object definitions

1 In the left pane of the server window, under AR System Objects, click an object
type.
2 In the right pane, select the objects you want to export. 3 Choose Tools > Export Locked Definitions. Figure 4-13: Object locking information
4 In the Lock Key field of the Object Lock dialog box, enter a lock key of up to 27
characters. You must enter a valid lock key consisting of alphanumeric characters (for example, 123456 or abcxyz or abc789). You cannot use double-byte characters. Objects with the same lock key are encrypted as a group in the definition file.
5 In the Verify Lock Key field, enter the lock key again. 6 Select a lock type, either Hidden or Read Only.
Filters, filter guides, and escalations can be hidden. For more information about lock types, see Types of object details on page 48.
7 Click OK.
During the export, locked objects can exist in the same definition file with unlocked objects. Because lock information is encrypted, no one can remove a lock or change the lock type in the definition file.
8 In the Save As dialog box, enter a file name, including the .def or .xml extension,
then click Save. If the definition file already exists, you can append the existing file.
Chapter 4
57
To export deployable applications

1 Choose Tools > Export Application. 2 In the Select Application dialog box (Figure 4-14), select a deployable application
from the list, and click OK.

Figure 4-14: Selecting a deployable application for exporting
3 In the Save As dialog box, enter a file name for the application.
The default file type is .def. To export as an .xml file, select .xml from the File Type field.
4 Click OK.
The application is exported to the .def or .xml format.
Converting definition files to .migrator format

You can convert object .def and .xml files to the .migrator format for viewing files in Migrator, or for exporting .def and .xml files within Migrator. You can convert a.def or .xml file in two ways: Choose Tools > Convert Definition Files. When the Open dialog box appears, select a .def or .xml file, and click Open. A progress bar appears as the file is being converted to the .migrator file format. Choose File > Open, select a .def or .xml file, and click Open. Migrator converts the .def or .xml file to a .migrator file with the same name.
58
Chapter
Migration options
This section describes options you can set before you perform migrations. The following topics are provided: Overview (page 60) General options (page 60) Migration options (page 62) Directory options (page 77) Viewing backup, script, and results files (page 78)
Chapter 5 Migration options
59
Overview
Migrator provides six categories of options that enable you to configure how to process object and data migrations, how to manage differences between source and destination, how to display migration results, and the directories to use for backup, result, script, and cache files. The following sections describe each option category. You can reset any options you have changed back to their default values by clicking the Set Default button for that set of options.
General options
Use the General options to change when login prompts occur, when cache refreshes happen, and whether confirmation prompts should be displayed when performing migrations. To reset options to their default values, click Set Default.
Figure 5-1: General options
To select general options

1 Choose Tools > Options.
The Migrator Options dialog box appears.

2 In the Migrator Options dialog box, select General.
60
General options
3 Select the following general options:
Login/Display Login Dialog Box for Each Server ConnectionIf unchecked, enables you to log in to multiple servers using a single password. If checked, you must log in every time you open a server window or whenever a server is referenced. You can use this option to specify account settings to limit available servers. See Adding and managing server accounts on page 28. CachingAllows you to cache the local server or update directly from the server. Refresh object cache and database on type changeIf checked, refreshes objects when changing to a different object type (for example, from active links to filters). Objects in Migrator are also refreshed when you open a server and when you press F5 to refresh manually. Cache server objects locallyIf checked, refreshes objects locally. Delete associated dependency and database files for .migrator binary files when Migrator file is closedProvides the option to keep or delete the database and dependency files that are generated with .migrator binary files. Previously, these files were always deleted when a .migrator file was closed, requiring them to be regenerated each time a .migrator file was reopened. This process could be time-consumingup to 40 minutes for the largest .migrator files. Retaining the database and dependency files eliminates the recaching process and allows .migrator files to be reopened faster. Because the files are retained, this option requires additional space on the server where the .migrator files are stored. The default value is not to delete the files (option unchecked). Migration ModeIf checked, confirmation prompts are displayed when performing migrations in Migration mode, or when migrating data entries to the same form.
4 Click OK.
The differences, dependencies, and migration result report options are covered in the report chapters at the end of this guide: Chapter 9, Dependency reports Chapter 10, Differences reports Chapter 11, Migration Result reports
61
Migration options
Migration options set how migrations are performed.
Figure 5-2: Migration options
62
Migration options
You can select the following migration options: Multiple-threadSpecifies options for using multiple threads during migrations. Required ObjectsSpecifies whether to migrate required menus, table field forms, join form members, Flashboards variable and data source objects, and forms related to menus. BackupSpecifies which types of objects you want to back up, where to back them up, and the type of file to back them up as. Object RemovalProvides options for deleting or disabling objects that reside on the destination server, but not on the source server, during a Form and Related Objects migration. Change HistorySpecifies how Migrator adds or merges entries in history fields after each migration. GroupsSpecifies how Migrator merges new groups with existing groups. DataSpecifies default settings for data migrations. These settings are used as the default settings in the Migrator Data Settings dialog box. RetryEnables you to specify the number of migration retries and the time (in seconds) between retries. The default number of retries is 3, and the default number of seconds is 300. Ignore PrefixesEnables to you specify prefixes that should be ignored during migrations. MasksEnables you to include or exclude objects in a migration or a Differences report. You can synchronize mask settings so that they are the same for both migrations and Differences reports. For each group of options, you can revert to the Migrator defaults by clicking Set Default.
Multiple-thread options
Using the Multiple-thread options, you can choose whether to use multiple threads for multiple migrations. The term thread refers to operating system functionality, allowing programs to break up into two or more independent work units for concurrent execution. Multiple threads allow the execution of other tasks while a migration is in progress, or to do multiple migrations concurrently. If you do not use multiple threads, you can run only one migration at a time. The default setting is multiple threads and execution of up to 10 migrations at a time. The optimal number of migrations to select depends on your hardware configuration. For more information about working with threads, see the Configuration Guide.
63
To select Multiple-thread options


2 Under Category, open the Migration list and select Multiple-thread. Figure 5-3: Multiple-thread options
3 Select Use Multiple Threads for Migrations to execute more than one migration at
a time; select Do Not Use Multiple Threads for Migrations to limit migrations to one at a time.
4 Enter the number of migrations you want Migrator to execute.
If you execute more migrations than the threads you have specified, the extra migrations are queued until a thread becomes available.
5 Click OK. 6 Restart your computer for the multi-thread option changes to take effect.
64
Migration options
Required Object options

Under Required Object settings, you can specify objects to be migrated automatically. These options guarantee that all required objects are included in a migration. With Shared Workflow Settings, you can either merge the list of forms linked to shared workflow objects on the source server with the list of forms on the destination server, or replace the list of associated forms on the destination server with the list on the source server.
To select Required Object options

1 Choose Tools > Options. 2 In the Migrator Options dialog box, select Migration > Required Objects. Figure 5-4: Required Objects options
3 Leave the option settings for the following objects at their default values of Yes to
have them migrated automatically: Menus Table field forms Join form members Flashboards variables Flashboard data sources Forms related to menus Forms required by applications
65
4 To require migration of forms required by applications, select Yes for the Migrate
Forms Required by Applications option. If you are migrating data for a form that the application does not own, the Yes setting ensures that the required form for the data is migrated to the destination. If this option is set to No and you are migrating data for a form that the application does not own, Migrator creates a special dataonly form as a placeholder for the data so that it can be migrated successfully. See Migrating applications on page 90.
5 To require migration of the state of an application, select Yes for the Migrate
Application States option. This property defines the application state (Maintenance, Production, or Test). It applies to deployable applications only. For more information about application states, see the Form and Application Objects Guide.
6 Select Yes or No for the Merge Shared Workflow option, depending on how you
want to handle shared workflow objects: YesThe list of shared workflow forms associated with the object on the source server merges with the list of shared workflow forms on the destination object. No (default)The list of shared workflow forms associated with the object on the source server replaces the list of shared workflow forms on the destination object.
7 Click OK.
Backup options
Backup options enable you to back up the destination server before a migration occurs. As a safeguard, Migrator copies the objects to be changed on the destination server to a backup directory before migration by default. (Only destination servers are backed up.) You can view backup files from a server or file window by selecting Backup Files in the left pane and viewing the files in the right pane.
NOTE
Migrator does not back up data for restored fields. Also, Migrator does not support backups of Flashboards or plug-ins to definition (.def) files. These objects can be backed up using .migrator files.
To select Backup options


2 Under Category, select Migration > Backup.
66
Migration options
Figure 5-5: Backup options
3 In the Backup the following objects area, select a backup option:
Back up all objects (default)all objects are backed up. Back up specified objectsA list of objects appears. The default selection is Yes for each object. If you do not want to back up an object, click the object name and select No from the drop-down list for that object. Disable allMigrator does not perform any backups.
4 In the Backup Root Directory section, select a location to store your backup files, or
accept the default Migrator backup directory shown. By using the Migrator backup directory, you can access backup files conveniently by clicking Backup Files in the left pane of the server window.
5 In the Backup File Type region, select the type of file you want your objects backed
up as.
NOTE
Make sure you have enough space on your computer for the backup files. Select a file format: Migrator (*.migrator)default setting Definition (*.def) Both Migrator files and definition (*.migrator and *.def)
6 Click OK.
67
Object Removal options

Object Removal options enable you to delete or disable objects from a Form and Related migration. Objects that can be disabled: Active links Escalations Filters Objects that can be deleted: Active links Escalations Filters Filter guides Active link guides Web services Migrator deletes or disables objects only on the destination server as part of a Forms and Related migration. For example, if you migrate Form 1 from Server A to Server B, Migrator deletes or disables Active Link x and Filter x from Server B.
NOTE
Object Removal options do not apply to locked workflow.
Figure 5-6: Migration object removal example
SERVER A SERVER B
FORM 1 Active Link: y z y z
FORM 1 Active Link:

Migrating Server A to Server B
x y z x y z
Filter:
Filter:
During a Forms and Related Objects migration, any objects related to a form that exist on the destination but not on the source can be deleted, disabled, or ignored on the destination when the migration takes place. If you specify that objects on the source should be deleted, Migrator backs up those objects before deleting them (see Backup options on page 66).
NOTE
Forms are never deleted during migrations. The default setting for these options is to disable all objects.
Migration options
To select Object Removal options

1 Choose Tools > Options. 2 Under Category, select Migration > Object Removal. Figure 5-7: Object Removal options
3 In the Delete or Disable Objects section, select how Migrator should handle objects
on the destination during a Form and Related Objects migration: Ignore All ObjectsMigrator ignores all objects on the destination server. Disable All Objects (default)Migrator disables all objects. The objects remain on the server disabled. Disable Specified Objects When Disable Objects is selected, Migrator disables the active links, escalations, or filters related to the selected objects. When Delete Objects is selected, Migrator deletes the active links, escalations, filters, filter guides, active link guides and web services related to the selected objects.
4 Click OK.
Change History options

With the Change History options, you can modify, merge, or append an AR System Change History. The change history of an object includes the owner of the object, who last modified it, and the date it was modified.
69
NOTE
Change History merging works only when the difference mask for the workflow property is enabled in the Options dialog box, and when the change history options have also been configured.
To select Change History options

1 Choose Tools > Options. 2 Select Migration > Change History. 3 In the Change History Merge Options area (Figure 5-8 on page 70), select how
Migrator should merge or add entries to the change history after each migration: Do not modify Change History (default)the existing change history on the source is not migrated to the destination. Merge Change History Append string to Change Historyenables you to enter some text, such as a description of the change history. Merge Change History and append a stringthe String field becomes enabled, and you can enter some text, such as a description of the merge.
4 Click OK. Figure 5-8: Change History options
70
Migration options
Group options
Group options enable you to choose how Migrator should merge new groups with existing groups. AR System defines several special groups that cannot be created using the Group option, including public, administrator, subadministrator, customize, submitter, assignee, and assignee group.
NOTE
Groups are migrated by group ID, not by group name.
To select Group options

1 Choose Tools > Options. 2 Under Category, select Migration > Groups. 3 In the Group Merging options area (Figure 5-9 on page 71), select how Migrator
should merge new groups with existing groups: Reject Duplicate GroupsMigrator generates an error for groups with existing request IDs. Generate New ID for All GroupsMigrator creates a new request ID for all groups. Replace Old Group with New GroupMigrator replaces old group information with new group information. Update Old Group with New Groups DataMigrator merges old group information with new group information.
Figure 5-9: Group options
71
4 For each group merging option, select either or both settings:
Ignore Required Fields Ignore Pattern Checking

5 Click OK.
Data options
Data options enable you to choose how Migrator should merge new data with existing data. Data is defined as the entries within forms.
To select Data options

1 Choose Tools > Options. 2 Select Migration > Data. 3 In the Data Merging options area (Figure 5-10 on page 73), select how Migrator
should merge new data with existing data: Reject Duplicate RecordsMigrator generates an error for records with existing request IDs. Generate New ID for All RecordsMigrator creates a new request ID for all records.
NOTE
This option is not supported for migrations in which the destination is a file. Replace Old Record with New RecordMigrator replaces old record information with new record information. Update Old Record with New Records DataMigrator merges old record information with new record information.
72
Migration options
Figure 5-10: Data options
4 For each data merging option, select one or both settings:
Ignore Required Fields Ignore Pattern Checking

5 In the Default Data Migration Mode section, select which data records to migrate:
Do not migrate any records. Migrate all records. Migrate query selection. Migrate first numberOfRecords records.
6 Click OK.
73
Retry options
Retry options enable you to specify if Migrator should stop a migration and attempt recovery if the server crashes, is stopped by another user, or becomes too busy to return results. Previously, Migrator would continue to migrate all objects even when the server stopped functioning. You can also specify the number of retries and the time (in seconds) between retries. The default number of tries is 3, and the default wait time is 300 seconds.
To set retry options

1 Choose Tools > Options. 2 Select Migration > Retry Options. 3 In the Number of Times to Retry (Figure 5-11), enter a number, or accept the
default value of 3. If you want no retries, enter 0.

4 In the Seconds to Wait Between Retries, enter a number, or accept the default of 300
seconds.
5 Click OK. Figure 5-11: Retry options
74
Migration options
Ignore Prefix option

This option enables you to instruct Migrator to bypass workflow objects that begin with specific prefixes during a direct or a scripted migration. All Migrator installations include a default list of prefixes in the Ignore Prefixes option dialog box. The administrator can add new prefix names, edit existing prefix names, or clear the list. A Set Defaults button is available to restore the default prefix list at any time. The default prefixes include those required to allow correct migration of CMDB, Approval Server, and SLA/SLM applications. They are:
AP OBJSTR RE BMC SLA zSLAGen
The Ignore Prefix option can be applied to all workflow objects except these: Data Roles Groups and Computed Groups Fields Views
Ignored prefixes in Results report

When a migration is completed, the Results report lists the prefixes that were ignored. The status information for workflow objects ignored during a migration notes these objects as ignored.
ITSM, SLA, and CMDB data

Migrator does not take the place of the current ITSM/SLA/CMDB installation processes, because it cannot execute the meta workflow used to generate workflow required by the client. Migrator allows administrators to safely move generated workflow from the system on which it was created to a production system without taking the meta workflow with it.
NOTE
All users must have administrator privileges to use Migrator. When migrating ITSM/ SLA/CMDB application-related data, administrators should first verify that they are a member of the required group or groups, in order for the data to be migrated correctly.
75
To specify prefixes to be ignored

1 Choose Tools > Options. 2 Select Migration > Ignore Prefix (Figure 5-12 on page 76). 3 Perform any of the following actions:
To add a prefix to the list, click Add, and enter the prefix name. To remove a prefix from the list, select the prefix, and click Remove. To edit the name of an existing prefix, select the prefix from the list, click Edit, and make the needed changes.
4 Click OK. Figure 5-12: Ignore Prefix option
Migration mask options

Migration mask options enable you to specify exactly which objects to compare between source and destination before a migration and what should be migrated if an object already exists. You can also synchronize migration mask options with the mask options for Differences reports, so that the settings are the same for both types of options. The Synchronize button provides a convenient way to create an exact match between the migration and Differences report mask options.
To set migration mask options

1 Choose Tools > Options, and select Migration. 2 Select Masks. 76 BMC Remedy Migrator Guide
Directory options
3 Click in the field for the type of object for which you want to set options (Figure 5-
13 on page 77), and select the option from the drop-down list.
4 To synchronize the migration mask options with those for the Differences report,
click Synchronize Difference Masks. For more information about Differences report mask options, see Mask options on page 134.
5 Click OK. Figure 5-13: Migration mask options
Directory options
Directory options enable you to specify the directories in which backup, migration result, script, and cache files are stored. Even when the directory path or name is changed, Migrator locates all the appropriate files for a specific server.
To select directory options

1 Choose Tools > Options. 2 Under Categories, select Directories.
When you are using Migrator for the first time, the default directory paths are shown. You can keep these default selections, or change them.
3 To change the directory path for a file type, click the button to the right of the
directory path field, and enter a new path.

4 Click OK.
77
Viewing backup, script, and results files

You can view the Migrator files on different servers regardless of the directory options setting.
To view your files

1 Click the server window associated with the backup, result, or script file you want
to view.
2 In the left pane of either the Object Type or Prefix view, click either Backup Files,
Script Files, or Result Files.

Figure 5-14: Viewing backup, script, or result files
The files are listed in the right pane. For each file, the list shows the name (including the date and time of the migration) and the migration status. To open a file, double-click the file name.
78
Chapter
Preparing to migrate
This section discusses what you need to know before you perform migrations. It describes the migration modes and provides a migration checklist. The following topics are provided: Defining migration modes (page 80) Copy/Prefix migrations (page 80) Migration checklist (page 81) Monitoring migrations (page 81) How objects are migrated (page 82)
Chapter 6 Preparing to migrate
79
Defining migration modes

Migrator executes migrations in two different modes: Migration mode and Scripting mode. In Migration mode, you perform a single migration immediately. In Scripting mode, you can create migration scripts that can be saved and run manually at your convenience, or scheduled to run at a specific date and time. You can use Scripting mode to migrate objects from one server to multiple servers. You can also use either Migration or Scripting mode to perform a copy/prefix migration on the same server (see Copy/Prefix migrations). Depending on how many threads you allocate in the Migration option, you can perform as many migrations simultaneously as there are threads. If Migrator uses up its allocation of threads, migrations are queued until a thread becomes available. For more information about threads, see Multiple-thread options on page 63.
Migration mode
In Migration mode, migrations run immediately.
Scripting mode
In Scripting mode, you create reusable sets of multiple server migrations and put them in a holding position. This keeps you from having to run each migration separately, one after the other. You can schedule them to run on a specific day and time, or you can open and run them whenever they are needed. For additional information about migration scripts and scheduling migration scripts, see Creating, running, and saving migration scripts on page 107 and Scheduling scripted migrations on page 114.
Copy/Prefix migrations
When using only one server, you cannot migrate identically named objects to the same server. You must change the prefix before a migration can begin. In a Copy/ Prefix migration, you migrate objects to the same server, and then change the objects prefix in the Prefix dialog box. The Copy/Prefix migration runs in either migration or scripting mode. It is useful for doing simple development or testing of workflow on the same server. It also keeps all the relationships between forms and related workflow separate.
80
Migration checklist
Migration checklist
Before you begin a migration, verify the following information: Are you licensed and logged on to all of the servers you want to migrate to and from? See Chapter 3, Licensing and logging on to Migrator for more information. Do you want to restrict users from accessing a destination server that is involved in a migration? (In Migrator, Administrator mode is set to on by default.) If yes: Select the production server window and choose the Migrate menu. Select Set Admin Mode on Destination Server to turn it on (check) and select it again to turn it off (uncheck). If Set Admin Mode on the destination server is selected, Migrator enables the Administrator-Only mode on the destination server (if your server supports it) during a migration, and turns it off when the migration is complete. Did you set up your migration and report options in the Tools menu? See Chapter 5, Migration options, for setting up migration options and Chapters 8 through 10 for setting up report options. If Enforced mode is enabled on the destination server, are all the objects on the destination server checked into Source Control? Migrator does not change objects on a destination server if Enforced mode is enabled in AR System and the object is checked out by another user. For more information about the use of source control in AR System, see the Configuration Guide. Do you want to review object dependencies or view object differences before you start migrating? See Chapter 10, Differences reports and Chapter 9, Dependency reports. Have you verified or added any prefixes for workflow items that should be ignored during the migration process? See Chapter 5, Migration options.
Monitoring migrations
Use the migration status pane to view active or completed migrations, and monitor and control migration activity. Use the migration status tabs to select and view migration activity and statistics. See Migration status pane on page 38 and Migration status tabs on page 39.
81
Controlling migrations
To control migrations from the migration status pane, click a status tab and then right-click a status line to open a menu with the following options: StartStarts a scheduled migration (before its scheduled time). RestartRestarts an interrupted or stopped migration (starting from the point of interruption and going forward). StopStops any type of migration. DeleteDeletes an interrupted, stopped, scheduled, or completed migration, along with the migration result files.
Viewing migration results

For every completed migration, Migrator creates a result report. To view a migration result report, click the Completed status tab in the migration status pane, and then double-click a status line that you want to view a report for. To resize an active migration result report, choose View > Zoom, then enter a percentage to shrink or enlarge the report. For additional information about migration result reports, see Chapter 11, Migration Result reports.
Resolving reported failures

If you see a failure reported after your migration, some might not have migrated properly. To view migration results, look at the migration status pane or generate a migration result report (see Overview of Migration Result reports on page 138). You can always restore the changed objects on a destination server by opening the appropriate Migrator backup file (see Backup options on page 66) and migrating it to the destination server.
How objects are migrated

This section explains how Migrator moves objects and manages join forms, table fields, and Form and Related Object migrations, and how Migrator manages embedded server names.
Form migrations
When migrating a form from one server to another, Migrator migrates the form and the menus referenced by the form. This makes sure that the form works correctly when a user opens it in BMC Remedy User. In some cases, Migrator tries to migrate more than the form and menus, as described in the following sections.
82
Migrating join forms

When migrating a join form, Migrator builds a tree that represents the structure of the join form. For example, to migrate Join Form A, Migrator goes over the tree from top to bottom to find all the regular forms first (shaded forms). To make sure that the forms are created in the correct order, all the regular forms are migrated first, then all the join forms.
Figure 6-1: Join form migration example
Order of join form migration: Regular Form D Regular Form H Regular Form I Regular Form F Regular Form J Join Form E Join Form G Join Form B Join Form C Join Form A
Form A
Form B
Form C
Form D
Form E
Form F
Form G
Form H
Form I
Form J
Before migrating the forms, Migrator processes them as follows: Retrieves Join Form A, and sees that it has two member forms: Join Form B and Join Form C. Retrieves Form B, sees that it is a join form, and adds it to the join form list. Retrieves Join Form C, sees that it is a join form, and adds it to the join form list. Looks at Join Form B and sees that it has two member forms: Regular Form D and Join Form E. Retrieves Regular Form D, sees that it is a regular form, and adds it to the regular form list. At this point, all processing stops for Regular Form D because it does not have any members. Retrieves Join Form E, sees that it is a join form, and adds it to the join form list. Looks at Join Form E, sees that it has two members: Regular Form H and Regular Form I. Retrieves Regular Form H, sees that it is a regular form, and adds it to the regular form list. At this point, all processing stops for Regular Form H because it does not have any members. Retrieves Regular Form I, sees that it is a regular form, and adds it to the regular form list. At this point, all processing stops for Regular Form I because it does not have any members. Looks at Join Form C and sees that it has two members: Regular Form F and Join Form G.
Chapter 6 Preparing to migrate 83
Retrieves Regular Form F, sees that it is a regular form, and adds it to the regular form list. At this point, all processing stops for Regular Form F because it does not have any members. Retrieves Join Form G, sees that it is a join form, and adds it to the join form list. Looks at Join Form G and sees that it has two members: Regular Form I and Regular Form J. Retrieves Regular Form I and sees that it is a regular form. However, it has already been added to the regular form list. At this point, all processing stops for Regular Form I because it does not have any members. Retrieves Regular Form J, sees that it is a regular form, and adds it to the regular form list. At this point, all processing for Regular Form J stops because it does not have any members. The forms are then migrated as follows: Regular Forms D, H, I, F, and J are migrated first, because they do not depend on any other forms. Join Forms E and G are migrated next, because they are required for Join Forms B and C. Join Forms B and C are migrated next, because they are required for Join Form A. Finally, Join Form A is migrated, which was the original request.
Migrating a form and related objects

When migrating a form with related objects, Migrator retrieves a list of the active links, filters, escalations, guides, applications, and web services attached to the form, according to the options you set. It then adds those objects to the list of objects to be migrated. For example, if you migrate a form with one active link and one filter, Migrator migrates the form, the active link, the filter, and any menus used by the form. If you migrate a join form, Migrator includes the objects related only to the join form. It does not include the objects related to the forms needed to complete the join form migration. AR System and Migrator use field IDs, not field names, to determine differences between source and destination environments. For example, if the source form has a field name of Field_ABC, and the destination form has a field name of Field_XYZ, with the same field ID, Migrator replaces instances of the form Field_XYZ with Field_ABC on the destination server. After a migration from a development server to a production server, you might notice that field names on forms or fields referenced in workflow (such as Set Fields actions) have been changed on the production server.
84
If field names are the same, but field IDs are not, and the migration includes data, then the scenario is reversed: Migrator migrates data to the destination form and creates entries on the destination server where the field IDs are the same. If the source form has a field name of Field_ABC and the target form has a field name of Field_ABC with different field IDs, Migrator migrates the data to the destination field ID that matches. If the field types are not the same, the migration fails. Before making modifications to your development environment, migrate the production server to the development server. This ensures that field IDs are synchronized. If you need to add fields to both environments manually, assign them the same field ID.
Archive forms
If you are migrating a form that has an archive form associated with it, the archive form is created on the destination if it does not already exist, or it is modified if it already exists. When a regular form is migrated for the first time, the server creates the form itself, then the archive form.
Managing embedded server names

Migrator replaces all object references to the source server with the name of the destination server when migrating from one server to another. When trying to determine if an object references the source server, Migrator uses the name of the server you defined in the Accounts dialog box. For example, if you define the server as a fully qualified host name (such as source.domain.com), Migrator uses source.domain.com as the name of the server it replaces. Any references to the unqualified name source are not replaced. If you define the server name as only source, Migrator replaces any references it finds to both the unqualified name source and the fully qualified host name source.domain.com. Migrator considers source.domain.com, source.some.otherdomain.com, and source.domain.net to be the same server. The following table outlines what happens to server references when Migrator replaces the reference for servers named source with the reference destination, when both of the servers are in the domain.com domain.
Table 6-1: Change in server references for source names (Sheet 1 of 2) Server name referenced source source.domain.com Server name replaced Action taken by Migrator with destination destination Migrator recognizes source and replaces it with destination. Migrator recognizes source and replaces it with destination.
85
Table 6-1: Change in server references for source names (Sheet 2 of 2) Server name referenced Server name replaced Action taken by Migrator with Migrator recognizes source and replaces it with destination, because it does not know that the domain is not the correct one. The object references a different server and Migrator leaves the reference intact.
source.otherdomain.ne destination t
server.domain.com
server.domain. com
The following table outlines what happens to server references when Migrator replaces the references for servers named source.domain.com with destination, when both of the servers are in the domain.com domain.
Table 6-2: Changes in server references for destination names Server name referenced source Server name replaced with source Action taken by Migrator Migrator does not recognize the name as the same as source.domain.com and does not replace it. Migrator recognizes source.domain.com and replaces it with destination. Migrator does not recognize the name as the same as source.domain.com and does not replace it. The object references a different server and Migrator leaves the reference intact.
source.domain.com
destination
source.otherdomain.net source.otherdomain. net
server.domain.com
server.domain.com
86
Chapter
Performing migrations
This section provides migration shortcuts and describes how to migrate objects, fields, and data. It also includes procedures on how to run and clear migrations, and how to perform Copy/Prefix migrations. The following topics are provided: Performing migrations (page 88) Migrating objects (page 88) Migrating applications (page 90) Migrating a form view and its associated fields (page 93) Migrating fields (page 93) Migrating data (page 95) Performing Copy/Prefix migrations (page 103)
Chapter 7
87
Migrations can be performed in either Migration mode or Scripting mode. Migrator defaults to the last mode used. In Migration mode, you can select one or more objects and start the migration immediately. In Scripting mode, you can select one or more objects and start the migration at a scheduled time, migrating objects from one server to another, between a server and a file, between files, or to multiple servers or multiple files. Migrator is fully Unicode capable. Migrator allows migration of objects and data between non-Unicode and Unicode servers. Migrator does not have to be executed on the same locale as a non-Unicode server. Definition (.def) files with multiple character encodings can be migrated as long as each block within the .def file contains the character encoding used at the beginning of the block. If that line is missing, the migration must be executed on a server of the same locale that was used to create the .def file.
Migrating objects
You can migrate objects between servers, between a server and a file, or between files.
IMPORTANT
If you have migrated hierarchical groups (groups that include both parent and child groups), the Differences report might show a difference between source and destination. This could be because a child group was migrated but not its parent. To resolve this difference, migrate both parent and child groups.
To migrate objects
1 Open windows for your source and destination.
To open a window for a server, choose File > New Server Window, and select a server. To open a window for a file, choose File > Open, and select a file.
2 Click in the source window. 3 Choose Migrate > Migration Mode.
88
Migrating objects
4 From the Migrate menu, choose the type of object migration to perform:
All AR System ObjectsMigrate all objects listed in the source window. Form and Related ObjectsMigrate a form and all of its related objects. Deploy ApplicationMigrate an application and all of its objects to the same server. See Migrating applications. Selected ObjectsMigrate only the objects selected in the source window.
5 From the Destination Type dialog box, select the destination type by clicking
Server or Migrator File. If you select Server, select a destination server and enter your user name and password. The source server is always the server window that is active at the time of the migration. To review object differences on the same server, select the same destination server as your source, and then add a prefix when prompted by the Prefix dialog box. If you select Migrator File, enter the file destination path, type a file name, and click Save. The migration is saved as a .migrator file.
6 If you are prompted to proceed with the migration, select Yes. 7 To view the progress and results of your migration, open the Migration Status
pane by choosing View > Migration Status if it is not already open. Select the All tab to see the progress of the migration; select the Completed tab to see a list of completed migrations. To view a results report for a completed migration, double-click the migration in the Completed tab. For more information about results reports, see Chapter 11, Migration Result reports.
Chapter 7
89
Migrating applications
You can migrate an application to another server, to the same server, between a server and a file, or between files using two methods: By migrating it as a selected object (Migrate > Selected Object). By deploying it (Migrate > Deploy Application). This method migrates the application and all of its supporting files.
Figure 7-1: Migrating applications
Migrating an application as a selected object

To migrate an application
1 Open the server or file window that includes the application you want to migrate. 2 In the right pane, select the application. 3 Choose Migrate > Selected Objects. 4 From the cascading menu, choose Select Destination.
NOTE
You can also select any server or file listed in the cascading menu.
5 In the Destination Type dialog box, choose Server or Migrator File.
If you select Server, select a destination server and, if necessary, enter your AR System user name and password.
90
Migrating applications
If you select Migrator file, enter the name of the .migrator file to serve as the destination. If you are prompted to proceed with the migration, select Yes.
6 To view the progress and results of the migration, open the Migration Status pane
by choosing View > Migration Status.
Deploying an application
When you deploy an application, Migrator migrates the application and all of its supporting objects to the destination.
Migrating application data to a file without a corresponding form

When creating an application using BMC Remedy Developer Studio, you can specify the data to be exported when the application is deployed. This information is shown in the Data tab in the Modify Application dialog box. In Migrator, when you deploy an application that contains data for forms that the application does not own, those forms are not automatically migrated. However, Migrator provides an option to migrate forms required by applications at deployment. When this option is set to Yes, the forms required by the application are included with the data in the migration.
Figure 7-2: Required Objects option: Migrate Fields Required by Applications
If this option is set to No when you deploy an application that contains data for forms that the application does not own, Migrator creates a special data-only form to receive the data being migrated. In the Object List window, this form is listed as a data-only form with a different icon than that of a regular form or a display-only form.
Chapter 7
91
Figure 7-3: Data-only form
During the migration, the data in this form is migrated, but not the form itself. For more information about required objects options in Migrator, see Required Object options on page 65.
Deploying an application to the same server

If you have an AR System 6.0 or later server, you can deploy an application to the same server as a copy/prefix migration. See Performing Copy/Prefix migrations on page 103.
To deploy an application
1 Open the server or file window that includes the application to deploy. 2 In the right pane of the window, select the application. 3 Choose Migrate > Deploy Application. 4 From the cascading menu, choose Select Destination.
NOTE
You can also select any server or file listed in the cascading menu.
5 In the Destination Type dialog box, choose Server or Migrator File.
If you select Server, select a destination server and, if necessary, enter your AR System user name and password. If you select Migrator file, enter the name of the .migrator file to serve as the destination. If you are prompted to proceed with the migration, select Yes.
6 To view the progress and results of your migration, open the Migration Status
pane by choosing View > Migration Status if it is not already open.
92
Migrating a form view and its associated fields
Migrating a form view and its associated fields

You can select a view of a form and its fields and display properties associated with that view instead of having to select all the fields and views for the form. When a view is selected for migration, Migrator searches for all of the fields with display properties for that view. It then migrates that view and its associated fields to the destination form. It checks each field on the destination form and takes the appropriate action: If the field exists on the destination, Migrator extracts the display properties from the destination field for all views except the view being migrated. It merges these display properties into the source field and compares what properties of the source field with those of the destination field. If the field does not exist on the destination, Migrator recreates the field, and verifies that it includes only the display properties of the field being migrated. Finally, Migrator creates or modifies the field on the destination using the new merged source field. If the field exists on the destination, Migrator extracts from the destination field the display properties for all views except the view being migrated. This process is repeated for each field in the view.
To migrate a form view and its fields

1 In the Migrator main window, select the form whose view you want to migrate. 2 Right-click on the form name and choose Form Details. 3 From the left panel, choose Views. 4 Select the view you want to migrate. 5 Choose Migrate > Selected View with Fields > Select Destination. 6 Select a form and click OK. 7 Click Yes in to confirm the migration.
Migrating fields
You can use Migrator to migrate fields from one AR System form to another. By migrating lower-level fields or field-level objects from one form to another, you can update forms at a more basic level. For example, you can migrate a Middle Name field to a form with only first and last name fields.
Chapter 7
93
To migrate fields
1 Open windows for the source and destination.
2 Choose Migrate > Migration Mode. 3 In the left pane of the source window under AR System Objects, click Forms. 4 In the right pane of the source window, select the form that includes the fields you
want to migrate.
5 Click View > Form Details, or double-click the form name to open a Form Detail
window for the form. The right pane lists the fields for the selected form.
Figure 7-4: Migrating fields
6 Perform one of the following actions:
To migrate all fields, choose Migrate > All Fields, or Migrate > All Views. To migrate fields of a specific type, choose Migrate > Migrate Field by Type. To migrate one or more fields, select the fields in the right pane. Use Shift-Click or Ctrl-Click to select multiple fields. Then, right-click and choose Migrate Selected Fields from the pop-up menu.
7 From the Destination Type dialog box, select Server or Migrator File.
If you select Server, select a destination server and enter your AR System user name and password. You are prompted to select a destination form. The source server is always the server window you have activated at the time of the migration. To review object differences on the same server, select the same destination server as your source, and then define a prefix. For the prefix, use a short string, such as prod. If you select Migrator File, select the .migrator file to which the field should be migrated. A list of forms in the .migrator file is displayed. If the file has no forms in it, you cannot migrate the field to that file.
Migrating data
If you are prompted to proceed with the migration, select Yes.

8 To view migration progress and results, open the Migration Status pane by
choosing View > Migration Status. Select the All tab to see the progress of the migration. Select the Completed tab to see a list of completed migrations. To view a results report for a completed migration, double-click the migration in the Completed tab. See Chapter 11, Migration Result reports.
Migrating data
You can migrate data entries associated with a form from one server to another, between a server and a file, or between files. For example, you can migrate data entries from a production server to a development server for testing newly designed applications with actual data. Or, you can migrate data from one file to another. Data is migrated individually or in a batch.
NOTE
If you stop and then restart a migration in progress, Migrator restarts the migration from the entry that was last migrated successfully. By default, Migrator uses the field IDs to map field values between the two forms you select. You can migrate four types of data: Individual entries All entries Searched entries X number of entries
Migrating individual entries in a form

To migrate individual entries in a form
1 Open a server window or a file containing the data entries you want to migrate.
2 Choose Migrate > Migration Mode or Scripting Mode. 3 In both the source and destination windows, perform the following tasks: a In the right pane, select the form that is the source or destination for the data
migration.
b Choose View > Form Details to open the Forms Detail window:
Chapter 7
95
4 Scroll to the bottom of the left pane of the source Form Detail window and click
Data. The right pane displays the data for the fields in the form.
NOTE
The columns displayed in the right pane for the form data are defined by the settings in the Form Properties dialog box in BMC Remedy Developer Studio. The Results List Fields tab specifies the fields to be displayed in results lists. If no fields are specified, Migrator uses the defaults for the form (field IDs 1 and 8). For example, in the Group form, Request ID and Long Group Name (fields 1 and 8) are displayed. To display additional fields, use BMC Remedy Developer Studio to enter those fields. See the Form and Application Objects Guide. The advanced search bar appears at the bottom of the Form Detail window, allowing you to search for data to include in the migration.
5 Do either of the following actions in the advanced search bar:
To find specific data, enter criteria in the Search Criteria field, and click Apply. The matching entries are listed in the Form Detail window. To include all data, leave the Search Criteria field blank.
6 Choose the data to migrate:
To migrate only the data found in your search, select the records from the source Form Detail window and drag and drop them into the destination Form Detail window. To migrate all the data from a specific form, first select the data in the right pane of the source Form Detail window. To select all the data records, highlight the first data record, hold down the Shift key, and then highlight the last data record.
7 Right-click in the right pane of the Form Detail window and select Migrate
Selected Entries. If you are migrating to a server, select the destination server in the Server dialog box. If you are migrating to a file, enter or select a .migrator file name.
8 Select the destination form in the Form List dialog box.
96
Migrating data
Migrating data entries

To migrate data entries
1 Open the windows that you want as the source and destination for the data you
are migrating. To open a window for a server, choose File > New Server Window, and select a server. To open a window for a file, choose File > Open, and select a file.
2 Choose Migrate > Migration Mode or Scripting Mode. 3 Choose Migrate > Form Data, then choose one of the following options:
Form Data OnlyOnly the entries within the form are migrated. Form and DataBoth the form and the entries within the form are migrated. Form, Related Objects, and DataBoth the form and the entries within the form are migrated, along with all related objects. If you are migrating forms and data to the same server, the Prefix dialog box appears. Enter a prefix. The Data Migration Settings dialog box appears.
Figure 7-5: Data Migration Settings dialog box
Chapter 7
97
The migration is listed at the top of the dialog box with the following information: Source NameThe name of the server or file from which the data is being migrated. If the source is a file, the complete file path is shown. A green check mark or a red X through the icon indicates whether the migration instructions are valid. Source FormThe name of the form that includes the data being migrated. Destination NameThe name of the server or . migrator file to which the data is being migrated. If the destination is a file, the complete file path is shown. Destination FormThe name of the AR System form on the destination to which the data applies. Object SettingsThe objects to be included in the migration, based on what you selected in step 3. Data ModeThe specific data to be migrated. The setting shown is based on the default value set in your migration options. Ignore pattern checking (yes/no)Whether pattern checking should be ignored. Ignore required fields (yes/no)whether required fields should be ignored. Num EntriesThe number of entries being migrated. Search criteriaAny search criteria specified for this migration. If you did not specify any search criteria, this column is blank. The Source and Destination areas show the names of the source and destination servers or files, and forms. For example, if you are migrating between two files, the source and destination file paths are shown.
Figure 7-6: Source and Destination information for data migration
4 Select the migration to highlight it. Figure 7-7: Selected migration in Data Migration Settings dialog box
98
Migrating data
NOTE
If your migration has any invalid instructions, the icon at the left of the server name has a red cross (X) through it, and a message appears in the lower-left area of the Data Migration Settings dialog box. You must make sure that all migration instructions are valid before you can continue.
5 In the Object Settings region, select a setting for the objects to be migrated:
Form OnlyMigrates only forms. Form and RelatedMigrates forms and related objects. Form Data OnlyMigrates only form data entries. Form and DataMigrates forms and data entries. Form, Related and DataMigrates forms, related objects, and data entries.
6 In the Data Settings region, select a data mode. The default selection shown
corresponds with the Data settings in your migration options. For more information about setting migration options, see Chapter 5, Migration options. Accept the selection shown, or choose another selection: No Data No data entries are migrated. You can set the default setting for this mode by choosing Tools > Options, expanding the Migration tree in the left pane, and then selecting Data from the same tree. All EntriesAll entries are migrated according to your selections and settings. Search SelectionEntries are migrated based on search criteria you specify. If the source is a file, this selection is not available. For information about creating a search, see Creating a data search on page 101. Number of EntriesNumber of entries that are migrated, starting from the newest to the oldest.
7 Select a data merging option. The default selection shown is based on the Data
settings in your migration options. For more information about setting migration options, see Chapter 5, Migration options. Either accept the selection shown, or choose another selection: Reject Duplicate EntriesMigrator generates an error for entries with existing request IDs. Generate New ID for All EntriesMigrator creates a new request ID for all entries. If the destination is a file, this selection is not available. Replace Old Entry with New EntryMigrator replaces old entry information with new entry information. Update Old Entry with New Entrys DataMigrator merges old entry information with new entry information.
8 For each data merging option selected, check the appropriate check boxes to enable
the following options: Ignore required fields Ignore pattern checking

Chapter 7 Performing migrations 99
9 Select a default migration mode:
Do not migrate any records Migrate all records Migrate query selection Migrate the first numberOfRecords records
10 Select server connection options:
Use List and Fast Server Threads By default, Migrator uses Fast and List server threads as an alternative to the standard Admin thread. The default setting for the Fast Thread Port is 390620; the default setting for the List Thread Port is 390635. To change these settings, enter different values. To disable Fast and List Treads and use the Admin thread, uncheck the box.
11 Check the Disable Related Workflow check box to have Migrator disable related
workflow during the data migration. The workflow is enabled after the migration is complete.
12 Check the Enable Field Mappings box to apply field mappings for the data
migration. See Using field mappings on page 102.

13 Perform one of the following actions:
Choose Apply, then OK, to begin the data migration.
NOTE
The OK button is disabled until all the migration instructions are valid in the Data Migrations Settings dialog box. Click Cancel to stop the data migration.
14 If you are asked if you want to start the migration, select Yes. 15 To view migration progress and results, open the Migration Status Pane window
and click the All and Completed tabs. Then, double-click the migration you want to check.
100
Migrating data
Creating a data search

A Migrator search allows you to create specific search criteria of your data records for a customized migration.
NOTE
This option is not available if the source is a file.
To create a data search

1 In the Data Migration Settings dialog box under Data Settings, select Search
Selection from the Data Mode list box. If you supply a number in the Number of Entries text box, only the first number of entries that match the search are migrated.
2 To create a search, click the list box next to the Search Criteria text box. Figure 7-8: Search Criteria dialog box
3 In the Search Criteria dialog box, enter search criteria. Use the following methods
to help build a search: Click Fields to display a menu for fields, selection values, and keywords. Choose Fields, Selection Values, or Keywords to display submenus with variables that are specific to the data records you are migrating.
IMPORTANT
Because Migrator relies on the API to generate qualification structures, Migrator does not support using locale-specific formatting in qualification strings. The API supports generic formatting such as dd-mm-yy for dates and number formats without punctuation (such as 15000 instead of 15,000). Because of this, do not use spaces, comma-separated values, or any other locale-specific punctuation when entering qualifications in Migrator. For example, when entering a keyword, be sure that there are no spaces. An entry such as $ TIMESTAMP$ (with a space between the $ and the T) causes an error. Here are some examples of searches you can create:
Creator = Administrator AND License Type = Fixed
In this example, Migrator searches for entries created by an administrator user with a fixed license.
Creator= Jane Doe
In this example, Migrator searches for entries created by the user Jane Doe.
Chapter 7 Performing migrations
101
4 Click OK to use the search, or Cancel to stop it.
Your search criteria appear in the Search Criteria field of the Data Migration Settings dialog box.
Figure 7-9: Search criteria for data migration
Using field mappings

The Enable Field Mapping option in the Data Migration Settings dialog box allows you to apply field mappings to a data migration. When you check the Enable Field Mappings check box, the Mappings button becomes active. Using this feature, you can map source fields to either a destination field or a keyword. You can also save mappings to a file for reuse later, to save time and reduce errors. You can load the saved mapping file instead of entering the mapping values again. When you save a mapping, the form name, the server the form resides on, and the data file name are saved. You can auto-map all fields according to the field ID or the field name used in BMC Remedy Developer Studio. You can remove any of these generated mappings or add mappings. Keep these conditions in mind when using field mappings: Field mapping in Migrator does not work with data files such as .arx files. Migrator does not perform any validations on field mappings. A source field can be mapped only once. A destination field can be mapped to more than one source field.
To apply field mappings

1 Check the Enable Field Mappings box in the Data Migration Options dialog box. 2 Click the Mappings button. 3 In the Field Mappings dialog box, enter the mappings you want to use for the data
migration. To auto-map field IDs or field names, click the Auto Map IDs or Auto Map Names buttons. To add a mapping, click Add Mapping. To delete one or more mappings from the Current Mappings list, select the mappings, and click Delete. To remove all of the mappings, click Delete All. To save a mapping, select the mapping and click Save.
Performing Copy/Prefix migrations
To load a mapping you have saved, click Load and select the mapping.
4 Click OK.
Performing Copy/Prefix migrations

When migrating objects to the same server, you must change the objects prefix so that the objects have unique names. This is called a Copy/Prefix migration.
NOTE
When migrating an application to the same AR System 6.0 or later server, you might notice that Migrator does not automatically deploy a prefixed version of the application. This is because the prefix is applied only to the application name, not its objects. As a result, you might see an error message stating that the server cannot create the application because its objects are already owned by the nonprefixed application. To migrate the application to the same server, choose Migrate > Deploy Application, and select the same server as the destination. This ensures that the prefixed version of the application is created and that it has referenced objects that are also migrated. Also, when a role is migrated to the same server without an application, a prefixed application name is assigned to the role, but the role name is not prefixed.
To perform Copy/Prefix object migrations

1 Open the window containing the objects you want to copy or migrate. 2 Select the objects you want to migrate. 3 In the Destination Type dialog box, select Server, then select the same server. Figure 7-10: Prefix dialog box
TIP
Dragging and then releasing an object within the same server window, or performing a copy and paste action, also opens the Prefix dialog box.
Chapter 7 Performing migrations
103
4 In the Prefix dialog box, perform one of the following tasks:
Click Add Prefix, then type the new prefix. Click Replace First [n] Characters with New Prefix, type a number, and then type a new prefix. Click Remove Old Prefix, then type the old prefix. Click Replace Old Prefix with New Prefix, type in the old prefix, and then type the new prefix. For the prefix, use a short string (5 or fewer characters).
5 Click OK. 6 If you are prompted to proceed with the migration, select Yes.
To view the progress and results of your migration, choose View > Migration Status.
NOTE
When viewing the status of a Copy/Prefix migration, the prefix does not appear with the server name.
104
Chapter
Working with migration scripts

This section describes the scripting process and explains how to set up and run a migration script. It describes how you can modify, schedule, change, and delete migration scripts. The following topics are provided: Scripting overview (page 106) Creating, running, and saving migration scripts (page 107) Modifying migration scripts (page 109) Scheduling scripted migrations (page 114)
Chapter 8 Working with migration scripts
105
Scripting overview
You can use migration scripts to create customized migrations between one or more servers, at a scheduled time. For example, you can select which objects to migrate by moving those objects from server 1 to server 2, then move all or some of the same objects to server 3. You can then schedule this script file to run at any time in the future.
Figure 8-1: How migration scripts handle multiple servers
Migration Starts
Source Server 1
Destination Server 1
Source Server 2
Migration Ends
Migrations within a script are executed in server pairs, not in the order in which they are created. For example, you might have a scripted migration from two source servers (Source Server 1 and Source Server 2) to three destination servers (Destination Server 1, 2, and 3). When the script is executed, Migrator performs the following tasks: First, it gets a list of all the source servers and then a list of all the destination servers. Next, it loops through each source server. Finally, it loops through each destination server for a source server to determine if any objects need to be migrated between the two servers. If so, Migrator migrates all of those objects. If not, Migrator continues to the next server pair, until all the server pair combinations have been checked.
106
Creating, running, and saving migration scripts
Creating, running, and saving migration scripts

The left pane of the Migration Script window contains additional elements for easier referencing and modification of scripts.
Figure 8-2: Migration script elements
The list can include elements such as: ServersLists the servers associated with the script. Migrator FilesLists the .migrator files associated with the script. FieldsPresents form fields that are scripted for migration. ViewsSupplies the number of views scripted. DataLists the data records contained within a form scripted for migration. Special MigrationsLists migrations in which an entire object type is migrated, or applications being deployed through migration. You can drag and drop entire object types (such as forms or active links) from the source tree view to a destination. Doing so migrates all the objects of that type. You can then run the script at any time and Migrator migrates all of the objects of that type (including new objects after script creation) that are found on the source. You can also deploy applications by way of migration, by selecting an application, right-clicking on it, choosing Deploy Application from the menu, and selecting a destination for the application.
Creating and saving migration scripts

Use these tips for faster creation of a migration script: In Scripting mode, dragging and dropping objects from a source server to a destination server window automatically creates a new migration script (or adds to an existing one). Double-clicking a script file from its saved location launches Migrator and opens the script in a window. Migrator allows you to have only one Scripting window open at a time. If a Scripting window is already open, Migrator adds to it.
107
To create a migration script

1 If you have more than one source server, make sure you are logged on to and have
server windows open for all the servers included in the scripted migration.
2 Choose Migrate > Scripting Mode. 3 Perform any type of object, field, or data migration between any licenses servers,
between a server and a file, or between files. A migration script window opens as soon as you script your first object, field, or data type. If you have several objects to script, you can minimize the window or resize the script window and continue migrating.
4 When you have completed your script, choose File > Save As. 5 Select a destination path and type a file name, making sure to save the file as a .mgrscript file.
TIP
Store your scripted files in the Migrator Script directory. This directory gives you access to the files from the Server Tree view by clicking the Scripts icon.
6 Click Save. 7 Close the script window.
Opening and running migration scripts

You can open and run a migration script any time, whether it is scheduled or unscheduled.
To open and run a migration script

1 Choose Script > Execute Migration Script. 2 In the Migrator Scripts dialog box, select the script you want to run and then click
Open. Migrator runs the scripted migration. To view a saved scripted file, open the Script Files directory in the left pane, and double-click the script name.
3 Select the scripted file and click the Execute Migration Script toolbar icon to run the
scripted migration.
NOTE
To view a progress indicator of an executing migration, select the All tab in the migration status pane. For more information about using the migration status pane, see Monitoring migrations on page 81.
108
Modifying migration scripts
You can also open or delete a migration script by right-clicking on a script and selecting the delete option from the pop-up menu.
Figure 8-3: Migration script menu

You can perform any of the following modifications to a migration script from the Migration Script window: Change the object elements. Add or remove a destination server. Change the name of a destination server. Add a description of the script. Add Before commands, After commands, or both. If migrating between servers, change login information for the source or destination server.
Figure 8-4: Migration Script window
109
When performing scripting procedures, use the following mouse shortcuts: If Migrator is not running, double-click a script file from its saved location to launch Migrator and open the script in a window. Right-click an object in the right pane of a server window to open specific menu options available for that object. Top tree options in the left pane of the script window, for example Forms and Groups, cannot be accessed by way of a right-click. If you go deeper within the tree view by clicking on objects, you can access lower-level objects by rightclicking. Click the Server tree view, then double-click Script Files, to view the files that are stored in the Script Files directory. Right-click a migration status line in the migration status pane under the All or Scheduled tabs to open a menu containing options for changing a scheduled migration.
Changing object elements in a script

To change object elements in a script
1 Choose File > Open or File > Recent Files to open the migration script whose
objects you want to change.

2 In the left pane of the migration script window, select AR System Objects, then
select the type of object you want to modify.

3 In the right pane, right-click on the object to modify. 4 From the pop-up menu that appears, select an action.
NOTE
The available selections in the menu depend on the type of object you have selected. For example, if you selected a regular form, the Data Mode, Number of Entries, and Search Criteria selections are not available.
5 If you are prompted to confirm your selection, click Yes to proceed, or Cancel to
stop the modification.

6 Choose File > Save to save the modified script.
110
Adding or removing a server in a script

WARNING
If you remove a server, all objects associated with that server are removed.
To add or remove a server in a script

1 In the right pane of the Migration Script window, click on the migration script for
which you want to add or remove a server.

2 In the left pane, click Servers. 3 Perform either of the following actions:
To add a source or destination server to the list of servers associated with the script:
a Choose Servers > Add Server. b In the Login dialog box, select a server and enter your login name along with
your password, and click OK. To remove a destination server from the list:
a In the right pane of the script window, select the server you want to remove. b Choose Servers > Remove Server, or right-click on the listed server and choose
Remove Server.
c In response to the confirmation prompt, select Yes to remove the server, or No
to cancel the server removal.
Editing server options for a script

You can add any number of servers to a script. For example, you might have an existing script that moves objects from a development server to a quality assurance server. You can edit the script by removing the development server and adding a production server, along with reassigning all scripted objects source and destinations based on the new servers. This ensures that all objects originally migrated to quality assurance are migrated to the production server.
To edit server options for a script

1 Open the migration script whose server options you want to change. 2 In the right pane of the script window, select the server whose options you want
to change.
111
3 From the Servers menu, choose the option you want to change:
Change Login InformationDisplays the Login dialog box, from which you can enter a new user name and password, or change server account information for the selected server. Add ServerDisplays the server list. You can select a server to add to the script. See Adding or removing a server in a script on page 111. Add Migrator FileDisplays the Open dialog box with the list of .migrator files in the Scripts directory. You can select a file to add to the script. Remove ServerEnables you to delete a server from the script. Remove FileEnables you to delete a file from the script. Change History OptionDisplays the Change History Merge Option. See Change History options on page 69. Change History StringDisplays the Change History String dialog box, from which you can change the string used when change history diaries are merged. See Change History options on page 69. Default Prefix OptionsDisplays the Prefix dialog box, from which you can change prefix information. See Performing Copy/Prefix migrations on page 103. Use Definition Files for BackupUse definition (.def) files as a backup file type. See Backup options on page 66. Use Migrator Files for BackupUse .migrator files as a backup file type. See Backup options on page 66. Back Up All Objects/Back Up Specific ObjectsEnables you to back up all files on a destination server, or selected files. See Backup options on page 66. Back Up DirectoryEnables you to select a directory for storage of backup files. See Backup options on page 66.
Modifying and removing objects in a script

Use the following procedures to modify objects in a script. You can change the source, destination, prefix options, or destination name. You can also remove an object from a script.
To change the source or destination in a script

1 In the Migration Script windows left pane, click AR System Objects. 2 In the right pane, click the object you want to modify. 3 Choose Objects > Change Source or Objects > Change Destination.
To change the prefix options in a script

1 In the right pane, click the object whose prefix options you want to change. 2 Choose Objects > Prefix Options. 112 BMC Remedy Migrator Guide
3 In the Prefix dialog box, change the options. See Performing Copy/Prefix
migrations on page 103.
To change the destination name

1 In the right pane, click the object whose destination name you want to change. 2 Choose Objects > Destination Name. 3 In the Destination Name dialog box, enter the new destination name.
To remove an object from a script

1 In the right pane, click the object you want to remove from the script. 2 Choose Objects > Remove Object. 3 In response to the prompt, click Yes to confirm the removal, or No to cancel it.
Adding Before or After commands and descriptions

Before and After commands enable you to add executable commands to a migration script, such as verifying that servers are running before a migration begins, sending email notifications related to a migration, or sending files to a remote server after a migration. Use the following procedure to add Before or After executable commands, or to add notes or a description to your scripted migration.
WARNING
If a script has a Before or After command (or both), the command must return a value of zero (0) for the script to work correctly. If the command returns any value other than zero, Migrator assumes that the command has failed. If the Before command fails, the execution of the script stops and no objects are migrated. If the After command fails, the objects will have been migrated.
To add descriptions and Before or After commands

1 If the Description window (located at the bottom of the Script window) is not open,
choose View > Description Bar.

Figure 8-5: Description bar for a migration script
2 (optional) Click the Description button and type a description for the command or
script.
3 Click the Before Command or After Command button and type a Run command line in the window (for executable file types such as .exe, .bat, or .com).
The Before command runs before a scripted migration occurs. The After command occurs after a scripted migration is complete.
Chapter 8 Working with migration scripts 113
4 Run the script to verify that the command you created works.
Scheduling scripted migrations

After you have created a migration script, you can set up a date and time for the migration to occur, as well as a user or group to notify upon completion. (Notifications are sent by way of the AR System Notification API and routed through the Alert system within the AR System server or other mechanism, depending on your configuration.) This is helpful for migrations that you perform regularly, during or after business hours. For example, you can schedule a scripted migration to run during off-peak hours when server usage is at a minimum. To test a scheduled migration script immediately, choose Script > Execute Migration Script.
IMPORTANT
If Migrator is not running when a migration script is scheduled to begin, Migrator starts the migration immediately the next time it is activated.
Scheduling migrations
Migrator uses the date and time on the client machine for running scheduled migrations. Migrator must also be running at the scheduled time for the migration to start.
To schedule a scripted migration

1 Choose Script > Schedule Migration Script. 2 In the calendar, click the button to the right of the Migration Script field. 3 In the dialog box, select a saved Migrator script file, and click Open. 4 In the calendar, use the arrows to select a month and then click a date on the
calendar for the migration to take place. Use the > and < buttons to change the month. Use the >> and << buttons to change the year.
114
Scheduling scripted migrations
Figure 8-6: Scheduling a migration
5 In the Time to schedule field, enter or select the hour and minute at which the
migration should begin.

6 (optional) In the Notify User on Completion text box, enter a user or group to
notify on completion. Migrator interfaces with AR System by way of the Application Programming Interface (API), which must first be set up to send the type of notification you want to use.
7 Click OK.
The scheduled migration appears in the migration status pane of the Script window.
Changing an existing migration schedule

Use the following procedure to change an existing migration schedule.
To change an existing migration schedule

1 In the migration status pane of the Script window, click the Scheduled tab and
select the scheduled migration you want to change.

2 Choose Script > Edit Scheduled Migration to display the Schedule Item dialog box. 3 Make any of the following changes:
In the calendar, select a month, and then click a date on the calendar for the migration to take place. In the Time to Schedule text box, select the hour and minute you want the migration to begin. (optional) In the Notify User on Completion text box, type in a user or group to notify on completion. Migrator interfaces with the AR System by way of the Application Programming Interface (API), which must first be set up to send the type of notification you want to use.
4 Click OK.
115
116
Chapter
Dependency reports
This section describes how to create, use, and customize Dependency reports. The following topics are provided: Overview of Dependency reports (page 118) Working with Dependency reports (page 120) Creating and using Dependency reports (page 120) Customizing a Dependency report (page 122)
Chapter 9 Dependency reports
117
Overview of Dependency reports

A Dependency report shows the interdependencies between workflow objects, and helps you determine which workflow objects are required by a specific workflow object. For example, Dependency reports determine what should be moved to a production (destination) machine to ensure that the application is migrated to the correct destination. The Dependency report is divided first into servers, then direct and indirect dependencies, then into object types. When creating a report using packing lists, the Dependency report goes outside a packing list and finds all dependent objects. A Migrator Dependency report shows upward or downward object dependencies. Upward DependenciesDisplays a list of objects that require the specified object. For example, if you generate an upward dependency report for a form, the report lists the active links, filters, escalations, and other objects that use that form. If you generate an upward dependency report for groups or roles, the report lists the forms or other server objects that use those groups and roles. Downward DependenciesDisplays a list of objects that the specified object requires. When a downward dependency report is created for a form, the objects for that form are not displayed in the report. When a downward dependency report is created for a form and related objects, the objects are displayed.
118
Overview of Dependency reports
Figure 9-1: Dependency report example (partial view)
The report display lists direct and indirect dependencies for the selected objects: Direct dependencies include those objects that are required by the object for which the report is generated. For example, the dependency report for the Administrator Preferences form lists the menus and groups that comprise the direct dependencies. For a packing list, direct dependencies would include all of the objects included in the packing list. Indirect dependencies include those objects required by objects listed in the Direct Dependency list.
119
Working with Dependency reports

You can view object dependencies before and after a migration to make sure you migrate all dependent objects and to verify that the correct objects exist on the correct server. You can migrate from the report view, as well as save or print the report. Table 9-1 outlines some techniques to use when working with Dependency reports:
Table 9-1: Options for working with Dependency reports To do this Resize a report Take this action Choose View > Zoom and enter a percentage to shrink or enlarge the report. This zoom percentage is also used when printing the report. Choose Tools > Options (see Customizing a Dependency report on page 122). Right-click in the right pane of the Dependency report window to display the options menu. Select the report window and press F5. Double-click a Migrator file to launch a report from its saved location. Choose Edit > Copy. Open the other application and choose Edit > Paste. You cannot edit this file. Drag the object starting at the source view (the server window used to select the workflow objects). Select the object name in the tree view (left pane). You can also left-click once on an object in the list view to select the object in the tree view.
Select colors Select migration and printing options Refresh dependency report information Display an object in a report in Migrator Create an image of the report to view in another application Add new object to a report Scroll to an object in the list view (right pane)
Creating and using Dependency reports

To create a Dependency report
1 Click the object type under AR System Objects in the left pane of a server window. 2 In the right pane, select the objects you want to review.
To select more than one object, hold down the Ctrl or Shift key when making your selections.
3 Right-click your selection to display a pop-up menu, or choose the View menu. 4 Choose Downward Dependencies or Upward Dependencies to display the
Dependency report in a window. The object dependencies are shown in the default colors or the colors you selected from the Dependency report options.
Creating and using Dependency reports
Viewing a Dependency report

When viewing Dependency reports, you can resize the report to fit your workspace. Choose View > Zoom, and enter a percentage to shrink or enlarge the report. If you need more viewing space, hide the migration status pane. Objects in the right pane are listed in the same order as they appear in the left pane. In the list view of the Dependency report, dependent objects are listed in alphabetical order within each server listing. For migrations, servers are also listed in alphabetical order. Objects listed in the report as Unable to locate object objectName on server and Object objectName lies on server. Unable to retrieve information. might be residing on a different server or might be missing. If there is more than one server referenced in the report, these servers are listed in alphabetical order.
Saving a Dependency report

To save a Dependency report
1 Right-click the Dependency report you want to save. 2 Choose File > Save As to display the Save As dialog box. 3 Select a destination path and type a file name, being sure to save the file as a .mgrtdep file. 4 Click Save.
Printing a Dependency report

When printing an active report, use the zoom percentage to size the report to fit your paper dimensions. Choose View > Zoom and then enter a percentage to shrink or enlarge the report. For information about changing the colors in a report before printing, see Customizing a Dependency report on page 122.
To print a Dependency report

1 Choose File > Print. 2 From the Print dialog box, select a printer, and click OK.
The report is printed in the same format as it is viewed on your screen.
121
To create an HTML file from a Dependency report

1 Choose File > Export to HTML. 2 Select a directory path where you want the file saved, and enter a file name. 3 Click Save. 4 Open the saved HTML file in any HTML editor to print, edit, or reformat the
report.
Migrating dependent objects from a Dependency report

To migrate dependent objects
1 Choose Migrate > Migration Mode. 2 From the Migrate menu, choose the type of dependency migration you want to
perform. For example, you can migrate All AR System Objects and Dependencies or All Forms and Dependencies.
3 In the Destination Type dialog box, select the destination type by clicking Server
or Migrator File.
a If you click Server, select the destination server, and click OK. The source server
is always the server window you have activated at the time of the migration. The objects you choose are migrated to the destination server you selected.
b If you click Migrator File, choose the destination path, enter a file name, and
click Save.
4 If you are prompted to proceed with the migration, select Yes.
Customizing a Dependency report

Migrator uses colors to correlate objects that are dependent on the specified objects. You can customize a Dependency report by selecting object colors.
To select color options for Dependency reports

1 Choose Tools > Options to open the Migrator Options dialog box. 2 Under Category, select Dependencies > Colors.
122
Customizing a Dependency report
Figure 9-2: Selecting dependencies color options
3 For each object dependency to be correlated (for example, all forms that are
dependent on each other):

a Click the object type. b From the color picker, click the box for the color you want. c Click OK. 4 Click OK to save your selections.
123
124
10
Chapter
Differences reports
This section describes how to create and use Differences reports, and discusses the benefits of working with them. It also supplies information about how to customize Differences reports. The following topics are provided: Overview of Differences reports (page 126) Working with Differences reports (page 129) Creating and using Differences reports (page 130) Customizing a Differences report (page 133)
Chapter 10 Differences reports
125
Overview of Differences reports

Differences reports compare objects between source and destination. You can identify object differences and migrate all differences, or only specified differences. You can use differences reports to compare objects between two servers, between a server and a .migrator file, or between two .migrator files. The Differences report provides two report views: Comparison and Object Details. You can switch between the views by clicking the tabs at the bottom of the report. The following sections explain each view.
Comparison view
By default, the Comparison tab view appears when you create a Differences report. The Comparison view provides the following information: Main settingsThe names of the source and destination file or servers Created onThe date and time the report was created Total resultsFor the items being compared, the number of objects that are the same, the number of objects with differences, the number of missing objects, and the total number of objects being compared. The remainder of the report provides details about each type of object (for example, regular forms, vendor forms, or menus). For each object, the report specifies: The name of the destination object The results (either the same as the destination or different) Action requiredWhat needs to be done to resolve the differences Source timestamp and destination timestampThe time stamps for the source and destination Destination modified statusWhether the destination is newer or the same.
NOTE
When comparing application objects that contain different workflow objects, the Differences report does not show differences among those applications. This is because applications do not actually contain objects in them; they only contain references to those objects. Applications are standalone objects similar to other AR System objects.
126
Overview of Differences reports
Figure 10-1: Differences Report comparison view
Object Details view

The Object Details tab view lists the details of each object being compared. For objects that have changed, the name of the user who made the change, and the date and time of the change, are displayed. Information for the source appears on the left; information for the destination appears on the right. You can change the color settings for the Differences report. See Differences color options on page 134.
127
Figure 10-2: Differences report Object Details view
NOTE
The AR System and Migrator use field IDs, not field names, to determine differences between source and destination environments. For example, if the source form has a field name of Field_ABC, and the destination form has a field name of Field_XYZ, with the same field ID, Migrator replaces instances of the form Field_XYZ with Field_ABC on the destination server.
NOTE
For objects with a lock type of Hidden, the object details are not displayed. You can view object differences before and after a migration to make sure you migrate all the objects correctly. You can also migrate from the report view, and save or print the report.
128
Working with Differences reports
Working with Differences reports

You can use these techniques when working with Differences reports.
Table 10-1: Working with Differences reports To do this Customize what a report displays Resize a report to your screen Take this action Choose Tools > Options, open the Differences tree view, and select the Display option. Choose View > Zoom and enter a percentage to shrink or enlarge the report. This zoom percentage can also be used when printing a report. Choose Tools > Options. See Customizing a Differences report on page 133. Right-click in the right pane of a Differences report window and choose options from the menu. Select the report window and press F5. Select the saved report from the directory where it is stored, and double-click to open it. Choose Edit > Copy. Open the other application and choose Edit > Paste. You cannot edit the copied file. Drag the object from the source server or form detail list view. Select the object name in the tree view left pane. You can also click once on an object in the list view to select the object in the tree view. Right-click the objects and select Differences.
Select colors for reports Select migration and printing options Refresh Differences report information Display a previously saved Differences report Create an image of the report to view in another application Add new object to a report Scroll to an object in the list view (right pane) Compare objects between servers, between .migrator files, between a server and a .migrator file, or between two objects on the same server
Put forms and related objects into a Select them and hold down the Ctrl key as you drag Differences report the objects into the report. Navigate between differences and Click the Previous or Next Differences icons (yellow missing items icons with red arrows) or Previous or Next Missing icons (yellow icons with blue arrows) in the toolbar.
129
Creating and using Differences reports

You can use a Differences report before a migration to see which objects are different and might need to be corrected. After a migration, you can use the report to verify which objects migrated correctly.
NOTE
If some items still show up in the Differences report as separate, verify that the migration mask options for the problem items have been set correctly.
To review object differences in a new Differences report

1 Open the window or windows from which you want to obtain differences
information.
2 Choose File > New Differences Window.
A new window appears with a blank Differences report.

3 Select the objects you want to include, and drag them to the new Differences
window.
4 In the Destination Type dialog box, select a destination, either a server or a .migrator file. a If you select Server, choose a server name from the Select Destination Server list.
If you choose the same server as your destination server, the Prefix dialog box appears. Enter a prefix name, and click OK.
b If you select Migrator file, choose a .migrator file from the list that appears. 5 To save the Differences report, choose File > Save, and enter a file name.
The file is saved as a .mgrdif file.
To review object differences by selecting object types

1 In the left pane of a window, click the object type under AR System Objects. 2 In the right pane of the window, select the specific objects you want to review. 3 Right-click your selection and choose Differences from the menu, or choose View
> Differences.
4 Select a destination, either a server or a .migrator file. a If you select Server, choose a server name from the Select Destination Server list.
If you choose the same server as your destination server, the Prefix dialog box appears. Enter a prefix name, and click OK.
b If you choose Migrator file, select a .migrator file from the list that appears.
The Differences report appears.

5 To save the report, choose File > Save, and enter a file name.
130
Creating and using Differences reports
Viewing a Differences report

You can change the size of a difference report to fit your workspace. Choose View > Zoom, and enter a percentage to shrink or enlarge the report.
NOTE
Clicking the Object Details tab does not display anything. To view object details, first click on and open the AR System Objects left pane and double-click an object to show its detail in the right pane. This action opens the Object Details tab. You can look at fields and views all the way to their base level by clicking down into the Report tree view. Also, right-clicking a field or view from the Report tree view displays a pop-up menu with the option to Show Object Details. For example, when comparing forms, to view field level differences in a report, expand the Forms tree view and right-click to select Show Object Details. You can then doubleclick a specific field in the list view to see a more detailed set of differences.
Figure 10-3: Differences report tree view
Saving a Differences report

To save a Differences report
1 Right-click the Differences report you want to save. 2 Choose File > Save As. 3 In the Save As dialog box, enter or select a destination path and a file name, being sure to save the file as a .mgrdif file. 4 Click Save.
131
Printing a Differences report

When printing an active report, you change the size of the report to fit your paper dimensions. Choose View > Zoom, then enter a percentage to shrink or enlarge the report. To change colors when viewing or printing a Differences report, choose Tools > Options. For information about changing the colors in a report, see Customizing a Differences report on page 133. You can print a Differences report using either of the following methods: By printing the report in the same format as viewed on your screen By exporting the report to HTML
To print a Differences report

1 Choose File > Print. 2 From the Print dialog box, select a printer. 3 Click OK.
To export a Differences report to HTML

1 Choose File > Export to HTML. 2 Select a directory path where you want the file saved, and enter a file name. 3 Click Save. 4 Open the saved HTML file in any HTML editor to print, edit, or reformat the
report.
Migrating differing objects

When migrating objects in a Differences report, only those objects that differ between the source and the destination, or that are missing on the destination, are migrated.
To migrate differing objects

1 Choose Migrate > Migration Mode. 2 From the Migrate menu, click the type of Differences migration you want to
perform. For example, you can migrate All Different AR System Objects or Selected Object.
3 When the migration is finished, press F5 to refresh the report display.
132
Customizing a Differences report

Table 10-2 lists ways you can customize the display, color, and masking options in a Differences report.
Table 10-2: Customizing options for a Differences report Option Display Colors What it does Specifies whether to display all objects that are the same, different, or missing. Establishes the colors for differentiating between objects. The default colors are: Greenobjects that are the same Redobjects that are different BlueObjects missing on the destination Graytable headers Masks Specifies which object properties are to be compared when generating, viewing, or printing a Differences report.
Differences display options

Using the Differences display options, you choose which objects to display in a Differences report. The default setting for the display options is set to all options checked.
To select display options for Differences reports

1 Choose Tools > Options to display the Migrator Options dialog box. 2 Under Category, click Differences, and select Display. Figure 10-4: Differences report display options
3 Select which objects to display:
All objects that are the same All different objects All missing objects
4 Click OK.
133
Differences color options

Using the differences color options, you choose the colors for comparing objects in a Differences report.
To select color options for Differences reports

1 Choose Tools > Options to display the Migrator Options dialog box. 2 Under Category, open the Differences and select Colors. Figure 10-5: Differences color options
3 For each object difference category, click the arrow to the right of the color box and
select a color, or accept the default colors shown: Green for displaying all objects that are the same. Red for displaying all different objects. Blue for displaying all missing objects. Gray for tables.
4 Click OK.
Mask options
Mask options enable you specify object properties that are compared when generating, viewing, or printing a Differences report. If the option is enabled for an object property, it is compared in the Differences report; if disabled, the object property is not compared and appears as the same in the Differences report.
NOTE
If the mask option for an object property is disabled, the detailed Differences report displays the header for that property group in green color regardless of the actual difference in the value of that property. Even though the mask option for that object property is disabled, a red X symbol is displayed against the property if its values differ, otherwise a green check mark is displayed. If you change the options while a report is open, you can refresh the report display by pressing F5. You can synchronize the Differences report mask settings so that they match those for migration mask settings.
To select mask options in Differences reports

1 Choose Tools > Options to display the Migrator Options dialog box. 2 Under Category, click Differences, and select any of the object types listed in
Table 10-3 to display the Differences mask options.

Table 10-3: Options for comparing preferences for Differences reports Choose this option Forms Fields Views Active Links Filters Escalations Containers Menus Distributed Maps To compare Form properties (Opens field and view properties.) Field properties View properties Active link properties Filter properties Escalation properties Application, guide, packing list, and web services properties (including application state) Character menu properties Distributed maps properties
Note: Migrator does not migrate DSO fields, only DSO
maps. Plug-in modules Plug-in definitions Distributed Pools Flashboards Flashboards Data Sources Flashboards Variables Flashboards Alarms Properties of plug-in modules Plug-in definitions Pools (threads) pending distributed operations Flashboards, Flashboards data source, Flashboards variable, and Flashboards alarm properties (depending on whether you own and have installed the BMC Remedy Flashboards 5.0 or later)
135
Figure 10-6: Differences report mask options
To change a mask option, click on the object type, and select Enabled or Disabled from the menu.
3 Select the object properties that you want to compare on the report.
To change an option, click the name, and select Enabled or Disabled from the dropdown list.
4 Click OK.
To set the Mask options back to the Migrator defaults, click Set Default. To cancel your changes, click Cancel.
To synchronize settings with migration mask settings

Click the Synchronize Migration Masks button.
136
11
Chapter
Migration Result reports
This section describes how to create, view, and customize Migration Result reports. The following topics are provided: Overview of Migration Result reports (page 138) Working with Migration Result reports (page 139) Customizing a Migration Result report (page 141)
Chapter 11 Migration Result reports
137
Overview of Migration Result reports

Migration Result reports provide details about how a migration performed: the start and end times, the source and destination points, what was migrated, the options that were in place at the time of the migration, and so on.
Figure 11-1: Migration Result report
138
Working with Migration Result reports
The Results report includes these categories: Overall migration statisticsData that pertains to the entire migration, including name of the report, the date and time at which it was generated, the version of Migrator used, the status of the migration (whether it was completed or interrupted), and the number of objects of each type that were migrated and (if any) failed to migrate. The settings selected for the migration, including the server used for the migration, change history settings, and any prefixes that were selected to be ignored for the migration. Statistics for each type of object included in the migration, including migration results and workflow changes, if any. Information from the source is listed on the left side of the report; information for the destination is listed on the right side. Icons in the first column indicate whether or not the migration was successful. A green check mark indicates that the object was migrated successfully. A red X indicates that errors occurred during the migration. A yellow Yield sign indicates a warning. A green arrow pointing to the right indicates that the object is still in the queue to be migrated.
Working with Migration Result reports

A Migration Result report shows statistical information about a completed migration. Migrator saves the report automatically. Table 11-1 outlines some options available when working with Migration Result reports.
Table 11-1: Options for working with Migration Result reports To Do this
Resize a Migration Result report to Choose View > Zoom and enter a percentage to your screen shrink or enlarge the report. This zoom percentage is also used when printing a report. Select colors Display an object type in a report Create an image of the report to view in another application Choose Tools > Options (see Customizing a Migration Result report on page 141). Double-click a Migrator file to launch a report from its saved location. Choose Edit > Copy. Open the other application and choose Edit > Paste. You cannot edit this file.
139
Viewing a Migration Result report

To view a Migration Result report
1 In the migration status pane, click the Completed status tab to find the migration
you are looking for.

2 Double-click the migration whose report you want to view.
Migrator generates and displays the Migration Result report. Migrator stores migration result reports in a Results File directory, which you can access from the left pane of the window.
Saving or removing a Migration Result report

Migrator automatically saves a Migration Result report on completion of a migration. You can view the report from the Migration status pane.
Saving a Migration Result report

After Migrator performs a migration, the saved Migration Result report appears by name in the Migration status pane under the Completed tab until you remove it. If the Directories option is set to the default for migration results, Migrator also saves the Migration Result report in the Result Files folder, located in the left pane of the server or file window.
Removing a Migration Result report

To remove a Migration Result report
1 Open the Migration status pane. 2 Select the Completed tab. 3 Right-click the report you want to remove, and choose Delete Migration.
Removing the Migration Result report within the migration status pane also removes the report from the Result Files folder.
Printing a Migration Result report

When printing a Migration Result report, you can change the report size to fit your paper dimensions. Choose View > Zoom, then enter a percentage to shrink or enlarge the report. Set the viewing or printing colors in a Migration Result report from the Tools menu under Options. For information about changing the colors in a result report, see Customizing a Migration Result report on page 141.
140
Customizing a Migration Result report
You can print a Migration Result report using either of the following methods: By printing the report in the same format as viewed on your screen By exporting the report to HTML
To print a Migration Result report

1 Choose File > Print in the report window. 2 In the Print dialog box, select a printer. 3 Click OK.
To export a Migration Result report to HTML

1 Choose File > Export to HTML. 2 Select a directory path, type a file name, and click Save. 3 Open the saved HTML file in any HTML editor to print, edit, or reformat the
report.

You can customize a Migration Result report using the Migration Results options. The Migration Results category is listed on the left pane of the dialog box. For migration statistics reports, you can select these migration result options: DisplaySpecifies which types of objects to show or hide in a report. ColorsSets the colors for displaying migration results.
Result display options

The result display options enable you to make a Migration Result report as detailed or as simple as you like, depending on the type of migration result statistics you need.
To select display options for Migration Result reports

1 Choose Tools > Options to open the Migrator Options dialog box. 2 Under Category, select Migration Results > Display.
141
Figure 11-2: Migration Results display options
To set an option, click the item, then select Show or Hide from the drop-down list.
3 To select the options for each item, click the item name, then select Show or Hide
from the drop-down list.

4 Click OK.
Result color options

The result color options enable you to choose colors for tables in a Migration Result report.
To select color options for Migration Result reports

1 Choose Tools > Options to open the Migrator Options dialog box. 2 Under Category, select Migration Results > Colors. Figure 11-3: Result color options
To change a color, click on the option name, and select a color from the color picker.
142
3 For each server object for which you want to change the color: a Click the object name. b From the color picker that appears, select a color, and click OK. 4 Click OK.
143
144
12
Chapter
Source Control
This section defines and describes how to use the Source Control (SC) integration feature in Migrator. This section assumes that you are already familiar with your SC system and that you understand how your SC database operates. It also assumes that you have enabled SC functionality in AR System and are familiar with its operation. The following topics are provided: Overview of Source Control (page 146) Starting SC in Migrator (page 146) Working with SC in Migrator (page 147)
Chapter 12
Source Control
145
Overview of Source Control

Migrator Source Control (SC) functions in the same way that the AR System SC functions, except that Migrator can generate differences reports between objects under SC. If SC is enabled AR System (Enforced mode enabled), Migrator can also enable SC. See the Configuration Guide.
NOTE
Source Control in this version of Migrator is not the version control used by the AR System 7.6.04 server. It is used only with AR System 7.5x and earlier servers. SC is a standard that was developed for tools to interface to Source Control systems (such as Microsoft Visual SourceSafe, PVCS, CM Synergy, and so on). Migrator provides an interface to the SC system so it can talk to these tools. This allows you to save your work with version numbers and checkin and checkout capability. The checkin and checkout capability lets teams share an application without overwriting each others work. Migrator migrates an object and replaces it within the Source Control system if: The object is checked in to SC. The object is checked out by the same user who is performing the migration. If the object is checked out by a user other than the user who is performing the migration, the object is not migrated. Since SC migration is multi-byte, all Unicode items are converted to multi-byte and back when working with SC.
Starting SC in Migrator
SC integration in Migrator is essentially the same as that in AR System. The one exception is that Migrator can compare the differences between SC objects using the Migrator differences report.
Figure 12-1: Migrator SC Options
146
Working with SC in Migrator
To generate a differences report for SC, choose Tools > Source Control > Show Differences. For information about working with differences reports, see Chapter 10, Differences reports.
NOTE
Groups, Data, DSO Maps, Fields, and Views cannot be added to SC.
To start and use SC in Migrator

1 Verify that you have SC enabled AR System for a particular server by viewing the
server window to see if SC columns are displayed.

2 Choose Tools > Source Control to display the Migrator SC options, or use the
Source Control toolbar.

The Migrator SC menu and toolbar buttons enable you to perform standard SC functions. You can also check out objects, convert them from a.def file to a .migrator file, and generate a differences report. The SC login box requests your name and password only when you log in for the first time. To verify that Migrator integrates to your Source Control systems application, view a window within Migrator. If SC is functioning, the following columns appear in the Migrator Server, Form Detail, and Script windows. Source control information in Migrator windows
Table 12-1: Source control information in Migrator windows Column heading In SC Checked Out By User SC Last Modified By SC Timestamp Description Verifies if the object is in SC. This heading only appears in a SC window. States who has the object checked out. States who last modified the object. States when an object was last accessed.
If you see a check mark over an objects icon, that object has been checked out. Migrator remembers column settings for the next viewing (see Rearranging window columns on page 41).
Chapter 12
Source Control
147
Table 12-2 lists and describes the functions available from the Migrator SC toolbar.
Table 12-2: Source control icons in Migrator SC toolbar (Sheet 1 of 2) Migrator SC icon Get Latest Version Description Retrieves the latest definition file for the object being checked into SC and imports it to a server. When you get an object, you are retrieving a copy. The file is not locked from other system administrators. Checks the file back into SC. If Enforced mode is enabled in AR System and you check in an object, the file is no longer locked and other system administrators can use it or modify it. If Enforced mode is disabled, more than one user can check in an object at the same time. Checks a file out of SC. If Enforced mode is enabled in AR System and you check out an object, the file is locked and no other system administrator can modify it. If Enforced mode is disabled, more than one user can check out an object at the same time. Overrides objects that have been checked out by someone else. You must have a working folder set in your SC client for this command to work properly. The file is no longer locked and the previous version is retained in the SC project. Adds the objects to the SC database. The file is archived in the SC project.
Check In
Check Out
Undo Check Out
Add to Source Control
Remove from Source Control
Removes the objects from SC.

Note: Removing files from SC does not remove them
from the server. Show History Shows the history of objects selected in the SC integration. History reports summarize information about revisions of the objects.
Show Differences
Checks out objects, converts them to a .migrator file, and generates a differences report. See Chapter 10, Differences reports.
User Information
Displays user information about administrators of the SC database.
148
Table 12-2: Source control icons in Migrator SC toolbar (Sheet 2 of 2) Migrator SC icon Refresh Status Description Refreshes the current status information of an object from the SC database.
Run Source Control Client
Runs the SC system client.
Chapter 12
Source Control
149
150
13
Chapter
Support for overlays and custom objects

This chapter describes how Migrator supports operations on the AR System overlays and custom objects. The following topics are provided: Operations on overlays and custom objects (page 152) Comparing objects at the same location (page 153) Migration of overlays and custom objects (page 155)
Chapter 13
151
Operations on overlays and custom objects

Beginning with release 7.6.04, BMC Remedy Migrator caches overlays and custom objects along with all origin AR System objects and displays them in the objects list. For example, if an overlay (ALI1__o) exists for an active link (AL1), BMC Remedy Migrator caches both these active links because they are valid AR System server objects. It displays both AL1 and AL1__o in the objects list of the server. BMC Remedy Migrator also enables you to perform the following operations: Compare and migrate overlays and custom objects in the same manner as origin AR System objects. When migrating objects, BMC Remedy Migrator does not migrate the overlayProp and overlayGroup properties. These properties are managed by the server, and their values are set only when you create an overlay or a custom object. See the Database Reference, Columns for overlay and custom objects, page 34. Compare objects within the same file or on the same AR System server. See Comparing objects at the same location on page 153 Specify backup and masking options, and create migration scripts and dependency reports for overlays and custom objects as you would for origin AR System objects.
NOTE
Migrator provides migration and comparison masks for view and field properties. However, BMC recommends that you do not disable the migration masks. If you do so, Migrator does not migrate overlays and custom objects corresponding to view and field objects that you modified or added in your source setup. Migrate overlays and custom objects along with origin AR System objects. See Migration of overlays and custom objects on page 155. BMC Remedy Migrator supports these operations only for those objects that the AR System server supports. See the Form and Application Objects Guide, Permitted and non-permitted modifications on overlays, page 129.
152
Comparing objects at the same location
Comparing objects at the same location

Beginning with release 7.6.04, you can compare objects that are the same type, exist in the same file or on the same AR System server, and have different names. For example, you can compare an object with its overlay if they exist on the same server.
NOTE
BMC Remedy Migrator does not yet support comparing objects that are the same type and have different names but exist in different locations.
To compare objects at the same location

1 In the objects list view of a file or an AR System server, select the objects that you
want to compare with other objects.

2 Select View > Differences > currentFileOrServerName.
The Source - Destination Mapping dialog box appears, as shown in Figure 13-1.
Figure 13-1: Source - Destination Mapping dialog box
Initially, the Destination Object Name column is empty.

3 Use one of the following methods to compare the source objects with other objects:
To compare overlay and origin objects in the same file or on the same server, perform one of the following actions: To compare origin objects with overlay objects, click the Map To Overlay button. Any overlay objects in the Source Object Name column are cleared. The names of the source objects suffixed with __o, which indicate the corresponding overlay objects, are populated in the Destination Object Name column.
Chapter 13
153
To compare origin objects with overlay objects, click the Map To Base button. Any origin objects in the Source Object Name column are cleared. The names of the source objects without the __o suffix, which indicate the corresponding origin objects, are populated in the Destination Object Name column.
NOTE
The Map To Overlay and Map To Base buttons are enabled only when comparing objects in a file or on an AR System 7.6.04 (or later) server. For overlaid objects, the difference report indicates the differences against their overlays. For unmodified objects, the difference report indicates that the corresponding overlays are missing. Change the values in Destination Object Name to the names of the objects that you want to compare with the source objects. For example, to compare two different active links (AL1 and AL2) on the same server:
a In the server objects list, select ALI1. b In the Source - Destination Mapping dialog box, enter AL2 in the Destination
Object Name column and click OK.
TIP
Edit the values in the Destination Object Name column only if you know the exact names of the objects that you want to compare. Otherwise, the difference report generated might not be of value. You cannot change the values in Source Object Name. Only the objects that you selected in the objects list are considered as source objects for comparison. Click the Prefix Dialog button to open the Prefix dialog box, where you can specify a prefix for the destination objects. See Creating and using Differences reports on page 130
4 Click OK.
BMC Remedy Migrator compares the objects and generates the difference report.
154
Migration of overlays and custom objects

This section describes situations that might occur when you attempt to migrate AR System overlays and custom objects, and how BMC Remedy Migrator handles those situations. Figure 13-2 on page 157 depicts the process that BMC Remedy Migrator follows for migrating overlays. As with origin AR System objects, you can migrate overlays and custom objects between the following locations: From one AR System server to another From an AR System server to a file From a file to an AR System server From one file to another
NOTE
When the destination location is a file, BMC Remedy Migrator updates it with the source objects, taking into consideration any masking options that you specify. It does not check whether overlaid or overlay objects are present at the destination.
Migrating overlays that exist at the destination

If you migrate an overlay from a source and that overlay exists at the destination, BMC Remedy Migrator overwrites the destination overlay. If you make changes to an overlaid object that are automatically reflected in its overlay, you cannot migrate only the overlay. You must migrate the overlaid object. The appropriate changes are automatically reflected in the overlay at the destination server.
Migrating overlays that do not exist at the destination

If you try to migrate an overlay from a source and that overlay does not exist at the destination, BMC Remedy Migrator checks whether the corresponding overlaid object exists at the destination server. If the overlaid object exists, BMC Remedy Migrator migrates the overlay. Consider this example. The source server contains an active link (AL1) and its overlay (AL1__o). The destination server contains only the unmodified object, AL1. If you try to migrate AL1__o, BMC Remedy Migrator migrates AL1__o.
Migrating overlays when corresponding overlaid objects do not exist at destination

If you try to migrate an overlay when the corresponding overlaid object is not present at the destination server, BMC Remedy Migrator attempts to migrate the overlay. However, the AR System server returns an error. BMC Remedy Migrator includes the error message in the result report, and continues its processing.
Chapter 13 Support for overlays and custom objects 155
Consider this example. An active link (AL1) and its overlay (AL1__o) exist at the source. Neither of these objects exists at the destination. When BMC Remedy Migrator attempts to migrate AL1__o, the destination AR System server does not create the overlay because the corresponding overlaid object does not exist.
Migrating origin objects for which overlays exist at the destination

If you try to migrate an origin AR System object for which a corresponding overlay exists at the destination, BMC Remedy Migrator migrates the origin object. The destination AR System server then evaluates the differences and updates the corresponding overlay with only the permitted modifications. See the Form and Application Objects Guide, Permitted and non-permitted modifications on overlays, page 129. If you try to migrate an overlaid form and all its related objects, BMC Remedy Migrator migrates the form, its objects, and their corresponding overlays, but does not migrate the overlay form. You must explicitly select the overlay that you want to migrate with its overlaid form.
Migrating objects from pre-7.6.04 AR System servers

If you try to migrate objects from an earlier version of the AR System server to an AR System 7.6.04 server, BMC Remedy Migrator migrates the origin objects but does not modify any overlays or custom objects.
Migrating objects from AR System server 7.6.04

If you try to migrate objects from an AR System 7.6.04 server to an earlier AR System server version, BMC Remedy Migrator: Migrates unmodified objects. Migrates custom and overlaid objects. However, it does not migrate the properties that indicate whether an object is custom or overlaid, because the properties are not supported on the earlier server version. Attempts to migrate overlays, but fails because the destination server does not support overlays.
156
Figure 13-2: Migration process for overlays

Start
User selects multiple AR System objects including base (overlaid and unmodified) and overlay objects
For each selected object: Is it an overlay object? Yes
No
Create or replace the object at the destination server by using a predefined migration process
Is the overlay present at the destination server?
No
Migrate the overlay to the destination server
Yes Replace the overlay at the destination server Was the overlay migrated successfully? No
Yes Add the result to the result report Add the error to the result report
Were all selected objects migrated?
No
Yes
End
Chapter 13
157
158
Appendix
Migrator command-line interface

This appendix discusses the Migrator command-line interface. The following topics are provided: Overview (page 160) XML files for processing commands (page 161) Logging (page 162) Command line options (page 162) Metadata mappings and CMDB (page 165) Metadata mappings and BMC Remedy ITSM (page 170) Examples of CLI migration commands (page 173)
Appendix A
159
Overview
The command-line interface (CLI) is a standalone application that delivers Migrator functionality without a graphical interface. You can use the command line to set migration options, migrate objects and data, compare information between migrations, and generate difference reports. In addition, you can use the CLI to compare information, including data and between migrations (which you cannot do with the graphic user interface). The Migrator CLI can be useful when performance is critical for large migrations or when making a quick comparison of objects to determine what to include in a patch release. Because the CLI does not require a lengthy caching process, you can perform migrations or comparisons of large files more quickly. The CLI also provides Configuration Management Database (CMDB) and IT Service Management (ITSM) support. CMDB support enables application developers to supply a class name from which Migrator can determine the required data and AR System objects that make up that class name. The ITSM mapping document includes support for mapping to an entry ID as a foreign key, and the ability to inject data during a migration. The CLI application, migratorcli.exe, is stored in the same directory as the main Migrator product at installation. The Migrator CLI currently supports a single-thread design, but you can supply multiple instructions within a single migration. The CLI provides full support for object reservation to ensure that Migrator either ignores newer or reserved objects on the destination, or blocks their update, depending on requirements. Migrations using the CLI are executed in the same order as in the graphic user interface (GUI), using the same processes. Backups can be configured using the Configuration file. The Migrator CLI can generate both Differences and Results reports; however, Results reports are the only reports generated through the CLI that can be opened in the Migrator GUI.
NOTE
Because the CLI does not use the Windows registry, any options you set through the GUI are ignored in the CLI.
160
XML files for processing commands
XML files for processing commands

The Migrator CLI uses four types of XML files as instruction sets to identify migration options and execute the migration or reporting specified. These files are included in the command-line sequence. You can use third-party XML editors to work with these files. Table A-1 lists and describes these files.
NOTE
The source and destination are not stored in any of these XML files. As a result, these files can be reused as needed for comparisons or difference reporting.
Table A-1: XML files used in Migrator command-line interface XML file Package Configuration Migrator CLI function Can be used to assemble multiple sets of instructions within one migration. Specifies migration, logging, mask, differences, change history, backup, and prefix options. For more information about options, see Options. Contains a single set of instructions for a migration. With the compare command, this file also can contain multiple named sets where the name is used to name the result file as well as the difference file. Enables migration of all objects found to be different or missing between source and destination. Used for migrations that include CMDB and ITSM.
Instruction
Difference Metadata mapping
The Migrator CLI also makes XSD schema files available that can be used to validate XML documents.
Appendix A
161
Figure A-1: How Migrator uses XML interpreters
Logging
When commands are executed through the command line, Migrator can generate log files that are stored in the Migrator directory. You can specify logging options such as the level of detail for log files and well as their format (such as plain text, XML, or HTML). The logging structure is based on the Apache logging design.
Command line options

Table A-2 describes the command options available through the Migrator CLI. Many commands provide a choice of two formats: abbreviated (a dash and a single letter), or detailed (two dashes and a descriptive string).
Table A-2: Migration commands and options (Sheet 1 of 4) Abbreviated Detailed -s -d --source --destination Function The server or file serving as the source. The server or file serving as the destination.
162
Command line options
Table A-2: Migration commands and options (Sheet 2 of 4) Abbreviated Detailed -e -q --sourceForm --qualification --count Function For data migrations, the start of a data block that determines the data to be compared or migrated. A string that represents the qualification used to obtain the data. The maximum number of items retrieved in a migration. When this count is reached, no further comparisons or migrations take place. A count of zero is the same as having no limit. Specifies use of the List port on the source, if the source is a server. The port number is the List port. Specifies the use of the Fast port on the destination, if the destination is a server. The integer value that uniquely identifies a field. By default, the ID is 1 for the entry ID, but can be changed to some other unique value, which is usually associated with a unique index on the same field for the form being migrated. Specifies whether related workflow should be disabled in the target form during a migration. The name of the file (.arm or .armx) that contains field mappings, if field mapping is enabled for this data migration. If a package XML file is included in this migration, the name of the file. The user name required to log in to the server. The default user name is Demo for both source and destination. The user name required, if any, for logging into the destination. If a user name is not specified with this command, Migrator defaults to the -u or the --user command. The password required, if any, for logging into the server. The default is (no password) for both source and destination. If a password is not specified, the command is ignored. The password required, if any, for logging into a destination server. Migrator defaults to the -p or -- password command if no password is specified for this command. The authentication, if any, used to log in to the server. The default is (no authentication). If no authentication is required, this command is not required. The TCP port number, if any, for connection to the AR System server. Appendix A Migrator command-line interface 163
--list
--fast --fieldid
--disable --fieldmap
-p -u
--package --user
--dst_user
-p
--password
--dst_password
-a
--authentication
-t
--tccport
Table A-2: Migration commands and options (Sheet 3 of 4) Abbreviated Detailed -r --rcpport --dst_tcpport --dst_rcpport --layout Function The RCP port number, if any, used for connection to the AR System server. The TCP port number, if any, for connection to the destination server. The RCP port number, if any, used for connection to the destination server. The format used for the generated log files. The options are: 0: XML 1: HTML 2: Simple 3: Console --level The level of detail to be provided in generated log files. The options are: 0: Off 1: Fatal 2: Error 3: Warning 4: Information (default) 5: Debug --logfile The name of the log file generated if the specified layout is HTML or XML. Ignored for Simple layout type. Migrate all specified instructions from source to destination. Compare all instructions specified between source and destination. With this command, you can specify what is to be compared with the following flags: -- different: items that are different -- same: items that are the same -- missing: items that are missing -g --configure --instruction
--xslt
-m -c
--migrate --compare
The name of the configuration XML file used in the command. The name of the instruction XML file used in the command. The name of the XSLT transformer file used to transform Difference reports from .xml format to any format you specify (such as HTML).
164
Metadata mappings and CMDB
Table A-2: Migration commands and options (Sheet 4 of 4) Abbreviated Detailed

--xsltx
Function The file extension to be applied to the transformed file. Defaults to '.html' if an extension is not specified. The type of object to be migrated. To migrate objects of a specific type, enter the object type in the command line, followed by either two empty quotes () to migrate all objects of that type, or the actual name of the object.
--form --activelink --filter --escalation --activelinkguide --filterguide --application --packinglist --webservice --menu --dsomap --dsopool --flashboard --alarm --variable --image --pluginmodeule --plugindefinition --metadata

The Migrator CLI includes metadata mappings to support CMDB and Atrium applications. These mappings are defined as XML elements and can be specified in the CMDBMetaData.xml and CMDBMetaDataEnableDelete.xml files, described in Mapping files on page 166. For more information about working with CMDB and Atrium applications, see the Atrium core documentation.
IMPORTANT
To prevent possible problems with migrations, be sure that both the source and destination are using the same CMDB version. Also, because Migrator does not back up metadata, migrate critical files to a .migrator file first for safekeeping. You can then restore these items by migrating from the source backup file to the destination.
Appendix A
165
Mapping files
The following mapping files contain the actual mapping details and define how the various CMDB forms relate to each other:
CMDBMetaData.xmlWhen this file is used, extra attributes and indexes that
are not found on the source are not deleted on the destination.
CMDBMetaDataEnableDelete.xmlWhen this file is used, Migrator performs a
full synchronization of source and destination, deleting any extra attributes and indexes on the destination that are not found on the source.
NOTE
When migrating or comparing CMDB classes, use the supplied CMDBConfiguration.xml file. This file is identical to the Migration Configuration file, with some different configuration options.
Mapping types
The mapping design consists of the following mapping types: AR System form-to-form data mappings AR System object mappings
Form-to-form data mappings

In form-to-form data mappings, you can map multiple forms to each other in the following relationships: one to one one to many many to many Within each of these relationships, you can define the fields used to link the entries from the forms. Every referenced form included in the mapping must be defined within the metadata mapping design.
Object mappings
In object mapping, you can define how one or more forms map to one or more objects, the object type (such as a form), and how the object name is calculated. For example, you might have a mapping includes this information for a field: Field 8 Text : Field 5364918
166
The field name would be calculated as: The contents of Field 8 + : + the contents of field 5364918. If Field 8 = Sample and field 5364918 = City, the field name would be calculated as Sample + : + City, or Sample:City.
Metadata XML document structure

The following section uses sample entries to explain the metadata XML document structure.
<meta-data xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation=Migration Meta Data.xsd>
The main root element can contain multiple <meta> items for each major metadata type, such as CMDB.
meta name
<meta name=CMDB identifier-form=OBJSTR:Class description=This is the meta-data for the CMDB application design> meta name is the root element for a specific meta-data design such as CMDB and contains all the form and object mappings that are specific to this element. meta nameThe name of the metadata item. It is used as the owner within the instruction XML document when attempting to migrate or compare metadata items within special items. identifier-formThe main form that contains the true name of the metadata. For CMDB, this is the form that contains the class name. This is known as the root form from which all other forms are mapped. descriptionText that describes the document.
form name
<form name=OBJSTR:Class unique-field-id=1 name-field-id=8 extends-form=form-name> form name identifies a specific form and how the data on that form relates to other definition forms or AR System objects or both. form nameThe name of the form on the AR System server. unique-field-idThe unique identifier for the field. By default, 1 is used. name-field-idThe field that contains the unique name of the entry. It is typically used only when the mapping item is the main identifying form. This is the field that is searched when a name is specified within the instruction document. extends-formThe name of the base form. Entries are mapped using the
unique IDs of this form and the form mapping that is defined for the extends form.
Appendix A
167
object type
<object type=Form cascade=all>
For AR System object mapping, this element and its children identify the object to which this form mapping maps.
object typeThe AR System object that does not include metadata. cascadeThe action to take if the parent entry is deleted. Options are: allPerfoms both creation and deletion of entries. create-orphanCreates only entries found on the source but are missing from the destination. Does not delete extra entries found on the destination. delete-orphanDeletes extra entries found on the destination but not on the source. Does not create extra entries found on the source. <field id=1/> and <text value=:/>
These items are contained within the <object> element, and are used to identify the fields and text that make up the name of the AR System object. The name is built based on the contents of the fields and the text value.
one-to-many form
<one-to-many form=formName local-key-id=3 foreign-key-id=2 cascade=all>
One-to-many mapping is used when a single entry in the main form is related to many entries within the specified form.
one-to-many formThe name of the external form where many entries match
one entry locally.

local-key-idThe field ID of the local key used in the external form to make
multiple entries from the local form.

foreign-key-idThe unique field ID used on the remote form. It is not
required, becaus the unique-field-id defined on the form can be used.

Cascade The action to take if the parent entry item is deleted. Options are:
all create-orphan (not currently supported) delete-orphan The <local-keys> and <foreign-keys> can be used if multiple fields are used for each corresponding attributes. These elements override the corresponding attributes.
168
many-to-one form
<many-to-one form=formName local-key-id=3 foreign-key-id=2>
This mapping type is used to define mapping of multiple entries in the local form to a single entry in the foreign form. Because this mapping has no cascade option, deleting or creating entries in this form does not affect the external form.
many-to-one formThe name of the external form, where one entry matches
many local entries.


foreign-key-idThe unique field ID used on the external form. This ID is not
required because the unique-field ID defined on the form can be used.
one-to-one form
<one-to-one form=formName local-key-id= foreign-key-id=>
In this mapping, every entry in the local form maps to one entry within the specified external form. Cascade is not defined for this mapping type.
one-to-one formThe name of the external form where one entry matches
one entry locally.


required because the unique-field ID defined on that form can be used.
many-to-many form
<many-to-many form=formName local-key-id=3 foreign-key-id=5 mapping-form= source-field-id=2 destination-field-id=1>
This mapping allows mapping of multiple entries in the local form to multiple entries in the external form. This mapping uses an intermediate form in which the unique fields from the local form are mapped to the unique fields on the external form.
many-to-many formThe name of the external form where many entries matches many local entries local-key-id The field ID of the local key used in the external form to make

required because the unique-field ID defined on that form can be used.

mapping-formThe name of the intermediate form used in the mapping.
Appendix A
169
source-field-idThe field ID in the mapping form that contains the value of
the unique-field ID of the source entry. This value comes either from the localkey-id field or the unique-field-id.
destination-field-idThe field ID in the mapping form that contains the
value of the unique-field-id of the destination entry. This value comes either from the foreign-key-id field or the unique-field-id of the external form. The <source-fields> and <destination-fields> can be used to override the attributes and where multiple fields can be defined for each. The source and destination field IDs must be defined for the mapping to succeed.
IMPORTANT
If you have migrated hierarchical groups (groups that include both parent and child groups), the Differences report might show a difference between source and destination. This could be because a child group was migrated but not its parent. To resolve this difference, migrate both parent and child groups.
Metadata mappings and BMC Remedy ITSM

The Migrator CLI provides support for BMC Remedy ITSM through XML documents that enable mapping to an entry ID as the foreign key, and the ability to inject data during migrations.
WARNING
Using Migrator CLI with BMC Remedy ITSM applications might introduce inconsistencies in the application data. Instead, BMC recommends that you use the Data Management Tool with BMC Remedy ITSM applications to ensure consistency.
XML mapping documents for BMC Remedy ITSM

The following BMC Remedy ITSM mapping documents are available:
ItsmMetaData.xml ItsmMetaDataEnableDelete.xml
A configuration file, ItsmConfiguration.xml, is also available, with the Group Data Merge option set to Replace. The COM:Company form serves as the root in the BMC Remedy ITSM mapping document. Table A-3 outlines the forms handled by the BMC Remedy ITSM mapping document.
Table A-3: Forms and BMC Remedy ITSM mapping (Sheet 1 of 3) Form COM:Company COM:CompanyAlias Target form n/a COM:Company Mapping type n/a one to one Local field ID n/a 1000000072 Foreign field ID n/a 1
170
Metadata mappings and BMC Remedy ITSM
Table A-3: Forms and BMC Remedy ITSM mapping (Sheet 2 of 3) Form FIN:ConfigCost CentersRepository FIN:CostCenterUDA Associations CTM:Region SIT:SiteCompanyAssociation SIT:Site SIT:SiteAlias SIT:SiteGroup CTM:People CTM:People CTM:LoginID User CTM:SupportGroup FunctionalRole CTM:SupportGroup Association CTM:LoginID CTM:PeopleWallet CTM:PeopleHRAttendance Mgmt CTM:PeopleHR TimeManagement CTM:PeopleHR TimeManagement CTM:PeopleEducation CTM:PeopleTravelProfile CTM:PeopleBenefitInfo CTM:PeopleITSkills CTM:PeopleWorkLog NTE:CFG-Notification Events CTM:PeopleOrganization PCT:ProductCatalog Target form COM:Company COM:Company COM:Company COM:Company SIT:SiteCompany Association SIT:Site COM:Company COM:Company SIT:Site CTM:People CTM:People CTM:People CTM:People Mapping type many to one many to one many to one many to one one to many one to one many to one many to one one to one many to one one to many many to one many to one many to one many to one many to one many to one many to one many to one many to one many to one many to one many to one many to one many to one many to one one to many Local field ID 1000000001 490009000 1000000001 1000000001 1 1000000074 1000000001 1000000001 1000000074 1000000080 101 4 4 1000000080 1000000080 1000000080 1000000080 1000000080 1000002139 1000000080 1000000080 1000000080 1000000080 1000000080 1000000080 1000000001 1 Foreign field ID 1000000001 179 1000000001 1000000001 1000000074 1 1000000001 1000000001 1 1 4 1 4 1 1 1 1 1 1 1 1 1 1 1 1 1000000001 1000000097
CTM:PeoplePermissionGroups CTM:People CTM:People CTM:People CTM:People CTM:People CTM:PeopleHR AttendanceMgmt CTM:People CTM:People CTM:People CTM:People CTM:People CTM:People COM:Company PCT:Product Company Association COM:Company
PCT:ProductCompany Association
many to one
1000000001
1000000001
Appendix A
171
Table A-3: Forms and BMC Remedy ITSM mapping (Sheet 3 of 3) Form PCT:ProductCompany Association CTM:SupportGroup CTM:SupportGroupAlias CTM:SupportGroup Assignments CTM:SYSAccessPermission Groups PCT:ProductAlias PCT:ProductModel-Version PCT:ProductCatalogAlias MappingForm CFG:GenericProdService Assoc CFG:GenericProdServiceAssoc CFG:GenericCompany ModuleAssoc CFG:ServiceCatalog CFG:ServiceCatalogAssoc CFG:ServiceCatalogAssoc CTM:PeopleTemplateSG CTM:PeopleWorkLog CTM:PeopleWorkLog NTE:CFG-NotificationEvents Target form Mapping type Local field ID 1000000097 1000000001 1000000079 1000000079 1000000001 1000000097 1000000097 1 1000000097 1000000799 1000000001 1 1000000001 1000000096 1000000097 1000002674 1000000080 1000000079 Foreign field ID 1 1000000001 1 1 1000000001 1 1 1 1 1 1000000001 1000000096 1000000001 1 1 1 1 1
PCT:ProductCatalog many to one COM:Company many to one
CTM:SupportGroup many to one CTM:SupportGroup many to one COM:Company many to one
PCT:ProductCatalog many to one PCT:ProductCatalog many to one PCT:ProductCatalog one to many PCT:ProductCatalog many to one PCT:ProductModel Version COM:Company CFG:ServiceCatalog Assoc COM:Company CFG:ServiceCatalog CTM:People CTM:People many to one many to one one to many many to one many to one one to many many to one
CTM:SupportGroup many to one
CTM:SupportGroup many to one
Mapping to a foreign entry ID field

When Migrator migrates or compares data based on the mapping document, it checks the entry ID maps on a per-form basis if the foreign field ID is an entry ID. If Migrator finds an entry for that entry ID value in the source entry, it obtains the destination value from the map, and replaces the field value in the entry being migrated or compared.
Injecting data
In the mapping document, you can define characters to inject into each entry being migrated or compared for the mapping item. This injection can be added within the <insert-value-fields> element, as shown.
<form name=COM:Company unique-field-id=179 type=update disable-related-workflow=false> 172 BMC Remedy Migrator Guide
Examples of CLI migration commands
<insert-value-fields> <field-value id=1000000076 value=LOAD/> </insert-value-fields> <name-fields>  <field id=1000000001/>  <field id=260000032/> </name-fields> </form>
Child elements can be added within the <insert-value-fields> element to specify field ID and value pairs to insert into an entry before that entry is modified or compared on the destination.
Form mapping data options

The following data migration options are available in the mapping document: merge type (default: update) disable related workflow (default: true) ignore pattern matching (default: true) ignore required fields (default: true)
<form name=FIN:ConfigCostCentersRepository type=update disable-related-workflow=true ignore-pattern-matching=true ignore-required-fields=true>
NOTE
For BMC Remedy ITSM, metadata migration is supported only with those companies for which an instance ID is the same on both the source and the destination. When a metadata migration is performed for the first time, the company name or company ID used in the source should not exist on the destination. Also, metatdata migration for BMC Remedy ITSM is not supported for sample company data provided with the installed product.

In each of the following compare (-c) examples, a comparison result report is generated named Specified Object Comparison.xml. If the --<object type> command is not included, the example is an all-object migration/comparison. The name of the comparison result file is All Object Comparison.xml.
Appendix A
173
WARNING
If the comparison result file already exists, it is overwritten with the new file.
Specified form migration/comparison

migratorcli m s <sourceLocation> -d <destinationLocation> --form Sample:Cities g Migrator Configuration.xml u Demo migratorcli c s <sourceLocation> -d <destinationLocation> --form Sample:Cities g Migrator Configuration.xml u Demo
All Form migration/comparison

WARNING
The must be specified for all items; otherwise, Migrator generates an error.
migratorcli m s <sourceLocation> -d <destinationLocation> --form g Migrator Configuration.xml u Demo migratorcli c s <sourceLocation> -d <destinationLocation> --form g Migrator Configuration.xml u Demo
Specified form and all filters migration/comparison

This example show how a you can specify multiple object types on the command line. This examples includes a single form and all filters. More object types can be added if needed.
migratorcli m s <sourceLocation> -d <destinationLocation> --form Sample:Cities filter g Migrator Configuration.xml u Demo migratorcli c s <sourceLocation> -d <destinationLocation> --form Sample:Cities filter g Migrator Configuration.xml u Demo
Specified CMDB migration/comparison

NOTE
In this command sequence, the metatype is required, because it defines the mapping to use within the mapping file CMDBMetaData.xmlfile.
migratorcli m s <sourceLocation> -d <destinationLocation> -metadata BMC_Person metatype CMDB y CMDBMetaData.xml g Migrator Configuration.xml u Demo migratorcli c s <sourceLocation> -d <destinationLocation> -metadata BMC_Person metatype CMDB y CMDBMetaData.xml g Migrator Configuration.xml u Demo
174
All CMDB migration/comparison

NOTE
In this command sequence, the metatype is required because it defines the mapping to use within the mapping file CMDBMetaData.xml.
migratorcli m s <sourceLocation> -d <destinationLocation> -metadata metatype CMDB y CMDBMetaData.xml g Migrator Configuration.xml u Demo migratorcli c s <sourceLocation> -d <destinationLocation> -metadata metatype CMDB y CMDBMetaData.xml g Migrator Configuration.xml u Demo
All object migration/comparison

migratorcli m s <sourceLocation> -d <destinationLocation> g Migrator Configuration.xml u Demo migratorcli c s <sourceLocation> -d <destinationLocation> g Migrator Configuration.xml u Demo
Deployable applications instruction file

NOTE
To execute this and the next three examples, you can use the following migration or comparison command sequences:
migratorcli -m -s <sourceLocation> -d <destinationLocation> -i <instructionFileName> -g MigratorConfiguration.xml -u Demo migratorcli -c -s <sourceLocation> -d <destinationLocation> -i <instructionFileName> -g MigratorConfiguration.xml -u Demo <?xml version=1.0 encoding=UTF-8 ?> - <instructions xmlns:xsi=http://www.w3.org/2001/XMLSchemainstance xsi:noNamespaceSchemaLocation=Migration Instructions.xsd> - <instruction enabled=true name=ExampleAppDeployment> - <special-instructions> -  <special type=deploy name=Sample enabled=true /> <special type=deploy name=Home Page enabled=true /> </special-instructions> </instruction> </instructions> Appendix A Migrator command-line interface 175
CMDB instructions
This example shows how you can migrate or compare a specific class within the CMDB system and remember to include the CMDBMetaData.xml mapping file on command line.
<?xml version=1.0 encoding=UTF-8 ?> - <instructions xmlns:xsi=http://www.w3.org/2001/XMLSchemainstance xsi:noNamespaceSchemaLocation=Migration Instructions.xsd> - <instruction enabled=true name=ExampleCMDB> - <special-instructions> -  <special type=meta-data name=BMC_Person owner=CMDB enabled=true /> </special-instructions> </instruction> </instructions>
Data instruction file

This example shows how you can migrate or compare data between one or more forms where a query or all data can be included.
<?xml version=1.0 encoding=UTF-8 ?> - <instructions xmlns:xsi=http://www.w3.org/2001/XMLSchemainstance xsi:noNamespaceSchemaLocation=Migration Instructions.xsd> - <instruction enabled=true name=ExampleData> - <data-instructions> - <data enabled=true source-form=User destination-form=User unique-field-id=1 type=data mode=search mergeoption=update ignore-required-fields=true ignore-patternmatching=true count=0 disable-related-workflow=false> <qualification>'Login Name' != $NULL$</qualification> <ports enabled=true list=390635 fast=390620 /> </data> - <data enabled=true source-form=Group unique-field-id=1 type=data mode=all merge-option=update ignore-requiredfields=true ignore-pattern-matching=true count=0 disablerelated-workflow=false> <ports enabled=true list=390635 fast=390620 /> </data> </data-instructions> </instruction> </instructions>
176
Multiple migrations or comparisons using one instruction file

This example show how you can migrate or compare objects, data and or special items in one instruction.
<?xml version=1.0 encoding=UTF-8 ?> - <instructions xmlns:xsi=http://www.w3.org/2001/XMLSchemainstance xsi:noNamespaceSchemaLocation=Migration Instructions.xsd> - <instruction enabled=true name=Example> - <object-instructions type=specified> - <objects type=Form enabled=true mode=specified> -  <object name=Sample:Cities destinationname=Example:Sample:Cities /> </objects> -  <objects type=Active Link enabled=true mode=all /> -  <objects type=Filter enabled=true mode=all /> </object-instructions> - <special-instructions> -  <special type=related name=Group enabled=true /> <special type=related name=User enabled=true /> </special-instructions> - <data-instructions> -  - <data enabled=true source-form=Sample:Cities type=data mode=number merge-option=update ignore-required-fields=true ignore-pattern-matching=true count=5 disable-relatedworkflow=false> <ports enabled=true list=390635 fast=390620 /> </data> </data-instructions> </instruction> </instructions>
Appendix A
177
Package file
This example shows how a package.xml file can be used to execute a series of migration instructions. Those instructions are executed in the order in which they appear in the file.
NOTE
To execute this example, you can use the following migration or comparison command sequences:
migratorcli -m -s <sourceLocation> -d <destinationLocation> -p <package_filename> -g MigratorConfiguration.xml -u Demo migratorcli -c -s <sourceLocation> -d <destinationLocation> -i <package_filename> -g MigratorConfiguration.xml -u Demo <?xml version=1.0 encoding=UTF-8 ?> - <package xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation=Migration Package.xsd configuration=> <instructions file=ExampleApplicationDeployment.xml type=all command=migrate enabled=true /> - <instructions file=ExampleCMDBInstruction.xml command=compare type=specified> -  <instruction name=ExampleCMDB /> </instructions> <instructions file=ExampleDataInstruction.xml type=all command=migrate enabled=true /> </package>
Using a Differences report as input

This example uses a command with a Differences report as input for a migration and a comparison.
NOTE
The migration/comparison extracts all objects and data that are different or missing and migrate/compare them between the specified source and destination. The specified source and destination do not need to be the same as those used to generate the difference report. Also, you do not need to include the CMDB meta mapping document if the Difference report was created for one or more CMDB-based classes, because the eport contains only objects and data.
178
migratorcli m s <sourceLocation> -d <destinationLocation>-difference <difference_report.xml> g Migrator Configuration.xml u Demo igratorcli c s <sourceLocation> -d <destinationLocation> -difference <difference_report.xml> g Migrator Configuration.xml u Demo
Appendix A
179
180
Appendix
Menus and shortcut keys
This section explains the Migrator main menu bar and lists the shortcut keys specific to Migrator. The following topics are provided: Main menu bar (page 182) Shortcut keys (page 189)
Appendix B
181
Main menu bar

The main menu bar, at the top of the Main Migrator window, provides access to most of Migrators features, such as: licensing and logging on to servers, migrating AR System objects between servers, exporting definitions, and printing. You can customize Migrators main menu to fit your individual working style. (See Customizing Migrator on page 39 for additional information.) If a menu contains commands that are gray, that command is unavailable for the task you are working on. Not all menu items are available or listed until you log in to a server and open a file. A brief description of all of the main menu commands appears in the following tables.
File menu
The selections available in the Migrator File menu depend on the window that is currently active. For example, the New Differences Object and New Migration Script selections become available only when a server window is open and active. The Export to HTML selection becomes available only when a dependencies, differences, or results report window is open and active.
Table B-1: File menu selections (Sheet 1 of 2) Menu selection New Server Window Use to Open a new server window. When you make this selection, you are prompted to choose a server. You can have multiple server windows open in a single session. Create a new .migrator file. When you make this selection, a definition window opens. You can add to he contents f this window by dragging objects to it from any open server window. Then, select either Server or Migrator File as the destination type. Create a new Differences report. When you make this selection, a new definition window opens. You can then add content by dragging objects to it from any open server window. Then, select either Server or Migrator File as the destination type. Create a new migration script. When you make this selection, a new window opens. You can then record migrations that are happening from one server o another, or to a file. Choose a file to open in Migrator. Close the active window. Save an open window or file using the existing name or a default. Save an open window or file with a new name. Choose a printer, a print range (pages), and number of copies. Preview the file you want to print (migration result, differences, and dependency reports only).
New Migrator File
New Differences Window
New Migration Script
Open Close Save Save As Print Print Preview
182
Main menu bar
Table B-1: File menu selections (Sheet 2 of 2) Menu selection Print Setup Send Export to HTML Recent Files Exit Use to Choose a printer, paper, and orientation. Open a send window form your email application so you can send the currently active file on your desktop. Export a report to HTML format for editing and printing. This selection appears only when a report is open. List the most recent files used. Shut down Migrator.
Edit menu
Table B-2 lists selections in the Migrator Edit menu.
Table B-2: Edit menu selections Menu selection Copy Paste Delete Use to Copy a selected object in a Migrator window. Paste an object that was copied into a Migrator window. Delete a selected object in a Migrator window.
View menu
The Migrator View menu provides several submenus. The Search Bar command is available only after opening a Form Details window; the Description Bar selection is available only after opening a Script window; and the Zoom selection is available only when you are viewing an active report.
Table B-3: View menu selections (Sheet 1 of 2) Menu selection By Application By Workspace By Form Normal Form Details Differences Form and Related Differences Use to Filter the server view to show only local and deployable applications. Filter the server view to show only objects included in a specified workspace or packing list. Filter the current Server/Definition view to display a subset or selected list of forms, together with related objects. Switch filtering off when users select viewing by form, application, or workspace. Show form details in a new window, including fields, views, and related objects. Show the differences between two or more selected objects. Show the differences between forms and their related objects.
Appendix B
183
Table B-3: View menu selections (Sheet 2 of 2) Menu selection Downward Dependencies Upward Dependencies Toolbars Migration Status Description Bar Status Bar Arrange Icons Zoom Refresh Synchronize Views Use to Show downward dependencies for a selected object. Show upward dependencies for a selected object. Select the toolbars you want displayed in the main window. Show or hide the migration status pane at the bottom of the main window. Show or hide the description bar (for before and after commands) when you are creating a migration script. Show or hide the status bar beneath the migration status pane. Arrange a windows icons alphabetically by name, automatically, or lined up on a grid. Set the Zoom factor for the dependencies, differences, and migration result reports, and for printing a report. Refresh the current view. Synchronize objects within the other open server and report windows.
Servers menu
The Servers menu is available only when a new script is created or an existing script is opened.
Table B-4: Servers menu selections Menu selection Change Login Information Add Server Add Migration File Remove Server Change History Option Change History String Default Prefix Options Use Definition Files for Backup Use Migrator Files for Backup Back Up All Objects Back Up Specified Objects Back Up Directory Use to Update login information, or log in as a different user. Select another server to add to the list of servers in a script. Add a .migrator file. Remove a server from the list of servers in a script. Modify the Change History options on a server in a script. Modify the string in the Change History options on a server in a script. Change the default prefix options on a server in a script. Specify a definition (.def) file format as the backup on a server in a script. Specify a .migrator file format as the backup on a server in a script. Back up all objects on a server in a script. Select the objects to be backed up on a server in a script. Specify a directory for storage of backup files on a server in a script.
184
Main menu bar
AR System Objects menu

The Objects menu is available only when a new script is created or an existing script is opened.
Table B-5: Objects menu selections Menu selection Change Source Change Destination Prefix Options Destination Name Data Mode Number of Records Search Criteria Remove Object Use to Change the source server for an object in a script. Change the destination server for an object in a script. Change the prefix options for an object in a script. Change the name of the object on the destination server in a script. Open the Data Migration Settings dialog box used to set up data migrations. Enter the number of records to use for a data migration. Enter an actual data migration search. Remove the object form the list of objects in a script.
Migrate menu
The following table outlines the Migrate menu and its submenus. The All Fields, All Views, and Migrate Field by Type submenus and selections are available only from a Form Detail window.
Table B-6: Migrate menu selections (Sheet 1 of 3) Menu selection All AR System Objects Form and Related Objects Deploy Application Selected Objects Form Data Use to Migrate all objects. Migrate selected forms and their related objects. Migrate an application and its supporting objects. Migrate selected objects. Display a submenu that allows you to: Migrate form data only. Migrate a form and data. Migrate a form, related objects, and data.
Appendix B
185
Table B-6: Migrate menu selections (Sheet 2 of 3) Menu selection Use to
Migrate Objects by Type Display a submenu that allows you to migrate the following objects: All forms All active links All filters All escalations All active link guides All applications All packing lists All web services All menus All groups All images All distributed maps All distributed pools All Flashboards All Flashboard data sources All Flashboard variables All Flashboard alarms All Fields All Views Migrate all fields form selected forms. Migrate all views from selected forms.
186
Main menu bar
Table B-6: Migrate menu selections (Sheet 3 of 3) Menu selection Migrate Field by Type Use to Select the following field types to migrate from selected forms (from the Form Detail window): Character fields Diary fields Integer fields Real fields Selection fields Date/time fields Decimal fields Buttons Panel fields Lines Boxes Text Attachments Tables Alert fields Result list fields View fields Flashboard fields Currency fields Date fields Time fields Set Admin Mode on Destination Server Migration Mode Scripting Mode Turn on or off the restriction of non-administrative users during a migration. Run migrations immediately. Create a migration script to save or schedule.
Script menu
Table B-7 lists selections available in the Migrator Script menu.
Table B-7: Script menu selections Menu selection Schedule Migration Script Edit Scheduled Migration Use to Schedule a migration for the specific month, date, and time, and the users to notify upon completion. Edit a scheduled migration.
Execute Migration Script Open and run a migration script.
Appendix B
187
Tools menu
The Tools menu includes Source Control options. If Source Control installed on your system, the Source Control submenu selections are also available.
Table B-8: Tools menu selections Menu selection Login Accounts Licenses Export Definitions Export Application Export Locked Definitions Convert Definition Files Customize Options Source Control Use to Open the Login dialog box. Manage user and server lists (where you add servers to Migrator) Display current licenses and add or edit existing licenses. Export object definitions to an AR System definition (.def) file. Export an application to an AR System definition (.def) or XML (.xml) file. Export locked object definitions to an AR System definition (.def) file. The lock key must be entered and verified, and a lock type selected. Convert Migrator definition (.def) files to Migrator (.migrator) definition format. Customize the main menu and toolbars. Configure Migrator options. Display a submenu that allows you to perform the following tasks: Get the latest version Check in a file Check out a file Undo a checkout action Add to Source Control Remove from Source Control Show the history Show the differences Show user information Activate the refresh status Run Source Control client
Window menu
The Window menu provides options for positioning Migrator objects on your screen.
Table B-9: Window menu selections (Sheet 1 of 2) Menu selection Close Close All 188 BMC Remedy Migrator Guide Use to Close the active window. Close all active windows.
Shortcut keys
Table B-9: Window menu selections (Sheet 2 of 2) Menu selection Next Previous Cascade Tile Horizontally Tile Vertically Arrange Icons Server and Window List Use to Display the next active window. Display the previous active window. Arrange windows so they overlap. Arrange windows as horizontal, non-overlapping tiles. Arrange windows as vertical, non-overlapping tiles. Arrange icons at the bottom of the Window menu. List the open servers and windows for a session with the active server or window checked.
Help menu
The Help menu provides options for displaying Migrator online help and version information.
Table B-10: Help menu selections Menu selection Help topics About BMC Remedy Migrator Use to Open Migrator help. Display program information, version number, and copyright date.
Shortcut keys
Migrator uses special shortcut keys for menu commands and when working in a server window using the Migrate and Tools menus.
Table B-11: Shortcut keys (Sheet 1 of 2) Menu File menu Key sequence Ctrl+N Ctrl+F Ctrl+R Ctrl+O Ctrl+P Ctrl+S Edit menu Ctrl+C Del Ctrl+V Migrate menu Ctrl+M Use to Open a new server window. Create a new .migrator file. Create a new differences window into which you can drag and drop content. Open an existing file or browser window. Print the active document. Save the active file. Copy a selection and put it on the clipboard. Delete selected objects form a server or file. Paste a selection from the clipboard and put it in an active file. Migrate selected objects.
Appendix B
189
Table B-11: Shortcut keys (Sheet 2 of 2) Menu Tools menu Key sequence Ctrl+D Ctrl+E Ctrl+U All F5 Ctrl+A Use to Show differences. Show downward dependencies. Show upward dependencies. Refresh the display. Select all choices in Form Detail and Server views.
190
Migrator Glossary
For a comprehensive glossary of AR System terms, see the Concepts Guide.
definition report
See dependency report, differences report, result report.

result report
The structure in which the data in the definition (.def) and Migrator (.migrator) is organized and manipulated.
dependency report
A report that shows the results of a migration. See also status pane.
results window
A report in AR System that displays a list of objects that show dependencies. Dependency reports can show either upward or downward dependencies. See also upward dependencies, downward dependencies.
destination server
The part of the main Migrator window that displays the results of a migration. See also status pane.
scripted migrations
The server where the current versions of AR System applications that are in production are used by users.
differences report
In scripting mode, the ability to create reusable sets of multiple-server migrations and put them in a holding position.
source server
A report that displays differences when comparing server objects.

downward dependencies
The server where AR System applications that are in development get modified or updated regularly.
status pane
A list of objects that the specified object requires, as in a downward dependency report.
immediate migrations
A subwindow of the main Migrator window that displays active, scheduled, and completed migrations, along with the status tabs. See also status tabs.
status tabs
In Migration mode, the performance of a single migration immediately.

list view
A series of tabs in the migration status pane for showing all, immediate, scheduled, or completed migrations. See also status pane.
tree view
The type of view displayed in the right pane of a server or report window.
migration
A type of view displayed in the left pane of a Migrator server, file, or report window.
upward dependencies
The process of moving and making existing data work on a different computer or operating system.
migration result report
A list of objects that require the specified object, as in an upward dependency report.
See result report.
Migrator Glossary
191
192
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index
Symbols
.mgrdif file 131 .mgrtdep file 121 .migrator files 107 selecting options 66 viewing backup files 78 Before commands in scripts 113 BMC Remedy Developer Studio 102 BMC Software, contacting 2
A
access points 48 Accounts dialog box 28, 85 active links, differences options for 135 adding Before or After commands 113 licensed servers 30 prefixes 103, 104 servers 29 Admin mode 81 advanced search bar 96 After commands in scripts 113 API 16, 115 applications application state 51, 66, 135 deployable 52 deploying 91, 107 exporting deployable 58 migrating 90, 103 viewing objects by 47 AR System fields that can be migrated 21 objects that can be migrated 20 using with Migrator 16 archive forms 85 authentication, user 33
C
cache creating cache files 42 database information 42 dependencies file 42 management 42 recaching hard drive 43 refreshing 61 server 42 updating cache files 43 calendar, using with scripted migrations 114 canceling data migrations 100 Change History options defined 63, 70 selecting 70 changing destination name 113 directories 77 object elements in scripts 110 scheduled migrations 115 character menu differences options 135 characters, nonalphabetical 37 checklist, migration 81 CLI 160 clients, number of 30 CMDB data 75 CMDB migrations form-to-form mappings 166 many-to-many forms 169 many-to-one forms 169 mapping files 166 mapping types 166 metadata mappings for migrations 165 object mappings 166
B
backup directory 66 file location 37 options 63, 66 root directory 67
Index
193
one-to-many forms 168 one-to-one forms 169 color options dependency reports 122 differences reports 133, 134 result reports 142 columns, rearranging order 41 command-line interface command examples 173 configuration files 161 difference files 161 instruction files 161 log files used with 162 metadata mapping files 161 object type 168 options 162 overview 160 package files 161 using differences report as input 178 XML document structure 167 XML files used in 161 XSD schema files 161 commands, Before and After 113 comma-separated values 101 comparison view, differences reports 126 completed migration 39 computed groups 54 configuration files 161 confirmation prompts, showing or hiding 61 controlling migrations 82 converting definition files 58 copy/prefix migrations 80, 103 copying objects to the same server 103 creating data search 101 dependency reports 120 differences reports 130 migration scripts 108 custom objects. See overlays customer support 3 customizing dependency reports 122 differences reports 133 main menu and toolbars 40 overview 39 result reports 141 window columns 41 data searches 96, 101 merging options 72 migrating 16, 95, 99 options 72 search qualifications 101 settings 99 data mappings, form-to-form 166 Data Migration Settings dialog box 97, 99 data sources, Flashboards 65 database information cache 42 data-only form 91 .def file extension 56 default options, reverting to 63 definition files converting 58 defined 56 exporting 56 definitions, object 56 deleting backup options 68 locked objects 55 object removal options 68 dependencies direct 119 downward 42, 120 file cache 42 indirect 119 upward 42, 120 dependency reports color options 122 creating and using 120 creating HTML file 122 customizing 122 defined 118 display options 120 downward dependencies 118 migrating objects 122 packing lists 118 resizing 121 saving 121 upward dependencies 118 viewing 121 deployable applications described 52 exporting 58 deploying applications data-only form 91 Migrate menu 107 prefixed versions 103 required objects option 91 to the same server 92 destination
D
data creating a data search 101 194 BMC Remedy Migrator Guide
changing destination name 113 destination type 89, 94, 130 destination server 17 adding to a script 111 Admin mode 81 Enforced mode 81 details form 45 object 48 Developer Studio 102 difference files 161 differences 147 differences reports color options 133, 134 Comparison view 126 creating and using 130 customizing 133 defined 126 display options 133 field IDs in 84, 128 field names in 85 for source control 147 illustrated 128 locked objects in 128 mask options 133, 134 migrating objects 132 Object Details view 127 printing 132 resizing 131 saving 131 using as input in command line 178 viewing 131 direct dependencies 119 directories directories options 77 root directory 67 disabling or deleting objects 63 display options differences reports 133 result reports 141 distributed server option (DSO) deleting forms 55 maps 135 pools 135 document structure, XML 167 documentation, AR System 11 domains domain.com 85 source.domain.com 86 downward dependencies 42, 118, 120 duplicate entries 99 dynamic groups 54
E
Edit menu 183 editing script server options 111 embedded server names 85 enabling field mapping 100 Enforced mode destination server 81 in source control 146, 148 entries, duplicate 99 entry points 48 escalation differences options 135 examples, command-line 173 exporting deployable applications 58 differences report to HTML 132 locked object definitions 57
F
failure to migrate 82 field IDs, in differences reports 84, 128 field mapping 102 fields mapping field values 95 migrating 21, 93 names in differences reports 85 File menu 182 files .mgrdif 131 .mgrtdep 121 .migrator 126 cache 42 converting XML files 58 definition 56 dependencies cache file 42 migration report result 37 script 37 viewing 78 filter differences options 135 firewall support 29 Flashboards alarms 135 data sources 65, 135 variables 65, 135 form name 167 forms archive forms 85 archiving 49 choosing with prefix 45 data-only form 91 form differences options 135 Index 195
intermediate 169 join forms 83 many-to-many 169 many-to-one 169 migrating join forms 49 one-to-many 168 one-to-one 169 preference server 32 related to menus 65 table field form migrations 65 viewing form details 45 form-to-form data mappings 166 migrating 49, 83
K
keyboard shortcuts 189 keys, license 28
L
left pane, main window 37 licensed server, adding 30 licenses license agreement 25 managing existing 31 obtaining license keys 28 purging 31 removing 31 transferring to another server 31 viewing Migrator license details 31 locked objects deleting 55 description 49 exporting definitions 57 lock type 57 report details 128 login authentication 33 changing login information in a script 112 options 61 preference server 32, 33 server login 32, 33 to two machines 32 user name 33
G
general options 60 group options defined 71 selecting 71 groups computed 54 dynamic 54 in object list view 53 merging new with existing 63 regular 54
H
Help menu 189 HTML file format, printing dependency reports 122 differences reports 132 result reports 141
I
IDs, field 85 ignoring prefixes 63 immediate migrations 17, 39 indirect dependencies 119 individual record migration 95 installation procedure 25 instruction files 161 integration, Migrator and AR System server 16 intermediate form 169 ITSM data 75
M
main menu bar customizing 39 described 182 overview 182 main window described 36 Object Type tab 37 Prefix tab 37 status bar 37 status pane 37 title bar 37 managing licenses 31 Migrator cache 42 server accounts 28
J
join forms automatic migrations 65
196
many-to-many forms 169 many-to-one forms 169 mapping field values 95 files for CMDB migrations 166 form-to-form 166 metadata 161 object 166 types for CMDB migrations 166 using field 102 mask options 76, 133, 134 menus Edit 183 File 182 forms related to 65 Help 189 main menu bar 182 Migrate 185 Objects 185 option for migrating 65 refresh conditions 53 Script 187 Servers 184 Tools 188 View 183 Window 188 merging new and existing groups 63 meta name 167 metadata, mapping 161 Migrate menu 185 migrating applications 103 archive forms 85 backup directory 66 controls 82 copy/prefix migrations 80, 103 data 16, 95 data entries 97 dependent objects 122 different objects 132 embedded server names 85 fields 21, 93 form and related objects 84 immediately 17, 80 individual records 95 join forms 65, 83 Migration mode 88 objects 20, 88, 122 scheduled migrations 114 scripted migrations 17, 107 Scripting mode 80 sequence of objects 18 special migrations 107 table field forms 65 with source control (SC) 146 migration status pane 37 migrations backup 63 Change History 63 CMDB data 75 completed 39 confirmation prompt options 61 controlling 82 copy/prefix 80, 103 copy/prefix migrations 103 data 63 data searches 101 directories options 77 failure 82 form and related objects 84 Forms and Related 68 immediate 39 impact on performance 17 ITSM data 75 menus 182 migration checklist 81 migration process, overview of 17 migration status pane 38 modifying migration scripts 109 multiple-thread 63 object removal 63 options 62, 63, 65, 69, 71, 72 performing 88 required objects 63 result files 37 retry option 63 scheduled 39 SLA data 75 special migrations 107 status tabs 39 synchronizing with difference mask options 76 table field forms 65 tracking progress of 39 tracking status of 38 viewing progress of 108 viewing results 82 modes Admin 81 Migration 88 Migration mode 80 Scripting mode 80 modifying destination name 113 existing servers 29
Index
197
migration scripts 111, 114 users 29 modifying migration scripts changing object elements 110 modifying objects 112 multiple server handling 106 multiple thread options defined 63 selecting 64 multiple threads 63 multiple-thread migrations 63 removing from a script 113 renaming 43 required 63 retrieving 18, 34 reviewing object differences in reports 130 types of details 48 viewing by application 47 viewing by workspace 47 viewing differences 130 viewing form details 45 Objects menu 185 one-to-many form 168 one-to-one form 169 opening migration scripts 108 server windows 33 options backup 63, 66 caching 61 Change History 63, 69 command-line interface 162 data 72 data merging 72 delete dependency and database files 61 dependencies color 122 directories 77 display 133 editing script server options 111 forms related to menus 65 general 60 group 71 Ignore Prefixes 63 ignore prefixes 81 join forms 65 login 61 mask 133, 134 menus 65 migration mode 61 multiple-thread 63 object removal 63, 68, 69 required object 63, 65 result report color options 139 result reports 141 retry 63, 74 reverting to Migrator defaults 63 table field forms 65 overlays comparing 153 migration 155 operations on 152 support for 151 overview
N
name form 167 meta 167 names, embedded server 85 new server window, opening 33 nonalphabetical characters, sorting 37 notification 115
O
Object Details view, differences reports 127 object mappings 166 Object object removal options 69 Object Type tab 37, 44 Object Type view 43 objects changing object elements in a script 110 copying to the same server 103 definitions 58 deleting from servers 55 deleting locked objects 55 dependencies 120, 121 differences 131 disabling or deleting 63 displaying in server window 43 how objects are migrated 82 locked 49 migrating 20, 88 migrating differing objects 132 migration sequence 18 modifying in scripts 112 object definitions 56 Object Type tab 37 objects menu 185 Prefix tab 37 related to form 84 removal 63 removal options 68 198 BMC Remedy Migrator Guide
dependency reports 118 differences reports 126 Migrator 16 result reports 138 scripted migrations 106 renaming objects 43 reports dependency 120, 121 differences 126 failure to migrate 82 migration dependencies 118 resizing 82, 121, 131 result 138 required object options defined 65 selecting 65 resizing a report dependency 121 differences 131 result 82 result files, location 37 result reports color options 139, 142 customizing 141 defined 138 overview 138 printing 140 removing 140 resizing 82, 139 saving 140 status details 139 viewing 140 working with 139 results, migration 82 retrieving objects 18, 34 retry options 74 reverting to default options 63 roles 54, 103 root directory, backup 67 running After commands 113 Before commands 113 scripted migrations 108
P
package files 161, 178 packing lists in dependency reports 118 in differences reports 135 in object list view 52 pattern checking 99 performance, impact of migrations 17 Performing 87 performing migrations 88 pools, distributed server option (DSO) 135 port numbers 29 preference server 32 Prefix tab, main window 37 Prefix view 44 prefixes adding and removing 103 changing options 112 choosing forms with 45 ignoring 63, 81 Prefix dialog box 89 printing differences reports 132 result reports 140 process, migration 17 product support 3 progress of a migration 39
Q
qualifications, data search 101
R
refreshing cache 61 regular groups 54 related objects, migrating 84 removal options, objects 63 removing licenses 31 object from a script 113 prefixes 103 result reports 140 servers 31
S
saving dependency reports 121 differences reports 131 result reports 140 scheduled migrations 39, 114 scheduling scripts changing 115 described 114 Script 187 script files, location 37 Script menu 187 Index 199
scripted migrations adding before or after commands 113 adding descriptions 113 adding servers 111 After commands 113 Before commands 113 changing a schedule 115 changing login information 112 changing object elements 110 creating 107 defined 17 migration status pane 115 modifying 109 modifying objects 112 opening and running 108 overview 106 removing objects from a script 113 removing servers 111 scheduling 114 server pairs 106 using calendar with 114 viewing script files 37, 78 Scripting mode defined 17, 80 migrating in 108 searches, data 96, 101 selecting directories option 77 general options 60 migration options 62 sequencing objects in a migration 18 server accounts, managing 28 server license dialog box 30 server windows displaying form details 46 displaying forms in 45 displaying objects 43 opening 33, 42 removing 31 viewing 41 working with 41 Servers 184 servers adding 28, 29, 30 adding or removing in scripts 111 Admin mode 81 authentication 33 changing login information in a script 112 deleting objects from 55 destination 17 editing server options for a script 111 embedded server names 85 Enforced mode 81 handling multiple servers 106 licensing and storing 30 logging on 32, 33 managing server accounts 28 opening a server window 33, 42 preference server 32 removing from view 31 server authentication 33 server cache 42 server pairs 106 server window description 37 source 17 source server 94 Servers menu 184 settings, data 99 shared workflow 66 shortcuts, keyboard 189 SLA data 75 sorting, nonalphabetical characters 37 source control (SC) defined 146 Enforced mode 146, 148 exceptions 147 generating differences report for 147 running in Migrator 146 working with 147 source server 17, 94 source.domain.com 86 special migrations 107 starting Migrator 26 state, application 51 status bar 37 in result reports 139 migration status pane 38 migrations 37 tabs 39 window 37 storing licenses 30 support files 42 support, customer 3 synchronized viewing 38 synchronizing mask options 76
T
tabs Comparison tab view 126 Completed 82, 140 Object Details 127 Object Type 44
200
Prefix 37 technical support 3 threads, in multiple migrations 63 title bar, main window 37 toolbars, customizing 39 tools for using Migrator dependency reports 120 result reports 139 source control (SC) 146 Tools menu 188 transferring licenses 31 tree view, differences reports 131 types, mapping for CMDB migrations 166 license details 31 migration results 82 objects by application 47 objects by workspace 47 result files 37 result reports 140 script files 37 synchronized window views 38 views migrating 93 Object Type view 43 Prefix view 44
U
uninstalling 26 upward dependencies 42, 118, 120 user authentication 33 user interface Data Migration Settings dialog box 99 main menu bar 37, 182 main window 36 Object Type tab 37 Prefix tab 37 report windows 37 right pane 37 status bar 37 status pane window 37 status tabs 39 title bar 37 toolbars 37 viewing information 37 window columns 41 users, modifying 29 using dependency reports 120 differences reports 130 Migration mode 80 Scripting mode 80
W
Web Services 52 Window menu 188 workflow shared 66 support files 42 working with .def file extensions 56 .xml file extensions 56 dependency reports 120 object definitions 56 result reports 139 server windows 41 source control (SC) 147 workspace, viewing objects by 47
X
XML document structure 167 XML files converting 58 defined 56 examples 173 exporting 56
V
variables, Flashboards 65 View menu 183 viewing backup files 37 dependency reports 121 differences reports 131 files 78 form details 45, 46 information in windows 37 Index 201
202
*099381* *099381* *099381* *099381*
*183990*

Remedy Migra Tor

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Remedy Migra Tor

Hochgeladen von

Copyright:

Verfügbare Formate

BMC Remedy Migrator 7.6.

BMC Remedy Migrator Guide

Contacting BMC Software

United States and Canada

Outside United States and Canada

Restricted rights legend

Support by telephone or email

Before contacting BMC Software

License key and password information

BMC Remedy Migrator Guide

BMC Remedy Migrator 7.6.04

Optimizing and Troubleshooting Guide Database Reference

BMC Remedy Migrator Guide

Title Java API

Java Plug-in API

BMC Remedy Email Engine Guide Error Messages Guide

Administrators Everyone Administrators Everyone Administrators / Developers Administrators / Developers

BMC Remedy Migrator 7.6.04

BMC Remedy Migrator Guide

Overview of BMC Remedy Migrator

Overview of BMC Remedy Migrator

BMC Remedy Migrator 7.6.04

How Migrator works

BMC Remedy Migrator Guide

How Migrator migrates

How Migrator migrates

Source and destination servers

The migration process

related objects, and required menus.

Overview of BMC Remedy Migrator

BMC Remedy Migrator 7.6.04

Figure 1-2: Migration process

Retrieve Object to be Migrated from Result File

Compare Source and Destination

Migrate Object 1. Create if missing 2. Update if different

Mark for Deletion/Disable

Are there more Objects to Migrate?

Deletion/Disable Marked Objects

Sequencing objects during a migration

BMC Remedy Migrator Guide

How Migrator migrates

Overview of BMC Remedy Migrator

BMC Remedy Migrator 7.6.04

AR System object and field migrations

BMC Remedy Migrator Guide

How Migrator migrates

Overview of BMC Remedy Migrator

BMC Remedy Migrator 7.6.04

BMC Remedy Migrator Guide

Installing and starting Migrator

Installing and starting Migrator

BMC Remedy Migrator 7.6.04

Memory usage and disk space requirements

Considerations for installation

BMC Remedy Migrator Guide

A progress bar appears as the files are extracted.

begin the installation.

Installing and starting Migrator

BMC Remedy Migrator 7.6.04

Migrator icon. Or, select Migrator from the Start menu.

and click Remove.

BMC Remedy Migrator Guide

Licensing and logging on to Migrator