12 Upgrading to OSM 7.3.5

Supported Upgrade Paths

You can upgrade to OSM 7.3.5 from any OSM 7.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 does 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), which are upgraded if the existing version is lower than the version to which you are upgrading.

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, you first 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.

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.3 OSM database schema, a new set of OSM 7.3 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 about 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.

About Installer Disk Space

The amount of disk space required when upgrading is often higher than the 600 MB recommended for a new installation, and depends on the amount of disk space that is being used by the existing system. Oracle recommends that you test the upgrade in a non-production environment to determine the space required for your database.

To reduce the amount of disk space when upgrading, ensure that you purge orphan data and unnecessary orders, and drop unnecessary partitions, in order to use as little data as possible. For information about purging data and dropping partitions, see the topic about managing the OSM database schema in OSM System Administrator's Guide.

About Execute Queues and Work Managers

Prior to OSM 7.2.4, the system prioritized work using execute queues. Execute queues have been replaced by work managers, which can be created and configured using WebLogic Server console. Running the installer removes the old execute queues and creates default work managers.

If you have custom execute queues running on your system, Oracle recommends that you remove them and create an equivalent work manager. For more information about creating and configuring work managers, see OSM System Administrator's Guide. For information about using work managers to optimize scheduled work, see Oracle Fusion Middleware Configuring Server Environments for Oracle WebLogic Server.

Preparing the Environment

To prepare the OSM environment:

1. Ensure that all transactions are committed and (if you are upgrading from a pre-7.2 version of OSM) all JMS messages are consumed.

2. Stop all of the processes running against OSM (including 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. Stop the OSM WebLogic application component oms.ear using the WebLogic console, and then delete the oms.ear file.

8. If you are upgrading from a version of OSM higher than 7.0, delete the OSM WebLogic Server application components (including oms.ear and cartridge_management_ws.ear) and any automation plug-in .ear files from WebLogic using the Administration 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.

9. 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.

10. 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:

• Upgrade the existing WebLogic domain. This option is supported for OSM 7.2.2 or later to OSM 7.3.5.

• Create a new WebLogic domain.

If you are upgrading an OSM release earlier than 7.2.2, you must create a new WebLogic domain.

Before you upgrade or create the WebLogic Server domain see the Fusion Middleware upgrade documentation and review the steps to:

• Upgrade custom security providers

• Upgrade Node Managers

• Upgrade WebLogic Domain

• Upgrade WebLogic Domain (remote managed servers)

Updating the WebLogic Domain

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

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

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

<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 a supported version for OSM 7.3.5 and import the OSM data. See "Software Requirements" for version details and information on required patches.

Refer to the Oracle Database documentation for information about upgrading Oracle Database Server and migrating data.

Updating Coherence Properties for Managed Servers

The coherence cluster property for non-OSM managed servers might all be set to the same default value, which creates a conflict in the environment.

If you are upgrading OSM in a non-clustered environment, you must update coherence properties from the default, after you upgrade the domain and before you run the installer.

To update coherence properties in a non-clustered environment:

1. Log in to the WebLogic Server Administration Console.

2. In the Domain Structure tree, expand Environment, and then click Servers.

   The Summary of Servers window is displayed.

3. Click Lock & Edit.

4. Do one or both of the following:

   • On the Coherence tab for each non-OSM managed server, set the Coherence Cluster property to None.

   • On the Coherence tab for the OSM managed server, set the Coherence Cluster Unicast Listen Port property to a unique port.

5. Click Save.

6. Click Release Configuration.

Upgrading the SDK Library Names

If you are upgrading to OSM 7.3.5 from a version prior to OSM 7.3.1, the installation includes changes to the names of some of the SDK library JAR files. If you have a custom implementation that has SDK library references in the classpath, you must change these references so that they use the new JAR file names.

Table 12-1 lists the old file names that you must replace with the new file names in classpath references.

Upgrading the Database Schema for OSM Versions 7.2.2.0.0 Through 7.2.2.3.4 Only

If you are upgrading to OSM 7.3.5 from OSM version 7.2.2.0.0 through OSM version 7.2.2.3.4, there is an extra procedure you have to follow. You must update the database schema to the one for OSM 7.2.2.3.5 before performing the full upgrade. If you are upgrading from any other version of OSM, you do not need to follow this procedure.

To upgrade the database schema for OSM versions 7.2.2.0.0 through 7.2.2.3.4:

1. Ensure the WebLogic Server domain is not running.

2. Download the OSM 7.2.2.3.5 patch from Oracle support. The patch number is 18422521.

3. Extract the installer from the patch file.

4. Run the installer. See "Installing OSM" for more information about running the installer.

5. Choose Custom Installation for the Setup Type when prompted.

6. When prompted to select the components to install, select only the Database Schema component.

   Selecting this option will cause the installer to migrate the database schema.

7. When prompted to enter database information, enter the information for your current OSM database.

8. When prompted to enter the database credentials, enter the user name and password for the current OSM core schema user and rule engine user.

9. In the Database Schema Found window, select Upgrade.

10. Continue with the installation of the database schema until the process is finished.

11. Perform the regular OSM upgrade to version 7.3.5. See "Performing the OSM Upgrade" for more information.

Upgrading the Database Schema for OSM Versions 7.2.2.3.12 and 7.2.2.3.13 Only

If you are upgrading to OSM 7.3.5 from OSM version 7.2.2.3.12 or OSM version 7.2.2.3.13, there is an extra procedure you have to follow. You must execute the following SQL statements on the OSM database schema before performing the full upgrade. If you are upgrading from any other version of OSM, you do not need to follow this procedure.

To upgrade the database schema for OSM versions 7.2.2.3.12 or 7.2.2.3.13:

1. Ensure the WebLogic Server domain is not running.

2. Log in to SQL*Plus using the credentials for the OSM core schema user.

3. Execute the following commands:

   update om_$install$version set same_as = '7.2.0.10.21' where object_name = 'om_jms_event';
   commit;
   

4. Log out of SQL*Plus.

5. Perform the regular OSM upgrade to version 7.3.5. See "Performing the OSM Upgrade" for more information.

Upgrading the Database Schema for OSM Version 7.2.0.10.0 Only

If you are upgrading to OSM 7.3.5 from OSM version 7.2.0.10.0, there is an extra procedure you have to follow. You must execute the following SQL statements on the OSM database schema before performing the full upgrade. If you are upgrading from any other version of OSM, you do not need to follow this procedure.

To upgrade the database schema for OSM version 7.2.0.10.0:

1. Ensure the WebLogic Server domain is not running.

2. Log in to SQL*Plus using the credentials for the OSM core schema user.

3. Execute the following commands:

   update om_$install$version set same_AS='7.2.2.1.35' where OBJECT_NAME='om_order_id_block';
   commit;
   

4. Log out of SQL*Plus.

5. Perform the regular OSM upgrade to version 7.3.5. See "Performing the OSM Upgrade" for more information.

Recovering from a Database Upgrade Failure

If an error occurs while the installer is upgrading the database schema, you can fix the error and rerun the installer. The installer then resumes the upgrade from the point of failure, which means you do not have to roll back the entire upgrade and start from the beginning.

For the procedure for upgrading OSM, see "Performing the OSM Upgrade."

When you run the installer, the installer generates and then stores an upgrade plan. When you re-run the installer after a failure, this plan is executed one action at a time. In general, each migration script and SQL statement that modifies the schema is a separate action and database transaction.

The following are the high-level steps in the process of recovering from a database upgrade failure. For information about handling an OSM database schema installation failure, see "Handling an OSM Database Schema Installation Failure."

1. Finding the Issue that Caused the Failure

2. Fixing the Issue that Caused the Failure

3. Restarting the Upgrade from the Point of Failure

Performing the OSM Upgrade

To upgrade OSM:

1. Start the WebLogic server in the new or upgraded WebLogic 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. Log in to SQL*Plus as sysdba and run the following:

   grant create any context to sysuser as sysdba with admin option
   

   where sysuser is a user with sysdba privileges that you intend to use during OSM installation.

4. Run the installer for OSM 7.3.5.

   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.

5. On the Component Selection screen, select the same components as were installed in your previous OSM installation. Ensure that the Database Schema is selected.

6. 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.

7. On the Database Analysis screen, click Upgrade.

8. 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.

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

10. 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 Application Clusters (Oracle 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.

11. If the domain is a new 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 19.

    • 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 18. You can configure Oracle RAC for failover or load balancing. Load balancing options are available only under the following circumstances:

    • If this is a multi-node cluster deployment.

    • If schema partitioning is selected.

12. Do one of the following:

    • Configure Oracle RAC by selecting one of the following options:

      • Configure WebLogic JDBC data sources to use additional RAC Database instances now.

        The installer preconfigures the database connections in WebLogic.

      • Configure WebLogic JDBC data sources manually after installation completes.

        You can add more Oracle RAC database instances manually after upgrading. See "Manually Configuring Additional Data Sources for an Oracle RAC Instance" for configuration details.

    • Deselect 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 other options described here. You cannot manually add and configure the Oracle RAC database instance.

13. Do one of the following:

    • If you chose to configure WebLogic JDBC data sources manually after installation or not to use Oracle RAC, click Next and go to step 18.

    • If you chose to use additional Oracle RAC Database instances now, continue selecting options on this screen as described in step 14.

14. Do the following:

    1. Under RAC operation mode, select one of the following options:

       • Load Balancing (Active Active) - Order and Service Management WebLogic Cluster Installations

         The Installer groups the WebLogic Server instances according to the number of Oracle RAC database instances. Each group is configured to a separate Oracle RAC database as the primary data source, and the remaining Oracle RAC database instances as secondary data sources. See "Connecting Oracle RAC with JDBC Multi Data Source" for more information.

         This option is available only if OSM is deployed to a WebLogic cluster.

       • Failover (Active Passive)

         The installer configures a multi data source and multiple data sources. The first data source connects to the primary database instance previously specified, and the subsequent data sources connect to other database instances to be specified. This option preconfigures the database connections in WebLogic for warm standby. See "Connecting Oracle RAC with JDBC Multi Data Source" and "Creating the Oracle Database for OSM" for more information.

    2. Under Listener Configuration, select one of the following options:

       • Remote Listener (Database Server-side load balancing)

       • Local Listeners

       See "Listener Considerations for Oracle RAC" for a discussion on listener functionality.

    3. Click Next.

15. If you did not previously specify the SID of the primary Oracle RAC instance, the installer displays an error message and takes you to the Database Connection Information screen to enter the SID (the host, port, and service name are protected). After entering the SID, installation resumes at the next step.

16. Do one of the following:

    • If you selected the remote listener option:

      1. In the SCAN Address field, you can modify the SCAN address if required.

      2. In the SCAN Port field, you can modify the SCAN port if required.

      3. Add a new row and specify the same Service Name as you did for the primary instance and a unique SID for each additional Oracle RAC instance. For a container database, use the PDB service name and the CDB SID.

      4. If you did not specify the SID of the primary Oracle RAC instance earlier in the upgrade, do so now in the first row. For a container database, use the CDB SID.

    • If you selected the local listeners option, add a new row for each additional Oracle RAC instance and specify:

      1. The host and port: Each row must use a different combination of host and port. For example, if you use the same host, you must use a different port.

      2. The service name or SID: Each row must specify either the same service name as the primary instance or a unique SID. Rows can also specify both service name and SID. Specify the same fields as you did for the primary instance. For example, if you only specified the SID for the primary instance, specify unique SIDs for the additional instances. For a container database, use the PDB service name and the CDB SID.

    All instances must be in the same database.

17. Click Next.

18. 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 domain, the screen will not be skipped and you can configure your JMS store information accordingly.

19. 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.

20. 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.3.5 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.

21. Reapply any oms-config.xml file customizations from the previous release. This file is located in the server startup directory, which is usually the home directory for the domain.

22. 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.

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

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

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

26. Shutdown and restart the WebLogic server in the new or upgraded domain.

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

28. Upgrade your cartridges. See "Upgrading Pre-7.3.5 Cartridges to OSM 7.3.5."

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 about how to do this.

XQuery Model Changes

The latest version of Saxon has a stricter approach to type checking. There are changes to how Saxon converts arguments and returns types to and from Java functions, so some XQuery functions that were written for earlier versions of Saxon might not work correctly.

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace ns1="http://www.metasolv.com/OMS/OrderModel/2002/06/25";

declare namespace mapUtil = "java:java.util.Map";
 
declare variable $mvmap external;
 
declare variable $mvkey as xs:string* external;
 
<model:modelVariable name="{/ns1:model/ns1:cartridge/@namespace}" namespace="SystemDefinedNamespace" xmlns:model="http://xmlns.oracle.com/communications/ordermanagement/model">
  <model:description>model variable</model:description>        
  {
    for $i in ($mvkey)
     let $r := mapUtil:get($mvmap,$i)
    return 
      <model:entry name="{$i}"  >
        <model:value>{$r}</model:value>
      </model:entry>          
   }     
</model:modelVariable>

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace ns1="http://www.metasolv.com/OMS/OrderModel/2002/06/25";
 
declare namespace jt="http://saxon.sf.net/java-type"; 
declare namespace mapUtil = "java:java.util.Map";
declare variable $mvmap as jt:java.util.Map external;
 
declare variable $mvkey as xs:string* external;
 
<model:modelVariable name="{/ns1:model/ns1:cartridge/@namespace}" namespace="SystemDefinedNamespace" xmlns:model="http://xmlns.oracle.com/communications/ordermanagement/model">
  <model:description>model variable</model:description>        
  {
    for $i in ($mvkey)
     let $r := mapUtil:get($mvmap,$i)
    return 
      <model:entry name="{$i}"  >
        <model:value>{$r}</model:value>
      </model:entry>          
   }     
</model:modelVariable>

declare function local:getAttachedProvOrderEBM() as element()*
{
   let $names := context:getAllAttachmentFileNames($context) 
   return
      if (fn:exists($names)) then
      (
          let$name := iterator:next(collection:iterator($names))
          return
              if (fn:exists($name)) then
              (
                  saxon:parse(saxon:base64Binary-to-string(saxon:octets-to-
              )
              else ()
      )
      else ()
};

declare function local:getAttachedProvOrderEBM() as element()*
{
   let $names := context:getAllAttachmentFileNames($context) 
   return
      if (fn:exists($names)) then
      (
          let$name := [1]($names))
          return
              if (fn:exists($name)) then
              (
                  saxon:parse(saxon:base64Binary-to-string(saxon:octets-to-
              )
              else ()
      )
      else ()
};

saxon:parse(xs:string(javaString:valueOf(context:getAttachment($context, xs:string($name)))))/provord:ProcessProvisioningOrderEBM

saxon:parse(xs:string(javaString:valueOf(context:getAttachmentAsString($context, xs:string($name)))))/provord:ProcessProvisioningOrderEBM

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-Oracle-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.

Additional Configuration for JMS Service Migration

For upgrading OSM instances in a clustered environment that make use of JMS service migration, you must perform the following procedure:

1. Log in to the WebLogic Server Administration Console.

   The Administration Console is displayed.

2. From the Domain Structure, click Services, then Messaging, then JMS Modules.

   The Summary of JMS Modules screen is displayed.

3. Click oms_jms_modules.

   The Settings for oms_jms_module screen is displayed.

4. For each instance of the oms_cartridge_deploy_managed_server queue (where managed_server is one of the managed servers in the cluster) do the following:

   1. Click oms_cartridge_deploy_managed_server.

      The Settings for oms_cartridge_deploy_managed_server screen is displayed.

   2. Click the Configuration tab then the General subtab.

   3. From the Templates list, select None.

   4. Click Save.

   5. Click the Subdeployment tab.

   6. From the Subdeployment list, select the omsJmsNonMigratableServer_managed_server that corresponds to the same managed server that appears in the oms_cartridge_deploy_managed_server queue name.

      For example, oms_cartridge_deploy_OSMServer1 should use the osmJmsNonMigratableServer_OSMServer1 subdeployment.

   7. Click Save.

   8. Click the Configuration tab then the General subtab.

   9. From the Template list, select omsJmsNonMigratableTemplate_managed_server. that corresponds to the same managed server that appears in the oms_cartridge_deploy_managed_server queue name.

      For example, oms_cartridge_deploy_OSMServer1 should use the omsJmsNonMigratableTemplate_OSMServer1 template.

   10. Click Save.

   11. Restart the managed server that the oms_cartridge_deploy_managed_server queue is associated with.

5. After you restart each managed server, log in to the OSM Order Management web client.

6. Click Refresh Cache.

   The Confirm Metadata Refresh dialog box appears.

7. Click Yes.

Configuring Attachment Location for Whole Server Migration

As of OSM 7.3.0, attachments are stored in the OSM database instead of the T3 file stores. However, if there are unprocessed orders that contain attachments from before the upgrade, those attachments continue to use the T3 file stores until the orders complete. You may need to move the location of this T3 file store to support whole server migration.

To configure the T3 file path:

1. Configure a shared directory accessible to each machine in the cluster. For example, you can use the same directory that you configured in "Configure Managed Servers for Whole Server Migration" or create a new directory in the same path.

   For example:

   /mnt/shares/oracle/cluster/attachments/
   

2. Log in to the WebLogic Server Administration Console.

   The WebLogic Administration Console is displayed.

3. Click Lock & Edit.

4. In Domain Structure, select Services, then File T3.

   The Summary of File (T3) Services appears.

5. Click Oms_Remote_file_system.

6. Click the Configuration Tab.

7. In the Path field, replace Attachments with a link to the shared directory.

8. Click Save.

9. Click the Targets tab.

10. Select the cluster name.

11. Select All servers in the cluster.

12. Click Save.

13. Click Activate Changes.

Cartridge Upgrade Prerequisites

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

• OSM is upgraded to 7.3.5 using the OSM installer.

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

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

• The Oracle WebLogic Server domain for OSM 7.3.5 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.3.5 cartridges to OSM 7.3.5:

1. Set global default Java preferences.

   In Design Studio, from the Window menu, select Preferences. Then expand Java and do the following:

   1. Select Installed JREs and check the box next to the Java 8 JRE you are using.

   2. Expand Installed JREs, select Execution Environments, select JavaSE-1.8 from the Execution Environments list, and select the newly installed JRE from the Compatible JREs list.

   3. Select Compiler and set the Compiler Compliance Level to 1.8.

2. Set global default OSM preferences.

   In Design Studio, from the Window menu, select Preferences. Then expand Oracle Design Studio and select Order and Service Management Preferences. Set the following values:

   • OSM SDK Home: Specify the local installation directory for the 7.3.5 OSM SDK.

     Note:

     If you have customized your build path, ensure that your environment is looking for automation.jar in the OSM_home/SDK/Automation/automationdeploy_bin directory.

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

3. Set cartridges to use the correct build path.

   For each cartridge, do the following:

   1. In the Studio Projects view, right-click on the cartridge and select Properties.

   2. Select Java Build Path and click the Libraries tab.

   3. Select the JRE System Library from the list and click Edit.

   4. Select Execution Environment and select the option that begins JavaSE-1.8 and references the location where you installed Java 8.

   5. Click OK.

   6. If automation_plugins.jar is present in the list on the Libraries tab, select it and click Migrate JAR File. Select the automation_plugins.jar file in the OSM_home/SDK/Automation/automationdeploy_bin directory.

   7. Click Finish.

   8. Click OK in the Properties window.

4. Set cartridge management variables.

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

   • Set FAST_CARTRIDGE_UNDEPLOY to true to undeploy a cartridge from OSM without purging cartridge metadata or order data, or set it to false to purge cartridge metadata and order data during the undeploy operation.

   • 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. If PURGE_CARTRIDGE_BEFORE_DEPLOY and FAST_CARTRIDGE_UNDEPLOY are set to true, the cartridge is undeployed using the fast undeploy functionality before it is redeployed. This redeploy method is referred to as a "fast redeploy."

     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. If both PURGE_ORDER_ON_UNDEPLOY and FAST_CARTRIDGE_UNDEPLOY are set to true, the operation uses the forced fast undeploy option, which quits open orders; neither the cartridge nor the associated orders are purged. If PURGE_ORDER_ON_UNDEPLOY is set to true and FAST_CARTRIDGE_UNDEPLOY is set to false, the operation uses the forced undeploy option, which purges the cartridge and associated orders.

     Caution:

     Undeploying a cartridge purges all existing orders for that cartridge.

5. In Design Studio, in the customAutomation directory of your cartridge workspace, replace automationMap.xsd with the latest version from the OSM_home/SDK/Automation/automationdeploy_bin directory. 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.

6. 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.3.5. If there are pending Order-to-Activate orders in your OSM instance, skip this step.

   For each cartridge in your workspace, in the Project editor Properties tab set the target version to 7.3.5 and update the version number if your cartridge is not using five-digit version numbers. See "Updating Cartridges to a Five-Digit Version."

7. 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:

   • "Automation Build Error - CartridgeName has an automation build file (automationBuild.xml). Automation build files are not supported for target version 7.3.5.".

     After fixing the problem, the automationBuild.xml file is removed from the src directory of the cartridge.

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

     After fixing the problem, Design Studio upgrades the OracleComms_OSM_CommonDataDictionary model project to the current version for 7.3.5 and 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)

   This step will automatically update the OracleComms_OSM_CommonDataDictionary, as mentioned previously in this step. You can also update the OracleComms_OSM_CommonDataDictionary manually. See "Updating the Common Data Dictionary Manually" for more information.

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

   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".

9. 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.

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

11. Redeploy all cartridges to the OSM 7.3.5 run-time environment.

Updating the Common Data Dictionary Manually

If you follow the procedures in "Upgrading Pre-7.3.5 Cartridges to OSM 7.3.5," it should not be necessary to update the OracleComms_OSM_CommonDataDictionary manually.

Many releases of OSM, including OSM 7.3.5, contain additions that have been made to the OracleComms_OSM_CommonDataDictionary.

Oracle recommends that you update the data dictionary whenever you upgrade Design Studio. However, if you do not plan to use the new OSM features, it is not mandatory to update it.

All changes made to the common data dictionary are additive and fully backward-compatible. If you decide not to update the data dictionary at the time you update your cartridges, and later you make any changes to your solution that require the updated common data dictionary, you can also update the common data dictionary using the Quick Fix option on the problem marker that informs you that a needed data element is not defined. If you prefer, you can update it using the manual procedure in this section.

To update the common data dictionary manually:

1. In Design Studio, from the Project menu, deselect Build Automatically.

2. In the Studio Projects view, right-click on the OracleComms_OSM_CommonDataDictionary project and select Delete.

3. In the confirmation dialog box, select Also delete contents... and click Yes.

4. Create the common data dictionary in your workspace. See "Creating the Common Data Dictionary Project in Your Workspace" for instructions.

5. Clean and build all cartridges in the workspace.

6. If desired, from the Project menu, select Build Automatically.

Upgrading Service Actions with Explicit Data Elements

Starting with Design Studio 7.3.4, if you have a Service Action with explicit data elements (data elements that are not grayed out in the Action editor Data Elements tab), those data elements will only be available in the mapping rule editor if the action has at least one action code and the explicit data elements are each assigned a data direction. (A Service Action is an action with an Action Type of Service in the Action editor Properties tab.) To add an action code to an Action:

1. In your Design Studio workspace, open the editor for the Action.

2. In the Action Codes tab, click Add.

3. In the resulting window, click Select.

4. Select an action code from the list and click OK.

5. Click OK again to add the action code.

To assign a data direction for a data element:

1. In your Design Studio workspace, open the editor for the Action.

2. In the Data Map tab, click the field corresponding to the action code you have added and data element that you would like to have available in the mapping rule.

3. Select a direction (for example Optional In) for the data element.

4. Repeat steps 2 and 3 for each data element you would like to use in the mapping rule editor.

After you have made the changes above, you should save your Action and perform a clean build of your cartridges.

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.3.5" for more information adding these data structures to the OSM common data dictionary.

After migrating a cartridge to version 7.3.5, you must set the cartridge target version to OSM version 7.3.5. 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 Modeling Guide for guidelines about modeling order components to use calculated start dates.

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 must 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:

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 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 common data dictionary project can coexist 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 or open an entity related to orchestration in a workspace using Design Studio 7.2 or later where the common data dictionary is not present.

If in the past you have seen this prompt and selected Do not show this prompt in the future, you must re-enable the prompt in order to create the common data dictionary.

To create the common data dictionary in your workspace:

1. If you have previously disabled the prompt:

   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 OK.

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

2. Open or create an orchestration entity, for example, an order item specification or an order component specification.

   You are prompted to confirm importing the common data dictionary.

3. Click OK.

   The OracleComms_OSM_CommonDataDictionary model project is created in your workspace.

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

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 update cartridges to use a five-digit version number:

1. In the Project editor Properties tab for each cartridge, change the value of Target Version from the current value (7.0.3 or earlier) to 7.3.5.

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:

   Automation Build Error - {Cartridge Name} has an automation build file (automationBuild.xml). Automation build files are not supported for target version 7.3.5. 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.

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 Modeling Guide for more information.

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 Data Entries Above the 1000-Character Limit

Starting with Design Studio 3.1.4 (compatible with OSM versions up to 7.0.3), Design Studio generates an error message to prevent creation of data entries above 1000 characters. In previous versions of Design Studio, you could create unbounded data dictionary entries (up to 9999 characters) in OSM cartridges and deploy the cartridges to OSM servers (up to OSM release 7.0.3). These OSM cartridge data entries were persisted in the OSM database as metadata that OSM used for creating run-time entities associated with orders.

However, the OSM database has always had a data entry limit of 1000 characters. Cartridges deployed with unbounded data entries using Design Studio 3.1.3 to an OSM 7.0.3 server would generate no errors, but at run time, if an order was submitted with a data entry of more than 1000 characters, the order processing would fail. This failure was caused by the OSM database data entry limit which does not normally support unbounded lengths greater than 1000 characters.

Following is an example of the Design Studio error messages generated in this situation:

Data Dictionary Model Error – Max length of the Data Element Bandwidth backing the Order Template node/adsl_service_details/bandwidth exceeds 1000.

You must resolve this error before you can deploy the OSM cartridge.

If there is a requirement for data entries that contain more than 1000 characters, OSM provides other ways to achieve this goal including:

• Modeling data dictionary entries as XML type so that the data entry can contain XML documents.

• Adding order remarks

• Adding attachments to order remarks

See OSM Modeling Guide for more information about these alternatives.