Cartridges and cartridge packs include entity specifications, characteristics, rulesets, and other artifacts that extend the content and functionality of Oracle Communications Unified Inventory Management (UIM). You can create your own cartridges and cartridge packs in Design Studio or obtain samples from Oracle. Both cartridges you create and those supplied by Oracle can be upgraded or extended after they are deployed.
Note:
Do not unseal or modify the base cartridges that are supplied with UIM.When you upgrade or extend a cartridge, there is the possibility of unexpected results. To ensure data consistency, you must follow the guidelines and leading practices provided in this chapter.
When you deploy a new version of a cartridge into UIM, existing specifications, characteristics, and rulesets are overwritten with the content in the new version. UIM uses names as unique identifiers. So when a specification, characteristic, or ruleset is deployed, it overwrites any existing version with the same name. Only the latest version is maintained in UIM. The origin of the overwriting specification, characteristic, or ruleset is irrelevant. It can come from a new version of the original cartridge or from an entirely separate cartridge.
Entity data from an earlier version of a cartridge is not changed when you deploy an updated cartridge, however. For example, if you created Logical Device entities based on a specification called Customer Edge Router, the entity data for those logical devices continues to exist in its original form when a new version of the specification is deployed following a cartridge upgrade.
But because a new version of the specification has replaced the old, the new version is used to display entities in UIM, even when the entities were created with an older version of the specification. As a result, there can be mismatches between the data and the new specification used to display it. Some data may no longer be visible in UIM, even though it still exists in the database. Similarly, data for characteristics introduced in the new version of a specification will be absent for entities created with the previous version.
For example, suppose the old version of the Customer Edge Router specification included a characteristic called Route Distinguisher Group, which has been removed from the new version. When the new version is installed, the data that populated that characteristic continues to exist in the database but is not displayed.
If the new version of the Customer Edge specification includes the characteristic Management IP Address and populated automatically by a ruleset when an entity is created, existing entities based on the old version of the specification will not include that information.
The section includes guidelines that you should follow to ensure that your extensions can be maintained even when a cartridge or cartridge pack is upgraded. Although these guidelines are oriented toward Oracle-supplied cartridges, many of the same considerations apply to cartridges that you create yourself.
There are two basic approaches to extending a cartridge or cartridge pack:
Making additive changes in separate cartridges
Modifying the content of renamed cartridges (”clone and own”)
In general, it is preferable to make additive changes. Because you are not modifying cartridges directly, the risk of complications during upgrade is reduced. See "Extending Cartridges By Adding New Content in Separate Cartridges". There are circumstances when you must unseal, rename, and modify cartridges, however. See "Renaming and Modifying Cartridges".
Important:
You should make sure to deploy only tested, stable extensions to your production environment, especially when you are modifying cartridges.In many cases, you can extend a cartridge or cartridge pack by creating a new cartridge that includes specifications and other artifacts that supplement the default content.
Because artifacts created in this way are separate from and named differently from the default contents, they will be preserved when you update the cartridge pack to a new version.
Inter-cartridge relationships make it possible to add separate content that is closely tied to the original content. You can establish relationships between specifications in one cartridge and specifications in another cartridge. In this scenario, you do not need to unseal or modify the original content of a cartridge pack. See the Design Studio Help for more information about implementing relationships among specifications in different cartridges.
Inter-cartridge relationships create dependencies between the cartridges. See "Tracking Cartridge Dependencies" for more information about dependencies. If you create an inter-cartridge relationship, deploy the cartridges, and subsequently redeploy or update the cartridge that includes the relationship target, the relationship is broken. You must re-establish it.
When you develop content in separate cartridges, you must be careful to name the corresponding Design Studio project uniquely to avoid conflicts. The project name must be unique in the workspace and among all cartridges that will be deployed to UIM.
The following list includes examples of extensions you can make additively:
You can add new global rules in separate cartridge to define new behaviors. Global rules are triggered at an extension point that applies to all specifications.
You can establish an assignment or reference from a configuration item in one cartridge to a specification in a separate cartridge by creating an upward reference from the specification.
You can use an upward reference to associate a new configuration specification in a separate cartridge to a configuration-enabled specification in another cartridge. For example, you can associate a new Service Configuration specification that you create to a Service specification in an Oracle-supplied sample cartridge.
You can use upward reference to associate related specifications in a separate cartridge to specifications in a another cartridge. For example, you can associate a new Device Interface specification that you create to a Logical Device specification defined in a sample cartridge.
You can add Inventory Group specifications in separate cartridge that you can use to group entities from other cartridges. For example, you could create inventory groups that you use to group MMS Server and Voice Mail Server entities for the GSM 3GPP sample cartridge pack.
Some types of extensions cannot be achieved by additive changes in separate cartridges. In these situations, you must unseal the affected cartridge, rename it, and then modify the necessary artifacts.
Renaming the cartridge before modifying it is a good practice because it differentiates the modified cartridge from the original. When you deploy the cartridge to UIM, for example, you can tell at a glance that it is the modified version.
See Design Studio Help for detailed instructions about unsealing and renaming cartridges.
The following list includes examples of situations when you need to modify cartridge contents
Adding a characteristic or attribute to an existing specification. The characteristic can be in a separate cartridge, but associating the characteristic to the specification requires unsealing the cartridge in which the specification is defined.
Removing a characteristic or attribute from an existing entity.
Changing existing Java logic.
Adding a new configuration item to a configuration specification.
Deleting a configuration item from a configuration specification. This option may require the database to be cleaned out, or the specification may need to be versioned.
Adding a new specification-based ruleset (as opposed to a global ruleset).
Updating an existing specification-based ruleset.
Observe the following guidelines when you unseal and rename a cartridge:
Keep a backup copy of the original cartridge.
To avoid naming conflicts among specifications, characteristics and other artifacts, do not deploy the original cartridge to UIM or open it in Design Studio at the same time as the renamed version.
Ensure that all cartridges on which the sample cartridge has a dependency are open in Design Studio before you rename it. See "Tracking Cartridge Dependencies" for more information.
You should consider the possible consequences of modifying the content of a cartridge after it has been deployed to UIM and after entity data has been created.
Making changes to existing specifications, characteristics, and other artifacts can cause issues when entity data has already been created. Problems can occur with the cartridge deployment or with UIM data.
For example, changing the type of a characteristic can cause difficulty with updating values assigned to it. Suppose you use Design Studio to change an existing required characteristic from a text field to a list. You deploy the new version of the cartridge successfully. When you open an entity that uses this characteristic in UIM, it displays its original value. If you try to modify the entity, however, this value will be lost because UIM forces you to set a value based on its new definition as a list with a limited set of values.
Deleting a specification, characteristic, or ruleset in a new version of a cartridge does not delete data that has been created in UIM based on it.
For example, if you delete a specification in Design Studio after entities based on it have been created in UIM, neither the specification itself nor the entities based on it are removed when you deploy the new version of the cartridge.
It is possible to inactivate a specification from UIM, but this requires that you delete all entities based on it and all entities related to those entities. Only then can you inactivate the specification. See the UIM Help for instructions about deleting entities and specifications.
For example, if you try to entirely inactivate a specification called PE Router without first deleting entities based on it, you see an error message. You must search for and delete all logical devices based on PE Router. If any of these devices includes device interfaces, they must also be deleted. Characteristics included in the specification do not need to be deleted.
Unlike specifications, which are not removed in UIM when they are deleted in a cartridge, relationships between entities in UIM are removed when those relationships are deleted in a new version of a cartridge. For example, suppose the CE Router specification and the CE Router Interface specification are related to each other. As a result you can create logical devices and interfaces based on that relationship in UIM.
If you deploy new versions of the specifications that lack this relationship, the relationship is also removed from UIM entities based on the specifications.
Renaming Specifications and Characteristics
If you rename a characteristic or specification in Design Studio and include the renamed versions in an updated cartridge that you deploy into UIM, the new versions of the artifacts do not replace the old ones. Because UIM uses the specification or characteristic name as the unique identifier, the renamed version appears to be new and therefore does not overwrite the existing version. This can result in issues with the display of data.
If you use Design Studio to rename a specification after entities based on it have been created in UIM, deploying the upgraded cartridge results in the following:
A new specification with the new name is created in UIM.
The original specification remains in UIM.
If you use Design Studio to rename a characteristic that is used in entities already created in UIM, deploying the upgraded cartridge results in the following:
The original characteristic is removed from the specification.
The renamed characteristic is added to the specification.
The data from the original characteristic remains in the database but does not appear in the new characteristic.
For characteristics, you can change the label without changing the name. The label is the text that is displayed in UIM. So if you need to change the displayed text but leave existing data in place, you can change the characteristic label. See the Design Studio Help for more information.
If you cannot avoid renaming and redeploying a cartridge that has already been deployed under its original name, there are steps you should take to avoid potential problems.
Important:
The information in this section is appropriate only for test and development environments. In a production environment, you should only deploy stable and tested extensions.Problems arise because redeploying a cartridge with a new name after it has previously been deployed results in duplicate Java classes in UIM with the same package name. Errors can result when these classes are called, for example, from a ruleset.
The recommended approach to avoid these errors when a cartridge is renamed after it has already been deployed is to reinstall the UIM server and clear the database (essentially a fresh install with a clean database).
An alternative but less reliable method is available in the WebLogic Server Admin Console. In the Deployments screen, examine the uim_custom_lib.ear file in the current version of the UIM/app/uim_custom_lib/uim_custom_lib_version directory.
Stop the server, remove the original cartridge JAR file, remove the server temporary files, and then restart the server.
Cartridges can have complex dependencies that you need to track. For example, suppose you include a specification from Cartridge A as a specification option in a configuration item in Cartridge B. In this situation, Cartridge B is dependent on Cartridge A. You must deploy Cartridge A before Cartridge B. Larger numbers of cartridges obviously lead to more complex dependencies.
Design Studio displays these dependencies in the Dependency tab of Inventory Project editors and prevents circular dependencies. UIM enforces these dependencies when you deploy cartridges. You see an error if you try to deploy a cartridge before all of its dependent cartridges have been deployed.
You should be aware of dependencies when you extend cartridges. For example, if you deploy an updated version of Cartridge A, you know that there is a possible impact on Cartridge B.
Extensions may also affect the order in which you deploy cartridges. For example, if you create a cartridge to supplement a cartridge pack, dependencies will probably mean that you have to deploy it last.
See UIM System Administrator's Guide and UIM Developer's Guide for information about grouping and deploying multiple cartridges.
Some cartridges include ruleset stubs that enable you to customize the behavior of entities without changing specifications. These ruleset stubs make it possible to customize validation and allocation functionality.
A ruleset stub is an empty ruleset that performs no operations by default. The full stub implementation includes the ruleset itself (.ruleset file), a rule file (.drl or .groovy file), an association to a specific extension point, and a reference to the ruleset extension point from a particular specification.
To implement your customized behavior, you define a ruleset that has the same name as the stub. You include the ruleset in a cartridge and deploy it into UIM after deploying the original cartridge. The customized ruleset overwrites the empty original.
For example, a cartridge could include a ruleset called AUTO_ALLOCATE_SERVICE_CONFIG that is associated with an extension point called AUTO_ALLOCATE_SERVICE_CONFIG_Ext. This extension point is in turn included in a Service Configuration specification.
To take advantage of the stub, you use Design Studio to create a cartridge that includes a ruleset also named AUTO_ALLOCATE_SERVICE_CONFIG.
Note:
Design Studio requires that all specifications and rulesets be uniquely named within a workspace. The original cartridge must not be open in the workspace (even if it is sealed) when you define the replacement ruleset.This ruleset includes the auto-allocation logic you want to implement. When you deploy the cartridge into UIM, the customized ruleset replaces the original, meaning that your logic is used for auto-allocation in entities based on the relevant Service Configuration specification.
If you deploy a new version of the original cartridge to UIM, the stub ruleset overwrites the customized version. You can re-deploy the cartridge with the customized ruleset to restore the desired functionality.
See UIM Developer's Guide and the Design Studio Help for more information about rulesets.
There may be cases where you want to provide a new version of an existing specification. For example, suppose you have been using a specification for a physical device and the manufacturer comes out with a new model of the device. Changing the original specification runs all of the risks associated with modifications, so you should copy the specification, assign it a name that indicates its status, and introduce the required changes. For example, if you have an existing Physical Device specification called LRI_PERouter, you could define an updated specification called LRI_PERouter-v2.
If related specifications and characteristics need to change along with the parent specification, you can manually version them, too. For example, if a Logical Device specification has an associated Device Interface specification, you can define a version of the Device Interface specification to reflect the update to the logical device.
When you deploy a new version of or make significant content changes to a cartridge, you should save a snapshot of the database. This enables you to roll back the upgrade if the new content causes unexpected or undesirable effects.
It is not necessary to create a snapshot for simple changes such as adding a small number of new specifications.
You should also make sure to maintain backup copies of original cartridges so that you can redeploy content if necessary.
You should also back up important data that is stored in the UIM file system, such as Java code and the cartridge deployment history. See UIM System Administrator's Guide and UIM Developer's Guide for information about these files.
There are some special considerations involving entity configurations that you should keep in mind while planning upgrades to cartridges. See UIM Concepts and UIM Help for information about using configurations.
As you create new configuration versions for a parent entity in UIM, you create a record of the state of the entity at various points in time. If you need to update a configuration specification, you have to choose between the potential for requiring transformation of data and the loss of configuration version continuity.
If maintaining continuity of configuration versions is not essential, you can follow the standard practice recommended for entities: set an end date for the configuration specification and define a new one containing the updates. This option is suitable for in-progress configurations. Because associations to configuration specifications cannot be changed after configurations have been created, however, you will need to recreate the affected parent entities and then create the first configuration version using the new configuration specification.
If maintaining the continuity of configuration versions is important, you should modify the configuration specification rather than replace it. Such modifications result in the kinds of issues discussed in "Considerations When Modifying Cartridge Content After Entity Data Creation", however: the data in older configuration versions will be displayed from the perspective of the modified specification. If you need to access data that would otherwise not be visible as the result of the modifications, you need to transform the data to conform to the new specification. This may be disruptive of in-progress configurations and require tightly synchronized changes to upstream systems.
Because specifications and characteristics must be uniquely named in a Design Studio workspace and in a UIM database, you should adopt a careful and systematic naming convention. If you are not careful about naming, you run the risk of overwriting an existing specification or characteristic or of having one of your specifications or characteristics overwritten when a cartridge is deployed.
For example, assume that a Logical Device specification called PE Router is included in an Oracle sample cartridge. If you build your own cartridge that includes an identically named specification, the specification in the sample will be overwritten when you deploy your cartridge.
Follow these guidelines to avoid naming issues:
Use specification and characteristic names that are unique and not generic. For example, you could include an identifying prefix to all specifications and characteristics you create.
Do not rename characteristics and specifications after entities based on them have been created in UIM. If you want to stop using a specification or characteristic of a particular name and use a similar one with a different name, you should create the new version and set an end date for the old version in Design Studio. After deploying the cartridge containing the changes, migrate entity data as necessary.
This section outlines the recommended life cycle of a Oracle-supplied sample cartridge or cartridge pacK.
You download the sample cartridge or cartridge pack.
If necessary, you develop the new specifications, rulesets, and other artifacts required by your business. See "Leading Practices for Extending Cartridges" for more information.
For example, you can define vendor-specific specifications for the particular networking equipment that you use. You package these extensions in separate cartridges that you deploy after deploying the sample cartridge pack.
You deploy the sample cartridge or cartridge pack along with your extensions to it.
Cartridge packs typically comprise several cartridges with dependencies on each other. You must deploy the cartridges in a specific order. If you are deploying cartridges by using a cartridge bundle, the deployment order is handled automatically.
You create inventory entities based on the sample and your extensions.
At a later date, Oracle upgrades the sample cartridge or cartridge pack.
You evaluate the enhancements included in the upgrade and plan any changes to your extensions that are required to take advantage of the new capabilities.
You deploy the upgraded cartridge or cartridge pack.
Because your extensions followed the recommended guidelines, the upgrade does not interfere with data you created using the previous version.
You deploy any new extensions of the sample along with updates to existing extensions.
You create inventory entities based on the upgraded sample and extensions.