Sun Java System Content Delivery Server Migration Guide Table Of ContentsPrevious ChapterNext ChapterBook Index

C H A P T E R  4
Migrating the Database

This chapter describes how to migrate the database from the Content Delivery Server, version 5.0 and version 5.0 PU1, to the Content Delivery Server, version 5.1.

This chapter covers the following topics:

Migration Steps and Labels

The database migration process consists of a series of steps where each step is considered a separate migration procedure. Steps can be classified as either a catalog read or write step or a vending read or write step. Catalog steps must be completed before beginning the vending steps. A read step must always precede a corresponding write step. The following list shows the sequence you must follow for the set of migration steps for a single server deployment:

1. Catalog read

2. Catalog write

3. Vending read

4. Vending write

When a catalog write step is run, Content Delivery Server server code is run by the migration process to pass all content through the submission and verification workflows. This process can require a large amount of memory. To prevent OutOfMemory errors, increase the maximum heap size allowed for the Java virtual machine by setting the EXTRA_JAVA_ARGS environment variable before running the catalog write step. For example, 

$ EXTRA_JAVA_ARGS="-Xmx1500M" cdsi db migrate db -s code -c -w

Do not change the minimum heap size. Setting the minimum heap size to a larger value results in the Java virtual machine requesting more memory as soon as it is started. When the Java virtual machine needs to fork Oracle processes, the operating system fails the execution requests. This is because every time a JVM machine needs to start a process, it must create a copy of itself first and there might be not enough available operating system memory to do so.

Database migration operates with labels for storing and loading transformed data. A label is a directory where migration data is stored between performing a read and a write step. The same label must be used during the migration of the catalog server and all its associated vending servers because catalog data is referenced during the vending step.

In the case of remote vending, keep the label for vending data in an NFS accessible (for both reading and writing) location. Copy the label for the catalog data to the remote vending site as sharing the catalog label impacts the performance of Content Delivery Server.

The directory associated with the label has the following structure:

/label/catalog

/label/vending/VENDING_NAME

If your migration requires custom implementations as defined by the configuration file, you need to extend the Java class path so that it contains the path to your implementations. You can specify the path by setting the EXTRA_JAVA_CP environment variable before running the migration steps. For example: 

$ EXTRA_JAVA_CP="/tmp/extra.jar" cdsi db migrate db -s code -c -r

Prerequisites to Migration

The following conditions are required to run the database migration:

Migration Terms and Variables

For the rest of this guide, the term “source database” refers to the Sun Java System Content Delivery Server, version 5.0 (or 5.0 PU1 as applicable) database. The term “target database” refers to the Sun Java System Content Delivery Server, version 5.1 database.

Environment Variable Settings

You must have the variables, CDS_HOME and ORACLE_HOME defined, and you must have the following directories in your PATH:

The Oracle home directory can refer to either the Oracle home directory created by the server installation or by the client installation. In each case, the Oracle database utilities must be fully installed.

Be aware that an export error could occur if the vending source and target databases are run different versions of Oracle server. Either make sure the same server version is used for both databases; otherwise, be sure to comply with the following rules:

For example, if the source database is running on Oracle Database 9i and the target database is running on the Oracle Database 10g, the Export utility must run on Oracle Database 9i and the Import utility must run on Oracle Database 10g.

Also, make sure the paths in your init_env.sh file are properly configured.

Configuring the Migration

Only one configuration file is needed for database migration, DBMigration.xml located in the default directory, $CDS_HOME/cfg/migration/. This configuration file can be used for all migration steps. This section describes the rules for creating a configuration file and defines the tags used in the DBMigration.xml file.

The database migration configuration file you create can be named something other than DBMigration.xml, but it must be located in the $CDS_HOME/cfg/migration directory and must be specified when executing the cdsi migrate command.

Migration File Tagging Conventions

Follow these general rules when creating a configuration file:

Correct: 


<label>/path</label>

Incorrect: 


<label>
/path
</label>

Specifying a number of threads greater than what is supported in an Oracle session results in an error. Be sure to specify a number that does not exceed the number of Oracle supported sessions.

Be aware also that if you are running on a high-end machine and the number of CPUs is greater than the number of supported sessions in Oracle, an error results.

Configuration File Tags

This section defines the <dbmigration> tag and tags that can be used within it. The <dbmigration> tag is required. It is a top-level tag and encloses all other migration configuration tags and must be the root tag in the XML file. The following tags are valid within <dbmigration>:

 


TABLE 4-1 Configuration File Tags

Tag Name

Tag Description

<dbmigration>

This tag is required.

It is a top-level tag configuration file tag. It encloses all other migration configuration tags and must be the root tag in the XML file.

<catalog>

Required.

Encloses the catalog specific portion of the migration configuration. The following tags are valid within <catalog>: <catalog_events>, <classpath>, <deployment>, and <server_config>.

This tag is valid within <server>.

<catalog_database_link>

Required.

Link that enables the remote Vending Manager server to access to the catalog database.

If the source Vending Manager server and the source Catalog Manager are deployed on the same database and have the same SID, create the catalog database link as follows:

create database link catalog_database_link
connect to SRC_CM_PS_APP identified by SRC_CM_PS_APP_Password
using ‘SRC_CM_SID’

If the source Catalog Manager server and the source Vending Manager server are deployed on different databases, create the catalog database link as follows:

First, modify the tnsnames.ora file in $ORACLE_HOME/network/admin to create a local service name:

database_link_name =
(description =
(address = (protocol = TCP) (host =
source_catalog_database_host) (port = 1521))
(connect_data =
(server = dedicated)
(service_name = source_catalog_sid)
))

 

Next create the database link using the local service name just created:

create database link catalog_database_link
connect to SRC_CM_PS_APP identified by SRC_CM_PS_APP_Password
using ‘database_link_name’

This tag is valid within <vending>.

<catalog_events>

Not required.

Indicates that the catalog events are stored into this Catalog Manager’s event table. Use this tag if the Catalog Manager is not deployed with a vending manager. The value indicates the vending code, which is used to extract existing catalog events. The optional pk attribute is used to restrict the events that are migrated. Refer to the <event_pk> tag description in this section for more information.

This tag is valid within <catalog>.

<classpath>

Not required.

Specifies an additional classpath that must be added to the default classpath when the server is booted. This tag is usually used when the server submission code depends on additional libraries. If <classpath> is used, it must contain at least one <element> tag.

<element> represents a single classpath element. The following macros are recognized in the tag’s value:

  • $cds.dist - Expands to the full path of the Content Delivery Server distribution directory.
  • $cds.home - Expands to the full path of the Content Delivery Server home directory.

This tag is valid within <catalog>.

<coverage>

Creates custom coverage definition for the verification process. The coverage specifies the percentage of records that must be verified for certain tables.

Each coverage tag can specify different ranges for either the amount of data in the table or the table name and the amount of data to be tested on the table. It has the following attributes:

  • min - Minimum number of rows that are required to match coverage
  • max - Maximum number of rows that are required to match coverage
  • name - Name of the table to use to match coverage

Specify the table coverage by providing a minimum or maximum value or by providing a table name.

Default values for the attributes are applied in the following circumstances:

  • If the min attribute is not specified, its default value is 0.
  • If the max attribute is not specified, its default value is the largest possible signed 64 bit value.

See Default Coverage Values for more information.

Just prior to verification, a table’s name and number of rows are passed though the list of coverage tags. First, the name is checked, and if the name matches, the coverage is selected. Next, the number of row is matched. If the number matches, the coverage is selected.

This tag is valid within <dbmigration>.

<deployment>

Required.

Specifies the deployment name that is used by the migration process during content resubmission.

This tag is valid within <catalog>.

<destination>

Not required.

Specifies the path for the label directory that is used during write steps. If the steps are executed on different systems, the file system path can differ from it. <destination> has an optional style attribute. If the system where the write steps are executed uses a different path separator (for example, DOS instead of UNIX® standard), specify dos or unix as the value for the style attribute as appropriate.

This tag is valid within <label>.

<event_pk>

Not required.

Specifies a primary key in the CDS_EVENT table. Including the primary key in the CDS_EVENT table limits the extraction of the data in the table to this primary key’s value and to primary keys with larger values. The migration copies over only CDS_EVENT entries with primary keys that have values equal to or greater than the specified primary key.

The row with the specified primary key is included.

This tag is valid within <vending>.

<label>

Required.

Specifies the file system location where the data that was extracted from the source database is stored. The following tags are valid within <label>: <destination> and <location>.

This tag is valid within <server>.

<location>

Required.

Specifies the physical path for the label location.

This tag is valid within <label>.

<server>

Required if the server’s code is specified in the command line.

Encloses the server configuration entries. You must have one <server> tag for each Catalog Manager and all its associated Vending Managers. <server> takes the attribute, code, which distinguishes one server entry from another. The configuration file cannot contain more than one <server> tag with the same code value. The following tags are valid within <server>: <catalog>, <label>, <source_dbconf>, <target_dbconf>, and <vending>.

This tag is valid within <dbmigration>.

<server_config>

Not required.

Specifies the main Content Delivery Server configuration file that is used to start the deployment during content resubmission. The default value is CDS.properties.

This tag is valid within <catalog>.

<source_account>

Required.

Specifies the vending account name at the source configuration. The vending account name is used to extract the correct database connection information from the database configuration files and is also used to extract data from the source database.

This tag is valid within <vending>.

<source_dbconf>

Required.

Specifies the database configuration file, DBConf.xml, that is used to access the Catalog Manager and all Vending Manager databases that are migrated for that Catalog Manager. This file must be in the standard compliant with the database configuration file for Content Delivery Server, version 5.0. The only acceptable value is a file name. A search is done in the $CDS_HOME/cfg directory for the file.

This tag is valid within <server>.

<target_account>

Not required.

Specifies the vending account name at the target configuration. <target_account> is used to extract the correct database connection information from the database configuration files. If this tag is not used, the value of <source_account> is used instead.

<target_dbconf>

Required.

Specifies the database configuration file that is used to access the Catalog Manager and all Vending Manager databases that are migrated for that Catalog Manager. This file must be in the standard compliant with the database configuration file for Content Delivery Server, version 5.1. The only acceptable value is a file name. The file is searched for in the $CDS_HOME/cfg directory.

This tag is valid within <server>.

<threads>

Not required.

Specifies the number of parallel threads that are launched to run the migration. Takes an integer value of zero or higher. If zero is specified, the number of threads matches the number of CPUs found on the system. The default value is 0.

This tag is valid within <dbmigration>.

<vending>

Required if vending code is used.

Encloses the entire configuration relative to a single Vending Manager. <vending> takes the attribute, CODE, which distinguishes one server entry from another. The configuration file cannot contain more than one <vending> tag with the same code value. The following tags are valid within <vending>: <catalog_database_link>, <event_pk>, <source_account>, and <target_account>.

This tag is valid within <server>.


Default Coverage Values

If there are no coverage tags, the following default coverage is used: 


<verification>
<!-- do full coverage, if a table has less than 100 entries -->
<coverage max="100">100.0</coverage>
<!-- do 21% coverage for tables with (100,10000] entries -->
<coverage min="101" max="10000">21.0</coverage>
<!-- do 5% coverage for tables with more than 10000 entries -->
<coverage min="10001">5.0</coverage>
<!-- do 0.1% coverage for fulfillment_request table -->
<coverage table="fulfillment_request">0.1</coverage>
</verification>

The default values were estimated as optimal for coverage and for the amount of time that the verification script takes to run. The coverage tags are processed in the order they are found in the configuration file. The scan stops at the first matching tag in cases where the minimum and maximum coverage overlaps. The tags specifying the table names are exempt and are always checked first.

Use a floating point value in the text form, specified as the text value for the <coverage> tag.

The following example shows how to select 95% coverage for the category_item table: 


<coverage name=”category_item”>95</coverage>

The following example shows how to select 3% coverage for all tables: 


<coverage>3</coverage>

To migrate a single server deployment, you must define at least two catalog steps (one read and one write) and two vending steps (one read and one write). See the section, Running the Migration to learn how these steps are called during the execution.

For examples of migration files, see Configuration Examples.

Configuration Examples

This section provides three configuration examples that represent the most widely used deployment scenarios.

Single Server Deployment

This example shows a possible configuration file for single server deployment.


CODE EXAMPLE 4-1 Sample Configuration File for Single Server Deployment 
<dbmigration>
 
  <threads>0</threads>
 
  <server code="server1">
    <source_dbconf>DBConf.xml.source</source_dbconf>
    <target_dbconf>DBConf.xml.target</target_dbconf>
    <label>
      <location>/export/space0</location>
      <!--
      <destination style="dos">o:\mount...xport\space0</destination>
      -->
    </label>
 
    <catalog>
      <!--
      <classpath>
        <element>${cds.dist}/lib/external/bcel-5.1.jar</element>
      </classpath>
      -->
 
      <catalog_events pk="131123">vending1</catalog_events>
      <deployment>cds</deployment>
      <server_config>CDS.properties</server_config>
    </catalog>
 
    <vending code="vending1">
      <source_account>suncds.vending.server.1</source_account>
      <target_account>java.vending</target_account>
      <catalog_database_link>local_database_link</catalog_database_link>
    </vending>
 
    <!--
    <coverage name="fulfillment_request">0.1</coverage>
    <coverage max="100">100</coverage>
    <coverage min="101" max="10000">21</coverage>
    <coverage min="10001">5</coverage>
    -->
 
  </server>
   
</dbmigration>

Remote Vending Deployment

This example shows a possible configuration file for a deployment with one Catalog Manager and two Vending Manager servers (one local and one remote).


CODE EXAMPLE 4-2 Sample Configuration File for remote Vending Deployment 
<dbmigration>
 
  <threads>0</threads>
 
  <server code="server1">
    <source_dbconf>DBConf.xml.source</source_dbconf>
    <target_dbconf>DBConf.xml.target</target_dbconf>
  
    <label>
      <location>/export/space0</location>
      <!--
      <destination style="dos">o:\mount...xport\space0</destination>
      -->
    </label>
 
    <catalog>
 
      <!--
      <classpath>
        <element>${cds.dist}/lib/external/bcel-5.1.jar</element>
      </classpath>
      -->
 
      <catalog_events pk="131123">vending1</catalog_events>
      <deployment>cds</deployment>
      <server_config>CDS.properties</server_config>
    </catalog>
 
    <vending code="vending1">
      <source_account>suncds.vending.server.1</source_account>
      <target_account>java.vending</target_account>
      <catalog_database_link>local_database_link</catalog_database_link>
    </vending>
 
    <vending code="vending2">
      <source_account>suncds.vending.server.2</source_account>
      <target_account>ringtone.vending</target_account>
      <catalog_database_link>src.remote_database_link</catalog_database_link>
    </vending>
 
    <!--
    <coverage name="fulfillment_request">0.1</coverage>
    <coverage max="100">100</coverage>
    <coverage min="101" max="10000">21</coverage>
    <coverage min="10001">5</coverage>
    -->
 
  </server>
   
</dbmigration>

Logging Migration Information

During the catalog write step, the server code passes all content through the submission and the verification workflows. All the logging information from the server code is stored in the migration.server.log.* files in the $CDS_HOME/dist/cds/logs directory. To configure additional logging properties, such as the maximum size of log files, the maximum number of log files, and the logging thresholds, edit the file called logging.properties in the LABEL_DIRECTORY/catalog directory. This file is created during the catalog read step and is used only during a catalog write step.

The migration.log file contains migration messages, except for debugging messages, and can be found in the $CDS_HOME/dist/cds/logs directory. Examine the migration log files when resolving problems encountered in the migration. For more information on migration log files, see Messages in Chapter 5.

Instrumenting Content

Instrumentation is now handled through content resubmission. Modify the SubmissionVerifiedWorkflows.xml file as needed for your deployment of Content Delivery Server. See the Sun Java System Content Delivery Server Installation Guide for information.

Migrating the CDS_EVENT Table

Use the <event_pk> tag to optimize the migration of the CDS_EVENT table. The event table is used primarily for reporting purposes. It provides information that can help you improve the execution time of migrating a single vending server. You can specify the first primary key that is migrated by using the <event_pk> tag. The rest of the event table can be migrated after the server is up and running. The userid argument must also be modified accordingly. For a description of the <event_pk> tag, see Configuration File Tags.

For example, if the <event_pk> specified in the configuration file is 12345, then the following commands can be used to migrate the rest of the CDS_EVENT table: 


$ exp ’userid=CDS_VS_OWNER/dbpasswordx@CONNECT’ \
      ’file=CDS_EVENT.dmp’ \
      ’constraints=n’ ’grants=n’ ’indexes=n’ \
      ’log=export.log’ \
      ’query="where cds_event_id < 12345"’ \
      ’tables=CDS_EVENT’ \
      ’feedback=1000’
 
$ imp ’userid=CDS_VS_OWNER/dbpasswordx@CONNECT’ \
      ’tables=CDS_EVENT’ \
      ’log=import.log’ \
      ’file=CDS_EVENT.dmp’ \
      ’ignore=y’ \
      ’feedback=1000’

If the catalog server is deployed standalone, that is, running on a server separate from the vending servers, modify the query argument to separate catalog and vending events. Use 

’query="where server_instance_id = 0 and cds_event_id < 12345"’

to select catalog events and write them to the PS_OWNER schema. Use 

’query="where server_instance_id != 0 and cds_event_id < 12345"’

to select vending events and write them to the VS_OWNER schema.

The userid argument must also be modified accordingly. The <connect> argument is the name that Oracle client tools can resolve into a server connection. If no naming services are set up on the system, you can use direct addressing of your database instances: 


$ exp ’userid="CDS_PS_OWNER/passwordx@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=olddb.wireless.com)(PORT=1521)))(CONNECT_DATA=(SID=old_sid)))"’ \
          ’file=CDS_EVENT.dmp’ \
          ’constraints=n’ ’grants=n’ ’indexes=n’ \
          ’log=export.log’ \
          ’query="where cds_event_id < 12345"’ \
          ’tables=CDS_EVENT’ \
          ’feedback=1000’
 
$ imp ’userid="CDS_PS_OWNER/passwordx@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=newdb.wireless.com)(PORT=1521)))(CONNECT_DATA=(SID=new_sid)))"’ \
          ’tables=CDS_EVENT’ \
          ’log=import.log’ \
          ’file=CDS_EVENT.dmp’ \
          ’ignore=y’ \
          ’feedback=1000’

Refer to Oracle documentation for more information on Oracle naming schemas.

Migrating Events for a Standalone Catalog Deployment

If a newly deployed Catalog Manager is running standalone, you must specify the <catalog_event> tag. When specified, the catalog-specific events in all vending event tables are migrated to the catalog event table. For a description of the <catalog_event> tag, see Configuration File Tags.

Migrating Supported Devices Information for Editions

The information in this section addresses cases where the Catalog Manager administrator has changed the supported devices for one or more content items.

Generally, any edition submitted into both version 5.0 (or 5.0 PU1) and version 5.1 of Content Delivery Server database can have any number of derived content editions created by a DRM. Even when no DRM protection is chosen, a derived edition is still created. The Catalog Manager administrator can force the value of the supported devices property for any derived editions, thus modifying the input for the capability matching routine that determines which editions are allowed for download to which devices.

Since the content is being passed through the submission and verification workflows during migration, it is impossible to predict which derived editions created in the old database become which derived editions in the new database, especially since the number of editions in both databases might not be the same.

This factor prevents the migration process from matching the current selection of supported devices made for derived editions to newly created derived editions. Migration expands the supported devices property list to include devices selected for all derived editions of an originally submitted edition.

Migrating supported devices information for editions is handled in the following way: if the Catalog Manager administrator customized the supported devices property for any of the derived editions of an original edition, the values of the supported devices property for all of the derived editions of a single original edition are combined. This value is used as the supported devices property during resubmission of the original editions. Though the property is used during resubmission, it is inherited only by the derived editions. The property value originally defined for the original edition is not changed.

Running the Migration

Once the XML configuration file is in place, you are ready to execute the migration steps. To execute a single step, issue the following command: 


$ cdsi migrate db -s code -c | -v code -r | -w -f file

where

Use this option if your configuration file name is other than DBMigration.xml.

For example to run a catalog read step, enter the following command: 


$ cdsi migrate db -s code -c -r

To run a vending write step using an alternate configuration file, enter the following command: 


$ cdsi migrate db -s code -v code -w -f file

When running a database migration command, you must specify -c or -v and -r or -w.

The default database migration file, DBMigration.xml, is located in the $CDS_HOME/cfg/migration/ directory.


Note - Once the migration process is started, do not modify the configuration file. Any change to it requires that the migration process be restarted from the beginning.

To complete the migration, you must execute all the read and write steps for the Catalog Manager server and for all the Vending Manager servers being migrated. When migration begins, the Catalog Manager server must be placed in READ ONLY mode or the application server running it must be shut down. READ ONLY means that no modifications can be made to the Catalog Manager database, that is, developers cannot submit any content and administrators cannot make any modifications. Data integrity can be lost during the migration process if these requirements are not met.

To migrate a Vending Manager server, its application server must be shut down.

Keep the following points in mind regarding the deployment of Content Delivery Server during the migration:

If you are running Content Delivery Server on the same machine as both the source and target database servers, you can ignore this item. You do not have to start Content Delivery Server on the database server.

Migrating with Single Server Deployment

For a single server deployment, follow these migration steps:

1. Restrict access to the Catalog Manager and Developer Portal.

2. Execute the catalog read step.

3. Execute the catalog write step on the target deployment.

4. (Optional) Verify that the migration of the Catalog Manager was successful.

You can use the migration verification script provided by Content Delivery Server. See Verifying Migration Completion for information on how to run the script.

5. Grant the following system-level privileges to the source Vending Manager schemas:

Run the following command: 


grant create any synonym to source_vending_schema_VS_APP

Run the following command: 


grant drop public synonym to source_vending_schema_VS_APP

Run the following command: 


grant create database link to source_vending_schema_VS_APP

These steps enable the Vending Manager application to create synonyms and database links during the vending read step.


Note - If these privileges are not granted, the vending read step fails. Failure occurs when reading the category_item table extraction, because during extraction, the resource_instance of a Catalog section is accessible only when a synonym is created.

Alternatively, you can log directly into each Catalog and Vending Manager database and grant public access.

6. If the Catalog Manager and the Vending Manager point to the same database (if not, skip to Step 7), create a database link to source_vending_schema_VS_APP as follows:

a. Log into the source Vending Manager database as source_vending_schema_VS_APP user of the database.

b. Create the database link to source_vending_schema_VS_APP: 


create database link catalog_database_link
connect to SRC_CM_PS_APP identified by SRC_CM_PS_APP_Password
using ‘SRC_CM_CID’

Provide this database link by including the <catalog_database_link> tag in the <vending> tag section in the DBMigration.xml file for this Vending Manager database server. See Configuration File Tags for a description of the <catalog_database_link> tag.

7. If the Catalog Manager and the Vending Manager point to different databases, create a database link to source_vending_schema_VS_APP as follows:

a. Log into the source Vending Manager database as system user.

b. Create a local service name for the remote database name by adding the following entry to the network configuration file, tnsnames.ora, located in $ORACLE_HOME/network/admin: 


database_link_name =
   (description =
      (address = (protocol = TCP) (host = source_catalog_database_host) (port = 1521))
      (connect_data =
         (server = dedicated)
         (service_name = source_catalog_sid)
      )
   )

c. Log into the source Vending Manager database as source_vending_schema_VS_APP user of the database.

d. Create a database link using the local service name just created: 


create database link catalog_database_link
connect to SRC_CM_PS_APP identified by SRC_CM_PS_APP_Password
using ‘database_link_name’

Provide this database link by including the <catalog_database_link> tag in the <vending> tag section in the DBMigration.xml file for this Vending Manager database server. See Configuration File Tags for a description of the <catalog_database_link> tag.

8. If the Catalog Manager and the Vending Manager are deployed on different databases, create a database system user and password for the databases in the DBSysUser.xml file located in the $CDS_HOME/cfg directory: 


<DBUsers>
  <DBServer name = “DBServer1”>
    <User>system</User>
    <Password>dbpassword</Password>
  </DBServer>
 
  <DBServer name = “DBServer2”>
    <User>system</User>
    <Password>dbsyspassword</Password>
  </DBServer>
 
</DBUsers>

For detailed information on the DBSysUser.xml file, see the Sun Java System Content Delivery Server Installation Guide.

9. Edit the DBmigration.xml file for this remote Vending Manager to point to the modified (source) DBConf.xml file.

10. Shut down Content Delivery Server’s single server completely.

11. Execute the vending read step.

12. Execute the vending write step.

13. (Optional) Verify that the migration of the Vending Manager was successful.

14. Start the new (target) server.

Migration Guidelines for Remote Vending Deployment

To ensure that the vending read step is successful, check that you have access from the Vending Manager to the catalog schema, which could be deployed on a separate machine. If a proxy server is used, be sure to enable the proxy for the port in use by the database.

Migrating with Remote Vending Deployment

For deployments with at least one remote Vending Manager, that is a Vending Manager running on a server separate from the Catalog Manager, follow these migration steps. The scenario assumes that at least one Vending Manager (denoted as VM) is running in single server mode with the Catalog Manager. Remote Vending Managers are denoted as RVM.

The first part of the procedure describes how to migrate the source Catalog and Vending Managers. The second part of the procedure describes how to migrate the remote Vending Managers.

1. Restrict access to the Catalog Manager and Developer Portal.

2. Execute the catalog read step.

3. Execute the catalog write step on the target deployment.

4. (Optional) Verify that the migration of the Catalog Manager was successful.

You can use the migration verification script provided by the Content Delivery Server. See Verifying Migration Completion for information on how to run the script.

5. Grant the following system-level privileges to the source Vending Manager (VM) schemas:

Run the following command: 


grant create any synonym to source_vending_schema_VS_APP

Run the following command: 


grant drop public synonym to source_vending_schema_VS_APP

Run the following command: 


grant create database link to source_vending_schema_VS_APP

These steps enable the Vending Manager application to create synonyms and database links during the vending read step.


Note - If these privileges are not granted, the vending read step fails. Failure occurs when reading the category_item table extraction, because during extraction, the resource_instance of a Catalog section is accessible only when a synonym is created.

Alternatively, you can log directly into each Catalog and Vending Manager database and grant public access.

6. Log into the source Vending Manager(VM) database as source_vending_schema_VS_APP user.

7. If the Catalog Manager and the Vending Manager(VM) point to the same database, create a database link to source_vending_schema_VS_APP as follows:

a. Log into the source Vending Manager(VM) database as source_vending_schema_VS_APP user of the database.

b. Create the database link: 


create database link catalog_database_link
connect to SRC_CM_PS_APP identified by SRC_CM_PS_APP_Password
using ‘SRC_CM_CID’

Provide this database link by including the <catalog_database_link> tag in the <vending> tag section in the DBMigration.xml file for this Vending Manager database server. See Configuration File Tags for a description of the <catalog_database_link> tag.

8. If the Catalog Manager and the Vending Manager(VM) point to different databases, create a database link to source_vending_schema_VS_APP as follows:

a. Log into the source Vending Manager(VM) database as system user.

b. Create a local service name for the remote database name by adding the following entry to the network configuration file, tnsnames.ora, located in $ORACLE_HOME/network/admin: 


database_link_name =
   (description =
      (address = (protocol = TCP) (host = source_catalog_database_host) (port = 1521))
      (connect_data =
         (server = dedicated)
         (service_name = source_catalog_sid)
      )
   )

c. Log into the source Vending Manager database as source_vending_schema_VS_APP user of the database.

d. Create a database link using the local service name just created: 


create database link catalog_database_link
connect to SRC_CM_PS_APP identified by SRC_CM_PS_APP_Password
using ‘database_link_name’

Provide this database link by including the <catalog_database_link> tag in the <vending> tag section in the DBMigration.xml file for this Vending Manager database server. See Configuration File Tags for a description of the <catalog_database_link> tag.

9. If the Catalog Manager and the Vending Manager are deployed on different databases, create a database system user and password for the databases in the DBSysUser.xml file located in the $CDS_HOME/cfg directory: 


<DBUsers>
  <DBServer name = “DBServer1”>
    <User>system</User>
    <Password>dbpassword</Password>
  </DBServer>
 
  <DBServer name = “DBServer2”>
    <User>system</User>
    <Password>dbsyspassword</Password>
  </DBServer>
 
</DBUsers>

For detailed information on the DBSysUser.xml file, see the Sun Java System Content Delivery Server Installation Guide.

10. Shut down the old Catalog Manager and the (source) Vending Manager(VM) server.

11. Execute the vending read step for VM.

12. Execute the vending write step for VM.

13. (Optional) Verify that the migration of VM was successful.

Migrating the Remote Vending Managers

1. Modify the DBConf.xml file for the source remote Vending Manager (denoted as RVM) by adding the Catalog element so that the remote Vending Manager can access the catalog database: 


<CDSDatabase>
 
    <DBServer name="DBServer1">
        <Hostname>dbhost1host.domain.com</Hostname>
        <Port>port_number</Port>
        <SID>dbsid</SID>
        <Tablespace>USERS</Tablespace>
        <Tablespace name="catalog">USERS</Tablespace>
        <Tablespace name="catalog indexes">USERS</Tablespace>
        <Tablespace name="content">USERS</Tablespace>
        <Tablespace name="content indexes">USERS</Tablespace>
        <Tablespace name="event">USERS</Tablespace>
        <Tablespace name="event indexes">USERS</Tablespace>
        <Tablespace name="subscriber">USERS</Tablespace>
        <Tablespace name="subscriber indexes">USERS</Tablespace>
        <Tablespace name="vending">USERS</Tablespace>
        <Tablespace name="vending indexes">USERS</Tablespace>
        <TempTablespace>TEMP</TempTablespace>
    </DBServer>
 
    <Catalog>
        <Prefix>5.0_schema</Prefix>
        <Password>dbpassword</Password>
        <DBServer>DBServer2</DBServer>
    </Catalog>
 
    <Vending name="cds.vending.server.1">
        <Prefix>5.0_schema</Prefix>
        <Password>dbpassword</Password>
        <DBServer>DBServer2</DBServer>
    </Vending>
 
    <DBServer name="DBServer1">
        <Hostname>dbhost2.domain.com</Hostname>
        <Port>port_number</Port>
        <SID>dbsid2</SID>
        <Tablespace>USERS</Tablespace>
        <Tablespace name="catalog">USERS</Tablespace>
        <Tablespace name="catalog indexes">USERS</Tablespace>
        <Tablespace name="content">USERS</Tablespace>
        <Tablespace name="content indexes">USERS</Tablespace>
        <Tablespace name="event">USERS</Tablespace>
        <Tablespace name="event indexes">USERS</Tablespace>
        <Tablespace name="subscriber">USERS</Tablespace>
        <Tablespace name="subscriber indexes">USERS</Tablespace>
        <Tablespace name="vending">USERS</Tablespace>
        <Tablespace name="vending indexes">USERS</Tablespace>
        <TempTablespace>TEMP</TempTablespace>
    </DBServer>
 
</CDSDatabase>

In this example, DBServer1 denotes the machine where the source remote Vending Manager (RVM) is deployed. DBServer2 denotes the machine where the source Catalog Manager is deployed.

The prefixes for the Catalog and Vending elements designate the 5.0 (or 5.0 PU1 as applicable) schemas.

After you have completed the migration process, remove the Catalog element from this file as this element is only needed for migration purposes.

The source remote Vending Manager(RVM) database does not have the Catalog Manager schema in the DBConf.xml so that information must be included manually.

For a detailed description of the database configuration file, see the Sun Java System Content Delivery Server Installation Guide.

2. Create a database system user and password for the Catalog database in the DBSysUser.xml file located in the $CDS_HOME/cfg directory: 


<DBUsers>
  <DBServer name = “DBServer1”>
    <User>system</User>
    <Password>dbpassword</Password>
  </DBServer>
 
  <DBServer name = “DBServer2”>
    <User>system</User>
    <Password>dbsyspassword</Password>
  </DBServer>
 
</DBUsers>

For detailed information on the DBSysUser.xml file, see the Sun Java System Content Delivery Server Installation Guide.

3. Log into the source remote Vending Manager(RVM) database machine as system user and create a local service name for the remote database name by adding the following entry to the network configuration file, tnsnames.ora, located in $ORACLE_HOME/network/admin: 


database_link_name =
   (description =
      (address = (protocol = TCP) (host = source_catalog_database_host) (port = 1521))
      (connect_data =
         (server = dedicated)
         (service_name = source_catalog_sid)
      )
   )

4. While logged into the (source) remote Vending Manager(RVM) database, grant the following privileges to SRC_RVM_VS_APP:

Run the following command: 


grant create any synonym to SRC_RVM_VS_APP

Run the following command: 


grant drop public synonym to SRC_RVM_VS_APP

Run the following command: 


grant create database link to SRC_RVM_VS_APP

5. Log into the source remote Vending Manager database as SRC_RVM_VS_APP user.

6. Create a database link using the local service name just created: 


create database link catalog_database_link
connect to SRC_CM_PS_APP identified by SRC_CM_PS_APP_Password
using ‘database_link_name’

Provide the database link by including the <catalog_database_link> tag in the <vending> tag section in the DBMigration.xml file for this Vending Manager database server. For a description of the <catalog_database_link> tag, see Configuration File Tags.

7. Edit the DBmigration.xml file for this remote Vending Manager to point to the modified (source) DBConf.xml file.

8. Deploy the target remote Vending Manager (RVMX) and edit the target DBConf.xml file to point to the Catalog Manager schema.

The following sample DBConf.xml file points to the addition of the Catalog Manager schema: 


<CDSDatabase>
 
    <DBServer name="DBServer1">
        <Hostname>dbhost1host.domain.com</Hostname>
        <Port>port_number</Port>
        <SID>dbsid</SID>
        <Tablespace>USERS</Tablespace>
        <Tablespace name="catalog">USERS</Tablespace>
        <Tablespace name="catalog indexes">USERS</Tablespace>
        <Tablespace name="content">USERS</Tablespace>
        <Tablespace name="content indexes">USERS</Tablespace>
        <Tablespace name="event">USERS</Tablespace>
        <Tablespace name="event indexes">USERS</Tablespace>
        <Tablespace name="subscriber">USERS</Tablespace>
        <Tablespace name="subscriber indexes">USERS</Tablespace>
        <Tablespace name="vending">USERS</Tablespace>
        <Tablespace name="vending indexes">USERS</Tablespace>
        <TempTablespace>TEMP</TempTablespace>
    </DBServer>
 
    <Catalog>
        <Prefix>5.1_schema</Prefix>
        <Password>dbpassword</Password>
        <DBServer>DBServer1</DBServer>
    </Catalog>
 
    <Vending name="cds.vending.server.1">
        <Prefix>5.1_schema</Prefix>
        <Password>dbpassword</Password>
        <DBServer>DBServer2</DBServer>
    </Vending>
 
    <DBServer name="DBServer2">
        <Hostname>dbhost2.domain.com</Hostname>
        <Port>port_number</Port>
        <SID>dbsid2</SID>
        <Tablespace>USERS</Tablespace>
        <Tablespace name="catalog">USERS</Tablespace>
        <Tablespace name="catalog indexes">USERS</Tablespace>
        <Tablespace name="content">USERS</Tablespace>
        <Tablespace name="content indexes">USERS</Tablespace>
        <Tablespace name="event">USERS</Tablespace>
        <Tablespace name="event indexes">USERS</Tablespace>
        <Tablespace name="subscriber">USERS</Tablespace>
        <Tablespace name="subscriber indexes">USERS</Tablespace>
        <Tablespace name="vending">USERS</Tablespace>
        <Tablespace name="vending indexes">USERS</Tablespace>
        <TempTablespace>TEMP</TempTablespace>
    </DBServer>
 
</CDSDatabase>

In this example, DBServer1denotes the machine where the target Catalog Manager is deployed. DBServer2 denotes the machine where the target remote Vending Manager (RVM) is deployed.

The prefixes for the Catalog and Vending elements designate the 5.1 schemas.

9. Update DBMigration.xml so that it points to the modified DBConf.xml (the target DBConf file).

The remote Vending Manager deployment does not have the Catalog Manager schema information in the DBConf.xml so that information must be included manually.

10. Create a label_directory/catalog directory on the machine where the remote Vending Manger is deployed.

label_directory is the file system location where the data that was extracted from the source database is stored as specified by the <label> tag in the DBMigration.xml file.

11. Copy the .completed, .success, and *.SSO files from the label_directory/catalog directory from the machine where the Catalog Manager is deployed.

The .completed and .success files are required when determining whether the Catalog Manager database is correctly populated with data. The .SSO file contains data about reinstrumented content and Ids.

12. Edit the DBmigration.xml file for this remote Vending Manager to point to the modified (source) DBConf.xml file.

Provide the database link by including the <catalog_database_link> tag in the <vending> tag section in the DBMigration.xml file for this Vending Manager database server.

13. Shut down the remote Vending Manager, RVM.

14. Execute the vending read step for RVM.

15. Execute the vending write step for RVM.

16. (Optional) Verify that the migration of RVM was successful.

17. Start RVM on the target deployment.

Repeat Steps 1 through 17 for each remote Vending Manager.

Correcting Path Name Discrepancies

Remember that when executing the catalog write step, you might run into problems if the paths to Content Delivery Server home directory do not match for both the application server and the database server when network paths are used. To correct this problem, follow these steps:

1. Open the $CDS_HOME/deployment/deployment_name/conf/SubmissionVerifierWorkflows.xml file.

2. Save a backup copy of this file.

3. Replace all absolute paths to the JAR files with suitable paths on the database server.

4. Execute the catalog write step.

Verifying Migration Completion

You can use the verification migration script to verify that the migration of the database is successful. To run the verification script, enter the following command at the prompt: 


$ cdsi migrate verifydb -s code -c | -v code -f file

where

Use this option if your configuration file name is other than DBMigration.xml.

A -c or -v flag is required to identify a catalog or vending step.

For example, when verifying the migration of the Catalog Manager, enter the following command: 


$ cdsi migrate verifydb -s code -c

When verifying the migration of the Vending Manager, enter the following command: 


$ cdsi migrate verifydb -s code -v code

After migration verification is completed, you might need to set some content types to be read only, you must run an SQL command to specify the content type to be read only before you deploy the latest version of Content Delivery Server. See Step 12 in Chapter 1, Migrating Content Delivery Server for details.


Note - The Catalog and Vending Search Service components use the Solr search server to index content and handle search queries. Be aware that building the index, after migration has completed and the target servers are started, can take some time. If you run a search query immediately after migration, the search results might not return matches from the total set of content.

Post Migration Modifications

After migration of the Catalog Manager and Vending Manager completes, any changes to existing Vending Manager Account Server information must be updated to enable synchronization of information between the Catalog and Vending Managers. To update the information, follow these steps:

1. Log into the Catalog Manager.

2. Click Accounts in the main menu bar.

The console displays the Account Management page for Vending Manager Servers.

3. Click the Vending Manager Server account you want to modify.

4. Click Edit.

Update the account information as needed. For information on updating account information, click Help on the console.

5. Repeat Steps 3 and 4 for each Vending Manager Server account.

Building the Search Index

After migration has completed and the target server is started, you need to build the search index. The Catalog and Vending Search Service components use the Solr search server to index content and handle search queries. For each service, you must create an index for content in the Catalog and Vending Managers. The search indexes are managed independent of the content database.

To build the search index for the Catalog Manager, log into the Catalog Manager administration console and enter the following URL in the address field of your browser:

http://host:port/admin/main/search_update?action=rebuild

host:port is the host name and port number for the server on which the Catalog Manager is running. A message is shown when the building process completes.

To build the search index for the Vending Manager, log in to the Vending Manager administration console and enter the following URL in the address field of your browser:

http://host:port/vsadmin/main/search_update?action=rebuild

host:port is the host name and port number for the server on which the Vending Manager is running. A message is shown when the building process completes.

Be aware that building the index can take some time. If you run a search query immediately after migration, the search results might not return matches from the total set of content. For more information on the search index, see the Sun Java System Content Delivery Server System Management Guide.

 



Sun Java System Content Delivery Server Migration Guide 820-1945-10 Table Of ContentsPrevious ChapterNext ChapterBook Index

Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.