remedy migra tor

www.bmc.com

BMC Remedy Migrator 7.6.04

BMC Remedy Migrator Guide

January 2011

If you have comments or suggestions about this documentation, contact Information Design and Development by email at [email protected].

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 INC2101 CITYWEST BLVDHOUSTON TX 77042-2827 USA

Telephone 713 918 8800 or800 841 2031

Fax 713 918 8000

Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000

© Copyright 2001–2011 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 legendU.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.

http://www.bmc.com

mailto:[email protected]

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 athttp://www.bmc.com/support. From this website, you can:

■ 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 [email protected]. (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:

■ 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

■ 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

http://www.bmc.com/support



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:

■ E-mail [email protected]. (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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11AR System documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 1 Overview of BMC Remedy Migrator 15

How Migrator works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16How Migrator migrates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Source and destination servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17The migration process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Sequencing objects during a migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18AR System object and field migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2 Installing and starting Migrator 23

Memory usage and disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Considerations for installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Installing Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Starting Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Uninstalling Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3 Licensing and logging on to Migrator 27

Migrator licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Adding and managing server accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Licensing and managing servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Adding a licensed AR System server in Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . 30Managing existing Migrator licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Logging in to an AR System server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Preference servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Logging on and opening a server window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 4 Navigating in Migrator 35

Navigating in Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36The main Migrator window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Viewing information in Migrator windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Viewing synchronization within windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Contents 5

Using the migration status pane and tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Migration status pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Migration status tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Customizing Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Customizing the main menu and toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Rearranging window columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Working with server windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Opening a server window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Displaying objects in a server window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Types of object details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Deleting objects from servers or files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

File types used in migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Exporting object definitions on a server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Converting definition files to .migrator format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Chapter 5 Migration options 59

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60General options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Migration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Multiple-thread options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Required Object options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Backup options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Object Removal options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Change History options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Group options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Data options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Retry options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Ignore Prefix option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Migration mask options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Directory options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Viewing backup, script, and results files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Chapter 6 Preparing to migrate 79

Defining migration modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Migration mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Scripting mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Copy/Prefix migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Migration checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Monitoring migrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Controlling migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Viewing migration results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Resolving reported failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

How objects are migrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Form migrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Managing embedded server names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Chapter 7 Performing migrations 87

Performing migrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

6 BMC Remedy Migrator Guide

Migrating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Migrating applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Migrating an application as a selected object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Deploying an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Migrating a form view and its associated fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Migrating fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Migrating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Migrating individual entries in a form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Migrating data entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Creating a data search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Using field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Performing Copy/Prefix migrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 8 Working with migration scripts 105

Scripting overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Creating, running, and saving migration scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Creating and saving migration scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Opening and running migration scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Modifying migration scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Changing object elements in a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Adding or removing a server in a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Editing server options for a script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Modifying and removing objects in a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Adding Before or After commands and descriptions . . . . . . . . . . . . . . . . . . . . . . 113

Scheduling scripted migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Scheduling migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Changing an existing migration schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 9 Dependency reports 117

Overview of Dependency reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Working with Dependency reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Creating and using Dependency reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Viewing a Dependency report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Saving a Dependency report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Printing a Dependency report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Migrating dependent objects from a Dependency report . . . . . . . . . . . . . . . . . . . 122

Customizing a Dependency report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Chapter 10 Differences reports 125

Overview of Differences reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Comparison view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Object Details view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Working with Differences reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Creating and using Differences reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Viewing a Differences report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Saving a Differences report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Printing a Differences report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Migrating differing objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Contents 7

Customizing a Differences report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Differences display options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Differences color options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Mask options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Chapter 11 Migration Result reports 137

Overview of Migration Result reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Working with Migration Result reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Viewing a Migration Result report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Saving or removing a Migration Result report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Printing a Migration Result report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Customizing a Migration Result report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Result display options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Result color options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Chapter 12 Source Control 145

Overview of Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Starting SC in Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Working with SC in Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Chapter 13 Support for overlays and custom objects 151

Operations on overlays and custom objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Comparing objects at the same location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Migration of overlays and custom objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Migrating overlays that exist at the destination . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Migrating overlays that do not exist at the destination . . . . . . . . . . . . . . . . . . . . . 155Migrating overlays when corresponding overlaid objects do not exist at

destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Migrating origin objects for which overlays exist at the destination . . . . . . . . . . 156Migrating objects from pre-7.6.04 AR System servers . . . . . . . . . . . . . . . . . . . . . . 156Migrating objects from AR System server 7.6.04. . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Appendix A Migrator command-line interface 159

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160XML files for processing commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Command line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Metadata mappings and CMDB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Mapping files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Mapping types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Metadata XML document structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Metadata mappings and BMC Remedy ITSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170XML mapping documents for BMC Remedy ITSM . . . . . . . . . . . . . . . . . . . . . . . . 170Mapping to a foreign entry ID field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Injecting data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Form mapping data options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Examples of CLI migration commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173


Specified form migration/comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174All Form migration/comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Specified form and all filters migration/comparison . . . . . . . . . . . . . . . . . . . . . . 174Specified CMDB migration/comparison. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174All CMDB migration/comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175All object migration/comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Deployable applications instruction file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175CMDB instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Data instruction file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Multiple migrations or comparisons using one instruction file . . . . . . . . . . . . . . 177Package file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Using a Differences report as input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Appendix B Menus and shortcut keys 181

Main menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182File menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Edit menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183View menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Servers menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184AR System Objects menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Migrate menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Script menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Tools menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Window menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Shortcut keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Migrator Glossary 191

Index 193

Contents 9

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 administrator’s guide describes the tasks involved in installing and using Migrator.

Migrator documentsThis 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






You can access product help through each product’s 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 Description Audience

Concepts Guide1 Overview of AR System architecture and features; includes information about add-on products that extend AR System functionality and a comprehensive glossary for the entire AR System documentation set.

Everyone

Installation Guide Instructions for installing AR System. Administrators

Introduction to Application Development with BMC Remedy Developer Studio

Information about the development of AR System applications, including an introduction to using BMC Remedy Administrator.

Developers2

Form and Application Objects Guide

Information about AR System applications and their user interface components, including forms, fields, views, menus, and images.

Developers

Workflow Objects Guide Information about the AR System workflow objects (active links, filters, and escalations) and how to use them to create processes that enforce business rules.

Developers

Configuration Guide Information about configuring AR System servers and clients, localizing, importing and exporting data, and archiving data.

Administrators

BMC Remedy Mid Tier Guide Information about configuring the mid tier, setting up applications for the mid tier, and using applications in browsers.

Administrators

Integration Guide Instructions for integrating AR System with external systems by using web services, plug-ins, and other products, including LDAP, OLE, and ARDBC.

Administrators/Developers/Programmers3

Optimizing and Troubleshooting Guide

Information about monitoring and maintaining AR System and AR System applications to optimize performance and solve problems.

Administrators/Developers/Programmers

Database Reference Database administration topics and rules related to how AR System interacts with specific databases; includes an overview of the data dictionary tables.

Administrators/Developers/Programmers

BMC Remedy Distributed Server Option Guide

Information about implementing a distributed AR System server environment with BMC Remedy Distributed Server Option (DSO).

Administrators

BMC Remedy Flashboards Guide

Instructions for creating, modifying, and administering flashboards to display and monitor AR System information.

Administrators/Developers

C API Reference Information about AR System data structures, C API function calls, and OLE support.

Programmers

C API Quick Reference Quick reference to C API function calls. Programmers


AR System documents

1 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 MigratorGuide 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.

Java API Information about Oracle Java classes, methods, and 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.

Programmers

Java Plug-in API Information about Java classes, methods, and variables used 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.

Programmers

BMC Remedy Email Engine Guide

Instructions for configuring and using BMC Remedy Email Engine.

Administrators

Error Messages Guide Descriptions of AR System error messages. Administrators/Developers/Programmers

Master Index Combined index of all books. Everyone

BMC Remedy Approval Server Guide

Instructions for using BMC Remedy Approval Server to automate approval and signature processes in your organization.

Administrators

Release Notes Information about new features, compatibility, and international issues.

Everyone

Release Notes with Known Issues

Information about new features, compatibility, international issues, installation planning, and open issues.

Everyone

BMC Remedy User Help Instructions for using BMC Remedy User. Everyone

BMC Remedy Administrator Help

Instructions for using BMC Remedy Administrator to develop AR System forms, workflow objects, and applications.

Developers

BMC Remedy Import Help Instructions for using BMC Remedy Import. Administrators

BMC Remedy Alert Help Instructions for using BMC Remedy Alert. Everyone

BMC Remedy Mid Tier Configuration Tool Help

Instructions for configuring BMC Remedy Mid Tier. Administrators

BMC Remedy Browser Help

Instructions for using AR System forms in browsers. Everyone

BMC Remedy Migrator 7.6.04 BMC Remedy Migrator Guide

Outlines procedures for installing BMC Remedy Migrator, setting options, and performing migration tasks.

Administrators / Developers

BMC Remedy Migrator online help

Procedures for setting BMC Remedy Migrator options and performing migration tasks.

Administrators / Developers

BMC Remedy Encryption Security 7.6.04 BMC Remedy Encryption Security Guide

Provides an overview of the BMC Remedy Encryption Security products and explains how to install and configure them.

Administrators

Title Description Audience

Preface 13

Chapter

1
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)



How Migrator worksIf 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.


How Migrator migrates

How Migrator migratesYou 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 serversWith 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 processTo 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.



Figure 1-2: Migration process

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 migrationMigrator 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.

Start

Yes

No

Retrieve Objectto be Migratedfrom Result File

Compare Source and Destination

IsDestinationDifferent or

Missing?

Migrate Object1. Create if missing2. Update if different

Mark forDeletion/Disable

Arethere moreObjects to

Migrate?

Update Result File

IsSourceMissing?

Deletion/DisableMarked Objects

Stop

No

No

Yes

Yes



Table 1-1: Object migration sequence

Sequence Object Sequence Object

1 Groups 15 Active link guides

2 Roles 16 Distributed Server Options: DSO maps

3 Regular forms:� 3a Views� 3b Fields

17 Distributed Server Options: DSO pools

4 Join forms:� 4a Views� 4b Fields

18 Flashboards variables

5 Display-only forms:� 5a Views� 5b Fields

19 Flashboards data sources

6 View forms:� 6a Views� 6b Fields

20 Flashboards

7 Vendor forms:� 7a Views� 7b Fields

21 Flashboards alarms

8 Fields 22 Filter guides

9 Views 23 Web Services

10 Images 24 Packing lists

11 Menus 25 Applications

12 Active Links 26 Plug-in modules

13 Filters 27 Plug-in definitions

14 Escalations 28 Data



AR System object and field migrationsMigrator migrates the following AR System objects and fields.

ObjectsAR 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



FieldsAR 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

2
Installing and starting Migrator
This section describes how to install, start, and uninstall Migrator.


� 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)



Memory usage and disk space requirementsBefore installing Migrator, make sure that your computer has the following memory and disk space:

� Memory—512 MB minimum; 1 GB recommended.

� Disk space—At 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 installationFollow 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.


Installing Migrator

Installing MigratorUse 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.



Starting MigratorAfter 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 MigratorUninstall 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.


Chapter

3
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.


� 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)



Migrator licensesYou 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 accountsUsing 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, andBMC 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.


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 Do this

Add a new server 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.

Modify an existing server Select the server, click Modify, and make the appropriate changes.

Delete a server Select the server, and click Delete.

Add or modify the Users list 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 must include a specific home directory for that user in the directory path.

View port columns for firewall support

Select Advanced Server Properties. Select a server and 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.



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 serversOne 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 MigratorWhen 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.


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 licensesThe 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 detailsTo view Migrator license details for a server, choose Tools > Licenses.

Removing an AR System server and its Migrator license from viewRemoving 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.



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 serverThe 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 serversYou 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.


Logging in to an AR System server

AuthenticationAdministrators 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 windowMigrator 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


� 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.



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.


Chapter

4
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.


� 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)



Navigating in MigratorThe 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 windowWhen 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


Navigating in Migrator

The Migrator main window includes the following areas:

� Title bar—Displays the currently open server.

� Main menu bar and toolbars—Appears 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 tab—groups objects in folders by how they are named. See “Displaying objects in the Object Type view” on page 43.

� Prefix tab—Lists 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 bar—Appears 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 windowsIn 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 (:).



Viewing synchronization within windowsTo 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 tabsYou 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 migration’s status. You can also control active migrations and view information about active, completed, and scripted migrations.

Migration status paneThe 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 What it does

Name Lists the script name or migration name.

Status 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.


Customizing Migrator

Migration status tabsThe 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:

� All—Shows all immediate and scheduled migrations in progress.

� Immediate—Shows all immediate migrations that are in progress, queued, or interrupted.

� Scheduled—Shows all scheduled migrations, as indicated by migration scripts.

� Completed—Shows all completed migrations. To display the migration statistics in a migration result report, click the Completed tab and then double-click a migration listing.

Customizing MigratorYou can customize the Migrator main menu, toolbars, and columns in windows.

Customizing the main menu and toolbarsTo 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 Migrator’s default toolbars and main menu, use the following procedure:

Type Designates a scheduled or immediate migration.

Progress Indicates the completion percentage for a migration.

Start Time Indicates the actual start time for a migration.

End Time Indicates the actual end time for a migration.

Source Lists the name of the source server.

Destination Lists the name of the destination server.

Description Displays a brief description of the migration.

Table 4-1: Information in migration status pane (Sheet 2 of 2)

Field What it does



� 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 Migrator’s 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 box—Toolbars 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.


Working with server windows

Figure 4-4: Customize dialog box—Command tab

4 When you have finished making changes, click OK.

Rearranging window columnsYou 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.

Working with server windowsUse 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.



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

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 managementWhen 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.

List of licensed servers



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 objectsTo 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 cachingDuring 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 windowWhen you log in to a server, the objects for that server are displayed in a server window.

Displaying objects in the Object Type viewThe 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.



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 viewThe 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.



Viewing objects by formYou 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 right-clicking a form in the right pane and then choosing Form Details. This action displays the Form Detail tree view.



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.



Viewing objects by applicationYou 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 workspaceA 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.



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 detailsThe 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

FormsTable 4-2: Items listed for forms (Sheet 1 of 2)

Item Description

Form Name The name of the object.

Type For forms, the type of form, such as Join or Regular.

Access Point 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.

New Entry Point 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 Whether any search entry points are available for the object. A search entry point can be clicked to start a search.

Owner The name of the user who created the object.



Active links, filters, and escalations

Timestamp The date and time on which the object was created or changed.

Last Changed The name of the user who last updated the object.

Lock State 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:� None—Allows users to view and modify the object. � Read-only—Prevents users from modifying the object, but

allows them to view its details.� Hidden—More 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

The number of fields of each type included in the form.

Member A, Member B, and so on

If this is a join form, the names of the member forms.

Table 4-3: Items listed for active links, filters, and escalations (Sheet 1 of 2)

Item Description

Name The name of the active link, filter, or escalation.

Primary Form The name of the form that appears in BMC Remedy User when the application opens.

Forms Referenced The number of forms referenced.

Enabled Whether this object is enabled.

Order The execution order for this object.

Execute On The action on which this object executes.

If Actions The number of if actions included.

Else Actions The number of else actions included.

Owner The name of the user who created this object.

Timestamp The date and time on which this object was last changed.

Table 4-2: Items listed for forms (Sheet 2 of 2)

Item Description



Active link guides and filter guides

Last Changed The name of the user who last changed this object.


allows them to view its details.For more information about locked objects, see the Form and Application Objects Guide.

Control Field (active links only)

Typically a menu field or a button, which fires an active link when selected.

Focus Field (active links only)

A field on which an active link fires when the field gains focus.

Qualification The text of any qualification created for this object.

Table 4-4: Items listed for active link guides and filter guides (Sheet 1 of 2)

Item Description

Name The name of the active link guide or filter guide that appears in the server window the BMC Remedy System Administration Console.

Form Name The name of the form to which the guide applies.

Type The type of form to which the guide applies, for example, a regular form.

Label The name of the guide that appears in the Open dialog box in Remedy User.

Owner The name of the user who created the guide.

Timestamp The date and time on which the guide was last changed.

Last Changed The name of the user who last changed the guide.

Table 4-3: Items listed for active links, filters, and escalations (Sheet 2 of 2)

Item Description



Applications


allows them to view its details.� Hidden—More 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 guide’s function.

Table 4-5: Items listed for applications (Sheet 1 of 2)

Item Description

Application Name The name for the application.

Application Label The name for the application that appears in the Open dialog box in BMC Remedy User, and in the application title bar.

Primary Form The form that appears when the application is opened in BMC Remedy User.

Primary View The view of the form that appears when the form is opened.

Owner The name of the user who created the application.

Timestamp The date and time on which the application was last changed.

Last Changed The name of the user who last changed the application.



Application State The current production state of the application, for example, Maintenance or Test.

Table 4-4: Items listed for active link guides and filter guides (Sheet 2 of 2)

Item Description



Packing lists

Web Services

Type 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.

Description A description of what the application does or other pertinent information.

Table 4-6: Items listed for packing lists

Item Description

Packing List Name The name of the packing list.

Packing List Label The label used, if any, for the packing list.

Owner The name of the user who created the packing list.

Timestamp The date and time on which the packing list was last changed.

Last Changed The name of the user who last changed the packing list.



Description A description of the packing list’s function.

Table 4-7: Items listed for web services (Sheet 1 of 2)

Item Description

Web Services Name The name of the web service.

Form Name The form used as the access for the web service.

Web Services Label The name that is displayed to users.

Owner The name of the user who created the web service.

Timestamp The date and time on which the web service was last changed.

Last Changed The name of the user who last changed the web service.

Table 4-5: Items listed for applications (Sheet 2 of 2)

Item Description



Menus

Groups



Description A description of the web service’s function.

Table 4-8: Items listed for menus

Item Description

Menu Name The name of the menu.

Type The type of menu, either Character, File, Search, SQL, or Data Dictionary.

Refresh The condition on which the menu is refreshed, either On Connect, On Open, or on 15 Minute Interval.

Timestamp The date and time on which the menu was last changed.

Owner The name of the user who created the menu.

Last Changed The date and time on which the menu was last changed.



Table 4-9: Items listed for groups (Sheet 1 of 2)

Item Description

Group ID The unique ID for the group

Group Name The name of the group.

Table 4-7: Items listed for web services (Sheet 2 of 2)

Item Description



Flashboards

Plug-ins

Roles

Group Type The permission type for the group, either None, View, or Change.

Category 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.

Table 4-10: Items listed for Flashboards

Item Description

Flashboards A tool for representing data visually from AR System forms.

Flashboards alarms 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.

Table 4-11: Items listed for plug-ins

Item Description

Plug-in modules 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.

Plug-in definitions Definitions for selected plug-ins.

Table 4-12: Items listed for roles

Item Description

Role ID The unique identifier for this role.

Role Name The name of the role.

Application The application to which this role belongs.

Table 4-9: Items listed for groups (Sheet 2 of 2)

Item Description



Deleting objects from servers or filesAlthough 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 objects—impact warning message

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.

Objects affected by deletion



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 migrationsYou 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 binary-based. 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 serverUse 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.


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.



� 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 formatYou 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.


Chapter

5
Migration options
This section describes options you can set before you perform migrations.


� Overview (page 60)� General options (page 60)� Migration options (page 62)� Directory options (page 77)� Viewing backup, script, and results files (page 78)



OverviewMigrator 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 optionsUse 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.


General options

3 Select the following general options:

� Login/Display Login Dialog Box for Each Server Connection—If 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.

� Caching—Allows you to cache the local server or update directly from the server.

� Refresh object cache and database on type change—If 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 locally—If checked, refreshes objects locally.

� Delete associated dependency and database files for .migrator binary files when Migrator file is closed—Provides 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-consuming—up 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 Mode—If 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”



Migration optionsMigration options set how migrations are performed.

Figure 5-2: Migration options


Migration options

You can select the following migration options:

� Multiple-thread—Specifies options for using multiple threads during migrations.

� Required Objects—Specifies whether to migrate required menus, table field forms, join form members, Flashboards variable and data source objects, and forms related to menus.

� Backup—Specifies 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 Removal—Provides 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 History—Specifies how Migrator adds or merges entries in history fields after each migration.

� Groups—Specifies how Migrator merges new groups with existing groups.

� Data—Specifies default settings for data migrations. These settings are used as the default settings in the Migrator Data Settings dialog box.

� Retry—Enables 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 Prefixes—Enables to you specify prefixes that should be ignored during migrations.

� Masks—Enables 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 optionsUsing 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.



� 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.


Migration options

Required Object optionsUnder 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


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



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 data-only 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:

� Yes—The 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 optionsBackup 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.


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 objects—A 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 all—Migrator 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.



Object Removal optionsObject 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

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.

FORM 1

SERVER A SERVER B

zActive Link: y

Filter: yz

FORM 1

Migrating Server A to Server B z

zy

Active Link: x

Filter: x

y


Migration options

� To select Object Removal 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 Objects—Migrator 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 optionsWith 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.



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


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 History—enables you to enter some text, such as a description of the change history.

� Merge Change History and append a string—the 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


Migration options

Group optionsGroup 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


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 Groups—Migrator generates an error for groups with existing request IDs.

� Generate New ID for All Groups—Migrator creates a new request ID for all groups.

� Replace Old Group with New Group—Migrator replaces old group information with new group information.

� Update Old Group with New Group’s Data—Migrator merges old group information with new group information.

Figure 5-9: Group options



4 For each group merging option, select either or both settings:

� Ignore Required Fields

� Ignore Pattern Checking

5 Click OK.

Data optionsData 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


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 Records—Migrator generates an error for records with existing request IDs.

� Generate New ID for All Records—Migrator 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 Record—Migrator replaces old record information with new record information.

� Update Old Record with New Record’s Data—Migrator merges old record information with new record information.


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.



Retry optionsRetry 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


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


Migration options

Ignore Prefix optionThis 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 reportWhen 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 dataMigrator 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.



� To specify prefixes to be ignored


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 optionsMigration 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.


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 optionsDirectory 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


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.



Viewing backup, script, and results filesYou 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.


Chapter

6
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.


� Defining migration modes (page 80)� Copy/Prefix migrations (page 80)� Migration checklist (page 81)� Monitoring migrations (page 81)� How objects are migrated (page 82)



Defining migration modesMigrator 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 modeIn Migration mode, migrations run immediately.

Scripting modeIn 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 migrationsWhen 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 object’s 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.


Migration checklist

Migration checklistBefore 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 migrationsUse 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.



Controlling migrationsTo 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:

� Start—Starts a scheduled migration (before its scheduled time).

� Restart—Restarts an interrupted or stopped migration (starting from the point of interruption and going forward).

� Stop—Stops any type of migration.

� Delete—Deletes an interrupted, stopped, scheduled, or completed migration, along with the migration result files.

Viewing migration resultsFor 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 failuresIf 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 migratedThis 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 migrationsWhen 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.


How objects are migrated

Migrating join formsWhen 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

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.

FormB

FormH

FormF

FormE

FormD

FormA

FormJ

FormC

FormG

FormI

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



� 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 objectsWhen 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.


How objects are migrated

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 formsIf 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 namesMigrator 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 Server name replaced with

Action taken by Migrator

source destination Migrator recognizes source and replaces it with destination.

source.domain.com destination Migrator recognizes source and replaces it with destination.



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.

source.otherdomain.net

destination Migrator recognizes source and replaces it with destination, because it does not know that the domain is not the correct one.

server.domain.com server.domain.com

The object references a different server and Migrator leaves the reference intact.

Table 6-2: Changes in server references for destination names

Server name referenced Server name replaced with Action taken by Migrator

source source Migrator does not recognize the name as the same as source.domain.com and does not replace it.

source.domain.com destination Migrator recognizes source.domain.com and replaces it with destination.

source.otherdomain.net source.otherdomain.net

Migrator does not recognize the name as the same as source.domain.com and does not replace it.

server.domain.com server.domain.com The object references a different server and Migrator leaves the reference intact.

Table 6-1: Change in server references for source names (Sheet 2 of 2)

Server name referenced Server name replaced with

Action taken by Migrator


Chapter

7
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.


� 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)



Performing migrationsMigrations 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 objectsYou 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.


Migrating objects

4 From the Migrate menu, choose the type of object migration to perform:

� All AR System Objects—Migrate all objects listed in the source window.

� Form and Related Objects—Migrate a form and all of its related objects.

� Deploy Application—Migrate an application and all of its objects to the same server. See “Migrating applications.”

� Selected Objects—Migrate 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.”



Migrating applicationsYou 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.


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 applicationWhen 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.



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 serverIf 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.


Migrating a form view and its associated fields

Migrating a form view and its associated fieldsYou 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 fieldsYou 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.



� To migrate fields

1 Open windows for the source and destination.




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 dataYou 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:



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.


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.



2 Choose Migrate > Migration Mode or Scripting Mode.

3 Choose Migrate > Form Data, then choose one of the following options:

� Form Data Only—Only the entries within the form are migrated.

� Form and Data—Both the form and the entries within the form are migrated.

� Form, Related Objects, and Data—Both 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



The migration is listed at the top of the dialog box with the following information:

� Source Name—The 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 Form—The name of the form that includes the data being migrated.

� Destination Name—The 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 Form—The name of the AR System form on the destination to which the data applies.

� Object Settings—The objects to be included in the migration, based on what you selected in step 3.

� Data Mode—The 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 Entries—The number of entries being migrated.

� Search criteria—Any 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


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 Only—Migrates only forms.

� Form and Related—Migrates forms and related objects.

� Form Data Only—Migrates only form data entries.

� Form and Data—Migrates forms and data entries.

� Form, Related and Data—Migrates 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 Entries—All entries are migrated according to your selections and settings.

� Search Selection—Entries 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 Entries—Number 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 Entries—Migrator generates an error for entries with existing request IDs.

� Generate New ID for All Entries—Migrator creates a new request ID for all entries. If the destination is a file, this selection is not available.

� Replace Old Entry with New Entry—Migrator replaces old entry information with new entry information.

� Update Old Entry with New Entry’s Data—Migrator 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



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.


Migrating data

Creating a data searchA 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.



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 mappingsThe 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 migrationsWhen migrating objects to the same server, you must change the object’s 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 non-prefixed 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.



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.


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.


Chapter

8
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.


� Scripting overview (page 106)� Creating, running, and saving migration scripts (page 107)� Modifying migration scripts (page 109)� Scheduling scripted migrations (page 114)



Scripting overviewYou 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

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.

Migration Starts

Migration Ends

Source Server 1 Destination Server 1

Destination Server 2


Source Server 2 Destination Server 1




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:

� Servers—Lists the servers associated with the script.

� Migrator Files—Lists the .migrator files associated with the script.

� Fields—Presents form fields that are scripted for migration.

� Views—Supplies the number of views scripted.

� Data—Lists the data records contained within a form scripted for migration.

� Special Migrations—Lists 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 scriptsUse 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.



� 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 scriptsYou 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.


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

Modifying migration scriptsYou 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



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 right-clicking.

� 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.



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.


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 scriptYou 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.



3 From the Servers menu, choose the option you want to change:

� Change Login Information—Displays 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 Server—Displays 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 File—Displays 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 Server—Enables you to delete a server from the script.

� Remove File—Enables you to delete a file from the script.

� Change History Option—Displays the Change History Merge Option. See “Change History options” on page 69.

� Change History String—Displays 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 Options—Displays the Prefix dialog box, from which you can change prefix information. See “Performing Copy/Prefix migrations” on page 103.

� Use Definition Files for Backup—Use definition (.def) files as a backup file type. See “Backup options” on page 66.

� Use Migrator Files for Backup—Use .migrator files as a backup file type. See “Backup options” on page 66.

� Back Up All Objects/Back Up Specific Objects—Enables you to back up all files on a destination server, or selected files. See “Backup options” on page 66.

� Back Up Directory—Enables you to select a directory for storage of backup files. See “Backup options” on page 66.

Modifying and removing objects in a scriptUse 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 window’s 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.



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 descriptionsBefore 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.



4 Run the script to verify that the command you created works.

Scheduling scripted migrationsAfter 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 migrationsMigrator 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.


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 scheduleUse 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.


Chapter

9
Dependency reports
This section describes how to create, use, and customize Dependency reports.


� 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)



Overview of Dependency reportsA 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 Dependencies—Displays 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 Dependencies—Displays 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.


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.



Working with Dependency reportsYou 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:

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.

Table 9-1: Options for working with Dependency reports

To do this Take this action

Resize a report Choose View > Zoom and enter a percentage to shrink or enlarge the report. This zoom percentage is also used when printing the report.

Select colors Choose Tools > Options (see “Customizing a Dependency report” on page 122).

Select migration and printing options

Right-click in the right pane of the Dependency report window to display the options menu.

Refresh dependency report information

Select the report window and press F5.

Display an object in a report in Migrator

Double-click a Migrator file to launch a report from its saved location.

Create an image of the report to view in another application

Choose Edit > Copy. Open the other application and choose Edit > Paste. You cannot edit this file.

Add new object to a report Drag the object starting at the source view (the server window used to select the workflow objects).

Scroll to an object in the list view (right pane)

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.


Creating and using Dependency reports

Viewing a Dependency reportWhen 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 reportWhen 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.



� 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


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.


Customizing a Dependency reportMigrator 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.


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.


Chapter

10
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.


� 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)



Overview of Differences reportsDifferences 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 viewBy default, the Comparison tab view appears when you create a Differences report. The Comparison view provides the following information:

� Main settings—The names of the source and destination file or servers

� Created on—The date and time the report was created

� Total results—For 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 required—What needs to be done to resolve the differences

� Source timestamp and destination timestamp—The time stamps for the source and destination

� Destination modified status—Whether 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.


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.



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.


Working with Differences reports

Working with Differences reportsYou can use these techniques when working with Differences reports.

Table 10-1: Working with Differences reports

To do this Take this action

Customize what a report displays Choose Tools > Options, open the Differences tree view, and select the Display option.

Resize a report to your screen Choose View > Zoom and enter a percentage to shrink or enlarge the report. This zoom percentage can also be used when printing a report.

Select colors for reports Choose Tools > Options. See “Customizing a Differences report” on page 133.

Select migration and printing options

Right-click in the right pane of a Differences report window and choose options from the menu.

Refresh Differences report information

Select the report window and press F5.

Display a previously saved Differences report

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.

Add new object to a report Drag the object from the source server or form detail list view.

Scroll to an object in the list view (right pane)

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.

Compare objects between servers, between .migrator files, between a server and a .migrator file, or between two objects on the same server

Right-click the objects and select Differences.

Put forms and related objects into a Differences report

Select them and hold down the Ctrl key as you drag the objects into the report.

Navigate between differences and missing items

Click the Previous or Next Differences icons (yellow icons with red arrows) or Previous or Next Missing icons (yellow icons with blue arrows) in the toolbar.



Creating and using Differences reportsYou 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.


Creating and using Differences reports

Viewing a Differences reportYou 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 double-click 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.



Printing a Differences reportWhen 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


2 Select a directory path where you want the file saved, and enter a file name.

3 Click Save.


Migrating differing objectsWhen 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


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.


Customizing a Differences report

Customizing a Differences reportTable 10-2 lists ways you can customize the display, color, and masking options in a Differences report.

Differences display optionsUsing 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.

Table 10-2: Customizing options for a Differences report

Option What it does

Display Specifies whether to display all objects that are the same, different, or missing.

Colors Establishes the colors for differentiating between objects. The default colors are:� Green—objects that are the same� Red—objects that are different� Blue—Objects missing on the destination� Gray—table headers

Masks Specifies which object properties are to be compared when generating, viewing, or printing a Differences report.



Differences color optionsUsing the differences color options, you choose the colors for comparing objects in a Differences report.

� To select color options for Differences reports


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 optionsMask 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.


Customizing a Differences report

� To select mask options in Differences reports


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 To compare

Forms Form properties (Opens field and view properties.)

Fields Field properties

Views View properties

Active Links Active link properties

Filters Filter properties

Escalations Escalation properties

Containers Application, guide, packing list, and web services properties (including application state)

Menus Character menu properties

Distributed Maps Distributed maps properties

Note: Migrator does not migrate DSO fields, only DSO maps.

Plug-in modules Properties of plug-in modules

Plug-in definitions Plug-in definitions

Distributed Pools Pools (threads) pending distributed operations

FlashboardsFlashboards Data SourcesFlashboards VariablesFlashboards Alarms

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)



Figure 10-6: Differences report mask options

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 drop-down 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.

To change a maskoption, click onthe object type,

and select Enabledor Disabled from

the menu.


Chapter

11
Migration Result reports
This section describes how to create, view, and customize Migration Result reports.


� Overview of Migration Result reports (page 138)� Working with Migration Result reports (page 139)� Customizing a Migration Result report (page 141)



Overview of Migration Result reportsMigration 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


Working with Migration Result reports

The Results report includes these categories:

� Overall migration statistics—Data 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 reportsA 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 your screen

Choose View > Zoom and enter a percentage to shrink or enlarge the report. This zoom percentage is also used when printing a report.

Select colors Choose Tools > Options (see “Customizing a Migration Result report” on page 141).

Display an object type in a report 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.



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 reportMigrator 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 reportAfter 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 reportWhen 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.


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


2 Select a directory path, type a file name, and click Save.


Customizing a Migration Result reportYou 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:

� Display—Specifies which types of objects to show or hide in a report.

� Colors—Sets the colors for displaying migration results.

Result display optionsThe 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


2 Under Category, select Migration Results > Display.



Figure 11-2: Migration Results display options

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 optionsThe result color options enable you to choose colors for tables in a Migration Result report.

� To select color options for Migration Result reports


2 Under Category, select Migration Results > Colors.

Figure 11-3: Result color options

To set an option,click the item,

then select Showor Hide from thedrop-down list.

To change a color,click on the optionname, and select a

color from the colorpicker.


Customizing a Migration Result report

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.


Chapter

12
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.


� Overview of Source Control (page 146)� Starting SC in Migrator (page 146)� Working with SC in Migrator (page 147)



Overview of Source ControlMigrator 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 other’s 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 MigratorSC 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


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.

Working with SC in MigratorThe 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

If you see a check mark over an object’s icon, that object has been checked out. Migrator remembers column settings for the next viewing (see “Rearranging window columns” on page 41).

Table 12-1: Source control information in Migrator windows

Column heading Description

In SC Verifies if the object is in SC. This heading only appears in a SC window.

Checked Out By User States who has the object checked out.

SC Last Modified By States who last modified the object.

SC Timestamp States when an object was last accessed.



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 Description

Get Latest Version 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.

Check In 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.

Check Out 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.

Undo Check Out 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.

Add to Source Control Adds the objects to the SC database. The file is archived in the SC project.

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.


Working with SC in Migrator

Refresh Status Refreshes the current status information of an object from the SC database.

Run Source Control Client Runs the SC system client.

Table 12-2: Source control icons in Migrator SC toolbar (Sheet 2 of 2)

Migrator SC icon Description


Chapter

13
Support for overlays and custom objects
This chapter describes how Migrator supports operations on the AR System overlays and custom objects.


� Operations on overlays and custom objects (page 152)� Comparing objects at the same location (page 153)� Migration of overlays and custom objects (page 155)



Operations on overlays and custom objectsBeginning 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.


Comparing objects at the same location

Comparing objects at the same locationBeginning 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.



� 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.


Migration of overlays and custom objects

Migration of overlays and custom objectsThis 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 destinationIf 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 destinationIf 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.



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 destinationIf 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 serversIf 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.04If 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.


Migration of overlays and custom objects

Figure 13-2: Migration process for overlays

Start

For each selected object:Is it an overlay

object?

Create or replace the object at the destination server by using a

predefined migration process

No

Is the overlaypresent at the

destination server?Migrate the overlay to the

destination server

End

Replace the overlay at the destination server

Add the result to the result report Add the error to the result report

Was the overlay migrated

successfully?

Yes

Were all selected objects migrated?

Yes

No

No

No

User selects multiple AR System objects including base (overlaid

and unmodified) and overlay objects

Yes

Yes


Appendix

A
Migrator command-line interface
This appendix discusses the Migrator command-line interface.


� 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)



OverviewThe 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.


XML files for processing commands

XML files for processing commandsThe 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.

The Migrator CLI also makes XSD schema files available that can be used to validate XML documents.

Table A-1: XML files used in Migrator command-line interface

XML file Migrator CLI function

Package Can be used to assemble multiple sets of instructions within one migration.

Configuration Specifies migration, logging, mask, differences, change history, backup, and prefix options. For more information about options, see Options.

Instruction 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.

Difference Enables migration of all objects found to be different or missing between source and destination.

Metadata mapping Used for migrations that include CMDB and ITSM.



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 optionsTable 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 Function

-s --source The server or file serving as the source.

-d --destination The server or file serving as the destination.


Command line options

-e --sourceForm For data migrations, the start of a data block that determines the data to be compared or migrated.

-q --qualification A string that represents the qualification used to obtain the data.

--count 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.

--list Specifies use of the List port on the source, if the source is a server. The port number is the List port.

--fast Specifies the use of the Fast port on the destination, if the destination is a server.

--fieldid 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.

--disable Specifies whether related workflow should be disabled in the target form during a migration.

--fieldmap The name of the file (.arm or .armx) that contains field mappings, if field mapping is enabled for this data migration.

-p --package If a package XML file is included in this migration, the name of the file.

-u --user The user name required to log in to the server. The default user name is Demo for both source and destination.

--dst_user 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.

-p --password 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.

--dst_password 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.

-a --authentication 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.

-t --tccport The TCP port number, if any, for connection to the AR System server.





-r --rcpport The RCP port number, if any, used for connection to the AR System server.

--dst_tcpport The TCP port number, if any, for connection to the destination server.

--dst_rcpport The RCP port number, if any, used for connection to the destination server.

--layout 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.

-m --migrate Migrate all specified instructions from source to destination.

-c --compare 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 The name of the configuration XML file used in the command.

--instruction The name of the instruction XML file used in the command.

--xslt The name of the XSLT transformer file used to transform Difference reports from .xml format to any format you specify (such as HTML).




Metadata mappings and CMDB

Metadata mappings and CMDBThe 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.

--xsltx The file extension to be applied to the transformed file. Defaults to '.html' if an extension is not specified.

--form--activelink--filter--escalation--activelinkguide--filterguide--application--packinglist--webservice--menu--dsomap--dsopool--flashboard--alarm--variable--image--pluginmodeule--plugindefinition--metadata

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.





Mapping filesThe following mapping files contain the actual mapping details and define how the various CMDB forms relate to each other:

� CMDBMetaData.xml—When this file is used, extra attributes and indexes that are not found on the source are not deleted on the destination.

� CMDBMetaDataEnableDelete.xml—When 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 typesThe mapping design consists of the following mapping types:

� AR System form-to-form data mappings

� AR System object mappings

Form-to-form data mappingsIn 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 mappingsIn 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’



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 structureThe 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 name—The 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-form—The 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.

� description—Text 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 name—The name of the form on the AR System server.

� unique-field-id—The unique identifier for the field. By default, 1 is used.

� name-field-id—The 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-form—The 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.



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 type—The AR System object that does not include metadata.

� cascade—The action to take if the parent entry is deleted. Options are:

� all—Perfoms both creation and deletion of entries.

� create-orphan—Creates only entries found on the source but are missing from the destination. Does not delete extra entries found on the destination.

� delete-orphan—Deletes 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 form—The name of the external form where many entries match one entry locally.

� local-key-id—The field ID of the local key used in the external form to make multiple entries from the local form.

� foreign-key-id—The 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.



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 form—The name of the external form, where one entry matches many local entries.


� foreign-key-id—The 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 form—The name of the external form where one entry matches one entry locally.


� foreign-key-id—The unique field ID used on the external form. This ID is not 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 form—The 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 multiple entries from the local form.

� foreign-key-id—The unique field ID used on the external form. This ID is not required because the unique-field ID defined on that form can be used.

� mapping-form—The name of the intermediate form used in the mapping.



� source-field-id—The 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 local-key-id field or the unique-field-id.

� destination-field-id—The 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 ITSMThe 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 ITSMThe 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 Target form Mapping type Local field ID Foreign field ID

COM:Company n/a n/a n/a n/a

COM:CompanyAlias COM:Company one to one 1000000072 1


Metadata mappings and BMC Remedy ITSM

FIN:ConfigCostCentersRepository

COM:Company many to one 1000000001 1000000001

FIN:CostCenterUDAAssociations


CTM:Region COM:Company many to one 1000000001 1000000001

SIT:SiteCompanyAssociation COM:Company many to one 1000000001 1000000001

SIT:Site SIT:SiteCompanyAssociation

one to many 1 1000000074

SIT:SiteAlias SIT:Site one to one 1000000074 1

SIT:SiteGroup COM:Company many to one 1000000001 1000000001

CTM:People COM:Company many to one 1000000001 1000000001

CTM:People SIT:Site one to one 1000000074 1

CTM:LoginID CTM:People many to one 1000000080 1

User CTM:People one to many 101 4

CTM:SupportGroupFunctionalRole

CTM:People many to one 4 1

CTM:SupportGroupAssociation


CTM:PeoplePermissionGroups CTM:People many to one 1000000080 1

CTM:LoginID CTM:People many to one 1000000080 1

CTM:PeopleWallet CTM:People many to one 1000000080 1

CTM:PeopleHRAttendanceMgmt


CTM:PeopleHRTimeManagement


CTM:PeopleHRTimeManagement

CTM:PeopleHRAttendanceMgmt

many to one 1000002139 1

CTM:PeopleEducation CTM:People many to one 1000000080 1

CTM:PeopleTravelProfile CTM:People many to one 1000000080 1

CTM:PeopleBenefitInfo CTM:People many to one 1000000080 1

CTM:PeopleITSkills CTM:People many to one 1000000080 1

CTM:PeopleWorkLog CTM:People many to one 1000000080 1

NTE:CFG-NotificationEvents


CTM:PeopleOrganization COM:Company many to one 1000000001 1000000001

PCT:ProductCatalog PCT:ProductCompanyAssociation

one to many 1 1000000097

PCT:ProductCompanyAssociation






Mapping to a foreign entry ID fieldWhen 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 dataIn 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”>

PCT:ProductCompanyAssociation

PCT:ProductCatalog many to one 1000000097 1

CTM:SupportGroup COM:Company many to one 1000000001 1000000001

CTM:SupportGroupAlias CTM:SupportGroup many to one 1000000079 1

CTM:SupportGroupAssignments

CTM:SupportGroup many to one 1000000079 1

CTM:SYSAccessPermissionGroups


PCT:ProductAlias PCT:ProductCatalog many to one 1000000097 1

PCT:ProductModel-Version PCT:ProductCatalog many to one 1000000097 1

PCT:ProductCatalogAliasMappingForm

PCT:ProductCatalog one to many 1 1

CFG:GenericProdServiceAssoc

PCT:ProductCatalog many to one 1000000097 1

CFG:GenericProdServiceAssoc PCT:ProductModelVersion

many to one 1000000799 1

CFG:GenericCompanyModuleAssoc


CFG:ServiceCatalog CFG:ServiceCatalogAssoc

one to many 1 1000000096

CFG:ServiceCatalogAssoc COM:Company many to one 1000000001 1000000001

CFG:ServiceCatalogAssoc CFG:ServiceCatalog many to one 1000000096 1

CTM:PeopleTemplateSG CTM:SupportGroup many to one 1000000097 1

CTM:PeopleWorkLog CTM:People one to many 1000002674 1

CTM:PeopleWorkLog CTM:People many to one 1000000080 1

NTE:CFG-NotificationEvents CTM:SupportGroup many to one 1000000079 1




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 optionsThe 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.

Examples of CLI migration commandsIn 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.


WARNING If the comparison result file already exists, it is overwritten with the new file.

Specified form migration/comparisonmigratorcli –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/comparisonThis 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


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/comparisonmigratorcli –m –s <sourceLocation> -d <destinationLocation> –g “Migrator Configuration.xml” –u Demomigratorcli –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/XMLSchema-instance” 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>

CMDB instructionsThis 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/XMLSchema-instance” 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 fileThis 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/XMLSchema-instance” 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” merge-option=“update” ignore-required-fields=“true” ignore-pattern-matching=“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-required-fields=“true” ignore-pattern-matching=“true” count=“0” disable-related-workflow=“false”> <ports enabled=“true” list=“390635” fast=“390620” /> </data> </data-instructions></instruction></instructions>

Multiple migrations or comparisons using one instruction fileThis 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/XMLSchema-instance” 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” destination-name=“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-related-workflow=“false”> <ports enabled=“true” list=“390635” fast=“390620” /> </data> </data-instructions> </instruction></instructions>

Package fileThis 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 inputThis 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.


migratorcli –m –s <sourceLocation> -d <destinationLocation>--difference <difference_report.xml> –g “Migrator Configuration.xml” –u Demoigratorcli –c –s <sourceLocation> -d <destinationLocation> --difference <difference_report.xml> –g “Migrator Configuration.xml” –u Demo


Appendix

B
Menus and shortcut keys
This section explains the Migrator main menu bar and lists the shortcut keys specific to Migrator.


� Main menu bar (page 182)� Shortcut keys (page 189)



Main menu barThe main menu bar, at the top of the Main Migrator window, provides access to most of Migrator’s features, such as: licensing and logging on to servers, migrating AR System objects between servers, exporting definitions, and printing. You can customize Migrator’s 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 menuThe 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 Use to

New Server Window 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.

New Migrator File 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.

New Differences Window

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.

New Migration Script 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.

Open Choose a file to open in Migrator.

Close Close the active window.

Save Save an open window or file using the existing name or a default.

Save As Save an open window or file with a new name.

Print Choose a printer, a print range (pages), and number of copies.

Print Preview Preview the file you want to print (migration result, differences, and dependency reports only).


Main menu bar

Edit menuTable B-2 lists selections in the Migrator Edit menu.

View menuThe 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.

Print Setup Choose a printer, paper, and orientation.

Send Open a send window form your email application so you can send the currently active file on your desktop.

Export to HTML Export a report to HTML format for editing and printing. This selection appears only when a report is open.

Recent Files List the most recent files used.

Exit Shut down Migrator.

Table B-1: File menu selections (Sheet 2 of 2)


Table B-2: Edit menu selections


Copy Copy a selected object in a Migrator window.

Paste Paste an object that was copied into a Migrator window.

Delete Delete a selected object in a Migrator window.

Table B-3: View menu selections (Sheet 1 of 2)


By Application Filter the server view to show only local and deployable applications.

By Workspace Filter the server view to show only objects included in a specified workspace or packing list.

By Form Filter the current Server/Definition view to display a subset or selected list of forms, together with related objects.

Normal Switch filtering off when users select viewing by form, application, or workspace.

Form Details Show form details in a new window, including fields, views, and related objects.

Differences Show the differences between two or more selected objects.

Form and Related Differences

Show the differences between forms and their related objects.



Servers menuThe Servers menu is available only when a new script is created or an existing script is opened.

Downward Dependencies

Show downward dependencies for a selected object.

Upward Dependencies Show upward dependencies for a selected object.

Toolbars Select the toolbars you want displayed in the main window.

Migration Status Show or hide the migration status pane at the bottom of the main window.

Description Bar Show or hide the description bar (for before and after commands) when you are creating a migration script.

Status Bar Show or hide the status bar beneath the migration status pane.

Arrange Icons Arrange a window’s icons alphabetically by name, automatically, or lined up on a grid.

Zoom Set the Zoom factor for the dependencies, differences, and migration result reports, and for printing a report.

Refresh Refresh the current view.

Synchronize Views Synchronize objects within the other open server and report windows.

Table B-3: View menu selections (Sheet 2 of 2)


Table B-4: Servers menu selections


Change Login Information

Update login information, or log in as a different user.

Add Server Select another server to add to the list of servers in a script.

Add Migration File Add a .migrator file.

Remove Server Remove a server from the list of servers in a script.

Change History Option Modify the Change History options on a server in a script.

Change History String Modify the string in the Change History options on a server in a script.

Default Prefix Options Change the default prefix options on a server in a script.

Use Definition Files for Backup

Specify a definition (.def) file format as the backup on a server in a script.

Use Migrator Files for Backup

Specify a .migrator file format as the backup on a server in a script.

Back Up All Objects Back up all objects on a server in a script.

Back Up Specified Objects

Select the objects to be backed up on a server in a script.

Back Up Directory Specify a directory for storage of backup files on a server in a script.


Main menu bar

AR System Objects menuThe Objects menu is available only when a new script is created or an existing script is opened.

Migrate menuThe 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-5: Objects menu selections


Change Source Change the source server for an object in a script.

Change Destination Change the destination server for an object in a script.

Prefix Options Change the prefix options for an object in a script.

Destination Name Change the name of the object on the destination server in a script.

Data Mode Open the Data Migration Settings dialog box used to set up data migrations.

Number of Records Enter the number of records to use for a data migration.

Search Criteria Enter an actual data migration search.

Remove Object Remove the object form the list of objects in a script.

Table B-6: Migrate menu selections (Sheet 1 of 3)


All AR System Objects Migrate all objects.

Form and Related Objects

Migrate selected forms and their related objects.

Deploy Application Migrate an application and its supporting objects.

Selected Objects Migrate selected objects.

Form Data Display a submenu that allows you to:� Migrate form data only.� Migrate a form and data.� Migrate a form, related objects, and data.



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 Migrate all fields form selected forms.

All Views Migrate all views from selected forms.




Main menu bar

Script menuTable B-7 lists selections available in the Migrator Script menu.

Migrate Field by Type 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

Turn on or off the restriction of non-administrative users during a migration.

Migration Mode Run migrations immediately.

Scripting Mode Create a migration script to save or schedule.



Table B-7: Script menu selections


Schedule Migration Script

Schedule a migration for the specific month, date, and time, and the users to notify upon completion.

Edit Scheduled Migration

Edit a scheduled migration.

Execute Migration Script Open and run a migration script.



Tools menuThe Tools menu includes Source Control options. If Source Control installed on your system, the Source Control submenu selections are also available.

Window menuThe Window menu provides options for positioning Migrator objects on your screen.

Table B-8: Tools menu selections


Login Open the Login dialog box.

Accounts Manage user and server lists (where you add servers to Migrator)

Licenses Display current licenses and add or edit existing licenses.

Export Definitions Export object definitions to an AR System definition (.def) file.

Export Application Export an application to an AR System definition (.def) or XML (.xml) file.

Export Locked Definitions

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 Definition Files Convert Migrator definition (.def) files to Migrator (.migrator) definition format.

Customize Customize the main menu and toolbars.

Options Configure Migrator options.

Source Control 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

Table B-9: Window menu selections (Sheet 1 of 2)


Close Close the active window.

Close All Close all active windows.


Shortcut keys

Help menuThe Help menu provides options for displaying Migrator online help and version information.

Shortcut keysMigrator uses special shortcut keys for menu commands and when working in a server window using the Migrate and Tools menus.

Next Display the next active window.

Previous Display the previous active window.

Cascade Arrange windows so they overlap.

Tile Horizontally Arrange windows as horizontal, non-overlapping tiles.

Tile Vertically Arrange windows as vertical, non-overlapping tiles.

Arrange Icons Arrange icons at the bottom of the Window menu.

Server and Window List List the open servers and windows for a session with the active server or window checked.

Table B-9: Window menu selections (Sheet 2 of 2)


Table B-10: Help menu selections


Help topics Open Migrator help.

About BMC Remedy Migrator

Display program information, version number, and copyright date.

Table B-11: Shortcut keys (Sheet 1 of 2)

Menu Key sequence Use to

File menu Ctrl+N Open a new server window.

Ctrl+F Create a new .migrator file.

Ctrl+R Create a new differences window into which you can drag and drop content.

Ctrl+O Open an existing file or browser window.

Ctrl+P Print the active document.

Ctrl+S Save the active file.

Edit menu Ctrl+C Copy a selection and put it on the clipboard.

Del Delete selected objects form a server or file.

Ctrl+V Paste a selection from the clipboard and put it in an active file.

Migrate menu Ctrl+M Migrate selected objects.



Tools menu Ctrl+D Show differences.

Ctrl+E Show downward dependencies.

Ctrl+U Show upward dependencies.

All F5 Refresh the display.

Ctrl+A Select all choices in Form Detail and Server views.

Table B-11: Shortcut keys (Sheet 2 of 2)

Menu Key sequence Use to


Migrator Glossary

For a comprehensive glossary of AR System terms, see the Concepts Guide.

definitionThe structure in which the data in the definition (.def) and Migrator (.migrator) is organized and manipulated.

dependency reportA 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 serverThe server where the current versions of AR System applications that are “in production” are used by users.

differences reportA report that displays differences when comparing server objects.

downward dependenciesA list of objects that the specified object requires, as in a downward dependency report.

immediate migrationsIn Migration mode, the performance of a single migration immediately.

list viewThe type of view displayed in the right pane of a server or report window.

migrationThe process of moving and making existing data work on a different computer or operating system.

migration result reportSee result report.

reportSee dependency report, differences report, result report.

result reportA report that shows the results of a migration. See also status pane.

results windowThe part of the main Migrator window that displays the results of a migration. See also status pane.

scripted migrationsIn scripting mode, the ability to create reusable sets of multiple-server migrations and put them in a holding position.

source serverThe server where AR System applications that are “in development” get modified or updated regularly.

status paneA subwindow of the main Migrator window that displays active, scheduled, and completed migrations, along with the status tabs. See also status tabs.

status tabsA series of tabs in the migration status pane for showing all, immediate, scheduled, or completed migrations. See also status pane.

tree viewA type of view displayed in the left pane of a Migrator server, file, or report window.

upward dependenciesA list of objects that require the specified object, as in an upward dependency report.

Migrator Glossary 191

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

Aaccess points 48Accounts dialog box 28, 85active links, differences options for 135adding

Before or After commands 113licensed servers 30prefixes 103, 104servers 29

Admin mode 81advanced search bar 96After commands in scripts 113API 16, 115applications

application state 51, 66, 135deployable 52deploying 91, 107exporting deployable 58migrating 90, 103viewing objects by 47

AR Systemfields that can be migrated 21objects that can be migrated 20using with Migrator 16

archive forms 85authentication, user 33

Bbackup

directory 66file location 37options 63, 66root directory 67

selecting options 66viewing backup files 78

Before commands in scripts 113BMC Remedy Developer Studio 102BMC Software, contacting 2

Ccache

creating cache files 42database information 42dependencies file 42management 42recaching hard drive 43refreshing 61server 42updating cache files 43

calendar, using with scripted migrations 114canceling data migrations 100Change History options

defined 63, 70selecting 70

changingdestination name 113directories 77object elements in scripts 110scheduled migrations 115

character menu differences options 135characters, nonalphabetical 37checklist, migration 81CLI 160clients, number of 30CMDB data 75CMDB migrations

form-to-form mappings 166many-to-many forms 169many-to-one forms 169mapping files 166mapping types 166metadata mappings for migrations 165object mappings 166

Index 193


one-to-many forms 168one-to-one forms 169

color optionsdependency reports 122differences reports 133, 134result reports 142

columns, rearranging order 41command-line interface

command examples 173configuration files 161difference files 161instruction files 161log files used with 162metadata mapping files 161object type 168options 162overview 160package files 161using differences report as input 178XML document structure 167XML files used in 161XSD schema files 161

commands, Before and After 113comma-separated values 101comparison view, differences reports 126completed migration 39computed groups 54configuration files 161confirmation prompts, showing or hiding 61controlling migrations 82converting definition files 58copy/prefix migrations 80, 103copying objects to the same server 103creating

data search 101dependency reports 120differences reports 130migration scripts 108

custom objects. See overlayscustomer support 3customizing

dependency reports 122differences reports 133main menu and toolbars 40overview 39result reports 141window columns 41

Ddata

creating a data search 101

data searches 96, 101merging options 72migrating 16, 95, 99options 72search qualifications 101settings 99

data mappings, form-to-form 166Data Migration Settings dialog box 97, 99data sources, Flashboards 65database information cache 42data-only form 91.def file extension 56default options, reverting to 63definition files

converting 58defined 56exporting 56

definitions, object 56deleting

backup options 68locked objects 55object removal options 68

dependenciesdirect 119downward 42, 120file cache 42indirect 119upward 42, 120

dependency reportscolor options 122creating and using 120creating HTML file 122customizing 122defined 118display options 120downward dependencies 118migrating objects 122packing lists 118resizing 121saving 121upward dependencies 118viewing 121

deployable applicationsdescribed 52exporting 58

deploying applicationsdata-only form 91Migrate menu 107prefixed versions 103required objects option 91to the same server 92

destination



changing destination name 113destination type 89, 94, 130

destination server 17adding to a script 111Admin mode 81Enforced mode 81

detailsform 45object 48

Developer Studio 102difference files 161differences 147differences reports

color options 133, 134Comparison view 126creating and using 130customizing 133defined 126display options 133field IDs in 84, 128field names in 85for source control 147illustrated 128locked objects in 128mask options 133, 134migrating objects 132Object Details view 127printing 132resizing 131saving 131using as input in command line 178viewing 131

direct dependencies 119directories

directories options 77root directory 67

disabling or deleting objects 63display options

differences reports 133result reports 141

distributed server option (DSO)deleting forms 55maps 135pools 135

document structure, XML 167documentation, AR System 11domains

domain.com 85source.domain.com 86

downward dependencies 42, 118, 120duplicate entries 99dynamic groups 54

EEdit menu 183editing script server options 111embedded server names 85enabling field mapping 100Enforced mode

destination server 81in source control 146, 148

entries, duplicate 99entry points 48escalation differences options 135examples, command-line 173exporting

deployable applications 58differences report to HTML 132locked object definitions 57

Ffailure to migrate 82field IDs, in differences reports 84, 128field mapping 102fields

mapping field values 95migrating 21, 93names in differences reports 85

File menu 182files

.mgrdif 131

.mgrtdep 121

.migrator 126cache 42converting XML files 58definition 56dependencies cache file 42migration report result 37script 37viewing 78

filter differences options 135firewall support 29Flashboards

alarms 135data sources 65, 135variables 65, 135

form name 167forms

archive forms 85archiving 49choosing with prefix 45data-only form 91form differences options 135

Index 195


intermediate 169join forms 83many-to-many 169many-to-one 169migrating join forms 49one-to-many 168one-to-one 169preference server 32related to menus 65table field form migrations 65viewing form details 45

form-to-form data mappings 166

Ggeneral options 60group options

defined 71selecting 71

groupscomputed 54dynamic 54in object list view 53merging new with existing 63regular 54

HHelp menu 189HTML file format, printing

dependency reports 122differences reports 132result reports 141

IIDs, field 85ignoring prefixes 63immediate migrations 17, 39indirect dependencies 119individual record migration 95installation procedure 25instruction files 161integration, Migrator and AR System server 16intermediate form 169ITSM data 75

Jjoin forms

automatic migrations 65

migrating 49, 83

Kkeyboard shortcuts 189keys, license 28

Lleft pane, main window 37licensed server, adding 30licenses

license agreement 25managing existing 31obtaining license keys 28purging 31removing 31transferring to another server 31viewing Migrator license details 31

locked objectsdeleting 55description 49exporting definitions 57lock type 57report details 128

loginauthentication 33changing login information in a script 112options 61preference server 32, 33server login 32, 33to two machines 32user name 33

Mmain menu bar

customizing 39described 182overview 182

main windowdescribed 36Object Type tab 37Prefix tab 37status bar 37status pane 37title bar 37

managinglicenses 31Migrator cache 42server accounts 28



many-to-many forms 169many-to-one forms 169mapping

field values 95files for CMDB migrations 166form-to-form 166metadata 161object 166types for CMDB migrations 166using field 102

mask options 76, 133, 134menus

Edit 183File 182forms related to 65Help 189main menu bar 182Migrate 185Objects 185option for migrating 65refresh conditions 53Script 187Servers 184Tools 188View 183Window 188

merging new and existing groups 63meta name 167metadata, mapping 161Migrate menu 185migrating

applications 103archive forms 85backup directory 66controls 82copy/prefix migrations 80, 103data 16, 95data entries 97dependent objects 122different objects 132embedded server names 85fields 21, 93form and related objects 84immediately 17, 80individual records 95join forms 65, 83Migration mode 88objects 20, 88, 122scheduled migrations 114scripted migrations 17, 107Scripting mode 80sequence of objects 18

special migrations 107table field forms 65with source control (SC) 146

migration status pane 37migrations

backup 63Change History 63CMDB data 75completed 39confirmation prompt options 61controlling 82copy/prefix 80, 103copy/prefix migrations 103data 63data searches 101directories options 77failure 82form and related objects 84Forms and Related 68immediate 39impact on performance 17ITSM data 75menus 182migration checklist 81migration process, overview of 17migration status pane 38modifying migration scripts 109multiple-thread 63object removal 63options 62, 63, 65, 69, 71, 72performing 88required objects 63result files 37retry option 63scheduled 39SLA data 75special migrations 107status tabs 39synchronizing with difference mask options 76table field forms 65tracking progress of 39tracking status of 38viewing progress of 108viewing results 82

modesAdmin 81Migration 88Migration mode 80Scripting mode 80

modifyingdestination name 113existing servers 29

Index 197


migration scripts 111, 114users 29

modifying migration scriptschanging object elements 110modifying objects 112

multiple server handling 106multiple thread options

defined 63selecting 64

multiple threads 63multiple-thread migrations 63

Nname

form 167meta 167

names, embedded server 85new server window, opening 33nonalphabetical characters, sorting 37notification 115

OObject Details view, differences reports 127object mappings 166Object object removal options 69Object Type tab 37, 44Object Type view 43objects

changing object elements in a script 110copying to the same server 103definitions 58deleting from servers 55deleting locked objects 55dependencies 120, 121differences 131disabling or deleting 63displaying in server window 43how objects are migrated 82locked 49migrating 20, 88migrating differing objects 132migration sequence 18modifying in scripts 112object definitions 56Object Type tab 37objects menu 185Prefix tab 37related to form 84removal 63removal options 68

removing from a script 113renaming 43required 63retrieving 18, 34reviewing object differences in reports 130types of details 48viewing by application 47viewing by workspace 47viewing differences 130viewing form details 45

Objects menu 185one-to-many form 168one-to-one form 169opening

migration scripts 108server windows 33

optionsbackup 63, 66caching 61Change History 63, 69command-line interface 162data 72data merging 72delete dependency and database files 61dependencies color 122directories 77display 133editing script server options 111forms related to menus 65general 60group 71Ignore Prefixes 63ignore prefixes 81join forms 65login 61mask 133, 134menus 65migration mode 61multiple-thread 63object removal 63, 68, 69required object 63, 65result report color options 139result reports 141retry 63, 74reverting to Migrator defaults 63table field forms 65

overlayscomparing 153migration 155operations on 152support for 151

overview



dependency reports 118differences reports 126Migrator 16result reports 138scripted migrations 106

Ppackage files 161, 178packing lists

in dependency reports 118in differences reports 135in object list view 52

pattern checking 99performance, impact of migrations 17Performing 87performing migrations 88pools, distributed server option (DSO) 135port numbers 29preference server 32Prefix tab, main window 37Prefix view 44prefixes

adding and removing 103changing options 112choosing forms with 45ignoring 63, 81Prefix dialog box 89

printingdifferences reports 132result reports 140

process, migration 17product support 3progress of a migration 39

Qqualifications, data search 101

Rrefreshing cache 61regular groups 54related objects, migrating 84removal options, objects 63removing

licenses 31object from a script 113prefixes 103result reports 140servers 31

renaming objects 43reports

dependency 120, 121differences 126failure to migrate 82migration dependencies 118resizing 82, 121, 131result 138

required object optionsdefined 65selecting 65

resizing a reportdependency 121differences 131result 82

result files, location 37result reports

color options 139, 142customizing 141defined 138overview 138printing 140removing 140resizing 82, 139saving 140status details 139viewing 140working with 139

results, migration 82retrieving objects 18, 34retry options 74reverting to default options 63roles 54, 103root directory, backup 67running

After commands 113Before commands 113scripted migrations 108

Ssaving

dependency reports 121differences reports 131result reports 140

scheduled migrations 39, 114scheduling scripts

changing 115described 114

Script 187script files, location 37Script menu 187

Index 199


scripted migrationsadding before or after commands 113adding descriptions 113adding servers 111After commands 113Before commands 113changing a schedule 115changing login information 112changing object elements 110creating 107defined 17migration status pane 115modifying 109modifying objects 112opening and running 108overview 106removing objects from a script 113removing servers 111scheduling 114server pairs 106using calendar with 114viewing script files 37, 78

Scripting modedefined 17, 80migrating in 108

searches, data 96, 101selecting

directories option 77general options 60migration options 62

sequencing objects in a migration 18server accounts, managing 28server license dialog box 30server windows

displaying form details 46displaying forms in 45displaying objects 43opening 33, 42removing 31viewing 41working with 41

Servers 184servers

adding 28, 29, 30adding or removing in scripts 111Admin mode 81authentication 33changing login information in a script 112deleting objects from 55destination 17editing server options for a script 111embedded server names 85

Enforced mode 81handling multiple servers 106licensing and storing 30logging on 32, 33managing server accounts 28opening a server window 33, 42preference server 32removing from view 31server authentication 33server cache 42server pairs 106server window description 37source 17source server 94

Servers menu 184settings, data 99shared workflow 66shortcuts, keyboard 189SLA data 75sorting, nonalphabetical characters 37source control (SC)

defined 146Enforced mode 146, 148exceptions 147generating differences report for 147running in Migrator 146working with 147

source server 17, 94source.domain.com 86special migrations 107starting Migrator 26state, application 51status

bar 37in result reports 139migration status pane 38migrations 37tabs 39window 37

storing licenses 30support files 42support, customer 3synchronized viewing 38synchronizing mask options 76

Ttabs

Comparison tab view 126Completed 82, 140Object Details 127Object Type 44



Prefix 37technical support 3threads, in multiple migrations 63title bar, main window 37toolbars, customizing 39tools for using Migrator

dependency reports 120result reports 139source control (SC) 146

Tools menu 188transferring licenses 31tree view, differences reports 131types, mapping for CMDB migrations 166

Uuninstalling 26upward dependencies 42, 118, 120user authentication 33user interface

Data Migration Settings dialog box 99main menu bar 37, 182main window 36Object Type tab 37Prefix tab 37report windows 37right pane 37status bar 37status pane window 37status tabs 39title bar 37toolbars 37viewing information 37window columns 41

users, modifying 29using

dependency reports 120differences reports 130Migration mode 80Scripting mode 80

Vvariables, Flashboards 65View menu 183viewing

backup files 37dependency reports 121differences reports 131files 78form details 45, 46information in windows 37

license details 31migration results 82objects by application 47objects by workspace 47result files 37result reports 140script files 37synchronized window views 38

viewsmigrating 93Object Type view 43Prefix view 44

WWeb Services 52Window menu 188workflow

shared 66support files 42

working with.def file extensions 56.xml file extensions 56dependency reports 120object definitions 56result reports 139server windows 41source control (SC) 147

workspace, viewing objects by 47

XXML document structure 167XML files

converting 58defined 56examples 173exporting 56

Index 201

*183990**183990**183990**183990*

*183990*

remedy migra tor

Documents