IBM TRIRIGA Application Platform Version 3 Release 4.2. Object Migration User Guide

Transcription

1 IBM TRIRIGA Application Platform Version 3 Release 4.2 Object Migration User Guide

2 Note Before using this information and the product it supports, read the information in Notices on page 41. This edition applies to version 3, release 4, modification 2 of IBM TRIRIGA Application Platform and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2011, All rights reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents ABOUT THIS GUIDE... 1 Conventions... 1 Intended Audience... 1 Prerequisites... 1 Support OBJECT MIGRATION... 2 Overview... 2 To Access Object Migration... 2 Object Migration Page... 3 Object Types... 4 Dependents EXPORT OBJECTS... 6 Create a New Export Package... 6 Manipulate the Package Contents... 9 To Add Objects to an Export Package... 9 Use a Package to Create a File Object Migration Export Tips IMPORT OBJECTS Upload the Migration Package Background Uploads Upload Process Validate the Migration Package Validation Process Summary Comparison Validate Import the Migration Package Import Process Object Migration Import Tips... 33

4 4. MIGRATION OF DATABASE TABLE INDEXES Export the Indexes Import the Indexes CONFIGURE THE OBJECT MIGRATION LOG WORKFLOW MODELS EXPORTED AS TEXT INDEX NOTICES Privacy Policy Considerations Trademarks... 43

5 About This Guide This guide describes IBM TRIRIGA Object Migration tool, giving procedures, best practices, and tips. Conventions This document uses the following conventions to ensure that it is as easy to read and understand as possible: Note A Note provides important information that you should know in addition to the standard details. Often, notes are used to make you aware of the results of actions. Tip A Tip adds insightful information that may help you use the system better. Attention An Attention notice indicates the possibility of damage to a program, device, system, or data. Intended Audience This guide is for Application Administrators and other users responsible for maintaining the IBM TRIRIGA applications. Prerequisites This guide assumes the reader has a basic understanding of Web-based applications and has administrator access to the IBM TRIRIGA software. Support IBM Software Support provides assistance with product defects, answering FAQs, and performing rediscovery. View the IBM Software Support Site at Copyright IBM Corporation 2011,

6 1. Object Migration Overview When you have finished developing or customizing an application, you will want to migrate the objects (e.g., business objects, forms, workflows) that represent your work to other IBM TRIRIGA Application Platform environments where they will be used. IBM TRIRIGA Application Platform has an element that allows you to select objects and write them to a file that can be read by other IBM TRIRIGA Application Platform environments. There is also a corresponding element to read objects from a file into an IBM TRIRIGA Application Platform environment. Both of these elements are part of a tool in the platform named Object Migration. Attention Do not allow users to access the IBM TRIRIGA environment while you are processing Object Migration packages. User activity could result in data corruption or locked tables. To Access Object Migration The Object Migration tool can be accessed by two methods: from the Tools menu item or from the Data Modeler. To Access Object Migration Step 1 To access the Object Migration tool from the Tools menu item, navigate to Tools > Administration > Object Migration. The system opens the Object Migration page. Step 2 To access the Object Migration tool from the Data Modeler, navigate to Tools > Builder Tools > Data Modeler. Step 3 Select Object Migration from the Utilities menu. The system opens the Object Migration page. Copyright IBM Corporation 2011,

7 Object Migration Page The following steps describe the actions on the Object Migration page. Actions on Object Migration Page Export Packages and Import Packages on the Object Migration page are separate sections. Step 1 To see the specifications for an Object Migration package, click the hyperlinked name. Step 2 To delete an Object Migration package, select the check box to the left of the package Name and click Delete. Step 3 If you want to create a new package for Export containing the same items as one of the packages listed, click the copy package icon next to the package s name. Only existing objects are put into the new package. Tip Use the copy package feature to re-export a set of objects that you previously imported. For example, use the copy package feature if you import a package into an environment, make some changes to those objects, and then migrate them somewhere else. The system opens the Create Package page. Change the Name as appropriate and enter a Description. Note The Name cannot contain special characters. Step 4 Create Mode is preset to From Package. Step 5 When you click Create Package, the system opens the Object Migration page. See the description of this page below. The Object Migration page deals with imports and exports. An export specifies a set of objects to be written out to a file so it can be read by other IBM TRIRIGA Application Platform environments. An import contains objects from a file to be migrated into this platform environment. Exports are discussed in Export Objects. Imports are discussed in Import Objects. The Object Migration page shows the status of each Object Migration package (e.g., New, Validated, Export Pending, Exported, Imported, Validation Pending, Validation Failed), the user who created the package, and the package s description. Packages in either the Export Packages section or the Import Packages section are listed in alphabetical order by package name. Copyright IBM Corporation 2011,

8 Object Types The following object types are supported by Object Migration. See the Application Building for the IBM TRIRIGA Application Platform 3 collection of user guides for more information about an object type. Alternate Form List Associations Budget Token Business Object Calendar Set Document Form Group Hierarchy Structure List Module Navigation Collection Navigation Item Portal (post 3.0) Portal Section Query Record Data Scorecard (post 3.0) Styles Workflow Note Use the Record Data object type only for moving setup data, templates, and other items imported once and used as a template after that. The following Object Types not are supported by Object Migration: Action item Manager Portal (pre-3.0) Scorecard (pre-3.0) Query list Query portal section Quick add list Shortcut list Site Style Copyright IBM Corporation 2011,

9 State Family Note Images that are stored in Record Data are not moved from the source to the target via the Object Migration export/import process. During Export, Object Migration includes a simple path to the image file (located in the source system s userfiles folder) in the Record Data XML. During Import, this path is saved in the target system s record but the image is not visible to the user. For images to be available in the target environment after import, copy the image files from the source userfiles folder into the target userfiles folder. Dependents The concept of dependents is key to Object Migration. Object Migration copies objects from an environment or updates an environment with objects from a different environment. Any object can have one or more objects dependent on it. For example, a business object could have several forms; in order for the forms to properly migrate, the business object must already exist in the target environment or be contained in the same package. This means that the form is a dependent of the business object. In other words, the form cannot be imported without the business object. Note Unless otherwise stated, selecting an object to include in the export does not automatically include any of the object s dependents. Copyright IBM Corporation 2011,

10 2. Export Objects Exporting is the process of taking objects you want to migrate to other IBM TRIRIGA Application Platform environments and writing them to a file. There are three basic steps in exporting objects: To Export Objects Step 1 Create an export package. Step 2 Specify what objects should be included in the export package. This step is the most complicated part of the process. It involves including just the right objects in the package. It also may involve excluding objects from the package. Step 3 Use the export package to write the specified objects to a file. Tip If you want to migrate newer versions of the same objects that you previously migrated, you can reuse the package you previously created and repeat this step. Create a New Export Package Follow the steps below to create an export package: To Create a New Export Package Step 1 From the Object Migration page, click New Export Package. The system opens the Create Package form. This gives the user a chance to create a package containing pre-loaded objects. Step 2 Enter a Name and Description for the new export package. Step 3 Select a value from the Create Mode drop-down box. If you select Empty, the package will not contain any pre-loaded objects. Copyright IBM Corporation 2011,

11 To Create a New Export Package If you select Full Package, the package will contain ALL objects from the entire system, except for Record Data. However, Record Data that is a dependent of something else in the package is included. The system uses a recursive find to make sure the Full Package is complete and includes all levels of dependents. Expect this Create Mode to take a long time to complete. If you select By Date, the package will contain objects from the entire system published on or after a date you specify in the Modified After (Date) field. Record Data is included only if it is a dependent of something else in the package. The system uses a recursive find to capture a SINGLE level of dependents. Note The modified date value for a Scorecard is established when Apply or Ok is clicked from within the application builder. Step 4 Click the Calendar icon to select a date for the Modified After (Date). Step 5 Click Create Package. The package created is the same other than pre-loaded content. The pre-loaded content is determined by the value selected for Create Mode. Step 6 Review the Object Migration page. As you add objects to an export package, the Navigation panel shows what objects are included in the export package. The Objects panel presents what is included in the selected item in the Navigation panel and displays objects. Use the Object Finder panel to look for an object. Note the extensive search capabilities. The Search Parameters section is described elsewhere. The Property panel contains the definition of the export package. The Messages panel displays what the system is doing with the export package. Clicking Clear removes all messages. At this point the export package has been created. If you selected either Full Package or By Date as the value for Create Mode, the package contains the pre-loaded objects described earlier; the next step is to add/delete objects. If you selected the Empty Create Mode, the package does not contain any objects; the next step is to specify which objects it will include. Copyright IBM Corporation 2011,

12 The actions on the top of the Object Migration page are as follows: Action Reset View Object Finder Export Description Resets the panels. Use to restore one of the panels. Clears the information in the Object Finder panel. The system builds the export package. Select how you want the system to build the package from the choices in the Objects panel. Save Cancel Saves the objects added to the Object Migration package so you can reopen to continue working on it at another time. Closes the Object Migration window. Unsaved changes are lost. Saves the layout of the panels (size, shape, placement). At times some of the actions disappear from the top of the Object Migration page. This indicates the Object Migration Agent is working on a background task, such as an Export. While the Object Migration panel is in this read-only mode, you can perform the other activities in the page, such as reviewing the items in the Navigation panel, but you cannot do any activities that change the package, such as a Delete or Adding an object. Copyright IBM Corporation 2011,

13 Manipulate the Package Contents Depending on the Create Mode you selected when creating the export package, a new export package may or may not include any objects. To Add Objects to an Export Package Follow the steps below to add objects to an export package: To Add Objects to an Export Package Step 1 Begin by using the Search Parameters section of the Object Finder panel to search for objects. For Object Type, select from the items in the drop-down list. Step 2 For Module, select from the items in the drop-down list. What you see depends on the selection you made for Object Type. Note You will not see the Module field for object types that are not dependent on modules. Those object types are: Budget Token, Document, Form Style, Group, Module, Navigation Collection, Navigation Item, Portal, and Portal Section. Step 3 If you select a module that has business objects, the system displays a Business Object parameter and drop-down list containing the business objects for the selected module. Step 4 If you want to restrict the search to objects modified on a date or later, click the Calendar icon next to Modified After (Date) to select a date. If you leave Modified After (Date) blank, the system returns objects regardless of when they were last modified. Note Beginning with IBM TRIRIGA Application Platform Version 3.4, all object types support Modified After (Date) queries. After you install or upgrade to IBM TRIRIGA Application Platform Version 3.4, changes made to the List, Styles, and Hierarchy Structure object types can be queried using Modified After (Date) information. In addition, if you use the Report Builder to create or modify queries, you must commit the changes by selecting Save or Save and Close. In previous releases, selecting a tab within the Report Builder dynamically saved changes made to a query. Copyright IBM Corporation 2011,

14 To Add Objects to an Export Package Step 5 If you want to restrict the search to objects modified by a specific user, click the People icon next to Modified By (User) field and select from the choices. If you leave Modified By (User) blank, the system returns objects regardless of which user last modified them. Note Some object types do not support a modified by in their record layout. For those object types, the system does not return any objects if you identify a user in the Modified By (User) field. The supported object types for the Modified By (User) field are: Query, Workflow, Document, Group, Navigation Collection, Navigation Item, and Record Data. Step 6 To further refine the search, enter some or all of the desired Object Name and select the filter (Equals, Not Equals, or Contains). For example, Contains Building finds objects containing the word Building. If you leave Object Name blank, the system does not filter the search results by Object Name. Tip There is a trick that may speed up your use of the Search Parameters section of the Objects panel. Depending on the parameter you pick, the system updates the drop-down boxes for the other unselected parameters accordingly. Instead of choosing an object type first, choose one of the other parameters first. For example, if you select a module first, the object type choices are restricted to those that contain that module. If you select Location for Module, the Object Type choices become Business Object, Form, Hierarchy Structure, List, Query, Record Data, and Workflow. The Business Object parameter appeared when you selected Location for Module. If you then select tribuilding for Business Object, the Object Type choices become Form, Query, Record Data, and Workflow. If you know a bit about the objects you are looking for, use this method to find them faster in the Search Parameters section. Step 7 Click Search. Step 8 Review the search results. The Search Results section of the Object Finder shows the objects that match the values in the Search Parameters section. Step 9 To add objects listed in the Search Results section to the export package, select the check boxes of the items and click Add Selected Objects. The Messages panel shows you what is happening. When the system finishes adding objects, the objects show in the Navigation panel. Copyright IBM Corporation 2011,

15 To Add Objects to an Export Package The system displays any dependent objects in the Object Finder panel. The Find Dependents section shows the objects for which dependents were found. The items listed in the Object Name column are hyperlinked to the object s definition in the system. What you see depends on the object s object type. The Search Results section shows specifics about the object and a description of each dependent found. The hyperlinked Business Object name shows the definition of the object in the system. The Description shows how the dependent was found. If the Description is blank, the object is not added as a dependent of another object. Step 10 To add objects listed in the Search Results section to the export package, select the check boxes of the items and click Add Selected Objects. Clicking Reset Search clears the Object Finder. The Navigation panel reflects the objects that have been added to the package. Step 11 Clicking one of the objects in the Navigation panel displays that object s details in the Objects panel. The Name field is a hyperlink to the object s definition in the system. What you see depends on the object s object type. The Description shows any dependency details. If the Description is blank, the object is not added as a dependent of another object. Find Dependents works the same as it does elsewhere in Object Migration. To delete an object, select the check box and click Delete. Step 12 Click Reset Search in the Object Finder to clear the current search data and return to select new search parameters. Step 13 Select the check box of an object and click Find Dependents. Copyright IBM Corporation 2011,

16 To Add Objects to an Export Package The system displays the object in the Find Dependents section. The Object Name is a hyperlink to the object s definition in the system. Note When you select Find Dependents for Record Data, all Associated Record Data is retrieved in the dependency results for the Record Data you selected. To add one or more of the items in the Search Results section to the objects list in the Navigation panel, select the check box of the item and click Add Selected Objects. To further drill into one of the dependents, select the check box of the item and click Find Dependents. To return the Object Finder to its state prior to the current search for dependents, click Reset Search. Tip As you find and select a dependent, you can find its dependents, select one and find its dependents, and so on, walking down through the layers of dependents until you find what you want (and ignore the rest). You can add dependents from two different perspectives: Method Add all the objects first, then find dependents. Add an object, then find its dependents; add another object and find its dependents; and so on. Description With this method, use the Object Finder to locate and add the objects. Once the objects are in the Navigation panel, note they are also in the Find Dependents section of the Object Finder and the dependents are in the Search Results section of the Object Finder. Select the check boxes for any dependents you wish to add to the object list in the Navigation panel and click Add Selected Objects. Select the check boxes for any dependents you wish to drill into the next level and click Find Dependents. Continue to add and find dependents until you have the dependents you want in the Navigation panel. With this method, use the Object Finder to locate and add the first object. Once the object shows in the Navigation panel, note it is also in the Find Dependents section of the Object Finder and the dependents are in the Search Results section of the Object Finder. Select the check boxes for any dependents you want to add to the object list in the Navigation panel and click Add Selected Objects. Select the check boxes for any dependents you want to drill into the next level and click Find Dependents. Continue to find and add dependents until you have the object and its dependents in the Navigation panel. Click Reset Search in the Object Finder and repeat the same process with the next object. Copyright IBM Corporation 2011,

17 Use the method that best matches your objectives and your familiarity with your IBM TRIRIGA implementation. Note If you attempt to add the same object to the Navigation panel more than once, the system ignores the subsequent attempts. The object is added only once. Tip You can use the Object Finder to search for dependents. You do not have to add anything to the Object Migration package to use the Object Finder. Set the initial Search Parameters and click Search. Click Find Dependents. In the dependents listed, find and select the one of interest. Click Find Dependents. At any time you can click the hyperlinked name to see the object s definition in the system. Continue to iterate through each layer of dependents until you find exactly what you want. Use a Package to Create a File When an export package contains the objects you want, you are ready to use the export package to create a file that contains the objects specified in the package. To Use a Package to Create a File Step 1 Locate the export package that contains the objects to be exported. Click Export. Step 2 In the Objects panel, the system asks if you would like to process the export synchronously (Wait) or asynchronously (Background). Select Wait or Background. IBM TRIRIGA Application Platform generates a.zip file containing an.xml file for each of the package s objects. This.zip file is used to transport your changes from one environment to another. Step 3 If you select Wait, the system generates the file and prompts you to download. Click Save. Step 4 Select the location and click Save. Step 5 If you select Background, the file is saved in the userfiles\objectmigration directory of the IBM TRIRIGA installation. For example, C:\Tririga\userfiles\ ObjectMigration\Building BO.zip Note While the Object Migration Agent is working on the Export package, you will not be able to change the definition of the package shown in the Object Migration screen. The actions available in the Object Migration screen change because it is now read-only. You can look at what is in the package, but you cannot search or add/delete objects. Copyright IBM Corporation 2011,

18 To Use a Package to Create a File The system sends a notification that the Export is complete. Note During the export process, IBM TRIRIGA Application Platform may log error and warning messages into the Object Migration log file. The Object Migration log file is in the log directory of the IBM TRIRIGA installation. For example, C:\Tririga\log\ObjectMigration.log. Once the.zip file is downloaded, the status of the Object Migration package changes to Exported. You are ready to migrate these objects into other IBM TRIRIGA Application Platform environments. Object Migration Export Tips Tip Messages Panel Navigation Panel Description Keep an eye on the Messages panel. It shows useful feedback as the Object Migration user interface is working. When you click Objects in the Navigation panel, the system fills the Objects panel with everything in the package (for example, Business Objects, Forms, Lists, and Queries). When you click one of the Object Types, the system fills the Objects panel with everything in the package about that Object Type (for example, business objects could display tribuilding, triproperty, or triproposedsite). Navigation Panel Hierarchy Object Migration Page To help the existing hierarchy load faster, when you reopen an existing Object Migration package, the system lazy loads the hierarchy in the Navigation panel. All folders in the Navigation panel are initially closed. You do not need to expand the nodes to see the objects. Instead, once the hierarchy is loaded, click any folder name and view its objects in the Objects panel. The layout properties for the Object Migration panels are saved as cookies in your browser. If you sign on to another computer, you inherit the properties set up by the user of that computer. One way to reset the layout to the as-delivered default is to click the Reset action. Copyright IBM Corporation 2011,

19 Tip Record Data Description If you are searching for Record Data, you must select a module. If you see a nothing found message you probably forgot to select a module. The Record Data display shows to which business object the Record Data belongs. User Activity Workflows Do not allow users to access the IBM TRIRIGA environment while you are processing Object Migration packages. User activity could result in data corruption or locked tables. When you search for workflows, the results include all workflows regardless of their status. If a workflow is under revision, the system exports the last published or retired version. When you add retired workflows to the Object Migration package and import them to another environment, the system automatically retires them in the target system. Copyright IBM Corporation 2011,

20 3. Import Objects After objects have been exported to a.zip file, you can import the contents of the.zip file into other IBM TRIRIGA Application Platform environments. There are three basic steps to importing the contents of the.zip file: To Import Objects Step 1 Upload the Object Migration package into IBM TRIRIGA Application Platform environment. The system performs a preliminary validation as it converts the contents to a form with which the platform can more directly work. During this validation, if an object s module or business object does not exist in the package or the system, the object is immediately marked as Invalid. Step 2 Validate the objects being migrated. The purpose of this step is to detect problems with the uploaded objects before actually importing them into the environment. For example, an upload package may contain a form that has a dependency on a workflow and/or a query. If the workflow or query does not exist in the package or the target environment, the import process cannot properly recreate that form definition - that is a problem. Step 3 Import the migrated objects into the target environment. This step performs the task of adding to and/or updating the target environment with the uploaded objects/data. Tip Import an Object Migration package when the environment has minimal system activity. Attention Do not perform normal production activities in a platform environment while importing an Object Migration package into that environment. Before starting the import steps, ensure that the Cleanup Agent is not running. If production mode is on, turn it off. When you have finished the import steps, allow the Cleanup Agent to run as it was running previously. Make sure production mode has the proper value. Restart the server. If you have questions about these concepts or procedures, refer to the IBM TRIRIGA Application Platform 3 Installation and Implementation Guide and the IBM TRIRIGA Application Platform 3 Administrator Console User Guide. Copyright IBM Corporation 2011,

21 Upload the Migration Package The purpose of this step is to upload the contents of a migration package.zip file to the IBM TRIRIGA Application Platform environment. During this step the system uploads the.zip file, extracts all objects from the.zip file, performs a preliminary validation on the objects, and shows the resulting objects and validation information in the Object Migration screen. Note Any temporary files created during the package upload process are deleted automatically. To Upload the Migration Package Step 1 From the Object Migration page, click New Import Package. Step 2 Click Browse to find the file. Click Ok to start the upload. The system extracts the objects from the.zip file, creates the objects in the Navigation panel of the Object Migration page, and performs a preliminary validation on the objects. On the Object Migration page, The Navigation panel shows what objects are included in the package being imported. The Objects panel presents what is included in the selected item in the Navigation panel. The Property panel contains the definition of the package being imported. The Messages panel displays what the system is doing with the package. Click Clear to remove all messages. Copyright IBM Corporation 2011,

22 To Upload the Migration Package The first preliminary validation done during the upload process checks: If a module is specified in an uploaded object, whether that module exists in the package or in the system. If a business object is specified in an uploaded object, whether that business object exists in the package or in the system. If a dependent item specified in an uploaded object is in neither the package nor the system, the object is tagged as Invalid and the object name is red. The second preliminary validation done during the upload process checks if the object name (including the module and business object if appropriate for that object type) is in the target system. If the object name is in the target system, the object name is blue. If the object name is not in the target system, the object name is green. Tip If an object name is green and you think it exists in the target system (it should be blue), or if an object name is blue and you think it does not exist (it should be green), carefully check the exact spelling of the object name + module name + business object name (if the object type has module and business object). There could be an extra space or a difference in capitalization. Note A Content object s name is always green (indicating new) in the Object Migration screen. Note If the target system contains more than one object with the same name (for example, a query at the module level and a query in one of the module s business objects), a warning is written to the Object Migration log. The import process updates the object in the target system that has the lowest Id with the object from the import package. The actions on the top of the Object Migration page are as follows: Action Reset View Summary Description Returns the Object Migration page to the state it was in when last saved. Use to restore one of the panels in the Object Migration screen. Details the warnings and errors found during validation. Copyright IBM Corporation 2011,

23 Action Comparison Report Validate Import Save Cancel Description Shows a detailed view of differences between the uploaded items and the existing items in the platform. Performs the validation process described in Validate the Migration. Imports the objects from the package to the target environment. Saves the information in the Object Migration window. Closes the Object Migration window. Unsaved changes are lost. At times some of the actions disappear from the top of the Object Migration page. This indicates the Object Migration Agent is working on a background task, such as a Comparison Report or an Import. While the Object Migration panel is in this read-only mode, you can do the other activities in the page, such as reviewing the items in the Navigation panel. Background Uploads You can use the system to facilitate background Uploads of Object Migration packages. Copy the file to be uploaded into the userfiles\objectmigration\uploads folder of the IBM TRIRIGA installation folder. An example of this location in Windows is C:\Tririga\userfiles\ ObjectMigration\Uploads. When a file is placed in this folder, the Object Migration Agent detects the file and automatically creates a Package for the file. Note Once the Object Migration package has been created, the system automatically deletes the file. Upload Process The following paragraphs describe how to handle a type of problem that may become apparent after you validate the migration objects. If you do not understand the problem this addresses, then continue reading the following part of this chapter that describes how to validate the migration. Then come back and read the following paragraphs again. While the platform is converting the contents of the.zip file, it uses the names of objects to match objects in the.zip file with objects that already exist in the target platform environment. For example, if the file contains a business object named tripeople and the target platform environment also contains a business object named tripeople, the platform decides that both business objects are really the same business object. When you validate the migration objects, you may discover that there are differences between the version of a query in the platform and the version of the query in the package. If you simply proceed to Copyright IBM Corporation 2011,

24 import the migration, the object for the query in the package replaces the object for the query in the platform. You lose the version of the query that was in the platform. If replacing the version of the query in the platform with the version of the query from the migration object is what you want to happen, there is no problem. However, you might decide that you want to keep both versions of the query and reconcile their differences after you are finished with importing the migration objects. One way to keep the version of the query that exists in the target environment is to change its name before you import the migration. Each Import revalidates the objects, so after renaming the object in the target environment, the names will no longer match, thus forcing the system to treat the object as New. After the Import, you will have both the original renamed query and the query from the package. To delete an uploaded object, click its name in the Navigation panel, which displays the object in the Objects panel. Select its check box in the Objects panel and click Delete. Validate the Migration Package The purpose of the validation step is to detect problems caused by differences between the migration objects and objects already in the target platform environment. To Validate the Migration Package Step 1 The objects uploaded from the.zip file are listed In the Navigation panel. Click the closed folder icon to show the details of the uploaded package. The names of the objects are in blue, green, or red. Blue means there is an object with the same object name and module and business object names (if appropriate for the object type) in the target platform environment. Note the icon. Green means that the object is in the migration package but there is no object with the same object name and module and business object names (if appropriate for the object type) in the target platform environment. Note the icon. Red means dependent items are in neither the package nor the target environment. Note the icon. Note A Content object s name is always green (indicating new) in the Object Migration screen. Note If the target system contains more than one object with the same name (for example, a query at the module level and a query in one of the module s business objects), a warning is written to the Object Migration log. The import process updates the object in the target system that has the lowest Id with the object from the import package. Copyright IBM Corporation 2011,

25 To Validate the Migration Package Step 2 To see an explanation for an object, click the hyperlinked name of the object in the Navigation panel. The Objects panel shows a brief Description. Note If you have red objects, you will not be able to import the migration. You must resolve each red problem before you can import the object into the target platform environment. Validation Process During the validation process, the system analyzes the uploaded XML (from the.zip), checking for invalid or missing references to other objects. For example, if a business object has a pre-create workflow, the validation process checks to make sure that workflow is in the package or the system. If not, the system logs a warning against that business object. Sometimes this analysis discovers more serious situations, causing the system to log an error against the object and rendering it Invalid (shown as red to the user). One example of this is attempting to change the business object type from standalone to embedded. IBM TRIRIGA Application Platform system does not allow this, and therefore Object Migration considers it an error. You must resolve all Invalid objects before you will be able to Import the package. Note The system always validates all objects before reporting a successful or failed validation. This allows the person responsible for importing the package to see all of the issues (warnings and errors) at hand. Summary To see all warnings and errors found during validation, click the Summary action on the top of the Object Migration screen. The Package Summary report appears. The Object Summary at the top of the Package Summary report lists statistics for each object type, with the Warnings and Errors hyperlinked to the corresponding summary section further down in the report. The body of the Package Summary report contains a separate section for each object type with warnings and/or errors. Within these sections, you will see the object name, module and business object if appropriate for the object type, and the corresponding warning or error message(s). Copyright IBM Corporation 2011,

26 A Package Summary example follows below: Name: Description: Status: TRIRIGA_10_ _After_0323 TRIRIGA_10_ _After_0323 Imported Package Summary Object Summary Type # of Objects New Existing Valid Invalid Warnings Errors 1 Budget Token Business Object Content Document Form Group Hierarchy Structure List Module Navigation Collection Navigation Item Portal Portal Section Query Record Data Scorecard Styles Workflow Object \ROOT\TRIRIGA\Item\Critical To Quality (CTQ) Item Response Record \ROOT\TRIRIGA\Location\Floor_Space_ Rollup Object Module Document Warnings Document Document Module Business Object Document Document Group Warnings Business Object Message 1) Error updating Existing Document [\ROOT\TRIRIGA\Item\Critical To Quality (CTQ) Item Response Record]. 1) Error updating Existing Document [\ROOT\TRIRIGA\Location\Floor_Space_Rollup]. Message 1 \Admin Group Group Group 1) Admin Group will not be imported. Object Module Query Errors Business Object 1 tritaskholdlog Display - tritask trilogging trilogging Message 1) Could not find Module [trilogging] in System or Package. Copyright IBM Corporation 2011,

27 Comparison Object Migration offers two comparison methods to find out more information about the differences between uploaded items and existing items in the system. You can compare the entire upload with the Comparison Report action or compare individual items with one of the Compare actions in the Objects panel. The comparison logic is the same for the Comparison Report and an individual Compare, with the main difference being that one compiles the result into a file and the other displays the result in the user interface. The following object types are compared: Alternate Form List Budget Token Business Object Calendar Set Form Form Style Hierarchy Structure List Module Navigation Collection Navigation Item Portal Portal Section Query The following object types are not compared: Content (because the information is binary) Document (because the information is binary) Group (because some groups are extremely large and a comparison could take several hours to run) Record Data (because the definition is a dynamically-structured XML based on sections, fields, and the like) Attention When one of these four object types is compared, the result is always No Differences. Do not be falsely assured by a No Differences comparison result for existing Content, Document, Group, and Record Data object types. Object Migration only performs a partial comparison for workflows. Object Migration compares just the header information of workflows, not the details (tasks). For a more detailed examination of workflows, use the Text Export Selected action. Copyright IBM Corporation 2011,

28 Attention Do not be falsely assured by a No Differences comparison result. Comparison Report A Comparison Report compares every object in the uploaded package with objects in the target system. The result is a tab-delimited.txt file. Each row in the Comparison Report represents one difference or conflict between the uploaded package and the target system. For example, if a business object has 10 differences, there will be 10 lines in the Comparison Report, one for each. Follow the steps below to create a Comparison Report: To Create a Comparison Report Step 1 Click Comparison Report at the top of the Object Migration page. Step 2 In the Objects panel, the system asks if you would like to process the Comparison synchronously [Wait] or asynchronously [Background]. Click Wait or Background. Step 3 If you select Wait the system generates the file and prompts you to download. Click Save. Step 4 Select the location and click Save. Step 5 If you select Background, the file is saved in the userfiles\objectmigration directory of the IBM TRIRIGA installation. For example, C:\Tririga\userfiles\ ObjectMigration\triLog Query Import.txt Step 6 Review the Comparison Report. Tip You may need assistance from your IT department to gain access to the file since this file is located on the server. Here is an example (trilog_query_import.txt) of the Comparison Report in tabdelimited.txt format. OBJECTID OBJECTNAME OBJECTTYPE PATH CATEGORY ELEMENT SOURCE TARGET triresponselog Find Query New Query New Object triresponselog Find Query Query No Differences tritaskholdlog Display - tritask Query New Object Copyright IBM Corporation 2011,

29 To Create a Comparison Report As the Comparison Report is a tab-delimited.txt file, it is ideal for import into Excel. Once in Excel, you can use the full capabilities of Excel to help analyze the information, for example, converting the header row into filters and filtering for your areas of interest. Tip Save Comparison Reports for future analysis and comparison. Compare The Compare action looks at just one object and compares what is in the uploaded package to what is in the target system. To use the Compare action: To Use Compare Step 1 To compare one of the objects in the upload with its counterpart in the system, select the object in the Navigation panel. The object displays in the Objects panel. Step 2 Select an item in the Objects panel and click Compare. Step 3 The system displays the result in the Objects panel Description column. The icon refers to objects in the migration package where there is no object with the same object name and module and business object names (if appropriate for the object type) in the target platform environment. The icon refers to objects with the same object name and module and business object names (if appropriate for the object type) in the migration package and the target platform environment. The icon means the object name and module and/or the business object in the migration object s name is present in both systems but different. Click the down arrow icon to expand the information. Click the right arrow icon to close that level. Copyright IBM Corporation 2011,

30 To Use Compare Step 4 To accurately decipher the information presented you must have knowledge of both the source and the target systems. The information presented is based on a comparison of the XML in the package with the target system. Red indicates that the element exists in the target but not the package. Green indicates that the element exists in the package but not the target. In the following example, the uploaded package has three new fields in the General section. If the item in the Description column displays two values in brackets, for example [false][true], the first/left value is the value in the package (source) and the second/right value is the one in the system (target). The values from the package (source) show as green and the values in the system (target) that will be overwritten show as red. After the Import is finished, the value in the target is the first value. Compare & Select Matching Objects The Compare & Select Matching Objects action identifies objects that the Object Migration comparison method considers identical between the source Object Migration package and the target environment. This provides a quick way to remove these objects, leaving only those objects that have undergone some kind of change. To use the Compare & Select Matching Objects action: To Use Compare & Select Matching Objects Step 1 To compare one of the objects in the upload with its counterpart in the system to identify matching objects, select the object in the Navigation panel. The object displays in the Objects panel. Step 2 Select one or more item(s) in the Objects panel and click Compare & Select Matching Objects. Step 3 The system displays the result in Description column of the Objects panel. Select New Objects The Select New Objects action identifies objects that the Object Migration comparison method finds in the source Object Migration package that are not in the target environment. To use the Select New Objects action: Copyright IBM Corporation 2011,

31 To Use Select New Objects Step 1 To see if one of the objects in the upload does not already exist in the system, select the object in the Navigation panel. The object displays in the Objects panel. Step 2 Select one or more item(s) in the Objects panel and click Select New Objects. Step 3 The system displays the result in Description column of the Objects panel. Select Existing Objects The Select Existing Objects action identifies objects that the Object Migration comparison method finds in the source Object Migration package that also in the target environment. To use the Select Existing Objects action: To Use Select Existing Objects Step 1 To see if one of the objects in the upload already exists in the system, select the object in the Navigation panel. The object displays in the Objects panel. Step 2 Select one or more item(s) in the Objects panel and click Select Existing Objects. Step 3 The system displays the result in Description column of the Objects panel. Text Export Selected The Text Export Selected action exports one or more workflows as text. You can export two versions of the same workflow as text and compare them to decide if you want to import a workflow from a migration package. To use the Text Export Selected action: To Use Text Export Selected Step 1 Select Workflow in the Navigation panel. Step 2 Select one or more workflows in the Workflow panel and click Text Export Selected. Step 3 Save the file to the system. Copyright IBM Corporation 2011,

32 Validate Once the import package contains only the objects you want to add to the system, it is time to validate the package. To Validate the Migration Package Step 1 Click Validate. Step 2 In the Objects panel, the system asks if you would like to process the validation synchronously (Wait) or asynchronously (Background). Select Wait or Background. Step 3 If you select Wait, the status in the Property panel changes when the validation completes. Step 4 If you select Background, the system reminds you that a Notification will be sent when the validation process is complete. The Background notification shows in the Notification section on your Home Portal. When the validation is finished, some of the objects in the Navigation panel may be shown in red. Note the icon. This means there is a problem with the object. To see an explanation of the problem, click the name of the object. A brief description of the problem shows in the Objects panel. If you have a red object after a validation, this indicates an Invalid object and you will not be able to import the migration. Each red problem must be resolved before you can import the objects into the target platform environment. There are two different approaches you can take to resolving Invalid objects. Method You can just delete the problem object Description You can delete an object when it is displayed in the Objects panel by checking its check box and clicking the Delete action in the Objects panel. Be aware that blindly removing objects from the Package can cause further problems during Validation and Import. For example, if you remove a new business object or module from the package and there are other objects in the package that reference this business object, the next time you validate, these other objects will become Invalid. You can fix the underlying problem and then validate the objects again For example, if the problem is a missing business object, you should re-export the package containing the missing business object, or you could manually create the required business object in the target platform environment and run the validation again. Copyright IBM Corporation 2011,