Chapter 3   Using the Upgrade Utility
to Automate Data Migration



This chapter describes how to automate the migration of data modules from BuyerXpert 3.x to 4.x using the Upgrade utility. It contains the following sections:

• Pre-Upgrade Tasks

• How to Use the Upgrade Utility

• Using the Upgrade Utility User Interface

• Migrating Multi-Organizational Data

Pre-Upgrade Tasks

---

You should complete the following tasks before using the Upgrade utility.

Backup BuyerXpert Data

You need to coordinate the backup of LDAP directory data, import files, customization files, and staging files before you begin installing BuyerXpert 4.x.

• LDAP directory data

• Import files

• Staged update files

• Customization files

• Oracle database

Set Up UNIX Access Permissions

The following UNIX permissions are required:

• Write access to the /tmp directory

• Execution access to the /bin directory

The Oracle users for both the default and staging data sources must have DBA privileges in order to run the Approval Log component.

Determine Data Import File Location Defaults

The data import files created by the Upgrade utility are stored in the /tmp directory. You may want to change this default because he /tmp directory is emptied each time you reboot a UNIX. To do so, change the default location in the upgradeinfo.ntv file.

Set Up a Staging Environment

It is useful to set up a staging environment on a different UNIX system before installing the Upgrade utility and migrating your data. Later, you can use your staging environment as a production environment.

The staging environment should meet the following requirements:

• The machine meets all the minimum hardware and software requirements for BuyerXpert 4.x. See the BuyerXpert Installation Guide for specific hardware and software requirements.

• BuyerXpert 4.x is installed and configured, along with all dependent and certified BuyerXpert software.

• Instances of BuyerXpert required applications should not be used by any other application. This includes Oracle, the iPlanet Application Server, and the iPlanet Directory Server.

Installing BuyerXpert 4.x

To access the Upgrade utility, you must install a dedicated installation of BuyerXpert 4.x and its components. To install BuyerXpert 4.x, follow the instructions in the BuyerXpert 4.x Installation Guide, chapter 4, "Installing BuyerXpert".

At the end of the installation, you will be asked if you want to install the Upgrade utility. Answer yes and BuyerXpert will install the Upgrade utility.

How to Use the Upgrade Utility

---

The Upgrade utility provides a graphical interface that allows you to initiate, manage, and monitor upgrade sessions. At any point you can stop the Upgrade utility and restart it at a later time.

The Upgrade utility allows you to migrate the following BuyerXpert data modules:

• Membership

• Catalogs

• Order Management System (OMS)

• Commodity Codes

• Accounting Codes

• Business Rules

• Permission

• Approval Process

Data Migration Tasks

You can automate the data migration from a BuyerXpert 3.x instance to a BuyerXpert 4.x instance using the Upgrade utility by completing the following tasks:

1. Create or define a profile on the Select Profile screen.

2. Select the components to upgrade on the Select Components to Upgrade screen.

3. Configure the site parameters by specifying the source parameters you are upgrading from and the destination parameters you are upgrading to on the Specify Site Parameters screen.

4. Select the modules to upgrade and run the profile for each from the Run Selected Modules screen.

Importing Large Amounts of Data

If you are importing large amounts of data from BuyerXpert 3.x to BuyerXpert 4.x to the Import utility, you can increase performance by selecting smaller increments of information to import at one time. For example, instead of importing all user groups for the membership component, you can select two or three user groups at a time.

Upgrading Membership

Upgrading the BuyerXpert membership component consists of migrating all user, organization, organizational unit, user group, and location. The membership module contains the following components:

• Organizations

• Organizational Units

• User Groups

• Users

• Location

• Default Location Rules

The Upgrade utility migrates the relationship between different membership components. The organizational hierarchy is represented through the organizational units and locations are migrated as part of the organization upgrade. Users are migrated as part of the organization upgrade.

---

Note	All migrated users are give the password "iplanet" and have selfadmin privileges.

---

You must migrate an organization and all of its users before you can migrate the user groups.

Access Control

Migrating membership access control data is conservative. If a migrated user does not have equivalent privileges in BuyerXpert 4.x, the user is given lower access privileges.

---

Note	All migrated users are give the password "iplanet" and have selfadmin privileges. You should set up a dummy upgrade user with superadmin privileges in your BuyerXpert 4.x system.

---

Upgrading Catalogs

You can migrate all catalogs or selected catalogs from BuyerXpert 3.x (CADIS) to BuyerXpert 4.x.

Each catalog is exported to an XML file that contains the extracted catalog data. BuyerXpert passes the XML file to the Catalog Loader, which imports the catalogs for use in BuyerXpert 4.x. The top level category in each XML file is the name of the individual catalogs.

Upgrading Order Management System (OMS)

The Order Management System (OMS) module contains the following components:

• Price Lists—Price Column, Price Item, Price List Information

• Adjustments

• Payment Terms

• Payment Instruments—Payment Type, Payment Subtype, Instrument, Credit Card Instrument

• Shipping Method

• Freight Terms

• Units—Unit Class, Unit Conversion Table, Unit Conversion Table Entry

The data migration process uses the following mapping between Adjustment name in BuyerXpert 3.x and BuyerXpert 4.x:

Table 3-1    Adjustment Component Mappings

BuyerXpert 3.x Template Name	BuyerXpert 4.x Template Name
ALLOWANCE	LINE_ADJUSTMENT
CHARGE	LINE_ADJUSTMENT
COLUMN_LOOKUP	PRICELIST_COLUMN_ADJUSTMENT
DISCOUNT	LINE_ADJUSTMENT
DISCOUNTMARKUP	PRICELIST_DISCOUNT_LOOKUP
FREIGHTBYSHIPMENTMETHOD	LINE_LEVEL_SHIPPING_CHARGE
FREIGHTBYSTATE	LINE_LEVEL_SHIPPING_CHARGE
FREIGHTBYCHARGE	LINE_LEVEL_SHIPPING_CHARGE
PROMOTION	LINE_ADJUSTMENT
TAXBYCOUNTRY	TAX_ADJUSTMENT
TAXBYSTATE	TAX_ADJUSTMENT
TAXBYTAXCODE	TAX_ADJUSTMENT

---

Note	You will need to rename any BuyerXpert 3.x adjustments that are not listed above before you can migrate them.

---

To migrate the membership module, select the components you wish to migrate from the Select Components to Upgrade screen to add them to your current profile.

Upgrading Commodity Codes

The commodity codes module does not contain any subcomponents. To migrate the commodity codes from BuyerXpert 3.x to BuyerXpert 4.x, select Commodity Codes in the Select Components to Migrate screen to add the components to your current profile.

Upgrading Accounting Codes

The accounting codes module does not contain any subcomponents. To migrate the accounting codes from BuyerXpert 3.x to BuyerXpert 4.x, select Accounting Codes in the Select Components to Migrate screen to add the components to your current profile.

Upgrading Business Rules

The Select Rule Modules to Upgrade screen allows you to select the following rule components and add them to your current profile:

• Interface

• Payment

• Pricing

• Product

• Shipping

• Tax

• Approval

• Security

• Miscellaneous

• Accounting Codes

Upgrading Permissions

To migrate the permission module, select the components you wish to migrate from the Select Components to Upgrade screen to add them to your current profile. The permissions components are as follows:

• Permissions Levels

• Permission Rules

Upgrading Approval

To migrate the approval module, select the components you wish to migrate from the Select Components to Upgrade screen to add them to your current profile. The approval components are as follows:

• Approver Matrix

• Delegations

• Approval Log

Using the Upgrade Utility User Interface

---

To start the Upgrade utility, access the following location. For example:

http://host_name:port_number/NASApp/upgrade/WelcomeProfile

The Select Profile screen displays.

Select Profile Screen

The Select Profile screen is the first welcome screen and allows you to define the profile for an upgrade session.

The following functions are available:

• Run Profile—The Run Selected Modules screen displays.

• Edit Profile—The Select Components to Upgrade screen displays.

• Remove Profile—The selected profile is removed.

• Create New Profile—Allows you to create a new profile.

• Drop ImpExp Tables—Deletes all information about the previous session (such as import data, log files, and report files).

To create a new profile, follow these steps:

1. Click Create New Profile. The Profile Name screen displays:

   
   
   

   You are prompted to enter a name for the new profile.

2. Enter a profile name and select Next.

   The Select Components to Upgrade screen displays.

Select Components to Upgrade Screen

The Select Components to Upgrade screen allows you to select the modules you want to upgrade. After you select the components you want to upgrade, you can choose to configure the profile or run the profile:

• Configure—The Specify Site Parameters screen displays.

• Run Profile—The Run Selected Modules screen displays.

Specify Site Parameters Screen

The Specify Site Parameters screen lets you define the BuyerXpert 3.x source parameters you are upgrading from and the BuyerXpert 4.x destination parameters you are upgrading to.

Table 3-2 lists the BuyerXpert 3.x source parameters and the BuyerXpert 4.x destination parameters.

Table 3-2    Upgrading Source Parameters 

BuyerXpert 3.x Source Parameters	BuyerXpert 4.x Destination Parameters
CADIS Source	hostname user name password
ORACLE source	iAS Datasource iAS Source SID
ORACLE destination	iAS Datasource iAS Source SID
LDAP	Host name Host port User name Password Root

Run Selected Modules Screen

The Run Selected Modules screen lets you select which module(s) to upgrade. The following functions are available:

• Run Module—This function upgrades the data modules you select. The Run Selected Modules screen allows you to select the data module you want to upgrade.

• Run Above Selected Modules—This function is the same as Run Module, except you can select multiple modules that are all updated at one time.

• Run Module in Express Mode—This function allows you to run both the data export and import processes. The Run Selected Modules screen allows you to select the data modules you want to upgrade.

• Run Report for Module—This function allows you to generate a report for the upgrade session. The Get Report screen displays, which allows you to generate a report for the selected modules.

• Change Profile—This function allows you change profiles. The Select Profile screen displays, which allows you to select and change a profile.

Selecting Modules to Upgrade

The Run Selected Modules screen displays when you select Run Profile from the Select Components to Upgrade Screen.

1. Select the modules you wish to upgrade and click Next to continue with the data migration process. The Run Selected Modules screen displays.

2. Select Run Modules or Run Above Selected Modules to upgrade the data modules you selected. The Export in Progress screen displays.
   
   

The Export Completed screen displays when the date export process completes.

Upgrade Status Screen

The Upgrade Status screen displays during the import process. It allows you to monitor the import process or stop an upgrade session.

Get Report Screen

The Get Report screen allows you to generate a report for the upgraded modules. The following functions are available:

• Get a Report—Displays the data import report for the Upgrade utility session.

• Get a Log File—Displays the data import log for the Upgrade utility session.

• Run Profile—Displays the Run Selected Modules screen.

Migrating Multi-Organizational Data

---

The Upgrade utility allows you to migrate data from a single organization structure into a multiple-organizational hierarchy structure. After you migrate the first BuyerXpert 3.x instance to a BuyerXpert 4.0 instance, additional BuyerXpert 3.x instances can be migrated to the BuyerXpert 4.0 instance.

This is achieved by modifying the following:

• LDAP configuration

• Membership import files

The following items need to be changed from the Configuration screen of the Upgrade utility:

• CADIS source

• Oracle source

Catalog destination (if migrating catalogs)

Modifying the LDAP Configuration

To eliminate the requirement of UID uniqueness across multiple organizations, complete the following tasks:

1. Start the console application and open the directory server that contains your data.

2. Change to your LDAP server configuration directory. For example:

   % cd /export/console/slapd-machine-name/config

3. Open the slapd.ldbm.conf file in a text editor.

4. Comment out the following line by inserting a # sign.

   # Plug in pre-operation on "uid uniquenes" /export.........

5. Restart the LDAP server.

Disable UID Uniqueness

You should disable UID uniqueness, which is set by default to the root directory during installation, by using the following procedure:

1. Start the console application and open the directory server that contains your data.

2. Select the configuration tab.

3. Expand the plug-in attribute on the left.

4. Deselect the UID uniqueness attribute.

Modifying the Membership Import Files

You need to modify the membership import files when you migrate a single organization structure to a multi-organization structure when you migrate membership data.

To do so, complete the following steps to change the parent of the organization you are importing:

1. Use the Run Selected Modules screen to select the membership module to upgrade on the Run Selected Modules screen (see "Select Components to Upgrade Screen"). Do not select Express mode. Instead, select Run Module or Run Above Selected Modules.

   The Upgrade utility begins the upgrade process for the membership module. When the data export completes, leave your browser open. Do not click Next to proceed with the import

2. Change to the destination directory that contains the import .imp files. For example:

   # cd /tmp

3. Open the following file in a text editor:

   orgunits_org_id_timestamp.imp

   For example, open orgunits_2000_10_11_04_40.imp.

4. Search for the line that contains the word organization. For example,

   insert_overwrite, Organization

   ^name,parent_org,duns_number,legal_type,display_name,\

   description,definable_id,status,effective_from_date,effective_to_da te,\

   email_adresses,websites,telephone_number,fax_number,\

   postal_address1,postal_address2,postal_address3,postal_address4,pos tal_address5,postal_address6

   John Hancock,,99-999-1701,C_CORP,John Hancock Mutual Life Insurance Co.,,2000,\

   enabled,01/02/1970,12/30/2036,\

   ,USA,^617^572-6000^,^617^572-7756^,\

   PO Box 111,Boston,MA,02117,,

5. Insert the following text o the right of the organization name, between the commas. For example:

   [Organization name=name_of_parent_org]

6. Save and close the file.

7. Return to your browser window. Click Next to continue importing data.