This chapter describes how to upgrade Oracle Communications Order and Service Management (OSM) to version 7.3.1.
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 Oracle WebLogic Server core software (if applicable)
Upgrade or create a new WebLogic domain (if applicable)
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 and redeploy cartridges to the OSM 7.3.1 server
For current version and patch information, see "OSM System Requirements."
Note:
If you are upgrading from OSM 7.3.0 to OSM 7.3.1, you do not need to upgrade the database or WebLogic Server, as the versions are the same.You can upgrade to OSM 7.3.1 from any OSM 7.x release.
Note:
If you are upgrading OSM using a patch from My Oracle Support, you must read the patch Readme text and the contents of this chapter. In some cases the patch Readme may provide specific instructions that supersede those instructions included in this chapter.Note:
If you upgrade to Order and Service Management 7.x from a prior version of OSM and your cartridges were developed with OSM Administrator tool, Oracle recommends that you migrate your cartridges into Oracle Communications Design Studio. Use Design Studio as the tool to design and deploy OSM 7.x cartridges. The recommended migration procedure, common migration issues, and issue resolutions are documented in release 7.3.2 Design Studio Order and Service Management Cartridge Migration Guide, which is available in the Oracle Help Center: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.
The procedures in this section should be performed only by a qualified database administrator.
If you are upgrading from OSM 7.3 to 7.3.1, you do not need to upgrade the database. 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.
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.
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.
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, make sure to 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.
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.
The following sections describe how to prepare the OSM environment for an OSM upgrade.
To prepare the OSM environment:
Ensure that all transactions are committed and (if you are upgrading from a pre-7.2 version of OSM) all JMS messages are consumed.
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.
Stop the WebLogic Server.
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.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.
Start the WebLogic server.
Stop the OSM WebLogic application component oms.ear using the WebLogic console, and then delete the oms.ear file.
If you are upgrading from a version of OSM higher than 7.0, delete the oms.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. Do not delete cartridge_management_ws.ear either from the deployments in the Administration Console or from the file system.
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.
Stop the WebLogic Server.
The following sections describe the steps to prepare the WebLogic domain for an OSM upgrade. You can:
Skip this step. This is supported for OSM 7.3 to OSM 7.3.1.
Upgrade the existing WebLogic domain. This option is supported for OSM 7.2.2 or OSM 7.2.4 to OSM 7.3.1.
Create a new WebLogic domain.
If you are upgrading an OSM release earlier than 7.2.2, you must create a new WebLogic domain for 12c.
Before you upgrade or create the WebLogic Server domain see Oracle Fusion Middleware Upgrade Guide for Oracle WebLogic Server 12c (12.1.3) and review the steps to:
Upgrade custom security providers
Upgrade Node Managers
Upgrade WebLogic Domain
Upgrade WebLogic Domain (remote managed servers)
The high-level steps for upgrading an OSM 7.2.2 or 7.2.4 WebLogic Domain to Oracle Fusion Middleware 12.1.3 are the following:
Note:
For more detailed instructions, follow the procedure that matches the upgrade for your domain in Oracle Fusion Middleware Upgrading to the Oracle Fusion Middleware Infrastructure.Install the recommended JDK and required third-party software. For more information, see "OSM System Requirements."
Download and Install WebLogic Server Software and ADF 12.1.3. For more information, see "Installing and Configuring the WebLogic Server Cluster."
Prepare the security store. The following steps use a basic OSM domain as an example:
Download the RCU version 11g from Oracle support as patch 16471709.
Run RCU version 11g to create only the OPSS schema (assuming the domain has only OPSS information to be upgraded).
Create a Data Source Instance pointing to the OPSS schema.
The JNDI name of the JDBC data source entered in the procedure will be used in the next step.
Re-associate the file-based security store to a database-based security store by using the WLST command reassociateSecurityStore
.
Run the WLST command by using the wlst.cmd (for Windows) or wlst.sh (for UNIX and Linux) command in the MW_home/oracle_common/common/bin directory. For example:
reassociateSecurityStore(domain=BEA, servertype=DB_ORACLE, jpsroot=cn=jpsroot, datasourcename=jdbc/OpssDataSource)
where BEA is your domain name, and jdbc/OpssDataSource is the JNDI name of the JDBC data source that you created in step c.
Note:
Ensure you have followed the steps in "Preparing the Environment" and that you have stopped and deleted the oms.ear file. Deleting the oms.ear file prevents the previous oms application from running in the new upgraded domain.Stop all WebLogic servers and processes.
For more information, see Oracle Fusion Middleware Upgrading to the Oracle Fusion Middleware Infrastructure.
Upgrade the security store by doing the following:
Go to the MW_home(12c)/oracle_common/upgrade/bin directory and run Oracle Fusion Middleware Upgrade Assistant by using the following command:
ua.sh/cmd
Select Schemas.
In the Available Components page, make sure you select Oracle Platform Security Services in order to upgrade the OPSS schema.
For more information, see Oracle Fusion Middleware Upgrading to the Oracle Fusion Middleware Infrastructure.
Use RCU version 12c to create the remaining (not including OPSS) database schemas that will be used by the domain. For more information, see "Creating Database Schemas Using RCU."
After the schemas are upgraded, reconfigure the domain by doing the following:
Go to the MW_home(12c)/oracle_common/upgrade/bin directory and run the Reconfiguration Wizard by using the following command:
reconfig.sh/cmd
In the Advanced Configuration step, select Deployments and Services.
Note:
In the Deployments Targeting Screen, ensure all (required) libs and applications are targeted to the OSM cluster but changes are not required for other servers. In the Service Targeting Screen, besides the OSM data-source to OSM cluster/server, ensure that all non-OSM data sources that are used by the domain are deployed into the Administration server, OSM cluster/server and proxy server.For more information, see Oracle Fusion Middleware Upgrading to the Oracle Fusion Middleware Infrastructure.
Upgrade component configurations by doing the following: For more information, see Oracle Fusion Middleware Upgrading to the Oracle Fusion Middleware Infrastructure.
Go to the MW_home(12c)/oracle_common/upgrade/bin directory and run Oracle Fusion Middleware Upgrade Assistant by using the following command:
ua.sh/cmd
Select WebLogic Component Configurations.
After the Upgrade Assistant successfully completes the WebLogic component configurations operation, start the servers and verify in WebLogic Console that all the relevant servers, applications, and libraries are upgraded to 12c. For information about packing and unpacking the upgraded domain to distribute to other machines in a clustered environment, see "Replicating the Domain on Other Machines."
For more information, see Oracle Fusion Middleware Upgrading to the Oracle Fusion Middleware Infrastructure.
Note:
After the domain upgrade finishes, and before you install OSM 7.3.1, you must use WebLogic Console to go to JMS Connection Factories (for example, oms_connection_factory) to ensure that the Default Targeting Enabled check box is not selected. If it is selected, de-select it and then re-start the servers, if necessary.To create a new WebLogic 12.1.3 domain with ADF 12.1.3:
Note:
You must create a new WebLogic 12.1.3 domain with ADF 12.1.3 if you are upgrading from OSM 7.0.x. Review the existing hardware and ensure it is supported by OSM 7.3.1, otherwise you must upgrade to supported hardware. For more information, see "General Hardware Sizing and Configuration Recommendations."Install the recommended JDK version. See "Software Requirements" for details on the recommended version.
Install Oracle Fusion Middleware Infrastructure 12.1.3 which includes Oracle WebLogic Server 12.1.3 and ADF 12.1.3. See "Software Requirements."
Apply any required Oracle WebLogic Server and ADF patches. See "Software Requirements" for details.
Create a new 12.1.3 domain. Use the same domain name as the existing domain. When creating the new 12.1.3 domain, Oracle recommends that you select Oracle Enterprise Manager template, in order to view and manage OSM logs. Also, you must select Oracle JRF. This is required for OSM as it makes use of ADF. See "Installing and Configuring the WebLogic Server Cluster."
Note:
When you select the Oracle JRF template, the template for WebLogic Coherence Cluster Extension is also selected. Do not deselect the coherence cluster extension template option.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 12.1.3 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 and Configuring the WebLogic Server Cluster" for information about installing OSM in a clustered environment in this guide.
The following section describes WebLogic domain updates that may be required.
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>
If you are currently running on an 11gR1 database, export the OSM data, upgrade the database to 12c (12.1.3) 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 from version 11gR1 to 11gR2 and how to migrate data.
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:
Log in to the WebLogic Server Administration Console.
In the Domain Structure tree, expand Environment, and then click Servers.
The Summary of Servers window is displayed.
Click Lock & Edit.
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.
Click Save.
Click Release Configuration.
The OSM 7.3.1 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 need to change these references so that they use the new JAR file names.
Table 12-1 lists the old file names that you need to replace with the new file names in classpath references.
Table 12-1 SDK Third-Party Library JAR File Names
Old File Name | New File Name |
---|---|
commons-codec-1.9.jar |
commons-codec.jar |
commons-collections4-4.0.jar |
commons-collections4.jar |
commons-io-2.4.jar |
commons-io.jar |
commons-lang-3.3.1.jar or commons-lang3-3.3.2.jar |
commons-lang3.jar |
commons-logging-1.1.1.jar |
commons-logging.jar |
commons-net-3.3.jar |
commons-net.jar |
commons-pool2-2.2.jar |
commons-pool2.jar |
commons-vfs2-2.0.jar |
commons-vfs2.jar |
httpclient-4.1.2.jar or httpclient-4.3.5.jar |
httpclient.jar |
httpcore-4.3.2.jar |
httpcore.jar |
jaxen-1.1.3.jar or jaxen-1.1.6.jar |
jaxen.jar |
ojdbc6.jar |
ojdbc7.jar |
resolver.jar |
xml-resolver.jar |
saxon9-dom.jar or saxon-license.lic |
saxon-ee-java-osm-license.jar |
saxon9-xpath.jar saxon9.jar saxon9ee.jar |
saxon-ee-java.jar |
text-table-formatter-1.1.1.jar |
texttablefmt.jar |
xschema.jar |
[no longer needed as a separate library, now part of xmlparserv2.jar] |
This procedure describes how to upgrade OSM to version 7.3.1.
Caution:
Before upgrading, refer to "About OSM Upgrades" for important preparation steps.If you are upgrading to OSM 7.3.1 from OSM version 7.2.2.0 through OSM version 7.2.2.3, there is an extra procedure you have to follow. You need to 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.
Note:
Make sure that you read the patch Readme text for any additional instructions that either augment or supersede the information provided in this section.To upgrade the database schema for OSM versions 7.2.2.0 through 7.2.2.3:
Ensure the Weblogic Server domain is not running.
Download the OSM 7.2.2.3.5 patch from Oracle support. The patch number is 18422521.
Extract the installer from the patch file.
Run the installer. See "Installing OSM" for more information about running the installer.
Choose Custom Installation for the Setup Type when prompted.
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.
When prompted to enter database information, enter the information for your current OSM database.
When prompted to enter the database credentials, enter the user name and password for the current OSM core schema user and rule engine user.
In the Database Schema Found window, select Upgrade.
Continue with the installation of the database schema until the process is finished.
Perform the regular OSM upgrade to version 7.3.1. See "Performing the OSM Upgrade" for more information.
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."
When the installer fails during an installation or upgrade, you receive an error message. Before you continue with the installation or upgrade, you must find and resolve the issue that caused the failure. There are several places where you can look to find information about the issue.
The database installation plan action spreadsheet is a file that contains a summary of all the installation actions that are part of this OSM database schema installation or upgrade. The actions are listed in the order that they are performed. The spreadsheet includes actions that have not yet been completed. To find the action that caused the failure, go to the OSM_home/Database/osm-db-installer-core/install/om_$install$plan_actions.csv file and review the status column. The failed action is the first action with a status that is FAILED. The error_message column of that row contains the reason for the failure.
The database installation log file gives a more detailed description of all the installation actions that have been run for this installation. The issue that caused the failure is located in the OSM_home/Database/osm-db-installer-core/install/dbInstaller.log file. The failed action is typically at the bottom, that is, the last action that was performed.
There are also the following database tables that contain information about the database installation:
om_$install$plan_actions: Contains the same information as the database plan action spreadsheet. Compare this table to the spreadsheet in cases of a database connection failure.
om_$install$plan: Contains a summary of the installation and any upgrades that have been performed on this OSM database schema.
Use the information in the log or error messages to fix the issue before you restart the upgrade process. For information about troubleshooting log or error messages, see OSM System Administrator's Guide.
In most cases, restarting the upgrade consists of pointing the installer to the schema that was partially upgraded, and then rerunning the installer.
Keep the following in mind when preparing to restart an upgrade:
Most migration actions are a single transaction, which is rolled back in the event of failure. However, some migration actions involve multiple transactions. In this case, it is possible that some changes were committed.
Most migration actions are repeatable, which means that they can safely be re-run even if they were committed. However, if a failed action is not repeatable and it committed some changes, either reverse all the changes that were committed and set the status to FAILED, or complete the remaining changes and set the status to COMPLETE.
To restart the upgrade after a failure:
Determine which action failed and why by using the information in "Fixing the Issue that Caused the Failure."
If the status for the failed action is STARTED, check the database to see whether the action is finished or still in progress.
If the failed action is still in progress, either end the session or wait for the action to finish (roll back).
Note:
The transaction might not finish immediately after the connection is lost, depending on how fast the database detects that the connection is lost and how long it takes to roll back.Fix the issue that caused the failure.
Note:
If the failure is caused by a software issue, contact Oracle Support. With the help of Oracle Support, determine whether the failed action modified the schema and whether you need to undo any of those changes.If you decide to undo any changes, leave the action status set to FAILED or set it to NOT STARTED. When you retry the upgrade, the installer starts from this action. If you manually complete the action, set its status to COMPLETE, so that the installer starts with the next action. Do not leave the status set to STARTED because the next attempt to upgrade will not be successful.
Restart the upgrade by running the installer.
The installer restarts the upgrade from the point of failure.
To upgrade OSM:
If you are using an existing WebLogic domain (for example, because you are upgrading from OSM 7.3.0), rename the oms-config.xml file from the old installation. This file is located in the server startup directory, which is usually the home directory for the domain.
Start the WebLogic server in the new or upgraded WebLogic 12.1.3 domain. If this is a clustered environment, start the administration, managed, and proxy servers.
Verify that any WebLogic patches you installed are displayed in the WebLogic log.
Log in to SQL*PLUS as sysdba and run the following:
grant create any context to sys as sysdba with admin option
Run the installer for OSM 7.3.1.
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.On the Component Selection screen, select the same components as were installed in your previous OSM installation. Ensure that the Database Schema is selected.
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.
On the Database Analysis screen, click Upgrade.
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.
On the WebLogic Configuration - Configuration Type screen, select Connect to a running WebLogic server.
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.
If the domain is a new 12.1.3 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 20.
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 19. 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.
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.Do one of the following:
Do the following:
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.
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.
Click Next.
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.
Do one of the following:
If you selected the remote listener option:
In the SCAN Address field, you can modify the SCAN address if required.
In the SCAN Port field, you can modify the SCAN port if required.
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.
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:
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.
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.
Click Next.
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 12.1.3 domain, the screen will not be skipped and you can configure your JMS store information accordingly.
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.
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.1 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.
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.
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.
Reapply customizations to views, tables, triggers, or other entities stored in the OSM database schema.
Reapply or rewrite any custom reports if schema changes were made to the newer database.
If a new WebLogic domain was created, copy the contents of the Attachments folder from the old WebLogic domain to the newly created WebLogic 12.1.3 domain. Ensure that the file permissions allow the OSM application to read and write the files copied to the new domain.
Shutdown and restart the WebLogic 12.1.3 server.
Refer to Design Studio Installation Guide for any required upgrade actions for Design Studio.
Upgrade your cartridges. See "Upgrading Pre-7.3.1 Cartridges to OSM 7.3.1."
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.
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.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.
XPath 2.0 introduced Map as an internal data type. If a variable of type java.util.Map
is not explicitly typed, Saxon casts the variable to the native XPath Map type. The solution is to explicitly bind any java.util.Map
variables to the Java namespace. For example,
Before:
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>
After:
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>
If a Java function returns a collection or array, Saxon converts this to an XPath sequence. The return object can no longer be passed to a java.util.Iterator
. The latest version of Saxon makes it easier to deal with collections. Instead of using a Java iterator, you can use the XPath sequence. For example,
Before:
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 ()
};
After:
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 ()
};
There are extensive changes to how overloaded methods are chosen. In most cases, these changes are transparent. But in the case of overloaded methods with the same number of arguments, if the supplied argument has an ambiguous type, Saxon is unable to resolve the method to invoke, for example, Invoking java.lang.String.valueOf() with a byte[]. The solution in these cases is to cast the argument to a proper Java type. For example,
Before:
saxon:parse(xs:string(javaString:valueOf(context:getAttachment($context, xs:string($name)))))/provord:ProcessProvisioningOrderEBM
After:
saxon:parse(xs:string(javaString:valueOf(context:getAttachmentAsString($context, xs:string($name)))))/provord:ProcessProvisioningOrderEBM
If a Java method returns null, the XPath value is an empty sequence. If the XQuery script does not correctly handle empty sequences, an XPath exception is thrown. You must ensure in the XQuery that invocations of Java functions that can return null are properly handled to check for empty sequences.
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.
To perform an active-passive to active-active conversion, you must run the installer twice. This type of conversion is allowed only if the schema is partitioned. Perform the following steps:
Shut down all managed servers in the OSM cluster.
Run the installer to downgrade from an Oracle RAC active-passive configuration to a non-Oracle-RAC configuration. Only the screens that are relevant to the conversion are listed here.
On the Component Selection screen, select Server and click Next.
On the Database Configuration Comparison screen, select Replace the existing JDBC data source configuration with the new connection information and click Next.
On the Oracle Real Application Clusters (Oracle RAC) screen, select Do not use Oracle RAC and click Next.
Run the installer to upgrade from a non-Oracle-RAC configuration to an Oracle RAC active-active configuration.
On the Component Selection screen, select Server and click Next.
On the Database Configuration Comparison screen, select Replace the existing JDBC data source configuration with the new connection information and click Next.
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.
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.
To perform an active-active to active-passive conversion, you must run the installer twice. Perform the following steps:
Shut down all managed servers in the OSM cluster.
Run the installer to downgrade from an Oracle RAC active-active configuration to a non-Oracle-RAC configuration. Only the screens that are relevant to the conversion are listed here.
On the Component Selection screen, select Server and click Next.
On the Database Configuration Comparison screen, select Replace the existing JDBC data source configuration with the new connection information and click Next.
On the Oracle Real Application Clusters (Oracle RAC) screen, select Do not use Oracle RAC and click Next.
Run the installer to upgrade from a non-Oracle-RAC configuration to an Oracle RAC active-passive configuration.
On the Component Selection screen, select Server and click Next.
On the Database Configuration Comparison screen, select Replace the existing JDBC data source configuration with the new connection information and click Next.
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.
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.
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.
For upgrading OSM instances in a clustered environment that make use of JMS service migration, you must perform the following procedure:
Log in to the WebLogic Server Administration Console.
The Administration Console is displayed.
From the Domain Structure, click Services, then Messaging, then JMS Modules.
The Summary of JMS Modules screen is displayed.
Click oms_jms_modules.
The Settings for oms_jms_module screen is displayed.
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:
Click oms_cartridge_deploy_managed_server.
The Settings for oms_cartridge_deploy_managed_server screen is displayed.
Click the Configuration tab then the General subtab.
From the Templates list, select None.
Click Save.
Click the Subdeployment tab.
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.
Click Save.
Click the Configuration tab then the General subtab.
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.
Click Save.
Restart the managed server that the oms_cartridge_deploy_managed_server queue is associated with.
After you restart each managed server, log in to the OSM Order Management web client.
Click Refresh Cache.
The Confirm Metadata Refresh dialog box appears.
Click Yes.
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:
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/
Log in to the WebLogic Server Administration Console.
The WebLogic Administration Console is displayed.
Click Lock & Edit.
In Domain Structure, select Services, then File T3.
The Summary of File (T3) Services appears.
Click Oms_Remote_file_system.
Click the Configuration Tab.
In the Path field, replace Attachments with a link to the shared directory.
Click Save.
Click the Targets tab.
Select the cluster name.
Select All servers in the cluster.
Click Save.
Click Activate Changes.
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 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.
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.3.1" for more information about running the OSM installer.
After you have upgraded your OSM system to version 7.3.1, perform the following procedure to enable your pre-OSM 7.3.1 cartridges to run in the newly upgraded environment.
Before you upgrade cartridges, ensure the following prerequisites are met:
OSM is upgraded to 7.3.1 using the OSM installer.
Design Studio is upgraded to the required version. See "Upgrading the Development and Administration Environment."
The OSM 7.3.1 SDK component is installed using the OSM installer.
The Oracle WebLogic Server domain for OSM 7.3.1 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.
To upgrade your pre-7.3.1 cartridges to OSM 7.3.1:
Set global default Java preferences.
In Design Studio, from the Window menu, select Preferences. Then expand Java and do the following:
Select Installed JREs and check the box next to the Java 7 JRE you are using.
Expand Installed JREs, select Execution Environments, select JavaSE-1.7 from the Execution Environments list, and select the newly installed JRE from the Compatible JREs list.
Select Compiler and set the Compiler Compliance Level to 1.7.
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.1 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.
Set cartridges to use the correct build path.
For each cartridge, do the following:
In the Studio Projects view, right-click on the cartridge and select Properties.
Select Java Build Path and click the Libraries tab.
Select the JRE System Library from the list and click Edit.
Select Execution Environment and select the option that begins JavaSE-1.7 and references the location where you installed Java 7.
Click OK.
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.
Click Finish.
Click OK in the Properties window.
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.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.
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.1. 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.1 and update the version number if your cartridge is not using five-digit version numbers. See "Updating Cartridges to a Five-Digit Version."
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/... is not defined...".
After fixing the problem, Design Studio upgrades the OracleComms_OSM_CommonDataDictionary model project to the current version for 7.3.1 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.
Some cartridges may fail to build if they contain Java classes which implement interfaces that have changed in OSM 7.3.1.
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".
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.
Clean and build all cartridges in the workspace again.
Redeploy all cartridges to the OSM 7.3.1 run-time environment.
This section provides information on upgrade impacts to cartridges from previous releases of OSM to version 7.3.1.
If you follow the procedures in "Upgrading Pre-7.3.1 Cartridges to OSM 7.3.1," it should not be necessary to update the OracleComms_OSM_CommonDataDictionary manually.
Many releases of OSM, including OSM 7.3.1, contain additions that have been made to the OracleComms_OSM_CommonDataDictionary. In 7.3.1, for example, there are updates to the data dictionary in support of the Assets and Accounts features.
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:
In Design Studio, from the Project menu, deselect Build Automatically.
In the Studio Projects view, right-click on the OracleComms_OSM_CommonDataDictionary project and select Delete.
In the confirmation dialog box, select Also delete contents... and click Yes.
Create the common data dictionary in your workspace. See "Creating the Common Data Dictionary Project in Your Workspace" for instructions.
Clean and build all cartridges in the workspace.
If desired, from the Project menu, select Build Automatically.
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.1" for more information adding these data structures to the OSM common data dictionary.
After migrating a cartridge to version 7.3.1, you must set the cartridge target version to OSM version 7.3.1. 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.
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.In Design Studio, from the Window menu, select Preferences, then select Oracle Design Studio, and then select Order and Service Management Preferences.
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.
Click OK.
Design Studio saves your order template inheritance preferences and closes the Preferences dialog box.
Clean and build the cartridges.
Resolve any problem markers that may result from order template inheritance discrepancies in your cartridges.
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 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 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:
If you have previously disabled the prompt:
From the Window menu, select Preferences.
The Preferences dialog box is displayed.
In the Preferences navigation tree, expand Oracle Design Studio, and then expand Order and Service Management Preferences.
Select Orchestration Preferences.
In the Common Data Dictionary area, select the Prompt To Create Orchestration Data Dictionary check box.
Click OK.
Design Studio saves the preference and closes the Orchestration Preferences dialog box.
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.
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.
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:
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.1.
Update the cartridge versions to 1.0.0.0.0 in the XML catalogs.
Open the Package Explorer view.
For each cartridge, open the catalog.xml file located in CartridgeName/xmlCatalogs/core.
Select the Source tab.
Each rewritePrefix attribute in the file includes the version 1.0.0. Change this version to 1.0.0.0.0.
Set up the event views for the orders in the cartridge.
Exit and restart Eclipse. If prompted to save any entities, select Yes.
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.
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:
Right-click on the error in the Problems pane and select Quick Fix from the menu.
Click Finish in the Quick Fix window and then click OK to confirm.
Rebuild the project.
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.
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.
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 Developer's Guide for more information about these alternatives.
Note:
Although OSM provides powerful orchestration and order provisioning engines, OSM is not a data warehouse and management system and should not be used as an intermediary between upstream and downstream systems.