This chapter provides an overview of extending Oracle Communications Unified Inventory Management (UIM).
Note:
Throughout this guide, the UIM_Home placeholder is used to represent the directory where you installed UIM. For a typical UIM installation, UIM_Home is opt/Oracle/Middleware/user_projects/domains/domain_name/UIM, where domain_name is the domain name you supplied when installing UIM.
UIM extensions can be categorized as static or dynamic:
Static extensions are changes made prior to rebuilding the application, which results in the changes becoming a part of the application deployment. For example, extending the data model involves adding content to the existing metadata files, which are contained within the inventory.ear file. So, you must rebuild the inventory.ear file to include the changed metadata files, and then redeploy the application for the changes to affect.
Dynamic extensions are made anytime, applied at run time, and do not require rebuilding the application for the changes to take effect. For example, a cartridge containing specifications can be deployed into UIM, making the specifications available within the application without rebuilding the application.
Cartridges can contain specifications, characteristics, rulesets, and extended code. You can create cartridges to meet specific business needs in Oracle Communications Design Studio. For example, if your equipment requires specific logic not provided by the EquipmentManager class, you can create your own class, inherited from the EquipmentManager class, and write a new method to address the specific equipment logic. The new method can then be called from within a ruleset.
The extensions defined within a cartridge may be static or dynamic. Cartridges are further explored in "Using Design Studio to Extend UIM".
You can statically extend the data model by adding new columns to existing tables, or by adding new tables. For example, your business requirements may dictate that you save particular information regarding a telephone number that the existing UIM data model does not save. You can extend the UIM data model to include this piece of information. Your business requirements may dictate that you save information unrelated to any data that the existing UIM data model saves. You can extend the UIM data model to include a new table to retain this information.
This is done through additions to the metadata. The UIM installation provides tools that enable you to automatically regenerate the data model based on the metadata, and to update the application (inventory.ear) to reflect the additions. This topic is further explored in "Extending the Data Model".
You can dynamically extend the data model through characteristics. For example, you can define a specification for a telephone number and add characteristics that further describe the telephone number. When you create entities in UIM based on a specification that includes characteristics, the characteristics are automatically included in the entities. This topic is further explored in UIM Concepts. For instructions on how to define characteristics in Design Studio, see the Design Studio Help.
An entity is a Java representation of UIM data, and an entity can be defined as life-cycle-managed in the metadata. Life cycle refers to an entity having a start to its life, an end to its life, and a defined state at any given point during its life. Life-cycle transition definitions are part of the UIM metadata, and you can extend these definitions to solve specific business requirements.
An entity can also be defined as topology-managed in the metadata. Topology is a graphical representation of the spatial relationships and connectivity among your inventory entities. Topology-managed entities map to topology entities, which are used in the graphical representation. UIM defines several entities as topology-managed, and you can extend topology by defining additional entities to be topology-managed.
Information on security is provided in UIM System Administrator's Guide. However, this guide (UIM Developer's Guide) provides additional security information specific to securing UIM APIs and UIM entities.
These topics are further explored in:
For information specific to securing web services, see UIM Web Services Developer's Guide.
A ruleset is custom code that extends existing logic at a specified point. You can dynamically extend UIM by creating rulesets to meet specific business needs. For example, if the default telephone number format does not match the telephone number format used by the country in which you are implementing UIM, you can use a ruleset to reformat the telephone number.
This topic is further explored in "Extending UIM Through Rulesets".
Web services are APIs that can be accessed over a network, such as the Internet, and run on a remote system hosting the requested services. UIM provides web services that are used for service fulfillment and for cartridge management. You can statically extend UIM by creating custom web services. For example, you can write a web service that performs a search for a specified entity, such as a pipe, a party, or a telephone number.
This topic is further explored in UIM Web Services Developer's Guide.
You can customize the user interface by adding fields or functionality to existing pages, or by adding new pages. For example, you may want to add a field named Type to the Equipment Maintenance page and populate it with your equipment type. Customizing the user interface statically extends UIM.
This topic is further explored in "Customizing the User Interface".
Localizing UIM is the process of changing the user interface and the online Help from the language in which it was written to another language. This process involves modifying files that contain text that displays in the user interface and the online Help.
This topic is further explored in "Localizing UIM".
You can optimize UIM performance by extending entity types that are heavily used in your UIM environment to implement the rowLock pattern.
This topic is further explored in "Optimizing Concurrent Resource Allocation".
You can extend UIM to interface with other external systems through federation, leasing in data, leasing out data, viewing data, or sharing data. UIM provides sample cartridges that you can configure and use, or extend and use as a starting point in creating a custom federation solution.
This topic is further explored in "Using the Federation Framework", "Federation Data Domain Cartridges" and "Federation Protocol Cartridges".
Several tools are available for extending UIM and are described in "Using Design Studio to Extend UIM".
Design Studio is an Eclipse-based integrated development environment. Design Studio is not part of UIM, but it does come with features specific to UIM that enable you to extend UIM. Information on using Design Studio to extend UIM is in "Using Design Studio to Extend UIM".
Additional tools such as Ant, Drools, and Groovy are available to you when extending UIM. The UIM installation includes a collection of Apache Ant executable targets that are used to extend the data model. These targets automate entity regeneration, entity recompilation, and repackaging the application EAR file to include the recompiled entities. The Drools and Groovy plug-ins can be used to edit ruleset syntax within Design Studio. Information on these tools, how to install them, and how to use them is in "Using Design Studio to Extend UIM".
Additional information needed to extend UIM is described in the following sections. The resources described here are intended to be used together. For example, the Javadoc provides specific information on methods that are available per entity, and method signatures may define specific entity attributes. However, the Javadoc does not get into details regarding the entity itself or any of the attributes it defines; this type of information is covered elsewhere. See "Information Model Documentation" for more information.
Entities are Java representations of UIM data. The entities that comprise UIM are detailed in Oracle Communications Information Model Reference and UIM Information Model Reference. The documents describe each entity, lists the entity attributes, provides examples, and includes information on patterns that are common across all entities.
Oracle Communications Information Model Reference and UIM Information Model Reference are located under “Oracle Communications Unified Inventory Management Developer Documentation" on the Oracle Software Delivery Cloud.
Information on UIM APIs is detailed in UIM API Overview. The document provides detailed information and code examples of numerous APIs presented within the context of a generic service fulfillment scenario, and within the context of a channelized connectivity enablement scenario. The document also provides information about transactions, exceptions, and logging when working the APIs. It also provides a complete listing of the UIM entity manager classes and common utility code examples.
The classes that comprise UIM, and the Platform classes upon which UIM is built, contain Javadoc. The Javadoc that comes with the UIM installation includes both UIM and Platform Javadoc.
To access the Javadoc:
Start the application server.
For instructions on how to start the application server, see UIM System Administrator's Guide.
From the application server console, deploy the UIM_Home/app/inventory.ear file, which automatically deploys the UIM_Home/doc/ora_uim_javadoc.war file.
For instructions on how to deploy a file from the application server console, see UIM System Administrator's Guide.
In your Web browser, do one of the following:
If UIM was installed with SSL, enter:
https://server:port/ora_uim_javadoc
If UIM was installed without SSL, enter:
http://server:port/ora_uim_javadoc
where server is the specific server on which the application is deployed and port is the port on which the application listens.
You should be aware of backward compatibility guidelines when extending UIM.
Before you extend UIM, understand the implications of backward compatibility and the effects on future upgrades.
UIM maintains backward compatibility for one release for all published external interfaces:
Manager interfaces and method signatures
Published extension points
Web service interfaces
UIM does not maintain backward compatibility for:
Metadata and physical data model
User interface
Localization
The UIM_Home/doc/ora_uim_delta.war file contains information regarding changes between releases. Oracle recommends that you review the WAR file content when upgrading UIM to determine if any of the upgrades affect your current extensions.
To read about code changes between releases:
Start the application server.
For instructions on how to start the application server, see UIM System Administrator's Guide.
From the application server console, deploy the UIM_Home/doc/ora_uim_delta.war file.
For instructions on how to deploy a file from the application server console, see UIM System Administrator's Guide.
In your Web browser, do one of the following:
If UIM was installed with SSL, enter:
https://server:port/ora_uim_delta
If UIM was installed without SSL, enter:
http://server:port/ora_uim_delta
where server is the specific server on which the application is deployed and port is the port on which the application listens.
For developers, the list of software tools expands beyond installing and running the UIM application. For instance, Design Studio, Java, and Eclipse plug-ins have specific version requirements with each UIM release.
Table 1-1 lists the developer-related software and the required versions.
Table 1-1 Software Versions for Developer Tools
Software | Version |
---|---|
Design Studio |
7.4.1 |
Java JDK |
Java 8 (with the latest critical patches applied) |
Groovy |
2.5.6 |
Drools |
7.31.0 |
Eclipse |
4.6 (Neon) |
Oracle WebLogic Server Enterprise Edition (included with the Oracle Fusion Middleware WebLogic Server) |
12c (12.2.1.4) |
Apache log4j |
2.9.1 |
Ant |
1.9.1 |
For more information on software requirements, see UIM Installation Guide.