This chapter provides information on extending the topology in Oracle Communications Unified Inventory Management (UIM). The topology is a graphical representation of the spatial relationships and connectivity among your inventory entities.
The topology uses a specific set of entities and a specific algorithm to determine the path between any two entities. This algorithm is called the path analysis. You can extend the topology to include additional entities in the topology, and you can modify the path analysis to suit your business needs.
The information presented in this chapter describes statically extending UIM, which can result in backward compatibility issues. See "Backward Compatibility" for the implications regarding this type of extension.
Note:
Before you begin reading about extending topology, it is important that you have an understanding of the following subjects described in UIM Concepts:
Connectivity
Topology
Topology entities are defined in the metadata and are used to display the topology. Topology-managed entities are also defined in the metadata and are indirectly used to display the topology. UIM maps topology-managed entities to one of two topology entities, and, as a result of the mapping, topology-managed entities indirectly display in the topology.
The metadata defines the following topology entities:
TopologyEdge
TopologyNode
TopologyNode entities represent locations, network nodes, or devices, and TopologyEdge entities represent pipes or network edges.
The metadata defines the topology entities in the topology-entities.xml file. Example 6-1 is an excerpt from this file that shows the definition of the TopologyNode entity.
Example 6-1 topology-entities.xml
<entity type="ocim:TopologyNode" interface="oracle.communications.inventory.api.entity.TopologyNode" accessControlled="true" entityIdSequenceGenerator="TopologySeqGen">
<implements interface="java.lang.Cloneable"/>
<implements interface=
"oracle.communications.inventory.api.entity.common.TopologyObject"/>
<attribute name="isTopLevelNode" index="true"/>
<attribute name="geometry" spatial="true"/>
<relationship name="businessObject">
<thisSide inverse="true"/>
<otherSide dependent="true" type="ocim:TopNodeAssociation"
attribute="topologyNode"/>
</relationship>
</entity>
The TopologyEdge entity is also defined in the topology-entities.xml file in the same manner.
Note:
There are actually several topology entities defined in the topology-entities.xml file that support topology. However, within the context of extending topology, this chapter focuses solely on the TopologyEdge and TopologyNode entities.
The metadata defines the following entities as topology-managed:
Equipment
GeographicPlace
LogicalDevice
Network
NetworkEdge
NetworkNode
PhysicalDevice
Pipe
The metadata defines these entities as topology-managed throughout the various *-entities.xml files. Example 6-2 is an excerpt from the equipment-entities.xml file. The example shows the entity definition for PhysicalDevice, which includes the implementation of the TopologyObject interface. Implementing the TopologyObject interface in the entity definition is what defines an entity as topology-managed.
Example 6-2 Topology-Managed Entity Definition
<entity type="ocim:PhysicalDevice" interface="oracle.communications.inventory.api.entity.PhysicalDevice" accessControlled="true" entityIdSequenceGenerator="PhyDeviceSeqGen">
<implements interface="oracle.communications.inventory.api.entity.common.PhysicalResource"/>
<implements interface="java.lang.Cloneable"/>
<implements interface="oracle.communications.inventory.api.entity.common.TopologyObject"/>
<implements interface=
"oracle.communications.inventory.api.entity.common.PhysicalMappingObject"/>
<implements interface="oracle.communications.inventory.api.entity.common.NetworkNodeEnabled"/>
.
.
.
</entity>
Entities defined as topology-managed in the metadata are mapped to either TopologyEdge or TopologyNode by the UIM-provided TopologyMapperImpl class.
The following topology-managed entities are mapped to TopologyNode:
Equipment
GeographicPlace
LogicalDevice
Network
NetworkNode
PhysicalDevice
Note:
The GeographicPlace entity is defined as topology-managed in the UIM metadata, and the UIM mapping logic indirectly maps this entity to TopologyNode. The mapping logic actually checks for GeographicLocation and GeographicSite, not GeographicPlace. GeographicPlace is a parent to GeographicLocation and GeographicSite. A place becomes a topology object when it is associated to a resource such as Logical Device or Physical Device.
To extend the topology:
Determine entities that you plan to define as topology-managed. (This step is performed by the business analyst, who relays the information to the developer.)
Determine the mapping of each topology-managed entity to TopologyEdge or TopologyNode. (This step is performed by the business analyst, who relays the information to the developer.)
Define identified entities as topology-managed in the metadata by creating new ext-*-entities.xml files. See "Defining an Entity as Topology-Managed" for more information.
Regenerate the entities to pick up the new ext-*-entities.xml files. See "Applying Metadata Static Extensions" for more information.
Extend the mapping logic to include the mapping of any additional entities defined as topology-managed in the metadata. See "Extending the Mapping" for more information.
An entity can be defined as topology-managed through a new file in the metadata.
Note:
Do not modify existing metadata files. See "Backward Compatibility" for the issues involved with making additions to the existing metadata files.
To define a new entity as topology-managed, add the <implements> element to the entity definition in the new *-entities.xml file to implement the TopologyObject interface. See "Defining New Entities" for more information.
To define an existing entity as topology-managed, add the <implements> element to the entity by extending the entity definition in the new *-entities.xml file to implement the TopologyObject interface. See "Extending Existing Entities".
If you define an entity as topology-managed in the metadata, you must also extend the BusinessObjectType class by modifying it to include an enumerated value for that entity. This provides the ability to keep a weak reference between the topology entity and the business object.
For example, the BusinessObjectType class defines the BusinessObjectType enumeration, and you must assign an enumerated value to any entities you define as topology-managed:
/**
* This class defines the business IDs for mapping Business objects to
* TopologyEdges and TopologyNodes in the topology model.
* Every different business entity must have a unique ID.
* Once a value has been set it cannot be changed.
*/
public enum BusinessObjectType {
LogicalDeviceDao(1), GeographicPlaceDao(2), PipeDao(3),
PhysicalDeviceDao(4), NetworkDao(5), NetworkNodeDao(6),
NetworkEdgeDao(7), EquipmentDao(8), PhysicalConnectorDao(9),
PhysicalPortDao(10), EquipmentHolderDao(11), CustomObjectDao(12),
ServiceDao(13), GeographicSiteDao(14), ServiceConfigurationVersionDao(15),
TopologyOnly(9999);
Entities defined as topology-managed in the metadata must be mapped to TopologyEdge or TopologyNode by extending the TopologyMapperImpl class.
This class is located in the oracle.communications.inventory.api.topology package.
If you extend the mapping, you must also configure the topologyProcess.properties file to point to your new mapper class.
For example, the file includes the following upon installation, and you must configure it to point to your new mapper class instead:
# mapperClass - The Class Object that maps the business model to Topology mapperClass=oracle.communications.api.topology.mapper.impl.TopologyMapperImpl
Path analysis is an automated process in UIM that helps you locate and assign pipes for enablement. You specify a starting point (the source), an ending point (the target), and a variety of optional criteria. Path analysis evaluates possible paths based on the criteria you provide and returns paths from which you can select. See UIM Concepts for more information.
Path analysis uses the topology to find paths.
Path analysis evaluates connections based on topology-managed entity data. Only entities in the topology are included in path analysis. You can configure and customize path analysis, as described in the following sections.
Path analysis can use two different algorithms to determine paths:
The Complex algorithm (the default) considers all possible paths between end points, which means evaluating a large number of permutations. You can use filtering to limit the amount of data to be processed. This mode of path analysis is suitable for complex networks with many possible connections.
The Simple Linear algorithm works by iteratively analyzing paths working from the end points toward a common node. This mode of analysis is suited to relatively simple scenarios where paths are inherently linear and include 10 or fewer hops, such as POTS. The Simple Linear algorithm has less impact on system performance than the Complex algorithm.
You can use the topologyProcess.properties file to configure path analysis. For example, the properties file includes the following upon installation:
# Path Analysis Properties simpleLinearMode=false simpleLinearModeMaxCycles=5 continueProcessingIndicator=true
The simpleLinearMode parameter is used to denote the path analysis mode. The default value is false, indicating that Complex mode is the default path analysis mode.
Note:
Before changing the value of this parameter, you need to be certain that the Simple Linear mode is appropriate for your needs. Path analysis will not find some kinds of paths in this mode.
You can extend path analysis so that Simple Linear mode is used when analyzing paths for particular pipe specifications, even when Complex mode is used for the application in general. See "Customizing Path Analysis" for more information.
The simpleLinearModeMaxCycles parameter denotes the number of connected neighbors that a Simple Linear path analysis finds before determining that a path cannot be found. The default value is 5. You can increase the value if path analysis fails to find paths.
The continueProcessingIndicator parameter denotes whether UIM will try to find a path with the Complex mode if no path can be found by using Simple Linear mode. The default value is true, indicating that if no path is found using Simple Linear mode, path analysis continues by attempting to find a path using Complex mode. Setting the value to false indicates that if no path is found using Simple Linear mode, path analysis stops.
You can use rulesets to customize path analysis. By associating rulesets to individual Pipe specifications, you can tailor path analysis to meet various business scenarios.
A sample ruleset is provided with UIM to serve as a starting place for three types of customization:
Adding additional filter criteria to the analysis. See "Adding Filtering Criteria" for more information.
Setting Simple Linear mode for path analysis involving a particular Pipe specification. See "Setting the Analysis Mode" for more information.
Specifying that only pipes based on particular specifications be included in a path analysis. See "Limiting the Analysis by Pipe Specification" for more information.
The PATHANALYSIS_FINDPATHS_SETCUSTOMCRITERIA sample ruleset is included in the UIM_Home/cartridges/sample/ora_uim_pathanalysis_sample cartridge.
You can customize path analysis by appending code to the body of the ruleset. The sample ruleset includes examples of each of the three types of customizations mentioned in this section.
The ruleset is applicable to Pipe specifications and must be associated with the PathAnalysisManager_findPaths base extension point and the oracle.communications.inventory.api.entity.PipeSpecification enabled extension point. The placement of the ruleset extension point must be BEFORE.
You can add filtering criteria to a path analysis. Filtering criteria restrict the amount of data that UIM considers when locating paths, reducing the amount of processing required.
Note:
Because the additional criteria are defined using standard JPAQL syntax, knowledge of JPAQL is required to implement this feature.
For example, you can limit the analysis to consider only nodes or edges that include particular characters in their names or only pipes in a particular status. Including the following code in the PATHANALYSIS_FINDPATHS_SETCUSTOMCRITERIA ruleset limits the path analysis to pipes in the Installed state.
filterStr.append("businessObject.referenceId == vPipe.ext:getColumn('ENTITYID') ");
filterStr.append(" && vPipe.adminState == pStatus ");
params.add("pStatus");
values.add(InventoryState.INSTALLED);
criteria.setAppendQuery (params, values, filterStr.toString());
You can configure path analysis to use Simple Linear mode when enabling pipes based on a particular specification. Including the following code in the PATHANALYSIS_FINDPATHS_SETCUSTOMCRITERIA ruleset sets the mode to Simple Linear when the ruleset runs. It also sets values for the SimpleLinearModeMaxCycles and ContinueProcessingIndicator parameters.
criteria.setSimpleLinearMode(true); criteria.setSimpleLinearModeMaxCycles(10); criteria.setContinueProcessingIndicator(true);
You can limit the pipe analysis so that it considers only transport pipes based on a particular specification. For example, you can filter out trunk and ISDN lines that are not valid connections for POTS. Similarly, if there are cables between a switch and an MDF that are not used for POTS, you can exclude them from the pipe analysis.
Note:
You can also limit path analysis to particular Pipe specifications by including a specification in the Transport configuration item of a Pipe configuration.
For example, including the follow code in the PATHANALYSIS_FINDPATHS_SETCUSTOMCRITERIA ruleset limits the path analysis to pipes based on the Sample Terminated Pipe specification:
SpecManager sm = InventoryHelper.makeSpecManager();
SpecSearchCriteria specCriteria = sm.makeSpecSearchCriteria();
CriteriaItem critSpecName = specCriteria.makeCriteriaItem();
critSpecName.setValue("SampleTerminatedPipe");
critSpecName.setOperator(CriteriaOperator.EQUALS_IGNORE_CASE);
specCriteria.setName(critSpecName);
List<Specification> specs = sm.findSpecifications(specCriteria);
ArrayList includeSpecs = new ArrayList();
for (Specification pipespec : specs){
includeSpecs.add(new Long(pipespec.getEntityId()));
}
criteria.setIncludeSpecifications(includeSpecs);
You can use the topology interfaces when writing rulesets or web services to meet business requirements that involve extending the topology or customizing path analysis.
The following sections describe the available topology interfaces. For information on the methods defined by any of these interfaces, see the Javadoc. For instructions on how to access the Javadoc, see "Javadoc Documentation".
TopologyObject is the only topology interface described in this section that is available to all entities. Defining an entity to implement this interface makes the entity topology-managed. Topology-managed entities must be mapped to TopologyEdge or TopologyNode.
The remaining interfaces described in this section are available to TopologyEdge and TopologyNode entities. Example 6-3 is an excerpt from the uim-common-entities.xml file showing the common manager interfaces defined for the entities, including TopologyEdge and TopologyNode.
Example 6-3 uim-common-entities.xml Manager Interfaces
<manager interface="oracle.communications.inventory.api.framework.policy.SearchPolicy"
class="oracle.communications.inventory.api.framework.policy.impl.SearchPolicyImpl"/>
<manager interface="oracle.communications.inventory.api.common.TransitionManager"
class="oracle.communications.inventory.api.common.impl.TransitionManagerImpl"/>
<manager interface="oracle.communications.inventory.api.common.AttachmentManager"
class="oracle.communications.inventory.api.common.impl.AttachmentManagerImpl"/>
<manager interface="oracle.communications.inventory.api.common.SequenceGenerator"
class="oracle.communications.inventory.api.common.impl.SequenceGeneratorImpl"/>
<manager interface="oracle.communications.inventory.api.consumer.ConsumerManager"
class="oracle.communications.inventory.api.consumer.impl.ConsumerManagerImpl"/>
<manager interface="oracle.communications.inventory.api.consumer.AssignmentManager"
class="oracle.communications.inventory.api.consumer.impl.AssignmentManagerImpl"/>
<manager interface="oracle.communications.inventory.api.common.ConfigurationInputManager"
class="oracle.communications.inventory.api.common.impl.ConfigurationInputManagerImpl"/>
<manager interface="oracle.communications.inventory.api.consumer.ConditionManager"
class="oracle.communications.inventory.api.consumer.impl.ConditionManagerImpl"/>
<manager interface="oracle.communications.inventory.api.consumer.ReservationManager"
class="oracle.communications.inventory.api.consumer.impl.ReservationManagerImpl"/>
<manager interface="oracle.communications.inventory.api.common.FederationManager"
class="oracle.communications.inventory.api.common.impl.FederationManagerImpl"/>
<manager interface="oracle.communications.inventory.api.common.EntityIdGenerator"
class="oracle.communications.inventory.api.common.impl.EntityIdGeneratorImpl"/>
<manager interface="oracle.communications.inventory.api.admin.SecurityManager"
class="oracle.communications.inventory.api.admin.impl.SecurityManagerImpl"/>
<manager interface="oracle.communications.inventory.api.topology.TopologyManager"
class="oracle.communications.inventory.api.topology.impl.TopologyManagerImpl"/>
<manager interface="oracle.communications.inventory.api.topology.mapper.TopologyMapper"
class="oracle.communications.inventory.api.topology.mapper.impl.TopologyMapperImpl"/>
<manager interface="oracle.communications.inventory.api.topology.PathAnalysisManager"
class="oracle.communications.inventory.api.topology.impl.PathAnalysisManagerImpl"/>
<manager interface="oracle.communications.inventory.api.topology.mapper.PathAnalysisMapper"
class="oracle.communications.inventory.api.topology.mapper.impl.PathAnalysisMapperImpl"/>
<manager interface="oracle.communications.inventory.api.topology.mapper.TopologyProfileMapper"
class="oracle.communications.inventory.api.topology.mapper.impl.TopologyProfileMapperImpl"/>
<manager interface="oracle.communications.inventory.api.capacity.CapacityManager"
class="oracle.communications.inventory.api.capacity.impl.CapacityManagerImpl"/>
<manager interface="oracle.communications.inventory.api.characteristic.CharacteristicManager"
class="oracle.communications.inventory.api.characteristic.impl.CharacteristicManagerImpl"/>
<manager interface="oracle.communications.inventory.api.role.RoleManager"
class="oracle.communications.inventory.api.role.impl.RoleManagerImpl"/>
<manager interface="oracle.communications.inventory.api.common.RowLockManager"
class="oracle.communications.inventory.api.common.impl.RowLockManagerImpl"/>
<manager interface="oracle.communications.inventory.api.framework.policy.LockPolicy"
class="oracle.communications.inventory.api.framework.policy.impl.LockPolicyImpl"/>
Package: oracle.communications.api.inventory.entity.common
This interface defines getter methods for the object's IDs: ID, ENTITYID, and OID. There are no setter methods because these IDs are generated for the object, not set for the object.
Package: oracle.communications.inventory.api.topology
This interface defines methods for finding and maintaining TopologyEdge and ToplogyNode entity objects.
Package: oracle.communications.inventory.api.topology.mapper
This interface defines the business rules for mapping topology-managed entity objects to a TopologyEdge entity object or a TopologyNode entity object.
Package: oracle.communications.inventory.api.topology
This interface defines methods for finding paths (edges and nodes) through the topology network based on specified criteria.
Package: oracle.communications.inventory.api.topology.mapper
This interface defines the business rules for mapping business object path analysis criteria to values used in the topology model. This object provides a mapping layer between the business model and the topology model for cases where the data in the topology model must be converted from a value in the business model.
Package: oracle.communications.inventory.api.topology.mapper
This interface defines mapping for service topology. While topology is extended through the metadata, service topology is extended through characteristics, specifications, extension points, and rulesets, all of which can be defined in Oracle Communications Design Studio. UIM provides a service topology sample cartridge that is a working example of how you could extend service topology. See UIM Cartridge Guide for more information on the service topology sample cartridge.
Package: oracle.communications.inventory.api.topology
This interface defines the available search criteria for the TopologyEdge entity object and is an input parameter to topology manager and topology mapper interface methods.
Topology logic references the UIM_Home/config/resources/event/ topologyProcess.properties file for specifying the mapper class and for configuring path analysis. You can also use this file to:
Turn off topology updates. If you turn off topology updates, you can rebuild the topology if you need to use a topology-related feature. See UIM System Administrator's Guide for more information.
For example, the file includes the following upon installation:
# disableTopology - turns Topology Refresh On or Off disableTopology=false
Opt whether to update the topology synchronously or asynchronously with business model updates. See UIM System Administrator's Guide for more information.
For example, the file includes the following upon installation:
# processSynchronous - Topology is refreshed as part of the transaction (true) # or asynchronoulsy in a seperate transaction (false) processSynchronous=true