This chapter explains how you work with cartridges and cartridge bundles in Oracle Communications Unified Inventory Management (UIM). It also provides information about the cartridge project archives that you use in Oracle Communications Design Studio.
Many cartridges, such as those in cartridge packs, are accompanied by cartridge project archives that you can import into Design Studio for review or extension. The project archives are ZIP files included in the larger cartridge pack ZIP file.
For example, in the Consumer VoIP cartridge pack, each of the deployable cartridge files, such as ora_uim_service_location_cartproj-*.jar is accompanied by a corresponding project archive file, such as ora_uim_service_location_cartproj-*.zip. (In the actual file names, the asterisk is replaced by a build number.)
See the Design Studio Help for information about importing project archive files into Design Studio. See "Upgrading and Extending Cartridges and Cartridge Packs" and UIM Developer's Guide for information about how you can extend cartridge projects in Design Studio.
You can deploy cartridges into UIM in the following ways:
From Design Studio. You can deploy cartridges and cartridge packs interactively from Design Studio to test environments. Design Studio enables you to manage cartridges in the test environment consistently, manage common test environment connection parameters across the design team, and compare cartridge version and build numbers in the development environment with those of the cartridges deployed in the test environment. See the Design Studio Help for more information.
By using the Design Studio Cartridge Management Tool (CMT). The CMT enables you to automate cartridge deployment. You can use the CMT to deploy cartridges into both test and production UIM environments. You can also use it to deploy cartridges into cluster environments. The CMT enables you to deploy cartridge pack bundles that include multiple individual cartridges. See the Design Studio Developer's Guide for more information about the CMT, and see "About Cartridge Bundles" for more information about cartridge bundles.
By using the UIM Cartridge Deployer Tool (CDT). The UIM CDT is a GUI-based tool that enables you to deploy cartridge projects. The Oracle Universal Installer installs the CDT as part of the UIM installation process. The CDT enables you to deploy cartridge pack bundles that include multiple individual cartridges. You can use the CDT to deploy cartridges into both test and production UIM environments. You can also use it to deploy cartridges into cluster environments. See "Using the Cartridge Deployer Tool" and "About Cartridge Bundles" for more information.
You must ensure the following to successfully deploy a cartridge:
All required base cartridges are deployed into UIM before deploying other cartridges. Oracle recommends that you deploy all base cartridges even if they are not immediately required. See "Base Cartridges" for more information
The user deploying the cartridge must have create table privileges on the UIM database schema. Characteristics within a cartridge require additional database tables and this user privilege is required.
The Cartridge Deployer Tool is a component of UIM. The Oracle Universal Installer installs the Cartridge Deployer Tool as part of the installation process in a location selected by the customer. See UIM Installation Guide for more information.
The Cartridge Deployer Tool does not validate cartridge dependencies. If any selected cartridge is dependent upon another cartridge, you must ensure that the cartridge upon which the dependency is based is already deployed or is selected first in the list for deployment.
Caution:
Before you start deploying cartridges using the Cartridge Deployer Tool, ensure that the WebLogic administration console is not locked for editing.To deploy cartridges:
Navigate to CDT_Home/CartridgeDeployerClients/CartridgeDeployer directory.
where CDT_Home is the directory where the Cartridge Deployer Tool was installed.
Run the following command:
./runCartridgeDeployer.sh
The Cartridge Deployer Welcome page appears.
Select the Deploy Cartridge option and click Next.
The Select Cartridge Type page appears.
From the Cartridge Type list, select Inventory and click Next.
The Cartridge Location page appears.
Click Browse to search for and select the cartridges you want to deploy.
You can select multiple cartridges from a single directory by holding down the Ctrl key.
Note:
The customized file browser shows only predefined cartridge extensions. UIM supports cartridges with only the .jar extension.Click Next.
The Configure Deployment Queue page appears.
View the details of the selected cartridges and click Next.
Note:
To add Deploy property or Model property, under Details for that cartridge, right-click on Properties and select the respective options for related menus.The WebLogic Connection Information page displays.
Do the following:
In the Host name or IP address field, enter the host name or IP address of the WebLogic Administration Server.
In the Port number field, enter the port number of the WebLogic Administration Server.
Select Use SSL (if enabled) while connecting to WebLogic Admin server.
(Optional) In the Keystore location field, enter the path or click Browse to search for the Keystore location. Leave this field blank if no Keystore location exists.
In the CMWS User field, enter the user name of the Cartridge Management Web service (CMWS) user.
Note:
Use your WebLogic administrator or CMWS user name.The CMWS user is a WebLogic server user belonging to the Cartridge_Management_Webservice group. The Cartridge_Management_Webservice group is also a member of the Administrators group.
In the Password field, enter the password for the CMWS user.
Note:
Use your WebLogic administrator user password.Click Next.
The Select WebLogic Target page displays.
In the list, select the managed server where the CMWS is deployed and click Next.
If the Secure Sockets Layer (SSL) is not configured correctly, the following message displays:
SSL Handshaking failed. You can proceed without SSL by unchecking SSL options on the bottom of this screen.
Note:
The SLL handshake fails when the Cartridge Deployer Tool connects to the CMWS using HTTPS.If you receive this message, click OK in the message dialog box, and deselect the Use SSL (if enabled) while connecting to Cartridge Management Web service check box located at the bottom of the page.
Click Next.
The Review Deployment page displays.
Review and confirm your selections and click Next.
The Cartridge Deployment page displays.
Note:
The Cartridge Deployer Tool rejects cartridges if a higher versions already exist. You can view rejected cartridges in the Cartridges rejected for this deployment session list.Click Deploy.
You can view the deployment progress.
Logs returned by the Cartridge Deployer Tool are displayed at the end of each cartridge deployment operation. The logs display whether the cartridge deployment succeeds or fails. In case of failure, the UIM server log includes detailed information about the specific error.
Note:
If the UIM server goes down during cartridge deployment, the cartridge is recovered after the UIM server is up again, or during the next cartridge deployment session, with the cartridge deployment request showing Failed.If a cartridge requires redeployment only, the CMWS will redeploy automatically. For more information on redeployment, see the WebLogic server administration console Help.
If a cartridge requires a redeployment and a restart, then you must deploy the cartridge, redeploy the inventory.ear file using the WebLogic administration server console, and then restart the server.
Note:
If you deploy a cartridge that contains Java code, the Cartridge Deployer automatically redeploys the inventory.ear file. In addition, you must manually redeploy the custom.ear file by using the WebLogic administration server console.To view deployed cartridges:
Locate the UIM_home/CartridgeDeployer directory.
From a command line, run the following command to run the Cartridge Deployer Tool executable:
./runCartridgeDeployer.sh
The Cartridge Deployer Welcome page displays.
Select the View Deployed Cartridges option, and click Next.
The Select Cartridge Type page displays.
Select Inventory in the Cartridge Type list, and click Next.
The WebLogic Connection Information page displays.
Do the following:
In the Host name or IP address field, enter the host name or IP address of the WebLogic Administration Server.
In the Port number field, enter the port number of the WebLogic Administration Server.
In the CMWS User field, enter the user name of the Cartridge Management Web service (CMWS) user.
Note:
Use your WebLogic administrator user name.The CMWS user is a WebLogic server user belonging to the administrators group.
In the Password field, enter the password for the CMWS user.
Note:
Use your WebLogic administrator user password.Click Next.
The Select WebLogic Target page displays.
Select the WebLogic targets where the Cartridge Management Web service is installed and click Next.
Note:
In some cases, the WebLogic targets may be different from where UIM is installed.If the SSL is not configured correctly, the following message displays:
SSL Handshaking failed. You can proceed without SSL by unchecking SSL options on the bottom of this screen.
Note:
The SLL handshake fails when the Cartridge Deployer Tool connects to the CMWS using HTTPS.Click OK in the message dialog box, and deselect the Use SSL (if enabled) while connecting to Cartridge Management Web service check box located at the bottom of the page.
Click Next.
The Deployed Cartridges page displays.
This page lists all of the cartridges that are currently deployed in UIM.
Cartridges can be bundled into a single deployable file. Deploying cartridge bundles offer two important advantages over deployable individual cartridges one at a time:
The cartridges are deployed as a unit, so only a single redeployment of the inventory.ear file in the WebLogic server administration console is required.
The cartridge bundle can be configured to ensure that cartridges are installed in the correct order to ensure that dependencies are met.
Cartridge bundles are JAR files that contain individual cartridges. For example, the cartridge bundle file for the Consumer VoIP cartridge pack (xxxx.jar) includes a number of individual cartridge files, such as yyyy.jar, zzzz.jar, and so on.
In addition to the cartridge bundles provided by Oracle (such as those in cartridge packs), you can create your own bundles. For example, if you create a domain solution for your business in Design Studio, you can create a cartridge bundle to make deployment easier.
The Cartridge Deployer Tool determines the appropriate order in which the cartridges are deployed, based on the dependencies of each cartridge.
If the bundle of cartridges is successfully deployed, the message your-bundle-name has been installed appears. The list of cartridges that are contained in the bundle is displayed in the Installed Cartridges table, in the Cartridge Management page.
To create a cartridge bundle:
Create a directory called META-INF/cartridges/.
Copy the cartridge JAR files you want to bundle to the META-INF/cartridges directory.
Create a MANIFEST.MF file and include the following properties:
Bundle-Name: unique_name_for_this_bundle
Bundle-Version: 5-digit_version_number
Bundle-BuildTime: yyy-mm-dd hh:mm:ss
Bundle-BuildNumber: build_number
Bundle-Category: Inventory
Bundle-Vendor: InventoryCartridge (Optional)
Bundle-RequiredExecutionEnvironment: Oracle-Communications/Inventory-7.2.0, JavaSE-1.6 (Optional)
Bundle-RequiredTargetVersion: 7.2.0 (Optional)
For example:
Manifest-Version: 1.0 Ant-Version: Apache Ant 1.7.1 Created-By: 20.9-b04 (Sun Microsystems Inc.) Bundle-Name: cableTV Bundle-Version: 7.2.2.0.0 Bundle-BuildTime: 2012-10-05 11:07:28 Bundle-BuildNumber: 1 Bundle-Category: Inventory
Place the file into the META-INF directory.
Navigate to the parent folder of META-INF.
Open a command window.
Run the following command:
jar cfM your-bundle-name.jar *.*
where your-bundle-name is the name of the bundle to be created.
The process of bundling multiple cartridges can be automated using Ant targets. Example 2-1 shows the cartbuild.xml file, which defines Ant targets that you can modify to bundle your own cartridges.
To modify the XML, and to run the Ant target defined within the XML:
Modify the following property name values:
bundle.name: Set the value to the name of the cartridge that will contain the bundled cartridges. Do not include .jar in the name of the cartridge: when the cartridge is created is it automatically appended with .jar.
workspace.dir: Set the value to path of your Eclipse workspace.
bundle.dir: Set the value to path where the created cartridge is to reside.
Within the copyfiles Ant target, modify the <fileset> and <include> elements to reflect the names of the individual cartridges that you are bundling.
From a command prompt, navigate to the directory that contains the XML file and enter the following to run the Ant target:
ant -f cartbuild.xml
This command assumes that individual cartridges specified in the copyfiles Ant target were already built within Design Studio, and that you did not change the name of the XML file.
<project name="cartridgebundle" default="all" basedir=".">
<property name="bundle.name" value="cart-bundle"/>
<property name="workspace.dir" value="c:/eclipse_workspace"/>
<property name="bundle.dir" value="d:/javatest/workspace/bundle"/>
<property name="meta.dir" value="${bundle.dir}/META-INF"/>
<property name="cartridges.dir" value="${meta.dir}/cartridges"/>
<target name="clean"
description="Deletes the bundle directory">
<delete dir="${bundle.dir}"/>
</target>
<target name="makefolders"
description="Create folders to contain temporaryfiles and target bundle jar">
<mkdir dir="${bundle.dir}"/>
<mkdir dir="${meta.dir}"/>
<mkdir dir="${cartridges.dir}"/>
</target>
<target name="copyfiles" depends="makefolders"
description="Copy selected cartridge jars to the temporary folder">
<copy todir="${cartridges.dir}">
<fileset dir="${workspace.dir}/custom-cartridge-1/cartridgeBin">
<include name="custom-cartridge-1.jar"/>
</fileset>
<fileset dir="${workspace.dir}/ custom-cartridge-2/cartridgeBin">
<include name="custom-cartridge-2.jar"/>
</fileset>
</copy>
</target>
<target name="makejar" depends="copyfiles"
description="Create the target bundle jar">
<jar compress="true" jarfile="${bundle.dir}/${bundle.name}.jar">
<fileset dir="${bundle.dir}">
<include name="**/*"/>
</fileset>
</jar>
</target>
<target name="clean.meta" depends="makejar"
description="Deletes the temporary META-INF directory">
<delete dir="${meta.dir}"/>
</target>
<target name="all"
depends="clean, makefolders, copyfiles, makejar, clean.meta"
description="Clean bundle folders and build the target bundle jar">
</target>
</project>
After you have deployed a number of cartridges to UIM, you may see error messages and be prevented from additional deployments. To resolve this problem, you must purge the DEV_MDS.MDS_COMPONENTS database table using one of the methods described below. This database table contains the metadata version history.
You can purge the metadata version history by using Fusion Middleware Control. You can also enable automatic purging of the data. See Oracle Fusion Middleware Administrator's Guide for information about launching and using Fusion Middleware Control.
To purge metadata version history by using the Fusion Middleware Control:
In the Fusion Middleware Control Farm home page, expand Application Deployments and select oracle.communications.inventory.
From the Application Deployment menu, choose MDS Configuration.
The MDS Configuration page is displayed.
In the Purge section, enter a number and select the unit of time in the Purge all unlabeled past versions older than field.
For example, enter 3 and select days.
Click Purge.
In the Confirmation dialog box, click Close.
To enable automatic purging in Fusion Middleware Control:
In the Fusion Middleware Control Farm home page, navigate to the WebLogic domain and select it.
From the WebLogic Domain menu, choose System MBean Browser.
The System MBean Browser page appears.
Expand Application Defined MBeans, then oracle.adf.share.config, then Server: name, then Application: oracle.communications.inventory, then ADFConfig, then ADFConfig, and ADFConfig.Select MDSAppConfig.
The Application Defined MBeans page appears.
For AutoPurgeTimeToLive, enter a value in seconds.
Click Apply.
You can purge metadata version history by using the purgeMetadata command in the WLST script. You must run the script from the appropriate Oracle home. Do not run the script from the WebLogic Server home. The script is located in the following directory.
WL_Home/common/bin
You specify the documents to be purged by using the olderThan parameter, specifying the number of seconds. The following example purges documents older than 100 seconds.
purgeMetadata(application='oracle.communications.inventory',server='AdminServer, olderThan=100)
If unexpected issues occur while you deploy a cartridge read the message that displays to troubleshoot the cause of the issue.
Common deployment errors occur for the following reasons:
The Design Studio project from which the cartridge was built has an error. Check the Problems view in Design Studio for error information, and then correct any problems before redeploying the cartridge into UIM. See the Design Studio Help for more information.
The UIM database data model does not match the version of the data model that Design Studio used to build the cartridge.
If you build a cartridge that relies on features found in an older version of the data model, deploying the cartridge into a UIM instance with a newer data model can result in deployment errors. Ensure that the data model that you use is the same version in both Design Studio and UIM.
The UIM version is not compatible with the version of Design Studio used to build the cartridge.
In this situation, the UIM cartridge reader encounters information it cannot handle and throws an error. Make sure you use the version of Design Studio and the Inventory plug-in that corresponds to your UIM version. If necessary, rebuild cartridges with the correct Design Studio version. You can see the Design Studio target version in the Target Version field of the inventoryCartridge file for the project.
Design Studio operates without a connection to the UIM database, so it is possible to create cartridges that are structured correctly in Design Studio but do not deploy properly into UIM. Ensure that the target UIM environment is configured with the correct schema, parameters, and base data that match the version of Design Studio being used.
The cartridge being deployed is dependent on another cartridge that has not yet been deployed.
Correct this by deploying the base or parent cartridge and then redeploying the cartridge that is dependent on the parent cartridge. A message displays telling you which cartridges are required if you try to deploy a child cartridge without the base.
In some cases, cartridges can be deployed without errors but still cause inconsistencies or unexpected behavior in UIM. These issues can be avoided by following the recommended guides for upgrading and extending cartridges and cartridge packs. See "Upgrading and Extending Cartridges and Cartridge Packs" for more information.