MigrationGuide forHEAT ServiceManagement

Migration Guidefor HEAT Service Management

Release 2014.3.1February 27, 2015

Copyrights and TrademarksCopyright © 2011-2015 FrontRange Solutions USA Inc. All Rights Reserved USE OF THIS SOFTWARE, SUBSCRIPTION SERVICES, AND RELATED USER DOCUMENTATION IS SUBJECT TO THE TERMS AND CONDITIONS OF THE APPLICABLE FRONTRANGE SOLUTIONS END-USER AGREEMENT, HEAT CLOUD SUBSCRIPTION SERVICES AGREEMENT, AND ANY TERMS OF SERVICE (“SUBSCRIPTION AGREEMENT”). YOU MUST AGREE TO THE TERMS AND CONDITIONS OF THE SUBSCRIPTION AGREEMENT IN ORDER TO USE THE SOFTWARE AND SUBSCRIPTION SERVICE. WARNING: The software described in this manual and its related user documentation are protected by copyright law. In no event, shall any part of the software or related user documentation be copied, reproduced, distributed, transmitted, stored in a retrieval system, or translated into any language, without the express written permission of FrontRange Solutions USA Inc.

HEAT may include the following and other third party and open source components:Microsoft SQL Server 2012 Management Objects (SMO) redistributable, Microsoft SQL Server CE 4.0 redistributable

Microsoft Entity Framework 5.0

Microsoft Access Database Engine 2010, 2007 Office System Driver: Data Connectivity Components, and Service Pack 1 for Microsoft Access Database Engine 2010 (KB2460011) 64-bit edition.

Saxon, developed by Michael Kay and licensed under the Mozilla Public License 1.0, available at www.mozilla.org/MPL/MPL-1.0.html

PetaPoco, Copyright 2011 Topten Software http://www.toptensoftware.com/petapoco/license

GWT-DND, GWT-Diagrams, GXT from Google

Adobe Flex

YUI, Copyright © 2011 Yahoo! Inc

RowACtions, File Uploader and DateTime Control; Copyright Jozef Sakalos

OWASP AntiSamy, Copyright (c) 2007-2008, Arshan Dabirsiaghi, Jason Li. All rights reserved.

PowerCollections from Wintellect, http://powercollections.codeplex.com/license re-linq from Remotion

Tinymce from Moxiecode Systems AB

CssCompactor by JsonFx, Copyright Stephen M. McKamey

Portions of this software are copyright 2009-20xx by Mats Bryntse Consulting

Portions Copyright © 2007 Douglas Day

Portions Copyright © 2007 James Newton-King

Portions Copyright © 2008 Jerry Hoff

Log4Net, developed by The Apache Software Foundation and licensed under the Apache License Version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0.

Portions Copyright © 2010 RENCI

Sencha Smart chart Legend, Copyright (c) 2011-2012 by Alexander Tokarev, [email protected].

JSch 0.0, Copyright (c) 2002-2014 Atsuhiko Yamanaka, JCraft,Inc. All rights reserved.

Jint (scripting library), Copyright© 2013 Sebastian Ros

ACE, Copyright (c) 2010, Ajax.org B.V. All rights reserved.

Jstz, Copyright (c) 2012 Jon Nylander

IPAddressRange, Copyright 2012-2013 J.Sakamoto, Ms-PL License

Quartz Scheduler source code and documentation are Copyright (c) Terracotta, Inc. Quartz Scheduler is licensed under the Apache License, Version 2.0 (the "license"); you may not use Quartz binaries or source in whole or in part except in compliance with the license. You may obtain a copy of the license at: http://www.apache.org/licenses/ LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the license for the specific language governing permissions and limitations under the license.

Migration Guide for HEAT Service Management Release 2014.3.1

FrontRange Solutions Trademark InformationThe following are trademarks of FrontRange Solutions USA Inc. and/or its affiliates in the United States and/or other countries: FrontRange Solutions®, FrontRange™, SaaSIT™, ModernizeIT™, SaaS2™, GoldMine®, GoldSync®, GoldMine® Answer Wizard™, GoldMine® Management Intelligence™, GoldMine® Manager's Console™, iGoldMine™, HEAT®, HEAT® Service & Support™, HEAT® PowerDesk™, iHEAT™, HEAT® Self Service™, HEAT® Manager's Console™, HEAT® Answer Wizard™, HEAT® Quick Start Wizard™, InfoCenter®, Automated Processes™, First Level Support®, enteo®, DeviceWall®, Centennial Discovery®, Discovery Dashboard®, MicroAudit®, SAM™, The HEAT Is On™, and other FrontRange products and brands.

Other Trademark InformationMicrosoft™, Access™, Office™, and Windows™ are trademarks of the Microsoft group of companies. Other products and brands are the trademarks of their respective owners or companies. Contact FrontRange Solutions USA Inc. at [email protected]. Copyright notice updated:February 2015


About this GuideDocument Contents

Intended Audience

Conventions

Contact Information

Document ContentsThe Migration Guide for HEAT Service Management Release 2014.3.2 contains the following sections:

About the HEAT Migration Tool

Before You Begin: Installing and Setting Up the HEAT Migration Tool

Step 1: Entering Information About the Source Database

Step 2: Entering Information About the Target Database

Step 3: Mapping Tables and Records

Step 4: Mapping Relationships

Step 5: Uploading the Data

Troubleshooting

Intended AudienceThis document is intended for system administrators who are migrating from ITSM Release 6.x, ITSM Release 7.x, and HEAT Classic to HEAT Service Management Release 2014.3.1.

Contact InformationContact FrontRange Solutions USA Inc. as follows:

Corporate Headquarters

Mailing address:


FrontRange Solutions USA Inc.490 North McCarthy Boulevard, Suite 100Milpitas, CA 95035USA

Email:

[email protected]

Technical Support

Contact FrontRange Solutions USA Inc. technical support at [email protected].

ConventionsThis guide uses the following conventions:

Convention Definition and usage

Bold Text that displays in a GUI element (such as a menu item, button, or element of a dialog box) and command names are shown in bold. For example: Click Edit from the toolbar.

Italic Variables appear in italics. Important information may be italicized for emphasis.

[] Square brackets surrounding a command-line argument mean that the argument is optional.

| Vertical bars separating command-line arguments mean that only one of the arguments can be used.

Note. Describes related, parenthetical information, such as an explanation, tip, comment, or other useful, but not imperative, information.

Caution. Describes mandatory information, but is not data-critical.


Convention Definition and usage

Warning. Describes mandatory information about an action that could cause a loss of data.


About the HEAT Migration ToolAbout the HEAT Migration Tool

New Functionality in HEAT Migration Tool Release 2014.3.2

Features of the HEAT Migration Tool

Limitations

HEAT Migration Tool Steps

Terminology

About the HEAT Migration ToolThe HEAT Migration Tool migrates customer data (such as information about incidents) and metadata (including customizations such as workflows) from the source system (ITSM Release 6.x, ITSM Release 7.x, or HEAT Classic) to the target system (HEAT System Management Release 2014.3.1). The HEAT Migration Tool supports transferring a large amount of data between the source and the target systems.

New Functionality in HEAT Migration Tool Release 2014.3.2The new functionality in the 2014.3.1 release of the HEAT Migration Tool is as follows:

Support "distinct" for source table.

Merge two records in the source database into one record in the target database.

Create a default value for a record in the target database when no default value exists in the source database.

Support many-to-one mappings.

Support the ability to append a new validation row for the target database.

Prompt the user to provide a task name.

Convert the server time zone.

Specify the Microsoft SQL timeout settings.


Features of the HEAT Migration ToolThe following table lists features of the HEAT Migration Tool and the source database systems with which they can be used.

Source Database System

Feature ITSM Release 7.x ITSM Release 6.x HEAT Classic

Defines custom data mappings. X X X

Restricts migration data. X X X

Provides default values for empty data records.

X X X

Provides an option to create tables or records that exist in the source database but do not exist in the target database.

X X X

Automatically adjusts the size of the records if they are different (except views).

X X X

Migrates data for link-based relationships. X X X

Assigns roles to employees. X X

Auto-corrects validation data. X X

Imports attachments related to a table or record.

X X

Select a specific record (such as CI.Service) to import.

X X

Creates business rules if they exist in the source database but not in the target database.

X X

Creates relationships. X X

Migrates the Service Catalog, including the out-of-the-box tasks.

X

Migrates request offerings. X

Migrates escalation schedules. X


Source Database System

Feature ITSM Release 7.x ITSM Release 6.x HEAT Classic

Migrates workflows and any quick actions that are referenced by the workflows.

X

Supports many-to-many mappings X X X

Specifies the Microsoft SQL timeout settings X X X

Converts the server time zone X X

Allows expressions X

LimitationsNote the following limitations when using the HEAT Migration Tool:

The HEAT Migration Tool only supports Microsoft SQL Server databases.

The HEAT Migration Tool does not migrate quick actions.

The only exception is in ITSM Release 7.x. The HEAT Migration Tool migrates workflows and any quick actions that are referenced by the workflows. However, those are the only quick actions that the HEAT Migration Tool migrates.

The HEAT Migration Tool supports the transfer of most relationship data that is supported in HEAT Release 2014.3.1. For example, HEAT currently does not support specified relationships, and therefore, the HEAT Migration Tool does not migrate that type of relationship. See Relationships for information about the relationships that are not compatible.

The HEAT Migration Tool does not migrate CMDB relationship (service map) data.

For the audit history, HEAT Release 2014.3.1 uses a shadow table while ITSM Release 6.x and ITSM Release 7.x use a name/value pair. Therefore, the HEAT Migration Tool cannot migrate audit history data in audit history form. However, you can copy the ITSM audit history data into HEAT Release 2014.3.1 and display it (as unformatted data) side by side next to the Release 2014.3.1 audit history data.

The HEAT Migration Tool does not migrate grids, forms, or layouts. You must manually create them after you migrate the data.


If you are migrating from ITSM Release 7.x and use the Service Catalog predefined task, the system occasionally does not convert some business rules. The system displays an error with this information. See Invalid Expression Data.

The HEAT Migration Tool does not migrate the following: business rules, Java scripts, regular expressions, and validation on-save rules.

HEAT Migration Tool StepsThe HEAT Migration Tool has a wizard- based user interface with steps for selecting source and target databases, defining the mapping between the source and target tables and records, and importing the data from the source to the HEAT Release 2014.3.1 database. These are the steps:

1 Enter information about the source database. See Step 1: Entering Information About the Source Database.

2 Enter information about the target (HEAT Release 2014.3.1) database. See Step 2: Entering Information About the Target Database.

3 Map the data between the source and target databases. See Step 3: Mapping Tables and Records.

4 Map link-based relationships. (Applies to certain database items in ITSM Release 6.x and ITSM Release 7.x only.) See Step 4: Mapping Relationships.

5 Import the source data. See Step 5: Uploading the Data.

TerminologyThis document uses the following terminology:

Source database: The source system. Can be HEAT Classic, ITSM Release 6.x, or ITSM Release 7.x.

Target database: The target system. In this case, it is always HEAT Release 2014.3.1. The HEAT database is comprised of an Application Server and a Database Server.

Table: A piece of a database. Each database has multiple tables.

Record. A piece of a table. Each table has multiple records.


Before You Begin: Installing and Setting Up the HEAT Migration Tool

Before You Begin

Installing the HEAT Migration Tool

Starting the HEAT Migration Tool

About Migrating Date and Time Values

About Setting the Timeout Value

Before You BeginIf you are migrating data from ITSM Release 6.x or ITSM Release 7.x, ensure that the MSDTC service is running on the local machine with network DTC access enabled.

You must install HEAT Service Management before you install and run the HEAT Migration Tool.

Set your runtime environment:If any database table has more than 100,000 rows of data, we recommend having 16 GB of memory, 20 GB of free disk space, and a core 2 CPU.

Otherwise, we recommend having 8 GB of memory, 10 GB of free disk space, and a core 2 CPU.

Installing the HEAT Migration Tool

1 Turn off any anti-virus software.

2 Stop all FrontRange Solutions services. Use the Task Manager to verify that no FrontRange Solutions processes are running.

3 Access the installation folder on the FrontRange Solutions product CD or download folder. Right-click HEATMigrationTool.exe and select Run as administrator.

The installer launches. The FrontRange Solutions HEAT Migration Tool welcome dialog box appears.

4 Click Next. The License Agreement dialog box appears.


5 Select I accept the terms in the license agreement and click Next. The Destination Folder dialog box appears.

6 Click Next to accept the default installation folder, or click Change and select a different folder. The Custom Setup dialog box appears.

7 Click Next. The Ready to Install the Program dialog box appears.

8 Click Install. The HEAT Migration Tool installs. When it finishes, the system displays the Completed dialog box.

9 Click Finish.

Starting the HEAT Migration ToolThe HEAT Migration Tool is located on the HEAT Application Server in a folder called C:\Program Files\FrontRange Solutions\HEAT\MigrationTool.

To open the HEAT Migration Tool, on the server where you installed the HEAT Service Management system, click Windows > Start > All Programs > FrontRange Solutions > HEAT > Migration Tool.

The HEAT Migration Tool opens and displays the Source Connection screen.

About Migrating Date and Time ValuesIn ITSM Release 6.x and ITSM Release 7.x, all DateTime fields are stored in the server time zone. However, in HEAT Service Management, DateTime fields are stored in UTC time. Therefore, when you migrate data, the dates and times will most likely be incorrect as they are in a different time zone instead of in UTC.

This feature only applies to date and time values that are stored as DateTime fields. It does not apply to fields that contain dates or times but are text fields.

This feature does not apply to migrations from HEAT Classic, because date and time fields in HEAT Classic are stored as varchar and not as DateTime fields.


To ensure that the migrated data is in the correct time zone, do the following before you begin the migration:

1 Open the HEAT Migration Tool.

2 Click the Settings icon on the bottom. The tool displays the Settings screen.

3 Check Date time conversion.

4 Select the time zone of the ITSM server from the Server time zone field.

5 Click Ok.

For example, if you selected (UTC-8:00) Pacific Time (US & Canada) for the server time zone, then when the HEAT Migration Tool migrates the data from ITSM to HEAT Service Management, the data will have date and time values of 8 hours later. If an incident was created in ITSM at 3:30, in HEAT Service Management, the record is converted so that it shows that it was created at 11:30 (8 hours later).

About Setting the Timeout ValueTo provide a timeout value, to avoid a long waiting time if you have a timeline for migrating data, you can set the amount of time before which the Microsoft SQL Server stops running. Usually, Microsoft SQL Server commands time out after approximately 20 minutes; however, in the past, sometimes the HEAT Migration Tool took longer than 20 minutes to migrate the data, causing the Microsoft SQL Server to time out, which stopped the migration.

To ensure that all Microsoft SQL Server commands have enough time to execute completely, set the timeout value by doing the following:

1 Open the HEAT Migration Tool.

2 Click the Settings icon on the bottom. The tool displays the Settings screen.

3 In the Sql command timeout (in min) field, enter a number. The default is 60.

4 Click Ok.


Step 1: Entering Information About the Source Database

Selecting the Source Database

Using ITSM Release 6.x and ITSM Release 7.x

Using HEAT Classic

Selecting the Source DatabaseThe first step of the HEAT Migration Tool is to enter information about the source database.

In the Application Type field, from the drop-down list, select the source database. You can select HEAT Classic, ITSM Release 6.x, or ITSM Release 7.x.

Depending on which source you select, the system displays a different screen. See one of the following sections:

Using ITSM Release 6.x and ITSM Release 7.x

Using HEAT Classic

Using ITSM Release 6.x and ITSM Release 7.xFor ITSM Release 6.x and ITSM Release 7.x, the HEAT Migration Tool uses the ITSM API to retrieve the metadata. See Figure 1 for an example of the Source Connection screen for ITSM.


Figure 1 -- Source Connection Screen for ITSM

1 Enter information about how to connect to the ITSM source database, as follows:

Field Description

Application Login Credentials

User The user name to log in to the source database.

Password The password for the user above.

Role The role for the user above.

Connection Name The name of the connection to the source database. The system displays the name of the default connection next to the word {Common}.

Follow these steps to select a different connection:

1 Click Select/Create connection.... The system displays the Connect to FRS Application Server screen.

2 Select a database.

3 Click OK. The system displays the name of the connection that you selected next to the word {Common}.


4 Click Next.... The system displays the Target Database screen. Go to Step 2: Entering Information About the Target Database.

Using HEAT ClassicFor HEAT Classic, the HEAT Migration Tool directly connects to the database and reads the metadata from the database. See Figure 2 for an example of the Source Connection screen for HEAT Classic.

Figure 2 -- Source Connection Screen for HEAT Classic

1 Enter information about how to connect to the HEAT Classic source database, as follows:

Field Description

Source Database

Database server The name of the source database server.

Integrated Login Choose if the target database uses Windows Integrated Security to connect to the source database. If you choose this option, you cannot choose SQL Authentication.

SQL Authentication Choose if the target database uses Microsoft SQL Server Authentication to connect to the source database. If you choose this option, you cannot choose Integrated Login.


Field Description

User (Used only if you chose SQL Authentication) The user name for the Microsoft SQL Server Authentication.

Password (Used only if you chose SQL Authentication) The password for the user above.

Database The name of the source database.

2 Click Next.... The system displays the Target Database screen. Go to Step 2: Entering Information About the Target Database.


Step 2: Entering Information About the Target DatabaseThe next step of the HEAT Migration Tool is to provide details about the target database, which is the HEAT Release 2014.3.1 database. The HEAT Release 2014.3.1 database is comprised of the HEAT Database Server and the HEAT Application Server. See Figure 3.

The HEAT Migration Tool requires a direct connection between the source database and the target database. Enter the target database information in the HEAT Database section.

The HEAT Migration Tool uses a web service on the HEAT Application Server to update the metadata. The information that you enter in the Application Login Credentials section is for the HEAT Application Server.

Figure 3 -- Target Connection Screen


Procedure

1 Enter data on the Target Connection screen as follows:

Field Description

HEAT Database

Database server The server name of the target database.

Integrated Login Choose if the target database uses Windows Integrated Security to connect to the HEAT Database. If you choose this option, you cannot choose SQL Authentication.

SQL Authentication Choose if the target database uses Microsoft SQL Server Authentication to connect to the HEAT Database. If you choose this option, you cannot choose Integrated Login.

User (Used only if you chose SQL Authentication) The user name for the Microsoft SQL Server Authentication.

Password (Used only if you chose SQL Authentication) The password for the user above.

Database The name of the target database. Select from the drop-down list.

Application Login Credentials

Application Base URL The location on your machine where the HEAT Application Server exists. In a deployed machine, this is the server name.

User The user name for the administrator of the HEAT Application Server.

Password The password for the user above.

Role The role of the user above. Select from the drop-down list. Usually, this is Administrator.

Tenant The tenant with which to connect to the HEAT Application Server. Select from the drop-down list.

2 Click Next. The system displays the Tasks screen. See Step 3: Mapping Tables and Records.


Step 3: Mapping Tables and RecordsThe system displays the Tasks screen.

If you are migrating from ITSM Release 7.x, the Tasks screen looks like the one shown in Figure 4. See Working with Predefined Tasks for more information about working with predefined tasks.

If you are migrating from ITSM Release 6.x, the Tasks screen is blank.

If you are migrating from HEAT Classic, the Tasks screen looks like the one shown in Figure 5. The data structure for HEAT Classic contains many dependencies, so to make the migration easier, the HEAT Migration Tool comes with six predefined steps. Although not required, we highly recommend that you migrate your data by performing the six steps in the recommended order.

Figure 4 -- Tasks Screen for ITSM Release 7.x

Figure 5 -- Tasks Screen for HEAT Classic


Use the Tasks screen and its resulting screens to set up the mappings for the tables and records in the source database to tables and records in HEAT Service Management Release 2014.3.1). After you set up the mappings, to actually create the mappings, you need to click Next.

This chapter contains the following sections:

Starting the Mapping Process

Setting Up a Mapping

Editing a Mapping

Working with Predefined Tasks

Finishing the Mapping Process

Starting the Mapping ProcessYou can start the mapping process from the Tasks screen by doing one of the following:

Clicking a predefined task or creating a new task (if you are using ITSM Release 7.x; see Figure 4 and Working with Predefined Tasks).

Clicking the New Mapping icon (if you are using ITSM Release 6.x).

Clicking Step1 BaseAction (if you are using HEAT Classic; see Figure 5).

The system displays the Map screen shown in Figure 6. This screen contains all of the tables in the source database.


Figure 6 -- Basic Map Screen

The HEAT Migration Tool automatically sets up the mappings of tables and records based on their names. For example, if there is a source table called AddressCountry and there is a target table called AddressCountry, the tool automatically maps these tables to each other.

Check the tables that you want to map and click Next. The system maps the tables that you checked.

Setting Up a MappingThere are times when the HEAT Migration Tool cannot automatically set up mappings for tables and records in the source database because no associated table or record exists in HEAT Service Management. Other times, you may want to align a table or record in the source database to a table or record in HEAT Service Management other than the one that the HEAT Migration Tool automatically set up.

For example, if there is a table called AddressState in the source database but no corresponding table in HEAT Service Management, the HEAT Migration Tool does not set up a mapping. However, you can create a


new table in HEAT Service Management called AddressState and then set up a mapping between the two tables. In this case, you must add a table and then set up the mapping between the table in the source database and the new table that you just created.

About Adding New Tables

Adding a New Table

Adding Multiple New Tables

Adding a New Record to a Table

Merging Records

Adding a Default Value

About Adding New Tables

Figure 7 -- Map Screen

Use the Map screen (see Figure 7 ) to create tables using the HEAT Migration Tool. You can also use this screen to set up mappings between tables in the source database and tables in HEAT Service Management, if they are not already set up.


To do this... Do this...

Search for a table in the source database Do one of the following:

Scroll through the list.

Enter the table name in the Filter field.

See errors and warnings for tables and records

Do one of the following:

Check Show only rows with Errors and/or Warnings.

Hover the mouse over the error icon.

See Viewing Errors.

Set up a mapping for a table in the source database with a table in the target database, when they are both in the same row

Check the box for that row.

Set up a mapping for a table in the source database with a table in the target database when the target table row is empty, or to change a source table mapping to a different target table

1 Click the name of the target table. The system displays a down arrow.

2 Click the down arrow and select a different target table. If the table does not exist yet, follow the process in Adding a New Table.

Create a new table for HEAT Service Management based on a table in the source database

See Adding a New Table.

Create multiple new tables for HEAT Service Management based on multiple tables in the source database

See Adding Multiple New Tables.

Create a record See Adding a New Record to a Table.

Populate a record with a default value when no default value exists

See Adding a Default Value.



Merge two records in a source table into one record in the target table (for example, if you have two records called first name and last name in the source table and you want to merge them into one record called full name in the target table)

See Merging Records.

Configure additional details about a table or record, or to edit a mapping set up 1 Double-click the row with the table or click the

Edit Object Mapping icon. The system displays the Edit Object Mapping screen as shown in Figure 15.

2 Follow the information in the Editing a Mapping section.

Adding a New Table

To create a table in HEAT Service Management based on a table in the source database, do the following:

1 In the Source Table column, find the table that you want to copy to HEAT Service Management.

2 Click the Add New Table icon that is found at both the end of the row and in the main toolbar. See Figure 7.

The system displays the first screen of the New Business Object Wizard which lists all the fields that are available for migration. See Figure 8. You cannot make changes on this screen.


Figure 8 -- New Business Object Wizard, Screen 1

3 Click Next.... The system displays the second screen of the New Business Object Wizard. See Figure 9. This screen lists the relationships in the business object. You cannot make changes on this screen.

HEAT Release 2014.3.1 only supports relationships that have a RecID. If the relationship does not contain a RecID, the HEAT Migration Tool displays an error message. You can still migrate the data, though, just not that particular relationship.



Click Next.... The system displays the third screen of the New Business Object Wizard. See Figure 10. This screen lists the rules in the business object, if any.



4 Click Finish. The system creates the table in HEAT Service Management and maps it to the source table.

5 To check that the HEAT Migration Tool created the table correctly, log in to the HEAT Service Management Configuration Console and search for the table by entering its name in the Search field. The system displays the table. Click the tabs to view the details of the table and ensure that it was created correctly.

When you add a table based on an existing table, the tool copies over the rules, but not the forms, grids, or layouts.

Adding Multiple New Tables

To add multiple tables that exist in the source database but do not exist in HEAT Service Management, do the following:

1 Find the tables in the source database that you want to copy to HEAT Service Management.

2 Highlight the rows.

3 Click the Add New Business Object icon in the main toolbar. For some tables in the source database, the tool adds the corresponding tables to HEAT Service Management. However, if there is an error in the table creation process, the tool displays an error icon next to the table name.

The tool creates the table in HEAT Service Management and maps it to the source database.


Figure 11 -- Map Screen with Errors

4 To check that the tool created the tables correctly, log in to the HEAT Service Management Configuration Console and search for the tables one at a time. Click the tabs to view the details of the tables and ensure that they were created correctly.

The HEAT Migration Tool only creates new tables if it can do so without any errors or exclusions. The tool displays an error icon if there is an error, such as the target not existing in the database.

If the error was due to a table not being created, start the New Business Object Wizard. You can review the errors and selectively ignore any metadata that cannot be migrated.

If the HEAT Migration Tool is unable to create the table automatically, you need to create it manually by following the procedure described in Adding a New Table.

When you add a table based on an existing table, the tool copies over the rules, but not the forms, grids, or layouts.

Adding a New Record to a Table

You can also add a new record to a table. See Figure 12. Click the Add icon.


Figure 12 -- New Business Object Group Member Screen

The tool displays an abbreviated version of the Business Object Editor screen, as shown in Figure 13.


Figure 13 -- Abbreviated Business Object Editor Screen

You can add records from the source table into the target table. Follow these steps:

1 Highlight all the rows with records that do not have a corresponding value in the Target Datatype column.

2 Click the Add icon. The tool fills in the values.

3 Click OK to save the new values.

Merging Records

You can merge two or more records in a source table into one record in a target table. For example, if you have two records, one called "first name" and the other called "last name" in the source table, and you want to merge them into one record, called "full name" in the target table, follow the steps here. You create an expression that


uses the standard HEAT expression syntax. For complete information on the HEAT expression syntax, see the HEAT online help.

1 On the Field Mappings screen, highlight the row that contains the new record.

2 In the Target Column column, select the new record name from the drop-down list.

3 In the Modify column, select Expression Converter from the drop-down list.

4 In the column called Expression (you may have to scroll to the right to see this column), enter an expression for the new merged record. For example, to create a new record based on the records called FirstName and LastName, enter "$(FirstName+" "+LastName).

5 Click OK to save the new values.

Adding a Default Value

You can add a value to a record in the target table, even if that record does not exist in the source table. This is in case you have a record in the target table that you want to add values to, but there is no record in the source table that can be mapped to this column in the table in HEAT Service Management. Follow these steps:

1 On the Field Mappings screen, add a new column, by clicking the Add new default field icon. The tool fills in the values.

2 Highlight the new row that you added.

3 Enter a value in the Target Column. For example, enter CIType.

4 In the Type column, select NewSourceRecord from the drop-down list.

5 Enter the corresponding value in the Expression column (you may have to scroll to the right to see this column). For example, enter Service.

When the data is migrated, the tool adds a new column to the target table with the value that you specified.


Editing a MappingTo edit a mapping that has already been set up, go to the Map screen in Figure 7 and click Edit Object Mapping. The system displays the Business Object Editor screen in Figure 15.

See the following sections:

About the Business Object Editor Screen

Table Mappings

Import these Records

Field Mappings

Relationships

Migrating a Workflow

About the Business Object Editor Screen

Figure 14 -- Business Object Editor Screen for ITSM Release 7.x


Figure 15 -- Business Object Editor Screen for HEAT Classic

The Business Object Editor screen has the following tabs:

Table Mappings

Import these Group Members

Field Mappings

Relationships (only for ITSM Release 6.x and ITSM Release 7.x)


Rules

Workflows (only for ITSM Release 7.x)

When you are done with the Business Object Editor screen, click OK.

Table Mappings

Use the Table Mappings tab to do the following:


Create a new table in HEAT Service Management based on a table in the source database

1 Enter the name of the new table in the Target Table field.

2 Click Create New Table.

Delete the existing data in the target table, before importing the data from the source table

1 Check Truncate Target Table.

2 Enter the criteria for truncating the target table in the Truncate Target Table filter field. Usually, this is a Microsoft SQL clause.

Specify how the source RecID and the target RecID are matched

Enter values in the Source -> Target Table Join Criteria fields.

Check Join Using these Columns and enter the column names for the source and the target tables.

For HEAT Classic, which does not have RecIDs for its tables, check Join Using this TSQL Statement. Some of the HEAT Classic tables have a composite primary key, meaning data from more than one column needs to be used to uniquely identify a record.

Specify if you want to insert new data, update existing data, or do both

Select one of the following options from the Update Mode drop-down list:

Insert and update

Insert only

Update only

Import attachments Check Import Attachments. This is not there anymore. Check that it's not there for HEAT Classic, ITSM 6 and ITSM 7.



Selectively import data

Specify criteria in the Filter By (TSQL Statement) field. You can enter any TSQL criteria here, including complex conditions using AND/OR keywords. Prefix the source table with “Source.” and prefix the target table with “Target.”. An example is Source.Status = Target.Status

Assign a role to the table or record that you import

Check a role name from the Assign these Roles drop-down list. Note: This is only an option for the Employee table. This option does not exist for other tables.

See errors and warnings for tables and records


Click Show all Errors/Warnings at the bottom of the screen to display a drop-down list.

See Viewing Errors.

Import these Records

Use the Import these Group Members tab to pick and choose which records to import.

Figure 16 -- Import These Group Members Tab

1 Check the records to import.

2 Click OK.


Field Mappings

From the Business Object Editor screen, click the Field Mappings tab to display the screen in Figure 17. Use this screen to describe how the data transfer will happen, from which record on the source side to which record on the target side.

Figure 17 -- Field Mappings Tab

Use the Field Mappings tab to do the following:


Display the records from a source table only one time

See Creating a Distinct Relationship.

Create a many-to-one relationship mapping See Creating a Many-to-One Relationship Mapping.

Set the default value for a record if a required source record has a null value

Enter a default value, such as 0, in the Value when Empty column for that record.



Convert data types automatically from char and varchar in the source table to nchar and nvarchar in the target table

Highlight the row with the record and under the Converter drop-down list, select Auto.

Populate a target record using a specified literal value

Highlight the row with the record and under the Converter drop-down list, select Literal.

In HEAT Classic, to convert the Profile.Employee table in the source database to the Employee table in HEAT Service Management

Highlight the row with the record and under the Converter drop-down list, select Profile Employee to Employee.

Search for a source field Enter the record name in the Filter text box. (Click Cancel to remove the filter condition.)

See errors and warnings for business objects, such as missing or incompatible information


Check Show only rows with Errors from the top of the page.

Click Show All Errors/Warnings at the bottom of the page to display a drop-down list.

See Viewing Errors.

Creating a Distinct Relationship

Follow these steps to display the records from a source table only one time. (Many tables have duplicate records and you only want to show each record once instead of multiple times, so that when you migrate the data, you only copy a distinct record instead of duplicate records.)


Figure 18 -- Creating a Distinct Relationship

1 Check Distinct By:.

2 In the drop-down list, select a record.

Creating a Many-to-One Relationship Mapping

Follow this process to create many-to-one mappings for validated records in a table. In earlier releases of the HEAT Migration Tool, you could only map records one-to-one. In this way, you can map many different records in the source table to one record in the target table. For example, if you had two records in the source table called PhoneCallLocal and PhoneCallLongDistance, you could map them both to one record in the target table called PhoneCall.

1 On the Field Mappings screen, highlight the row with the validated records to map. Rows with records

to map have a Mapping icon next to them.

2 Open the Field Values Mapping screen.

Figure 19 -- Field Values Mapping Screen

3 Highlight the value to map from the Source list.


4 Highlight the value to map from the Target list.

5 Click Map.

The tool adds the mapping to the Mapped Values list.

The value that you selected from the the Source list is no longer listed there, so you cannot map it again. However, the value that you selected from the Target list still appears in the list so that you can map a different value from the the Source list to this target value again.

6 To unmap the mapping, highlight it and click Break Map.

7 To add a new value to the Target list, click the Add icon. The tool displays the Field Values Append screen.

Figure 20 -- Field Values Append Screen

If the field is defined for other languages, the Field Values Append screen will have additional lines for the translated fields where you can enter the translated values.

8 Enter the name of the new value.


9 Click Ok. The tool validates the new value and the new value shows in the Target list.

10 To remove a value from the Target list, click the Remove icon. You can only remove the values that you have created during this session and not the values from the target table or that you created in previous sessions.

Relationships

(Optional. For ITSM Release 6.x and Release 7.x.) Use the Relationships tab to create relationships between tables and records.

The HEAT Migration Tool automatically maps the source and target relationships if there is a target relationship that matches the source relationship. The relationships are considered equal if the source and target relationship point to the same table or record and if the relationship constraints are the same.

Figure 21 -- Relationships Tab



Copy a relationship from the source to the target Click the green arrow at the end of the row.

Map a source relationship to an already existing target relationship

Click in the target column to show compatible relationships in the target table. After you specify the relationship mapping, the HEAT Migration Tool uses it during the metadata migration to replace the source relationship reference with the target relationship reference.

Quickly see which source records have a target relationship

Scroll through the list. Rows in white show relationships that are mapped.

Quickly see which source relationships are missing target relationships

Scroll through the list. Rows in blue do not have target relationships.

Quickly see which source and target values are not compatible

Scroll through the list. Rows in red contain errors. The tool displays information about the problem at the bottom of the screen.

Search for a source relationship Enter the field name in the Filter text box. (Click Cancel to remove the filter condition.)

See errors and warnings for relationships, such as missing or incompatible information


Check Show only rows with Errors and/or Warnings from the top of the page.


See Viewing Errors.

Rules

Use the Rules tab to create and overwrite rules.


Figure 22 -- Rules Tab


Copy a rule from the source database to the target database (for rules that exist on the target database but are different than the rule on the source database)

Click the green arrow at the end of the row.

Create a new rule for the target database, based on the source

Click the green plus sign at the end of the row.

Quickly see which source and target rules are not compatible

Scroll through the list. Rows in red contain errors. The tool displays information about the problem at the bottom of the screen.

Search for a source rule Enter the field name in the Filter text box. (Click Cancel to remove the filter condition.)



See errors and warnings for rules, such as missing or incompatible information


Check Show only rows with Errors and/or Warnings from the top of the page.


See Viewing Errors.

Migrating a Workflow

There is a Workflows tab on the Business Object Editor screen. See Figure 23. Use it to migrate the workflows and their associated quick actions.

Figure 23 -- Workflows Tab

The Workflows tab lists the workflows for the source and target databases. The HEAT Migration Tool matches them based on their workflow RecIDs and not necessarily based on the workflow content.

To create a new workflow from the source to the target, click the New icon at the right edge of the row.

To verify that the workflow was added to the target table correctly, log in to the HEAT Service Management Configuration Console and search for the target table. Click the Workflows tab and ensure that the workflow is listed and was created correctly.


Working with Predefined TasksCreating a New Task

About Predefined Tasks

Editing a Task

Creating a Task Template

Importing and Exporting

Creating a New Task

To start the mapping process, you can either click on a predefined task (see About Predefined Tasks), as shown in Figure 4, or you can create a new task. Every time you perform a mapping, the tool automatically saves the task.

1 To start a mapping by using a predefined task, from the Tasks screen, click the name of the predefined task.

The tool displays the Map screen.

2 To start a mapping without using a predefined task, from the Tasks screen, click Create New Task. The tool displays the Add/Edit migration action screen.

Figure 24 -- Add/Edit Migration Action Screen

3 Enter a name for the task, a display name for the icon, and a description.


4 To change the image for the new task, click the picture of the image. The tool displays a screen on which you can select a new image. Select an image and click OK.

5 Click Ok.

The task is saved and the tool displays the Map screen.

About Predefined Tasks

You can create your own predefined task so that it is always available to you. For example, when you are on the Map screen, if you check the box next to the Address source table (to map it to the Address target table) and then click Next, the next time that you go into this task, the box next to the Address source table is already checked.

If you are migrating from ITSM Release 7.x, the Task screen contains two predefined mapping templates. See Figure 4. The two templates are for mapping the Profile.Employee information and for mapping the Service Catalog. The configuration for both of these tasks is complex, so the templates provide an initial mapping that works for ITSM Release 7.x out-of-the-box databases. You can also create a new predefined task based on one of the templates.

To create a new predefined task based on one of these templates, click the down arrow next to Create New Task and select one of the two templates. See Figure 25.

Figure 25 -- Task Templates

Editing a Task

After you have created a new task, whenever you go to the Task screen, the system displays the new task. To edit the task, do the following:

1 Right-click on it and select Edit. The system displays the Add/Edit migration action screen.


2 (Optional) Enter a name for the task, a display name for the icon, and a description.

3 To change the image for the new task, click the picture of the image. The tool displays a screen on which you can select a new image. Select an image and click OK.

4 Click Ok from the Add/Edit migration action screen.

5 To delete a task, right-click on it and select Delete.

Creating a Task Template

To create a new task template, so that you can use it to create new tasks in the future, do the following:

1 Create a task. See Creating a New Task.

2 Right-click on the task and select Save as template. The system displays the Add/Edit migration action screen.

3 (Optional) Enter a name for the task template, a display name for the icon, and a description.

4 To change the image for the new task template, click the picture of the image. The system displays a screen on which you can select a new image. Select an image and click OK.

5 Click Ok from the Add/Edit migration action screen. The tool displays the new template name when you click the down arrow next to Create New Task.

6 To edit a task template, click the down arrow next to its name and select Edit.

7 To delete a task template, click the down arrow next to its name and select Delete.

Importing and Exporting

You can import an XML file or export the task data as an XML file by right-clicking on the task and selecting either Export mapping or Import mapping, or by clicking the XML buttons (see Figure 26). The tool displays a screen where you can either save the file (if exporting) or select a file (if importing).


Figure 26 -- Importing From and Exporting To XML

Finishing the Mapping ProcessTo verify that the specific records were added to the target table correctly, log in to the HEAT Service Management Configuration Console and search for the target table. Click the Object Fields tab to view the new records and ensure that they were created correctly.

When you have mapped all the tables and records in the source database to the target database, click Next. The HEAT Migration Tool displays the Relationships screen (see Step 4: Mapping Relationships) or starts the data upload (see Step 5: Uploading the Data).


Step 4: Mapping RelationshipsThe system only displays this screen if you select two or more tables or records that have many-to-many (also called ad-hoc) relationships defined. If you do not have many-to-many relationships defined, you will not see this screen.

If you do not see this screen, continue to Step 5: Uploading the Data.

About Relationships

Mapping Relationships

About RelationshipsIf you select two or more tables or records that have many-to-many (also called ad-hoc) relationships defined and then try to import the data, the HEAT Migration Tool displays the Relationships screen shown in Figure 27. The HEAT Migration Tool imports data and any ad-hoc relationships or link-based relationships. When you import the data, you need to import the relationship data, too.

In ITSM Release 6.x and ITSM Release 7.x, these relationships are called ad-hoc relationships. In HEAT Classic and HEAT Release 2014.3.1, these relationships are called many-to-many or link-based relationships. All terms refer to the same type of relationship.


Figure 27 -- Relationship Screen

This screen displays all the many-to-many relationships for the tables and records that you want to migrate. The tool automatically matches the relationships between source tables and records and target tables and records in two scenarios:

If the relationship names are the same

If the source and target table or record names are the same

This relationship data is stored in a FusionLink table.

Mapping RelationshipsIf there is more than one matching target relationship, you must manually select the correct target relationship as described below.

1 On the Relationships screen, select the relationships that you want to import.

2 Click Next....

3 At the confirmation prompt, click Yes. The tool starts uploading the data. Go to Step 5: Uploading the Data.


Step 5: Uploading the DataData Upload

Working With Duplicate Entries

Post-Upload Tasks

Data UploadThe tool uploads the data and reports the progress, including errors, on the Upload screen. See Figure 28. To abort the upload, click Stop.

Figure 28 -- Upload Screen

When the tool finishes the data upload, the system displays information about the migrated data. See Figure 29.


Figure 29 -- Upload Complete Screen

Working With Duplicate EntriesIn case of a unique constraint violation during the data import, the HEAT Migration Tool lists the duplicate entries with an option to filter out duplicate records or remove the unique constraint in the target database. See Figure 30.


Figure 30 -- Duplicates List Screen

The unique constraint violation commonly occurs during the data migration of employee records from ITSM Release 6.x and ITSM Release 7.x to employee records in HEAT Release 2014.3.1, although it can also occur with HEAT Classic. The HEAT Release 2014.3.1 employee table contains a unique constraint on the PrimaryEmail record, which was missing in the ITSM Release 6.x and ITSM Release 7.x employee tables, and therefore the PrimaryEmail record in ITSM Release 6.x and ITSM Release 7.x ends up with the same value in more than one record. The deduplication feature makes it easier to recover from this error.

You can either filter out the duplicate records or you can remove the unique constraint. After you select an option and click OK, the tool displays a message stating that it will run the deduplication feature. You must rerun the import.

Click the Duplicates detecting sql tab to view the duplicates so that you can fix the issue in the original ITSM database. See Figure 31.


Figure 31 -- Duplicates Detecting SQL Screen

Post-Upload Tasks

1 To check that the tool uploaded the tables and records correctly, log in to the HEAT Service Management Configuration Console and search for the tables and records one at a time. Click the tabs to view the details of the tables and records and ensure that they were created correctly.

2 The HEAT Migration Tool for Release 2014.3.1 migrates tables and records but does not migrate the grids, forms, or layouts. You must manually do this after you migrate the tables and records. See the online help in HEAT Service Management for information about creating grids, forms, and layouts.


TroubleshootingInitial Errors

Viewing Errors

Exporting Errors

Common Errors and Warnings

Logs

Initial ErrorsError Message

Connection failed. Network access for Distributed Transaction Manager (MSDTC) has been disabled. Please enable DTC for network access in the security configuration for MSDTC using the Component Services Administrative tool. The transaction manager has disabled its support for remote/network transactions.

Action

Review the information in the ITSM Installation and Deployment Guide (specifically the section called "Configuring MSDTC") for complete information about configuring and enabling MSDTC in your environment.


Viewing Errors

Figure 32 -- Viewing Errors

If there are any errors while creating tables and records, you can view them to see more details about them. From the New Business Object Wizard, you can either check Show only rows with Errors and/or Warnings at the top of the screen or you can click Show All Errors/Warnings at the bottom of the screen. See Figure 32.

The system displays a new screen with a list of the errors. See Figure 33.


Figure 33 -- Error Message

Double-click on an error message to see more details about the error. See Figure 34.

Figure 34 -- Error Details Screen

Exporting ErrorsFrom the Error Details screen in Figure 34, you can export your error messages to Microsoft Excel. This makes it easier to view and sort the error messages. To export the errors, click Export to Excel. You can also copy and paste the errors into any application, such as Notepad.

Common Errors and WarningsCannot Find a Relationship

RecID Does Not Exist

Error in New Business Object Creation

Some Records are Missing

Invalid Expression Data

Cannot Find a Relationship

The system gives you an error message if there is a relationship defined for the source table but not for the target table. See Figure 35.


Figure 35 -- Relationship Errors

The first three rows in the list (highlighted in blue) have this error. To fix this, copy the relationship over by clicking the green arrow at the end of the row. You can also map it to an existing relationship. To do this, click anywhere in a row without a relationship. The tool displays a drop-down list, that you can use to select an already-created relationship.

RecID Does Not ExistError Message

Constraint-based relationship without RecID as one of the fields in constraint is not supported.

Action

HEAT Release 2014.3.1 only supports relationships that have the record called RecID. If a relationship does not contain a RecID, the HEAT Migration Tool displays the error message above. You can still migrate the data; however, you cannot migrate that particular relationship.


Error in New Business Object CreationError Message

Unable to Save the Business Object as there are some validation errors. Please click on 'Show all Errors/Warnings' on the editor status bar to see the details.

Action

If you see the above error message when creating new tables and records, use the New Business Object Wizard to review the errors. You can selectively ignore the metadata that cannot be migrated and continue with the migration process.

Some Records are Missing

A common error is that the HEAT Migration Tool cannot save a record or table because some records are missing.

To fix this, create the missing records. The missing records are most likely from a different table that you have not migrated yet. Create the records by following the processes described in Step 3: Mapping Tables and Records.

Invalid Expression Data

This section only applies if you are migrating from ITSM Release 7.x and you used the Service Catalog predefined task.

Occasionally, the HEAT Migration Tool cannot convert some of the expressions in the tables. View the log (see Logs) for information about which expressions contain the invalid data. If you have not migrated the Profile.Employee table yet, the tool gives a warning message and does not convert the affected rules.

LogsThe HEAT Migration Tool maintains a log of all actions performed during the data import. The log file contains useful information about warnings and errors.


The log file is called log-file.txt and is located in the same folder as the HeatLoader.exe application. The HEAT Migration Tool uses the log4net framework to log the information, which is configured in the HeatLoader.exe configuration file.

The following screen is an example of the output of the log file.

Figure 36 -- Log File Screen Example


MigrationGuide forHEAT ServiceManagement

Documents

Transcript of MigrationGuide forHEAT ServiceManagement