Migrating the Business Space V6.2.0.x data

If you are migrating from WebSphere® Process Server V6.2.0.x, then, after you upgrade the product databases (which upgrades the Business Space database schema), you must migrate the Business Space database data.

Before you begin

Before you upgrade the database data, make sure you have completed the steps in Upgrading existing databases.

Important: When migrating Business Space data, the personalized information that is migrated for every Business Space user is limited to 10 of the most recently viewed pages and 60 of the most recently adjusted widgets.

When migrating Business Space data to V8.5.6, you must use the same LDAP that you used for the previous version.

The installBusinessSpaceWidgets and updateBusinessSpaceWidgets commands mentioned in this topic are run using the AdminTask object of the wsadmin scripting client.

The following conditions must be met:

Run the commands on the deployment manager node.
Run the commands in the connected mode, that is, do not use the wsadmin -conntype none option.
You must connect with a user ID that has WebSphere Application Server administrator privileges.

Start the wsadmin scripting client from the deployment_manager_profile/bin directory.

Procedure

Optional: If you have enabled specific BPM product widgets for remote endpoints, and the product for the widgets is not installed on the target system (the system you are migrating to), you must install the product widgets manually. A remote endpoint is a service endpoint that resides on a system that is "remote" to the Business Space server (that is, the service endpoint is not located on the Business Space server).
For example, in a configuration where you have two profiles, one for IBM® Business Process Manager and the other for IBM Business Monitor and you install Business Space on the server in the IBM Business Monitor profile, and have enabled the IBM Business Process Manager widgets for remote endpoint, you must install the IBM Business Process Manager widgets in the server manually. To do this, use the following procedure:
1. Copy the widget package files for the specific BPM product to a temporary folder on the local machine.
  Widget packages can be found in the install_root/BusinessSpace/registryData/product_name/widgets directory on the machine where the BPM product is installed.
2. Using the installBusinessSpaceWidgets command, install the product widgets (with the widget package files) on Business Space in the target installation. For more information, see installBusinessSpaceWidgets command.
Copy the widget definition files.
The V8.5.6 widget definition files and any custom widget definition files from a previous version must be copied manually to the following directory on one of the V8.5.6 target servers that participate in the cluster where Business Space is deployed: node_profile_root/BusinessSpace/datamigration/widgets. Create the directory if it does not exist.

To copy the widget definition files, use the following procedure.
1. To copy all of the non-custom Business Space V8.5.6 widget definition files, search for file names containing either iwidget.xml or iWidget.xml in the V8.5.6 node_profile_root/installedApps directory of all profiles that participate in the cluster where Business Space is deployed. Collect the files together and put them into the node_profile_root/BusinessSpace/datamigration/widgets directory on one of the V8.5.6 target servers that participates in the cluster where Business Space is deployed.
2. If you have custom widgets from V6.2, you must copy all of the custom widget definition files to the V8.5.6 installation of Business Space before migrating the Business Space data. To do this, copy all of the custom widget definition files from the earlier versions of Business Space into the node_profile_root/BusinessSpace/datamigration/widgets directory of the target server that you copied widget definition files to in step 2a.
  Note: Copy the widget files on all of the profiles that participate in the cluster where Business Space is deployed. Collect the files together, and put them into the node_profile_root/BusinessSpace/datamigration/widgets directory on one of the V8.5.6 target servers that participates in the cluster where Business Space is deployed.
Start the cluster in the target environment. Depending on your environment, use one of the following procedures:
- If the Business Space database being updated belongs to a non-clustered managed node where Business Space is configured, start the server on the node using the startServer command from the profile_root/bin directory of the migration target server. Use the following syntax:
```
startServer.sh server_name
```
  See startServer command in the WebSphere Application Server information center.
- If the Business Space database being updated belongs to a clustered environment, start the deployment manager, node, and all servers using the startManager, startNode, and startServer commands from the profile_root/bin directory of the migration target server. Use the following syntax:
```
startManager.sh
startNode.sh
startServer.sh server_name (start all servers on the node in sequence)
```
  See startManager command, startNode command, and startServer command in the WebSphere Application Server information center.
Migrate the Business Space data.
1. On the node that you copied widget definition files to in step 2, to prevent timeout errors, modify the com.ibm.SOAP.requestTimeout property by editing the soap.client.props file that is located in the properties subdirectory of the profile_root directory, where profile_root is the node that the migration target server belongs to. Change the com.ibm.SOAP.requestTimeout value from 180 to a larger value, such as 1800, which is 30 minutes.
2. On the node that you copied widget definition files to in step 2, run the migrateBSpaceData script to migrate Business Space V6.2 data to Business Space V8.5.6.
  The script is located in the following directory: target_install_root/BusinessSpace/scripts/. In a clustered environment, run the script on the node that you copied widget definition files to in step 2 The value of the -port parameter of migrateBSpaceData must be the SOAP port of the server that you run the script on. For more information about the migrateBSpaceData script, see migrateBSpaceData command-line utility.
  Command sample:
```
/opt/bpm85/WebSphere/AppServer/BusinessSpace/scripts/migrateBSpaceData.sh -host 9.110.191.64 -port 8880 -user admin -password admin -cluster AppCluster
```
3. After running the migrateBSpaceData script on the custom node profile to generate the directory for endpoints or catalogs under profile_root/BusinessSpace/datamigration, you must manually copy the directory that you generated from the custom node machine to the deployment manager machine under deployment_manager_profile_root/BusinessSpace/datamigration.
  Attention: If you fail to perform this step, you are presented with the following error: wsadmin>$AdminTask updateBusinessSpaceWidgets {-clusterName MyTop1.Support -endpoints /opt/BPM85/profiles/Custom01/BusinessSpace/datamigration/endpoints} CWMO1132E: No endpoint files found. The path to the endpoints file does not exist: [/opt/BPM85/profiles/Custom01/BusinessSpace/datamigration/endpoints]
Optional: Migrate the widget catalog for custom widgets.
If you have custom widgets and you are migrating a network deployment environment, you must run the updateBusinessSpaceWidgets command on the deployment manager profile to populate the migrated widget catalog of the custom widgets that were generated in XML format under the following folder: deployment_manager_profile_root/BusinessSpace/datamigration/catalog. Launch the updateBusinessSpaceWidgets command from the profile_root/bin directory of the deployment manager profile.
- Jython example:
```
AdminTask.updateBusinessSpaceWidgets('[-clusterName cluster_name -catalogs deployment_manager_profile_root/BusinessSpace/datamigration/catalog]')
```
- Jacl example:
```
$AdminTask updateBusinessSpaceWidgets {-clusterName cluster_name -catalogs deployment_manager_profile_root/BusinessSpace/datamigration/catalog }
```
Note: Catalog files are generated only if you have custom widgets.

For more information about the updateBusinessSpaceWidgets command, see updateBusinessSpaceWidgets command.
For network deployment environments, migrate the widget endpoints for both product and custom widgets.
If you are migrating a network deployment environment, run the updateBusinessSpaceWidgets command on the deployment manager profile to populate the migrated widget endpoints for both product and custom widgets that were generated in XML format under the following folder: deployment_manager_profile_root/BusinessSpace/datamigration/endpoints. Launch the wsadmin environment for the updateBusinessSpaceWidgets command from the profile_root/bin directory of the deployment manager profile.

This step is not necessary for stand-alone environments.

For more information about the updateBusinessSpaceWidgets command, see updateBusinessSpaceWidgets command.
- Jython example:
```
AdminTask.updateBusinessSpaceWidgets('[-clusterName cluster_name -endpoints deployment_manager_profile_root/BusinessSpace/datamigration/endpoints]')
```
- Jacl example:
```
$AdminTask updateBusinessSpaceWidgets {-clusterName cluster_name -endpoints deployment_manager_profile_root/BusinessSpace/datamigration/endpoints }
```
Stop the servers, node, and deployment manager in the target cluster. Repeat this step for each server in the cluster. Use the stopServer, stopNode, and stopManager commands from the profile_root/bin directory on the migration source target. Use the following syntax:
```
stopServer.sh server_name -username user_name -password password (stop all servers on the node in sequence)
StopNode.sh
StopManager.sh
```
If the profile has security enabled, the user name provided must be a member of the operator or administrator role. If the profile does not have security enabled, the -username and -password parameters are not necessary.

See stopServer command, stopNode command, and stopManager command in the WebSphere Application Server information center.
Verify that the previous steps are all successful by checking the migration traces and logs.
Remove obsolete database tables by running the postMigrateBusinessSpace620.sql script.
1. Log in to the database server as a user with read and write access on the database.
2. Connect to the database.
3. Locate the postMigrateBusinessSpace620.sql script for your database in the profile that you most recently configured, and save it to a location on the same system as the database.
  By default, the scripts are located in the following directory: target_deployment_manager_profile_root/dbscripts/Upgrade/deployment_environment_name/database_type/database_name.schema_name
  
  Important: This script might need to be modified if the default values do not match your environment.
4. Change to the directory where you copied the script, and run the postMigrateBusinessSpace620.sql script, as described in the header of the file.

Results

The Business Space database data is migrated to Business Space V8.5.6.

Tip: Previous superuser settings that defined Business Space administrators might be lost after the migration from V6.2. Set the superusers for V8.5.6 using the steps in Assigning the superuser role.

What to do next

If any of your widgets are deprecated in V8.5.6, follow the instructions in Deprecated widgets to replace the widgets after migration.