Skip Headers
Oracle® Communications Order and Service Management Installation Guide
Release 7.2.2

E35412-06
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

11 Upgrading to OSM 7.2.2

This chapter describes how to upgrade Oracle Communications Order and Service Management (OSM) to version 7.2.2.

About OSM Upgrades

Upgrading OSM consists of the following process:

  • Planning the upgrade

  • Implementing and testing the upgrade on a development system

  • Preparing to upgrade a production system

  • Implementing and testing the upgrade on the production system

The upgrade process includes these tasks:

  • Gather a list of components installed in your current OSM system

  • Document the configuration selections made when installing your current OSM system

  • Upgrade the platform (if applicable)

  • Upgrade the WebLogic Server

  • Upgrade or create a new WebLogic domain

  • Update the WebLogic domain

  • Upgrade the Oracle Database (if applicable)

  • Upgrade the OSM software

The post upgrade process includes these tasks:

  • Upgrade the development environment, including Oracle Communications Design Studio, Ant, GraphViz, OSM SDK, and OSM Tools.

  • Upgrade the administration environment, including Oracle Data Access Components (ODAC) client and the OSM Administrator application.

  • Upgrade and redeploy cartridges to the OSM 7.2.2 server.

For current version and patch information, see "OSM System Requirements."

Supported Upgrade Paths

You can directly upgrade to OSM 7.2.2 from OSM 6.3.1 and any OSM 7.0.x release.

About Backing Up Your Data

Before upgrading OSM, make a backup of your data files and the database. For general OSM backup and restore information, see OSM System Administrator's Guide. All of the backup information in that document is relevant to performing a backup prior to an upgrade.

OSM will not recreate or overwrite any existing WebLogic resources (including OSM users, groups and queues) except for the resources that were removed prior to upgrade (such as oms.ear and cartridge_management_ws.ear).

About Upgrading Oracle Database

The procedures in this section should be performed only by a qualified database administrator.

If you are performing an upgrade that requires a database version upgrade as well, the recommended method is to upgrade the database and then upgrade OSM. In this case, the normal backup and restore procedures as discussed in OSM System Administrator's Guide still apply. It is recommended to back up the database both before and after upgrading it.

In some cases, it may not be feasible to upgrade the database instance due to circumstances in your environment, such as the presence of other applications' data in the database instance. In that case, you must export the data from the older version of the database and import it into the new version. The recommended method for doing this is Oracle Data Pump Import and Export (impdp and expdp).

For information about how to use Oracle Data Pump, see the Oracle Database documentation. Important considerations for OSM include the following:

  • It is best to export and import in schema mode (the default).

  • Ensure that you export and import both the OSM Primary Schema and the OSM Notification Engine Schema.

  • By default, Data Pump Import creates the schema users and performs the necessary grants. It is a good idea to use the default and, if you do, you must ensure that users with the same names do not already exist in the new database instance.

About OSM Customizations

Any customizations to views, tables, triggers, or other entities stored in the OSM database schema must be reapplied after OSM is upgraded.

Any custom reports on the OSM database schema must be reapplied or rewritten if schema changes are made to the newer database.

About Creating a New Localization JAR File

If you have localized data in a pre-7.2.2 OSM database schema, a new set of OSM 7.2.2 localization files must be created and reapplied after OSM is upgraded. You cannot reuse the omsmodel_l10.jar file from a previous release.

For details on how to recreate the omsmodel_l10n.jar file, refer to OSM Developer's Guide. Reapply localization data from the previous versions of the JAR file to the newer JAR file.

Preparing for an OSM Upgrade

The following sections describe how to prepare the OSM environment for an OSM upgrade.

Preparing the Environment

To prepare the OSM environment:

  1. Ensure that all transactions are committed and all JMS messages are consumed.

  2. Stop all of the processes running against OSM (including the OSM Administrator, the XML Import/Export application, XMLAPI agents and others). For more information about how to stop OSM, see OSM System Administrator's Guide.

  3. Stop the WebLogic Server.

  4. Back up the OSM database.

    Caution:

    The OSM installer stops the OSM schema upgrade if it encounters any issues. This can render the schema unusable. The OSM installer cannot rectify this problem on its own.
  5. Do the following:

    • If you are creating a new WebLogic domain, back up the existing WebLogic server domain directory, custom SDK files, and scripts to a directory outside of your OSM installation.

    • If you are upgrading the existing OSM 7.2 WebLogic domain, archive the MW_home directory including all subdirectories. Archive the WLS_home directory as well if it is not located in the MW_home directory.

  6. Start the WebLogic server.

  7. If you are upgrading from OSM 6.3.1, un-register and un-deploy all 6.3.1 plug-ins including automation and task assignment plug-ins.

    Note:

    If an automation plug-in .ear file was deployed using OSM CMT, it must be un-registered and un-deployed using OSM CMT.
  8. Stop the OSM WebLogic application components (including the oms.ear, cartridge_management_ws.ear and any other automation plug-in .ear files) using the WebLogic console.

  9. If you are upgrading from a version of OSM higher than 6.3.1, delete the OSM WebLogic application components (including oms.ear and cartridge_management_ws.ear) as well as any automation plug-in .ear files from WebLogic using the console. Also, manually delete these files from their respective directories located under domain_home/servers/admin_server/upload/ where admin_server is the name of the administration server for the domain.

  10. If you are upgrading a development system that uses the Order-to-Activate cartridges and the Activation Integration Architecture emulators, remove the emulator .ear files from WebLogic using the console. Also, manually delete these files from under domain_home/servers/admin_server/upload/ where admin_server is the name of the administration server for the domain. You will have to re-deploy the emulator after the upgrade process is complete.

  11. Stop the WebLogic Server.

Upgrading or Creating the WebLogic Domain

The following sections describe the steps to prepare the WebLogic domain for an OSM upgrade. You can:

  • Create a new WebLogic domain.

  • Upgrade the existing WebLogic domain. This option is supported for OSM 7.2 to OSM 7.2.2 only.

Before you upgrade or create the WebLogic Server domain see Oracle Fusion Middleware Upgrade Guide for Oracle WebLogic Server 11g Release 1 (10.3.6) and review the steps to:

  • Upgrade custom security providers

  • Upgrade Node Managers

  • Upgrade WebLogic Domain

  • Upgrade WebLogic Domain (remote managed servers)

Upgrading the OSM 7.2 WebLogic Domain to WebLogic 10.3.6 and ADF 11.1.1.6

To upgrade an OSM 7.2 WebLogic Domain to WebLogic 10.3.6 and Oracle Application Development Framework (ADF) 11.1.1.6:

  1. Install the recommended JDK. See "OSM System Requirements."

  2. Go to My Oracle Support web site:

    https://support.oracle.com
    
  3. Click Patches and Updates.

  4. In the Patching Quick Links area click Latest Patchsets.

  5. Click Advanced Search.

  6. Next to the Product or Family field, click the search icon.

    The Search and Select: Product or Product Family screen appears.

  7. In the Search list, select All Products.

  8. In the Search field, enter Oracle WebLogic Server.

  9. Select Oracle WebLogic Server (beaowls).

  10. Next to the Release field, click the search icon.

    The Search and Select: Release screen appears.

  11. In the Release field select WLS 10.3.6.

  12. In the Patch Type list, select Patch.

  13. In the Description field, enter PLACEHOLDER. This is a keyword reserved for the WebLogic upgrade patch.

  14. Click Go.

    The Patch appears in the Results for Platform table.

  15. Click the patch number corresponding to the WebLogic Server upgrade installer.

  16. Click Download.

  17. Run the upgrade installer, choosing the same settings as your existing WebLogic Server installation.

  18. Download ADF 11.1.1.6. See "Software Requirements" for more information.

  19. Install ADF in the MW_home containing the upgraded version of WebLogic Server and the version of ADF you want to upgrade.

  20. Apply any required patches for WebLogic Server and ADF. See "Software Requirements" for details.

  21. Start the WebLogic Scripting Tool (WLST) by running one of the following commands:

    • For UNIX or Linux:

      MW_home/oracle_common/common/bin/wlst.sh
      
    • For Windows:

      MW_home/oracle_common/common/bin/wlst.cmd
      
  22. In WLST, enter the following command:

    upgradeJRF("domain_home")
    

    For example:

    upgradeJRF("/u01/Oracle/Middleware/user_projects/domains/OSM_Domain")
    
  23. Exit WLST by entering the following:

    exit()
    
  24. Update the WebLogic Server to the new JDK version. See Knowledge Article 1309855.1 on the My Oracle Support web site:

    https://support.oracle.com
    
  25. Repeat this procedure for all remote managed servers.

Creating a New 10.3.6 WebLogic Domain

To create a new WebLogic 10.3.6 domain with ADF 11.1.1.6:

Note:

You must create a new WebLogic 10.3.6 domain with ADF 11.1.1.6 if you are upgrading from OSM 6.3 or 7.0.x.
  1. Install the recommended JDK version. See "Software Requirements" for details on the recommended version.

  2. Install Oracle WebLogic Server 10.3.6. See "Software Requirements."

  3. Install ADF 11.1.1.6. See "Software Requirements."

  4. Apply any required Oracle WebLogic Server and ADF patches. See "Software Requirements" for details.

  5. Create a new 10.3.6 domain. Use the same domain name as the existing domain. When creating the new 10.3.6 domain you must select Oracle JRF. This is required for OSM as it makes use of ADF. See "Installing and Configuring WebLogic Server."

    Re-create user accounts and settings. You must recreate all the users and other settings that you had configured in your old domain in your new 10.3.6 domain. Note that password requirements may have changed with the newer version of Oracle WebLogic. If you are upgrading a system that uses the Order-to-Activate cartridges, users and settings to support the cartridges will have to be recreated. See "Updating Order-to-Activate Cartridges."

    If your previous domain was in a clustered WebLogic Server environment re-create the same environment. See "Installing OSM in a Clustered Environment" for information about installing OSM in a clustered environment in this guide.

Updating the WebLogic Domain

The following section describes WebLogic domain updates that may be required.

Updating JMS Security Policy Settings

Starting with OSM 7.0.1, JMS Queues or Topics that are part of the JMS system module (oms_jms_module) have a security policy. No action is required for applications built using the OSM SDK, but modifications are required to external (non-OSM) applications that communicate with OSM using JMS.

An application that communicates with OSM using JMS already has ejb-jar.xml and weblogic-ejb.jar.xml files in the code. Before these applications are used with OSM 7.0.1 or later, the following additions must be made.

In the ejb-jar.xml file, add a <security-identity> for each EJB. In the example below the EJB is a message-driven bean.

<message-driven>
   ...
   <security-identity>   
      <run-as>
         <role-name>test-role</role-name>
      </run-as>
   </security-identity>
</message-driven>
 

In the ejb-jar.xml file, include the <security-role> as a part of the <assembly-descriptor>:

 
<assembly-descriptor>
   <security-role>
      <description/>
         <role-name>test-role</role-name>
      </security-role>
   ...
</assembly-descriptor>

In the weblogic-ejb.jar.xml file map the <security-role> to the oms-automation user to allow EJBs to access the JMS resources:

<weblogic-ejb-jar>
   ...
   <security-role-assignment>
      <role-name>test-role</role-name>
      <principal-name>oms-automation</principal-name>
   </security-role-assignment>
   <run-as-role-assignment>
      <role-name>test-role</role-name>
      <run-as-principal-name>oms-automation</run-as-principal-name>
   </run-as-role-assignment>  
</weblogic-ejb-jar>

Upgrading the Database

If you are currently running on an 11gR1 database, export the OSM data, upgrade the database to 11gR2 and import the OSM data. See "Software Requirements" for version details and information on required patches.

Refer to the Oracle Database documentation for information on upgrading Oracle Database Server from version 11gR1 to 11gR2 and how to migrate data.

You can use the Oracle Data Pump Import and Export utility to migrate data from a version 11gR1 database to a version 11gR2 database. For information Oracle Data Pump, see the Oracle Database documentation. See "About Upgrading Oracle Database" for considerations when using the Oracle Data Pump Import and Export utility.

Upgrading OSM to 7.2.2

This procedure describes how to upgrade OSM from version 6.3.1 or 7.0.x to version 7.2.2.

Caution:

Before upgrading, refer to "About OSM Upgrades" for important preparation steps.

Performing the OSM Upgrade

To upgrade OSM:

  1. Start the WebLogic server in the new or upgraded WebLogic 10.3.6 domain. If this is a clustered environment, start the administration, managed, and proxy servers.

  2. Verify that any WebLogic patches you installed are displayed in the WebLogic log.

  3. Run the installer for OSM 7.2.2.

    Note:

    If you are upgrading from OSM 7.0.x, part of the SDK (the automation module) is not upgraded if installing to the original 7.0.x OSM directory. Specify a new directory to ensure complete installation of the new OSM SDK.

    Note:

    The OSM installer automatically migrates the OSM schema as part of the installation process if the Database Schema component is selected.
  4. On the Component Selection screen, select the same components as were installed in your previous OSM installation. Ensure that the Database Schema is selected.

  5. On the Database Credential Information screen:

    • Enter the username and password for the previous OSM schema.

    • Enter the username and password for the previous OSM rule engine schema.

  6. On the Database Analysis screen, click Upgrade.

  7. If your OSM application requires localization, you will be prompted during the upgrade (at the Database Schema Localization Information screen) to specify the path to your localized file.

  8. On the WebLogic Configuration - Configuration Type screen, select Connect to a running WebLogic server.

  9. On the WebLogic Server Connection Information screen, enter the WebLogic server connection information.

    If the installer detects an existing database configuration in the domain, and the database connection information is different from that supplied during the installation, the Database Configuration Comparison screen is displayed.

    This screen provides a comparison of database configuration differences in either a single-database setup, or an Oracle Real Applications Cluster (RAC) database setup, depending on your environment.

    If the database configuration for your previous OSM installation included a single-instance database, the pre-existing data source is a generic data source.

    If the database configuration for your previous OSM installation included an Oracle RAC database configuration, the pre-existing data source is a multi data source containing two generic data sources.

    See "Connecting Oracle RAC with JDBC Multi Data Source" for a discussion on how OSM supports Oracle RAC through the use of WebLogic multi data sources.

  10. If the domain is a new 10.3.6 domain, the Database Configuration Comparison screen will be skipped.

    On the Database Configuration Comparison screen, do one of the following:

    • Select Replace the existing JDBC data source configuration with the new connection information and click Next. If you are upgrading from a non-Oracle-RAC database to an Oracle RAC environment, you must select this option.

      Caution:

      The installation does not migrate any data to the new data source (including persisted JMS messages). All configuration parameters will be reset to their defaults. Therefore, any customizations will be lost. Ensure you have a backup of your previous installation before proceeding.
    • Select Leave the existing JDBC data source configuration intact and click Next. This is the default option. The installer continues at step 17.

    • Click the Back button repeatedly to return to the Database Connection Information screen and change your settings.

    If the current installation uses an Oracle RAC database connection, the Oracle Real Application Clusters (RAC) Configuration screen is displayed. Otherwise, installation continues at step 16. You can configure Oracle RAC for failover or load balancing. Load balancing options are only available in a multi-node cluster deployment.

  11. Select one of the following options:

    • Configure an additional Oracle RAC instance for load balancing using the installer.

      (Disabled for single-server deployments.) The installer configures half of the WebLogic Server instances to one Oracle RAC database instance as the first data source, and the other Oracle RAC database instance as the second data source. The other half of the instances in the WebLogic Server cluster are configured with the sequence of the Oracle RAC database instances swapped. See "Connecting Oracle RAC with JDBC Multi Data Source" for more information.

    • Configure an additional (secondary) Oracle RAC instance for failover using the installer.

      The installer configures a multi data source and two data sources. The first data source connects to the primary instance previously specified, and the second data source connects to the secondary instance to be specified. This option preconfigures the database connections in WebLogic for warm standby. See "Connecting Oracle RAC with JDBC Multi Data Source" for more information.

    • After installation completes, manually configure an additional Oracle RAC instance for load balancing in WebLogic.

      (Disabled for single-server deployments.) The installer configures a multi data source and one data source which connects to the Oracle RAC database instance previously specified. This option offers the flexibility to add one or more Oracle RAC database instances, post installation. See "Configuring an Additional Data Source for an Oracle RAC Instance" for configuration details.

    • After installation completes, manually configure an additional Oracle RAC instance for failover in WebLogic.

      The installer configures a multi data source and one data source that connects to the primary instance previously specified. This option offers the flexibility to add one or more Oracle RAC database instances, after installation. See "Configuring an Additional Data Source for an Oracle RAC Instance" for configuration details.

    • Do not use Oracle RAC.

      The installer configures a single data source for the Oracle RAC instance previously specified but does not create a multi data source. OSM will not use Oracle RAC for load balancing or failover.

      Note:

      If you decide in the future to implement Oracle RAC for load balancing or failover, you must run the installer again and select one of the first four options described here. You cannot manually add and configure the Oracle RAC database instance.
  12. Click Next.

    If you chose any option other than one of the first two options in step 11, proceed to step 16.

    If you chose to configure an additional Oracle RAC instance for load balancing or failover using the installer (first option), the Oracle RAC Listener Configuration screen is displayed.

  13. Specify whether your Oracle RAC instances use a remote listener (server-side load balancing enabled) or local listeners and click Next. See "Listener Considerations for Oracle RAC" for a discussion on listener functionality.

    If you chose the remote listener option and you did not previously specify the SID of the primary Oracle RAC instance, the installer takes you to the Database Connection Information screen to enter the SID (the host, port, and service name are protected). After entering the SID, you will be prompted to configure your Oracle RAC database instance for failover or load balancing, depending on your deployment. If you select any option other than the first option, the Database Connection Pool Information screen is displayed. If you select the first option, installation resumes at the next step.

    The Additional Oracle RAC Instance Connection Information screen is displayed.

  14. Specify the connection information for the additional Oracle RAC instance. Both instances must be in the same database.

    If you chose the remote listener option, enter the SID. (All other fields are protected).

    If you chose the local listeners option, you can edit any field except the service name.

  15. Click Next.

  16. In an upgrade installation, the JMS Store Information screen is skipped as long as there are pre-existing OSM JMS server configurations. If you have created a new 10.3.6 domain, the screen will not be skipped and you can configure your JMS store information accordingly.

  17. In the screens that follow, use the same installation configuration parameters as with the previous OSM installation.

    The installer notifies you when the upgrade is complete.

  18. In a new window, log into SQL*Plus as the OSM database user and run the procedure below in the primary database schema to gather schema statistics:

    BEGIN
    DBMS_STATS.GATHER_SCHEMA_STATS (
    OWNNAME=>USER, 
    ESTIMATE_PERCENT=>10,
    GRANULARITY =>'ALL',
    CASCADE =>TRUE, 
    BLOCK_SAMPLE=>TRUE);
    END;
    

    Because the upgrade to OSM 7.2.2 involves data movement, it is important that database statistics be updated. If you plan to verify the installation prior to daily automatic statistics collection, use the DBMS_STATS.GATHER_SCHEMA_STATS procedure to gather statistics manually.

    Oracle recommends setting the ESTIMATE_PERCENT parameter of GATHER_SCHEMA_STATS to DBMS_STATS.AUTO_SAMPLE_SIZE to maximize performance gains while achieving necessary statistical accuracy. With a larger ESTIMATE_PERCFENT value, statistics gathering for a large database could take several hours. If you prefer a faster, less accurate result, use a small ESTIMATE_PERCENT value such as 1.

    You can continue with the upgrade procedure while this statistics gathering runs.

  19. Reapply any other EAR file customizations from the previous release by undeploying the newly installed oms.ear file and redeploying an oms.ear file containing the required customizations.

  20. Reapply customizations to views, tables, triggers, or other entities stored in the OSM database schema.

  21. Reapply or rewrite any custom reports if schema changes were made to the newer database.

  22. If a new WebLogic domain was created, copy the contents of the Attachments folder from the old WebLogic domain to the newly created WebLogic 10.3.6 domain. Ensure that the file permissions allow the OSM application to read and write the files copied to the new domain.

  23. Shutdown and restart the WebLogic 10.3.6 server.

  24. Refer to Design Studio Installation Guide for any required upgrade actions for Design Studio.

  25. Upgrade your cartridges. See "Upgrading Pre-7.2.2 Cartridges to OSM 7.2.2."

  26. Reapply customizations to views, tables, triggers, or other entities stored in the OSM database schema.

  27. Reapply or rewrite any custom reports on the OSM database if schema changes are made to the newer database.

When the upgrade is complete, instruct your OSM Web client users to clear their browser's temporary cache files. Refer to the web browser's documentation for information on how to do this.

Important:

Users who do not clear their cache may experience unexpected errors while using the upgraded OSM Web client because the web browser may still be using the previous versions of certain OSM Web client files.

Converting OSM Data Source Configurations

During an OSM upgrade, you have the option to replace an existing data source configuration with another data source configuration based on the new database connection information you provide. The most typical scenario is to upgrade from a non-Oracle-RAC database configuration to an Oracle RAC database configuration.

To implement a data source configuration change, the installer removes the existing configuration and sets up a new one (either a single generic data source for a non-RAC configuration, or a multi data source and two generic data sources for an Oracle RAC configuration).

If you already have an existing data source/Oracle RAC configuration, you can convert from one type of configuration to another using the installer. This section describes three conversion scenarios.

Oracle RAC Active-Passive to Active-Active

To perform an active-passive to active-active conversion, you must run the installer twice. Perform the following steps:

  1. Shut down all managed servers in the OSM cluster.

  2. Run the installer to downgrade from an Oracle RAC active-passive configuration to a non-RAC configuration. Only the screens that are relevant to the conversion are listed here.

    1. On the Component Selection screen, select Server and click Next.

    2. On the Database Configuration Comparison screen, select Replace the existing JDBC data source configuration with the new connection information and click Next.

    3. On the Oracle Real Application Clusters (Oracle RAC) screen, select Do not use Oracle RAC and click Next.

  3. Run the installer to upgrade from a non-RAC configuration to an Oracle RAC active-active configuration.

    1. On the Component Selection screen, select Server and click Next.

    2. On the Database Configuration Comparison screen, select Replace the existing JDBC data source configuration with the new connection information and click Next.

    3. On the Oracle Real Application Clusters (Oracle RAC) screen, select Configure an additional Oracle RAC instance for load-balancing using the installer and click Next.

  4. Start the managed servers.

After the conversion, any in-flight orders will be picked up by OSM in the new environment and processed. If there are no in-flight orders, you can submit a new order for testing purposes. You can also check that the data sources have been assigned to the WebLogic Server instances correctly and that the JMS JDBC store, if configured, is using the correct multi data source.

Oracle RAC Active-Active to Active-Passive

To perform an active-active to active-passive conversion, you must run the installer twice. Perform the following steps:

  1. Shut down all managed servers in the OSM cluster.

  2. Run the installer to downgrade from an Oracle RAC active-active configuration to a non-RAC configuration. Only the screens that are relevant to the conversion are listed here.

    1. On the Component Selection screen, select Server and click Next.

    2. On the Database Configuration Comparison screen, select Replace the existing JDBC data source configuration with the new connection information and click Next.

    3. On the Oracle Real Application Clusters (Oracle RAC) screen, select Do not use Oracle RAC and click Next.

  3. Run the installer to upgrade from a non-RAC configuration to an Oracle RAC active-passive configuration.

    1. On the Component Selection screen, select Server and click Next.

    2. On the Database Configuration Comparison screen, select Replace the existing JDBC data source configuration with the new connection information and click Next.

    3. On the Oracle Real Application Clusters (Oracle RAC) screen, select Configure an additional (secondary) Oracle RAC instance for failover using the installer and click Next.

  4. Start the managed servers.

After the conversion, any in-flight orders will be picked up by OSM in the new environment and processed. If there are no in-flight orders, you can submit a new order for testing purposes. You can also check that the data sources have been assigned to the WebLogic Server instances correctly and that the JMS JDBC store, if configured, is using the correct multi data source.

Oracle RAC Active-Active to Active-Active

This conversion is most likely to happen in a development or testing environment where new or different Oracle RAC database instances are being introduced. The installer does not support this type of conversion. Instead, you perform the reconfiguration manually by logging in to the WebLogic Administration Console and changing the URLs of the data sources to point to the new Oracle RAC instances.

Upgrading the Development and Administration Environment

OSM supports a development and administration environment that includes the following software components that may require an upgrade:

  • Design Studio: The currently supported versions of the Design Studio core and plug-ins may be different than those certified with your source OSM release. There may also be additional plug-ins that were not available with your OSM source release. See Design Studio Compatibility Matrix (included in the Design Studio media pack) for Design Studio for Order and Service Management compatibility information.

  • Ant: Apache Ant is a Java tool that is required by the OSM XML Import Export application (XMLIE) and the OSM cartridge management tool (CMT) used for deploying custom task assignment algorithms. You may need to upgrade the Ant version to use these applications. See "Software Requirements" for version details.

  • GraphViz: GraphViz is a graphic visualization used with XMLIE to convert an OSM metadata XML document into an HTML presentation. See "Software Requirements" for version details.

  • ODAC Client: The OSM Administrator Application require the ODAC client to communicate with the OSM Server. See "Software Requirements" for version details.

  • OSM Administrator Application: The OSM Administrator Application can be upgraded using the OSM installer. See "Upgrading OSM to 7.2.2" for more information about running the OSM installer.

  • OSM SDK Tools and Samples: You can install new versions of the OSM SDK tools and samples using the OSM installer. See "Upgrading OSM to 7.2.2" for more information about running the OSM installer.

Upgrading Pre-7.2.2 Cartridges to OSM 7.2.2

Once you have upgraded your OSM system to version 7.2.2, perform the following procedure to enable your pre-OSM 7.2.2 cartridges to run in the newly upgraded environment.

Cartridge Upgrade Prerequisites

Before you upgrade cartridges, ensure the following prerequisites are met:

  • OSM is upgraded to 7.2.2 using the OSM installer.

  • Design Studio is upgraded to the required version. See "Upgrading the Development and Administration Environment."

  • The OSM 7.2.2 SDK component is installed using the OSM installer.

  • The Oracle WebLogic Server domain for OSM 7.2.2 is running.

  • Old existing domain configurations, such as JMS queues, users, groups, and emulators have been recreated in the new domain.

  • Automation plug-in .ear files are deleted from WebLogic using the console.

  • All cartridges are backed up.

Cartridge Upgrade Procedure

To upgrade your pre-7.2.2 cartridges to OSM 7.2.2:

  1. Set global default OSM preferences.

    In Design Studio, navigate to Window > Preferences > Oracle Design Studio > Order and Service Management Preference and set the following values:

    • Automation plug-in Build and Deploy Mode

      Select one of the following:

      • Optimized (Default): Allows automation components to be built and run within a common oms.ear file at run time, thus improving performance. This is the recommended (default) mode for cartridges with a target version of 7.2.0, which is the target version used in OSM 7.2.2.

      • Legacy: Refers to the pre-7.2.2 process of building and deploying each automation plug-in its own .ear file. If you need to build and deploy a cartridge in legacy mode (for example, because there is a fundamental incompatibility with class libraries), set the cartridge management variable instead (step 2).

      • Both (Allow server preference to decide): Allows automation components to be built and run in either mode, according to the dispatch mode defined on the OSM server.

    • OSM SDK Home: Specify the local installation directory for the 7.2.2 OSM SDK. Ensure that you extract the automation.jar file to this location.

    For information on automation plug-in dispatch modes and how performance is improved, see OSM Developer's Guide.

  2. Set cartridge management variables.

    For individual cartridges in your workspace, open the Cartridge editor > Cartridge Management Variables tab and set the following variables according to your requirements:

    • Set PURGE_CARTRIDGE_BEFORE_DEPLOY to true to undeploy the previous version of a cartridge before deploying the new version, or set it to false to update the cartridge with the changes for the new version.

      Note:

      If your cartridge has pending or completed orders that you do not want to purge, do not undeploy the cartridge, but deploy the new version with PURGE_CARTRIDGE_BEFORE_DEPLOY set to false.
    • Set ENTITY_CONFLICT_ACTION_ON_DEPLOY to replace to replace the old entities with the new (this is the default); set it to ignore to add the new entities and retain the old; or set it to abort to stop the process. This variable applies only if PURGE_CARTRIDGE_BEFORE_DEPLOY is set to false.

    • Set PURGE_ORDER_ON_UNDEPLOY to true to purge all existing orders associated with the cartridge, or set it to false if you do not want the system to undeploy the cartridge if it has pending orders.

      Caution:

      Undeploying a cartridge purges all existing orders for that cartridge.
    • Set BUILD_DEPLOY_MODE for the cartridge to overwrite the global value of Automation plug-in Build and Deploy Mode that you set in step 1. The cartridge-level value has precedence when building and deploying a specific cartridge. See step 1 for a description of each value.

  3. In Design Studio, in the customAutomation folder of your cartridge workspace, replace automationMap.xsd with the latest version from the OSM_home/SDK/Automation/automationdeploy_bin folder. Refer to the discussion about defining OSM preferences in the Design Studio Modeling OSM Processes Help for more information about how to define general preferences for the new OSM version.

  4. If there are no pending Order-to-Activate orders in your OSM instance, change the target version and cartridge versions to be compatible with OSM 7.2.2. If there are pending Order-to-Activate orders in your OSM instance, you must skip this step.

    For each cartridge in your workspace, open the Cartridge editor Properties tab and set the target version to 7.2.0 (which is the target version used in OSM 7.2.2) and update the version number. See "Updating Cartridges to a Five-Digit Version."

  5. Clean and build all cartridges.

    In this step, it is expected that builds will fail. Go to the Problems view and run the quick fix for the following errors:

    • "The automationBuild.xml file in cartridge ... is not the right version for this Design Studio ...".

      After fixing the problem, a new automationBuild.xml file is created in the src directory of the cartridge.

    • "Order Model Error - Order Template Node/ControlData/Functions/.../calculatedStartDate is not defined...".

      After fixing the problem, Design Studio applies the calculatedStartDate data structure from the OSM common data dictionary to the following entities:

      • Order Specifications in the Order Template tab

      • Order Components in the Order Template tab (if the Order Component contains control data)

      • Create Task in the Task Data tab (if the Creation Task contains control data)

    • "Order Model Error - Order Template Node/ControlData/Functions/.../duration is not defined...".

      After fixing the problem, Design Studio applies the duration data structure from the OSM common data dictionary to the following entities:

      • Order Specifications in the Order Template tab

      • Order Components in the Order Template tab (if the Order Component contains control data)

      • Create Task in the Task Data tab (if the Creation Task contains control data)

  6. Some cartridges may fail to build if they contain Java classes which implement interfaces that have changed in OSM 7.2.2.

    To fix this error, open the failed Java files in Design Studio, right-click the error marker, and run the quick fix "add unimplemented methods".

  7. If the same Java class exists in different cartridges (for example, if both cartridge A and B define a Java class com.mycompany.cartridges.log.LogActivity), then this class must be the same in both cartridges.

  8. Clean and build all cartridges in the workspace again.

  9. Redeploy all cartridges to the OSM 7.2.2 run-time environment.

Upgrade Impacts on Cartridges from Previous Releases to OSM 7.2.2

This section provides information on upgrade impacts to cartridges from previous releases of OSM to version 7.2.2.

Turning On Inheritance of Keys and Significance for Existing Cartridges

Starting with OSM 7.2, significance and keys are included in the information extended from a base order. The significance of an inherited data element within the order template is now inherited from the OSM entity that contributed it. For example, a data element an order component contributes to the ControlData structure defined on the order now inherits the significance value that is defined on the order component.

Providing this inheritance within the order template is recommended for new cartridge development. You have the option to turn this functionality on for existing cartridges.

Design Studio will detect conflicts such as incorrect significance behavior after you turn the functionality on, and raise problem markers. To resolve conflicts you must examine order data elements and align their significance values to adhere to inheritance rules (as described below). You must resolve problem markers before you can deploy your cartridges.

The order template inheritance functionality may impact cartridges that were developed in earlier releases of Design Studio as follows:

  • Unintended inheritance

    A data element now inherits its significance value from its order contributor; for example, from a base order, an order component, or an order item specification. If you intended for a data element marked Inherited in significance to inherit its significance value from its data schema, you need to set this manually.

    To ensure the inheritance uses the significance value you intended, check all data elements and explicitly mark them as significant or not according to your design requirements.

  • Inheritance discrepancies due to multiple order template contributors

    In the case of multiple inheritance where a data element is inherited on the order template from multiple entities, the inherited data element must have the same significance value as is set for the OSM entity from which it is inherited. For example, the ControlData/Functions data structure can be inherited on the order template from these OSM entities: an extended order, an order component, and an order item. If the ControlData/Functions data structure is set with a different significance value in any of the contributing OSM entities (on the Order Template tab of those entities), Design Studio creates a problem marker. You cannot build and deploy the cartridge until the marker is resolved.

    Note:

    Design Studio creates problem markers only if the order contributors have different values and the order has the significance set to Inherited.

    To resolve problem markers, examine the relevant data elements and align the significance so that it is consistent across all order contributors. You can set the same significance value on all Order Component Specification editor Order Template tabs for all order components contributing to the order, or you can override the significance value of that data structure on the order by using the Order editor.

After you resolve design discrepancies that may exist, use OSM preferences to turn on order template inheritance of keys and significance.

To turn on order template inheritance of keys and significance for existing cartridges:

Tip:

Disallow this functionality temporarily to minimize the immediate upgrade impact on your cartridges, and allow it later for optimal development convenience.
  1. In Design Studio, from the Window menu, select Preferences, then select Oracle Design Studio, and then select Order and Service Management Preferences.

  2. In the Order Template Inheritance field, do the following:

    • To allow significance defined on an order template data element to be inherited from child orders and other order contributors, select Inherit significance from order contributors.

    • To allow keys defined on an order to be inherited from child orders and from other order contributors, select Inherit keys from order contributors.

    Design Studio sets the order template inheritance preferences you specify as a global preference.

  3. Click OK.

    Design Studio saves your order template inheritance preferences and closes the Preferences dialog box.

  4. Clean and build the cartridges.

  5. Resolve any problem markers that may result from order template inheritance discrepancies in your cartridges.

Creating the Common Data Dictionary Model Project in Your Workspace

In releases of Design Studio prior to 7.2, you were required to manually model order component control data. Starting with release 7.2, Design Studio automatically creates control data structures for order components if you create the OracleComms_OSM_CommonDataDictionary model project in your workspace.

The model project can co-exist with existing cartridge projects and will automatically generate order component control data for new order components you create after creating the model project in your existing workspace. In this case, Design Studio updates the order component control data structure you have defined in the data schema of your existing base project. However, Design Studio does not replace the reference of ControlData in the order templates to use the model project schema instead of your existing project schema.

Design Studio will prompt you to create the OracleComms_OSM_CommonDataDictionary cartridge the first time you create an entity related to orchestration. If you initially choose not to create the model project in your workspace to minimize the impact of your cartridge upgrade, upon seeing this prompt, select Do not show this prompt in the future. Later, when you are ready to create the model project in your workspace, re-enable the prompt and accept it.

To create the model project in your workspace:

  1. From the Window menu, select Preferences.

    The Preferences dialog box is displayed.

  2. In the Preferences navigation tree, expand Oracle Design Studio, and then expand Order and Service Management Preferences.

  3. Select Orchestration Preferences.

  4. In the Common Data Dictionary area, select the Prompt To Create Orchestration Data Dictionary check box.

  5. Click Apply.

  6. Click OK.

    Design Studio saves the preference and closes the Orchestration Preferences dialog box.

    The next time you open or create an orchestration entity, Design Studio prompts you to create the OracleComms_OSM_CommonDataDictionary model project in your workspace.

See Design Studio Help for information on how the OracleComms_OSM_CommonDataDictionary model project creates order component control data.

Upgrading Cartridges to Use Optimized Build-and-Deploy Mode

To use the Optimized build-and-deploy mode to build and deploy automation plug-ins in OSM 7.2.2, you must upgrade cartridges with versions prior to 7.0.3. For detailed information about the Optimized build-and-deploy mode, see the discussion on automation plug-in dispatch modes in OSM Developer's Guide.

Upgrade your cartridges to use the Optimized build-and-deploy mode as follows:

Note:

Automation plug-ins that are built and deployed using Design Studio can be run in Optimized mode. Existing plug-ins that were built outside of Design Studio, can only be run in Legacy mode.

Note:

To use the Optimized build-and-deploy mode, XML Catalog support must be enabled. Design Studio will generate an error for a cartridge if its target version is later than 7.0.2 and the XML Catalog is disabled. For more information about XML catalogs, see OSM Developer's Guide.

If some of your cartridges need to be deployed using the Legacy mode, set a build-and-deploy mode at the cartridge level by setting the BUILD_DEPLOY_MODE cartridge management variable. For more information about setting build-and-deploy modes at the cartridge level, see the topic on defining automation plug-in build-and-deploy modes in the Design Studio Modeling OSM Processes Help.

For information on how OSM processes automation plug-ins based on the build-and-deploy mode defined in the OSM automation plug-in and the dispatch mode defined on the OSM server, see the discussion on dispatch modes in OSM Developer's Guide.

Updating Cartridges to a Five-Digit Version

Starting with OSM 7.2, cartridges use five digits to specify their version. If you choose to change the target version of your cartridges, you must update the version format.

To change the Target Version for each cartridge to 7.2.2:

  1. In the cartridge editor Properties tab for each cartridge, change the value of Target Version from 7.0.3 to 7.2.0.

  2. Update the cartridge versions to 1.0.0.0.0 in the XML catalogs.

    1. Open the Package Explorer view.

    2. For each cartridge, open the catalog.xml file located in CartridgeName/xmlCatalogs/core.

    3. Select the Source tab.

    4. Each rewritePrefix attribute in the file includes the version 1.0.0. Change this version to 1.0.0.0.0.

  3. Set up the event views for the orders in the cartridge.

  4. Exit and restart Eclipse. If prompted to save any entities, select Yes.

  5. When Eclipse is restarted, the Studio Project Upgrade window is displayed with a list of cartridges that should be upgraded. Click Finish to upgrade the cartridges. This can take several minutes. When the upgrade is finished, you are presented with the option to view the upgrade logs if you wish.

  6. Build all of the cartridges. Some cartridge builds will fail with the following error listed in the Problems pane:

    Order and Service Management Cartridge Error - The automationBuild.xml file in cartridge CartridgeName is not the right version for this DS OSM plugin release. Right click on problem marker for the Quick Fix.
    

    For each cartridge that fails to build with this error:

    1. Right-click on the error in the Problems pane and select Quick Fix from the menu.

    2. Click Finish in the Quick Fix window and then click OK to confirm.

    3. Rebuild the project.

If some of your cartridges need to be deployed using the Legacy mode, set a build-and-deploy mode at the cartridge level by setting the BUILD_DEPLOY_MODE cartridge management variable. For more information about setting build-and-deploy modes at the cartridge level, see the topic on defining automation plug-in build-and-deploy modes in the Design Studio Modeling OSM Processes Help.

For information on how OSM processes automation plug-ins based on the build-and-deploy mode defined in the OSM automation plug-in and the dispatch mode defined on the OSM server, see the discussion on dispatch modes in OSM Developer's Guide.

Specifying Task Views for Order-Related Automation

Starting with OSM 7.2, you can use the Automation View field to specify the query view that the automation plug-in uses for Order, Event and Jeopardy notifications. One default query task is available per role. You can add roles and configure default query tasks in the Order editor Permissions tab. In addition to triggering automation plug-ins, order data changed event notifications can trigger one other type of notification. See the discussion on Defining Event Notifications in OSM Developer's Guide.

This does not apply to Automation Tasks because data available to the automation plug-in is explicitly defined as a Task View.

Configuring Order Lifecycle Policy Transition Error Messages

Starting with OSM 7.2 you can configure the error messages and severity levels logged when an Order Lifecycle Policy condition fails instead of the full XQuery code being logged. For more information see the discussion on the Order Lifecycle Policy Transition Conditions tab in the Design Studio Modeling OSM Processes Help.

When cartridges are migrated, each Order Lifecycle Policy condition is set with the default level of ERROR. The first 1000 characters of the condition expression are the initial error message. After migration, you should re-configure the error message and level and the condition name in Design Studio.

Modeling Order Components to Use Calculated Start Dates

Starting with OSM 7.2.2 you can model order components to use a calculated start date calculated by OSM. OSM derives the start date while balancing order item durations and dependencies and the order component requested delivery date.

This functionality depends on two data structures existing in the OSM common data dictionary: calculatedStartDate and duration.

See "Upgrading OSM to 7.2.2" for more information adding these data structures to the OSM common data dictionary.

After migrating a cartridge to version 7.2.2, you must set the cartridge target version to OSM version 7.2.2. If you set the target version to OSM version 7.2 or earlier, OSM does not calculate start dates for order components. Instead, order components begin processing as soon as possible, based on dependencies.

See OSM Concepts for guidelines about modeling order components to use calculated start dates.