Skip Headers
Oracle® Communications Network Integrity Cisco Router and Switch UIM Integration Cartridge Guide
Release 7.1

E23705-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 About the Cartridge Components

This chapter provides information about the components that comprise the Oracle Communications Network Integrity Cisco Router and Switch UIM Integration Cartridge. The Cisco Router and Switch UIM Integration Cartridge is composed of a number of actions, each containing several processors:

Discover Enhanced Cisco SNMP Action

The Discover Enhanced Cisco SNMP action scans a Cisco device and provides a physical and logical hierarchical model of what is discovered. This action also models the associations between the physical and logical hierarchies.

This cartridge is designed to discover Cisco devices only, and attempts to discover non-Cisco devices result in a scan failure.

Table 5-1 shows the processors that belong to the Discover Enhanced Cisco SNMP action.

Table 5-1 Discover Enhanced Cisco SNMP Action Processors

Component Name

Processor

MIB II Properties Initializer

Processor

Cisco SNMP Properties Initializer

Processor

MIB II SNMP Collector

Processor

MIB II SNMP Modeler

Processor

Cisco SNMP Logical Collector

Processor

Cisco SNMP Physical Collector

Processor

Cisco SNMP Logical Modeler

Processor

Cisco SNMP Physical Modeler

Processor

Cisco Enhanced Modeler Processor


These processors are described in the following sections:

MIB II Properties Initializer Processor

The MIB II Properties Initializer processor outputs the following data sets:

  • snmpVendorNameMap: contains a snapshot of industry enterprise numbers to help identify devices that may be found in the network.

  • snmpIfTypeMap: contains a snapshot of ifTypes to help identify interface types that may be found in the network.

Table 5-2 shows a fragment of each data set provided by the MIB II Properties Initializer:

Table 5-2 Sample Output for MIB II Properties Initializer

Sample snmpIfTypeMap Sample snmpVendorNameMap

1: other (1)

0 = Reserved

2: regular1822 (2)

1 = NxNetworks

3: hdh1822 (3)

2 = IBM

4: ddnX25 (4)

3 = Carnegie Mellon

5: rfc877x25 (5)

4 = UNIX

6: ethernetCsmacd (6)

5 = ACC

7: iso88023Csmacd (7)

6 = TWG

8: iso88024TokenBus (8)

7 = CAYMAN

9: iso88025TokenRing (9)

8 = PSI

10: iso88026Man (10)

9 = ciscoSystems

251: vdsl2 (251)

34730 = FRANCILIENNE D'INGENIERIE ET DE SERVICES INFORMATIQUES SAS


The content of these property files changes occasionally, and they are maintained as part of cartridge revisions. SDK extensions to this cartridge can update the content of the property files. See About Design Studio Extension for more information.

Cisco SNMP Properties Initializer Processor

The Cisco SNMP Properties Initializer processor outputs the following data sets:

  • ciscoProductsMap

  • ciscoVendorNumbers

  • ciscoVendorTypesMap

ciscoProductsMap contains a mapping from the vendor-specific portion of the sysObjectId to Cisco device model name.

Example 5-1 provides an example of the ciscoProductsMap file contents.

Example 5-1 ciscoProductsMap File Content Sample

10 = cisco2000
      10 - represents the device specific portion of the sysObject (for example, 1.3.6.1.4.1.9.1.10)
      cisco2000 - represents the model name

ciscoVendorNumbers contains a list of supported Cisco vendor numbers.

ciscoVendorTypesMap contains a mapping from entPhysicalVendorType to the Cisco equipment part name.

Example 5-2 provides an example of the ciscoVendorTypesMap file contents

Example 5-2 ciscoVendorTypesMap File Content Sample

1.8 = cevOtherCscLink       1.8 – represents the device specific portion of the sysObjectId (i.e. .1.3.6.1.4.1.9.12.3.1.1.8)       cevOtherCscLink – represents the equipment part name.

Table 5-3 shows a fragment of each data set provided by the Cisco SNMP Properties Initializer:

Table 5-3 Sample Output for Cisco SNMP Properties Initializer

Sample ciscoProductsMap Sample ciscoVendorNumbers Sample ciscoVendorTypesMap

1 = ciscoGatewayServer

9

1 = cevOther

2 = ciscoTerminalServer

4857

1.1 = cevOtherUnknownCard

3 = ciscoTrouter

5771

1.2 = cevOtherMoH

4 = ciscoProtocolTranslator

5842

1.3 = cevNmeApaLink

5 = ciscoIGS

7003

1.5 = cevOtherSce8000Scm

6 = cisco3000

N/A

1.6 = cevOtherSce8000Sip

7 = cisco4000

N/A

1.8 = cevOtherCscLink

8 = cisco7000

N/A

2 = cevUnknown

9 = ciscoCS500

N/A

3 = cevChassis

10 = cisco2000

N/A

3.1 = cevChassisUnknown

1294 = ciscoCDScde250

N/A

12.1 = cevMidplaneUmg9820


The content of these property files changes occasionally, and they are maintained as part of cartridge revisions. SDK extensions to this cartridge can update the content of the property files. See "About Design Studio Extension ".

MIB II SNMP Collector Processor

The MIB II SNMP Collector is used to collect SNMP variables from a device. See "About Poll Lists".

MIB II SNMP Modeler Processor

The MIB II SNMP Modeler processor is used to model the data collected from the MIB II SNMP Collector processor. Modeling includes building the hierarchical relationship of logical device and child Interfaces.

Cisco SNMP Logical Collector Processor

The Cisco SNMP Logical Collector processor is used to collect Frame Relay, ATM and VLAN media data from the device. See "About Poll Lists".

Cisco SNMP Physical Collector Processor

The Cisco SNMP Physical Collector processor is used to collect the physical aspects (such as Chassis, Container, Module, Port) of the device. See "About Poll Lists".

Cisco SNMP Logical Modeler Processor

The Cisco SNMP Logical Modeler processor is used to model the data collected from the Cisco SNMP Logical Collector.

Cisco SNMP Physical Modeler Processor

The Cisco SNMP Physical Modeler processor is used to model the data collected from the Cisco SNMP Physical Collector.

Cisco Enhanced Modeler Processor

The Cisco Enhanced Modeler processor is used to programmatically walk the physical device tree and replace the existing generic specification with a specification which makes it complicit with UIM. Predecessor modelers all apply generic specifications to the entities.

Each physical entity has a field called modelName which is inspected for its value. The value is used as the specification name to be applied. The processor checks that the specification exists. If the specification exists, the processor applies that specification to the physical entity, overwriting the generic specification.

If the specification is not found, the generic specification remains and the object does not become UIM complicit. It is not staged for resolution to UIM.

When a physical entity does not have any value for modelName and its name starts with Artificial (a result of model correction invocation), a lookup table (remodeler.properties) is used to determine what specification to apply. See "Model Correction" for further information about model correction.

The lookup table allows you to specify (as an example) the key as "nativeEmsName and parent specification name", and value as the "specification name" to be applied. Model correction can produce many artificial entities, so using nativeEmsName and parent specification name in combination generally allows you to uniquely identify the intended entity in the hierarchy. A specification is applied to the physical entity when its nativeEmsName and parent specification name match.

Controlling modelName Content and Re-applied Specification

Systems Integrators can control the content of modelName, and so control the re-applied specification. The process is outlined as follows:

ciscoVendorType.properties sample
9 = cevModule
9.1 = cevModuleUnknownCard
9.2 = cevModuleCommonCards
9.3 = cevModuleC36xxType
9.4 = cevModuleVipPortAdapters
9.5 = cevModuleCpuType
9.5.1 = cevC7200Io1fe
9.5.2 = cevC7200Io
9.5.3 = cevCpuAS5300
9.5.7 = cevCpuRpm
9.5.8 = cevCpu2600
9.5.9 = cevCpu7200Npe300
9.5.10 = cevCpu1400
9.5.11 = cevCpu800
9.5.12 = cevCpuPSM1Gbps 

The suffix of discoveredModelNumber can have up to three tokens delimited by a "."

If discoveredModelNumber contains 9.5.12, and the lookup table contains 9.5.12 cevCpuPSM1Gbps, this is yielded.

If 9.5.12 is not found, and 9.5 is found, cevModuleCpuType is yielded.

If 9.5.12 and 9.5 are not found, but 9 is found, cevModule is yielded.

If 9.5.12 and 9.5 and 9 are not found, then modelName is populated with “Unknown”.

About remodeler.properties

The Discover Enhanced Cisco SNMP discovery action uses a generic remodeler to apply custom specifications to physical device results.

The process is data driven through a remodeler.properties file. Each line describes a remodeling rule in this format:

setspecification.<entity type>[.<attribute name>.<attribute match criteria>] = [<context>/]<specification>

The possible actions and match criteria for each are listed below.

<entity type> is a type like PhysicalDevice. The rule applies only to entities of this type.

<attribute name>.<attribute match criteria> is optional. If present, the attribute with the specified name must match the attribute match criteria for the rule to apply. Match criteria has rudimentary substring matching. The '*' character can be used for basic wildcarding:

  • SomeString - exact match SomeString

  • SomeString* - starts with SomeString

  • SomeString - ends with SomeString

  • SomeString* - contains SomeString

<context> is optional. If present, the context describes the specification that must be present on the parent entity for the rule to apply. For example, cevContainerPowerSupplyBay/artificial6509PowerSupplyHolderCard only matches an entity if the entity's parent has the specification cevContainerPowerSupplyBay. The context can describe the specifications for multiple ancestors, and not just the parent. In this case, specifications for ancestors are separated by “/”.

<specification> is the name of the specification to apply if the entity matches the rule.

The remodeler walks the physical device tree. For each entity, it looks for a matching rule and applies that specification. Rules are processed in the order that they appear in the property file. Once a rule is applied, processing of that entity stops.

Note:

Standard Java property file format must be followed. In particular, spaces and some other special characters on the left side of the equals must be escaped. For a full description of the Java property file format, consult the java doc for the load() method of the java.util.Properties class.

Devices Supported “Out of the Box”

The Cisco Router and Switch UIM Integration Cartridge is built to support three devices for integration with UIM:

  • cisco3640

  • cisco7206

  • cat6509

It does not support a full library of specifications for all hardware permutations found on these devices. If you try to discover these device instances, you may find certain hardware is not supported. To resolve to UIM, you may have to build up a library of specifications on Network Integrity and UIM to model these devices.

About Cisco Switches

Cisco Switches sometimes run CAT OS not IOS, and entityPhysicalVendorType is sparingly populated, so it cannot serve as the mechanism to identify hardware. To model Cisco switches with specifications staged for UIM, Systems Integrators must make extensive use of the remodeler.properties file, creating a mapping between discovered SNMP values and desired specifications.

Generally speaking, the recommended SNMP variable is entityPhysicalDesc populated into the description field for Equipment. However, different versions of CAT OS may yield varying values for entityPhysicalDesc for the same hardware, so multiple entries may be required if dealing with various OS versions.An example of the use of remodeler.properties is displayed in the following code. The class CiscoEnhancedModelerProcessorImpl contains code

if (discoveredSysObjId.equals(SYSOBJECTID_6509)) {
       new CiscoRemodeler(getClass(),"remodeler.properties").remodelDevice(physicalDevice);
} else {
       new CiscoRemodeler().remodelDevice(physicalDevice);
}

In this example, remodeler.properties is invoked for the Cisco 6509 to handle artificial objects created by model correction.To handle a particular Cisco switch, add another else if statement to identify it, and then invoke a custom remodeler.properties on it.The else statement invokes default properties to use the field modelName as the source for identifying the specification to apply via the mapping table ciscoVendorTypesMap.

Tips for Creating Specifications

This section identifies a number of integration points.

  1. Discovery fills in the field discoveredModelNumber from a SNMP variable entityPhysicalVendorType.

  2. discoveredModelNumber is interrogated, and the suffix is mapped to an entry in the table ciscoVendorTypesMap yielding modelName. modelName is thereby controlled using the content of the ciscoVendorTypesMap table.

  3. modelName as default is used to determine what specification to apply.

  4. If entity nativeEmsName starts with Artificial, and the device is Cisco 6509, remodeler.properties controls what specification to apply.

  5. If modelName is blank or unknown, you must either update ciscoVendorTypesMap or make use of remodeler.properties to model the device staging it for UIM.

If you discover a new device or a version of the three devices the cartridge supports out of the box, the specifications are applied and are visible in the entityType column in the Physical Tree in the Network Integrity UI.

If you see a generic specification in the entityType column in the Physical Tree as opposed to one that starts with “cev”, then you must create a specification for this entity in both Network Integrity and UIM to fully support the device and have it staged for UIM.

For example, if you discover a new device, the modelName field is probably filled with a mapped value from ciscoVendorTypesMap, with a generic specification applied. Inspect modelName for each entity in the tree to ascertain what specification to create and what lineage (parent/child) must be set for UIM. When you execute discovery and you no longer see generic specifications in your Physical Tree, you are ready to resolve the tree to UIM.

Specifications in Network Integrity and UIM must exist, and the names must be equivalent. UIM has more requirements on specifications, in that additional properties must be set including:

  • Parent child relationship and cardinality

  • Number of slots the Equipment card occupies.

Modeling in UIM for Discovery

The Network Integrity to UIM Web service does not consider that equipment could be modeled in UIM such that they are occupying multiple equipment holders (for example, a single equipment occupies two equipment holders).

In cases such as this, the Web service operations treat the child of each equipment holder as having a unique equipment. Consequently, Network Integrity assumes that two unique equipment exist, when it fact there is only one.This is a theoretical issue because, in Network Integrity, you must model equipment specifications in UIM in accordance with how Network Integrity discovers a device. When executing Cisco SNMP discovery, if an equipment instance occupies two equipment holders, this is not discoverable, and the device reports that an equipment instance occupies one equipment holder while the other equipment holder appears empty, even though the equipment physically occupies two equipment holder.To modify discovery and modeling so that the true representation is rendered, custom handling is required in the cartridges and Web service.

Detect Enhanced Cisco Discrepancies Action

The Detect Enhanced Cisco Discrepancies action provides discrepancy capability between discovered and inventoried data in UIM.

Table 5-4 shows the processors that belong to the Detect Enhanced Cisco Discrepancies action.

Table 5-4 Detect Enhanced Cisco Discrepancies Action Processors

Component Name

Processor

MIB II UIM Filters Initializer

Processor

Cisco UIM Filters Initializer

Processor

Discrepancy Detector


These processors are described in the following sections:

MIB II UIM Filters Initializer Processor

The MIB II UIM Filters Initializer processor is used to implement the following filters:

  • Filters are implemented to disregard the ID field for the Logical tree, as this is not a discovered value

  • Filters are implemented to treat Media Interface and Device Interface as the same object. Media Interface is derived from Device Interface, but UIM does not implement Media Interface.

  • Filters are implemented to disregard DeviceInterfaceConfigurationItem, as UIM does not implement it

  • Filters are implemented to ignore CR/LF in LogicalDevice description fields which may not be preserved in UIM

  • Filters are implemented to use the nativeEmsNamefield and EntityType Specification, as the comparator across all entities to determine whether two objects, one from discovery, and one from import, are the same object in the logical tree.

Cisco UIM Filters Initializer Processor

The Cisco UIM Filters Initializer processor is used to implement the following filters:

  • Filters are implemented to ignore CR/LF in PhysicalDevice description fields which may not be preserved in UIM

  • Filters are implemented to use the nativeEmsName field and EntityType Specification, as the comparator across all entities to determine whether two objects, one from discovery, and one from import, are one and the same object for the Physical tree.

Discrepancy Detector Processor

The Discrepancy Detector processor inherits base operations. See the chapter on the Base_Detection_Cartridge and the Default Comparison Algorithm in Network Integrity Developer's Guide.

See also Network Integrity MIB-II UIM Integration Cartridge Guide.

Import Cisco from UIM Action

The Import Cisco from UIM action imports logical and physical device trees from UIM. Set filters in the Import scan to determine what can be imported.

Table 5-5 shows the filters used with the Import Cisco from UIM action.

Table 5-5 Filters Used with Import Cisco from UIM Action

Filter Filter Qualifier Pattern Example

LogicalDeviceId (UIM ID)

EQUALS (default)

EQUALS_IGNORE_CASE

BEGINS_WITH

BEGINS_WITH_IGNORE_CASE

ENDS_WITH

ENDS_WITH_IGNORE_CASE

CONTAINS

CONTAINS_IGNORE_CASE

MgmtIPAddress::sysName::"LogicalDevice"

10.156.68.136.rot3640-11.LogicalDevice

Name

EQUALS

EQUALS_IGNORE_CASE

BEGINS_WITH (default)

BEGINS_WITH_IGNORE_CASE

ENDS_WITH

ENDS_WITH_IGNORE_CASE

CONTAINS

CONTAINS_IGNORE_CASE

sysName

rot3640-11

Mgmt Ip Address

EQUALS (default)

EQUALS_IGNORE_CASE

BEGINS_WITH

BEGINS_WITH_IGNORE_CASE

ENDS_WITH

ENDS_WITH_IGNORE_CASE

CONTAINS

CONTAINS_IGNORE_CASE

 

10.10.10.10

AssignmentState

EQUALS

UNASSIGNED

ASSIGNED

PENDING_UNASSIGN

PENDING_ASSIGN

DISCONNECTED

TRANSITIONAL

PORTED

The following patterns are in the enum but are not supported in UIM:

UNAVAILABLE

PENDING_UNAVAILABLE

PENDING_AVAILABLE

 

AdminState

EQUALS

INSTALLED

END_OF_LIFE

PENDING_INSTALL

PENDING_UNAVAILABLE

UNAVAILABLE

PENDING_REMOVE

PLANNED

 

The import functionality is implemented to

  1. Retrieve all the Logical Device IDs that match the filter criteria and have the specification deviceGeneric.

  2. Iterate over each ID to:

    • Retrieve the logical device tree and the associated physical device tree from UIM, while caching the ID of the Physical Device.

    • Persist the logical and physical device trees.

  3. Retrieve all the Physical Device IDs that match the filter criteria (if LogicalDeviceId is not set).

  4. Iterate over each Physical Id, if it is not already cached.

    1. Retrieve the physical device tree from UIM.

    2. Persist the physical device trees.

This action provides UI parameters that allow you to set filters when creating an import scan. The filters determine the set of entities included in the import scan.

Cisco UIM Initializer Processor

The Cisco UIM Initializer processor instantiates the cache used to hold physical devices Ids as they are retrieved.

Logical Device UIM Finder Processor

The Logical Device UIM Finder processor retrieves logical device Ids that match the filter criteria. Retrieval is done using ora_ni_uim_webservice operations.

The implementation includes filtering for logical devices that are constructed with the specification “deviceGeneric”, and interfaces with the specification “interfaceGeneric”. Any logical device using another logical device specification cannot be imported without custom handling.

A logical device with a specification other then “deviceGeneric” is not imported.

A DeviceInterface with a specification other then interfaceGeneric is not imported.

The interface branch is pruned at the parent object. An error indicator is displayed in the Network Integrity UI to indicate pruning has taken place. If interfaces with other specifications are required, you must implement custom handling.

An example of the error indicator is seen below. Serial0/0 has a subInterface with a foreign specification and so was pruned

Figure 5-1 shows an example of an error indicator. Serial0/0 has a subInterface with a foreign specification and was pruned.

Figure 5-1 Error Indicator

Error Indicator

MIB II UIM Importer Processor

The MIB II UIM Importer processor retrieves and processes the logical device tree from UIM. Fetching is done using ora_ni_uim_webservice operations.

See Network Integrity MIB-II UIM Integration Cartridge Guide.

Physical UIM Modeler Processor

The Physical UIM Modeler processor retrieves and processes the physical device tree from UIM. Retrieval is done using ora_ni_uim_webservice operations.

MIB II UIM Persister Processor

The MIB II UIM Persister processor stores the Device tree in Network Integrity.

Physical Device UIM Finder Processor

The Physical Device UIM Finder processor retrieves physical device Ids that match the filter criteria. Retrieval is done using the ora_ni_uim_webservice operations.

Physical Device UIM Importer Processor

The Physical Device UIM Importer processor retrieves and processes the physical device tree from UIM. Any physical device Ids that are found in the cache are disregarded. Fetching is done using the ora_ni_uim_webservice operations.A physical device with a foreign specification is not imported.A child object with a foreign specification is not imported. The child branch is pruned at the parent object. An error indicator is displayed in the Network Integrity UI to indicate pruning has occurred. If objects with other specifications are required, custom handling must be implemented.

Note:

Foreign specification means that this Network Integrity cartridge is not aware of the specification as it does not exist in the cartridge.

Physical Device UIM Persister Processor

The Physical UIM Persister processor stores the physical device tree in Network Integrity.

Resolve Cisco in UIM Action

The Resolve Cisco in UIM action resolves discrepancies between Network Integrity discovery and UIM Import. In other words, the action constructs and updates logical and physical device trees in UIM.

The implementation instantiates a class called BaseResolutionElement, which acts as a “triage system”. Handlers registered into BaseResolutionElement deal with particular entities.

When you submit one or more discrepancies to be resolved to UIM, the batch of discrepancies is sent to the BaseResolutionElement, which sets the order and priority of the discrepancies. BaseResolutionElement then calls entity handlers to dispatch the resolution to UIM. The entity handlers use the ora_ni_uim_webservice to communicate with UIM.

Note:

ora_ni_uim_device_sample and ora_ni_uim_cisco_device_sample cartridges must be installed in UIM for this action to function.

Table 5-6 displays the handlers called by BaseResolutionElement and their corresponding discrepancy types and definitions.

Table 5-6 Discrepancy Handling

Handler Discrepancy Type

Logical Device Handler

Entity+ (Entity is missing from UIM)

Attribute Value Mismatch (Entity has field value that differs)

Assoc+ (Peer entities are missing association between them)

Assoc- (Peer entities not discovered to be peers in discovery)

Device Interface Handler

Entity+

Entity- (Entity is in UIM but not discovered)

Attribute Value Mismatch

Assoc+

Assoc-

Physical DeviceHandler

Entity+

Attribute Value Mismatch

Assoc+

Assoc-

EquipmentHandler

Entity+

Entity-

Attribute Value Mismatch

Assoc+

Assoc-

EquipmentHolderHandler

Entity+

Entity-

Attribute Value Mismatch

Assoc+

Assoc-

PhysicalPortHandler

Entity+

Entity-

Attribute Value Mismatch

Assoc+

Assoc-


Table 5-7 shows the processors that belong to the Resolve Cisco in UIM action.

Table 5-7 Resolve Cisco in UIM Action Processors

Component Name

Processor

Resolution Framework Initializer

Processor

MIB II UIM Resolution initializer

Processor

Cisco UIM Filters Initializer

Processor

Resolution Framework Dispatcher


These processors are described in the following sections:

Resolution Framework Initializer Processor

The Resolution Framework Initializer processor is used to instantiate the BaseResolutionElement and the Web service connection class.

BaseResolutionElement evaluates discrepancies, which are then processed serially to UIM. Ordering is enforced to ensure that for example you create a LogicalDevice before you create a DeviceInterface. Ordering between logical and physical is random.

Table 5-8 lists the order of execution of discrepancies.

Table 5-8 Discrepancy Execution Order

Discrepancy Type Entity Type

Attribute Value Mismatch

All

Assoc-

DeviceInterface

PhysicalPort

Assoc-

LogicalDevice

PhysicalDevice

Entity-

DeviceInterface

Equipment

EquipmentHolder

PhysicalPort

Entity-

LogicalDevice

PhysicalDevice

Entity+

LogicalDevice

PhysicalDevice

Entity+

DeviceInterface

Equipment

EquipmentHolder

PhysicalPort

Assoc+

LogicalDevice

PhysicalDevice

Assoc+

DeviceInterface

PhysicalPort


MIB II UIM Resolution Initializer Processor

The MIB II UIM Resolution Initializer processor registers Entity Handlers into BaseResolutionElement. The following handlers are registered by this processor:

  • LogicalDeviceHandle

  • DeviceIntefaceHandler

Cisco UIM Filters Initializer Processor

The Cisco UIM Resolution Initializer processor registers Entity Handlers into BaseResolutionElement. The following handlers are registered by this processor:

  • PhysicalDeviceHandler

  • EquipmentHandler

  • EquipmentHolderHandler

  • PhysicalPortHandler

Resolution Framework Dispatcher Processor

The Resolution Framework Dispatcher processor is used to trigger BaseResolutionElement to evaluate and treat discrepancies using the registered entity handlers.

The entity handler creates a Web service message and populates data into the body of the message. The connection to UIM is established if it does not exist. The Web service message is sent to UIM. The entity handler waits for the response. When the response is received, it is inspected to observe the outcome. If a success message is returned, the discrepancy is marked success, if the message returns fail, or Exception, the discrepancy is marked fail. See Oracle Communications Network Integrity UIM Sample Web Service Guide for more details and examples.

Note:

There is no transaction handling across the Web service. If a discrepancy resolution is successful, a subsequent discrepancy resolution failure in the batch does not roll back the successful discrepancy resolution.

Each discrepancy resolution is an independent event.

The position of the object being treated in the hierarchy is significant. For example, an Entity+ for a logical device means that a logical device and all children interfaces is to be created. If the creation of one of the child entities fails, the rest of the entities continue to be created, but a fail message is sent to the discrepancy resolution result. In effect, creation is a “best effort” mechanism.

The same applies to device interfaces. For an Entity+ for a DeviceInterface, the handler attempts to create the device interface and all of its children subDeviceInterfaces where applicable.

Supported Creation Scenarios in UIM

This section lists supported creation scenarios in UIM:

Creation of a Logical Device and Physical Device

The first scenario deals with the creation of a logical device and physical device (with Network Integrity IDs) in UIM.

If there are no pre-existing logical device and physical device in UIM, you should see Entity+ for the root logical device and root physical device.Resolution of these two entities executes such that the entire logical device tree is created. The logical device tree attempts to create associations to the physical device tree (which does not exist yet), and association creation fails.

This is followed by creation of the physical device tree. The physical device tree attempts to create associations to the logical device tree. This succeeds, and the tree is complete. The events could occur in the reverse order as well.

Creation of the logical device tree includes logical device, and children device interfaces or subInterfaces.

Creation of the physical device tree includes physical device, and children equipment, equipment holders, and physical ports.

Creation of any object in the tree is dependent on the Id not being occupied. If the Id is occupied, object creation aborts, as it does for any children objects. If any objects fail to be created, the root object that initiated creation is marked fail or partial fail in the logs. However, parts of the tree may be fully created and available in UIM.

Aborting does not roll back any successfully created objects. The next round of import, discovery, and discrepancy detection highlights which objects do, and which do not exist, allowing you to continue resolution operations.

When objects are about to be created in UIM, no search is carried out to see if the object already exists in UIM with the same name/nativeEmsName. UIM does not guarantee name uniqueness.

If you find an object with the desired name and no children objects, you could adopt it in place of creating it. If two objects are found with the same name, custom handling is required. If an object is found with children objects, custom handling is required. If an object is found already participating in a tree, custom handling is required.

So in summary, the standard behavior is to create objects with the Network Integrity ID pattern. If the ID is occupied, creation aborts. Resolution does not search by name for existing objects; it creates them instead. Handling duplicate objects is usually carried out by a UIM administrator or system integrator to customize handling.

Creation of a Logical Device

If a physical device tree exists in UIM with Network Integrity IDs, but the logical device does not, you should see Entity+ for the logical device.

Resolution of the entity executes such that the logical device and any children of the logical device are created. As each object is created, where applicable, it is associated to the physical device tree.

Creation of a Device Interface

If a logical device exists in UIM but is missing a child device interface, you should see Entity+ for the device interface.Resolution of this entity executes such that the device interface and any children of the device interface are created. As each object is created, where applicable, it is associated to the physical port object.

Creation of a Physical Device

If a logical device tree exists in UIM with Network Integrity IDs but the physical device does not, you should see Entity+ for the physical device.Resolution of this entity executes such that the physical device and any children of the physical device are created. As each object is created, where applicable, it is associated to the logical device tree.

Creation of an Equipment

If a parent of an equipment exists in UIM with Network Integrity ID, but the equipment does not, you should see Entity+ for the equipment.Resolution of this entity executes such that the equipment and any children of the equipment are created. As each object is created, where applicable, it is associated to the logical device tree.

Creation of an Equipment Holder

If a parent of an equipment holder (that is, an equipment) exists in UIM with Network Integrity ID, but the equipment holder does not, you should see Entity+ for the equipment holder.Resolution of this entity executes such that the equipment holder and any children of the equipment holder are created. As each object is created, where applicable, it is associated to the logical device tree.

Creation of a Physical Port

If a parent of a physical port (that is, an equipment) exists in UIM with Network Integrity ID, but the physical port does not, you should see Entity+ for the physical port.Resolution of this entity executes such that the physical port is created. As each object is created, where applicable, it is associated to the device interface.

Creation of an Association between Logical Device and Physical Device

If a logical device and physical device exist in UIM with Network Integrity IDs, but the association between them does not exist, you should see two Assoc+. Associations are bidirectional; but discrepancy detection interrogates each object in isolation resulting in two Assoc+, one from the physical device side and the other from the logical device side.Resolution of the Assoc+ executes such that the logical device to physical device association is created. Then, an attempt is made to create the physical device to logical device association. The Web service detects the association already exists and returns success. These events can also happen in reverse.

Creation of an Association between Device Interface and Physical Port

If a device interface and physical port exist in UIM with Network Integrity IDs, but the association between them does not exist, you should see two Assoc+. Associations are bidirectional; but discrepancy detection interrogates each object in isolation resulting in two Assoc+, one from the device interface side and the other from the physical port side.Resolution of the Assoc+ executes such that the device interface to physical port association is created. Then, an attempt is made to create the physical port to device interface association. The Web service detects the association already exists and returns success. These events can also happen in reverse.

Teardown, Deletion, and Removal Scenarios in UIM

This section lists supported teardown scenarios in UIM:

Teardown of Association between Device Interface and Physical Port

If a device interface and physical port exist in UIM with incorrect associations between them, you should see two Assoc-. Associations are bidirectional; but discrepancy detection interrogates each object in isolation, resulting in two Assoc-, one from the device interface side and the other from the physical port side. Resolution of the Assoc- executes such that the device interface to physical port association is deleted. Then, an attempt is made to delete the physical port to device interface association. The Web service detects the association does not exist and returns success. The events can also happen in reverse.

Teardown of Association between Logical Device and Physical Device

If a logical device and physical device exist in UIM with incorrect associations between them you should see two Assoc-. Associations are bidirectional; but discrepancy detection interrogates each object in isolation resulting in two Assoc-, one from the logical device side and the other from the physical device side.

Resolution of the Assoc- executes such that the logical device to physical device association is deleted. Then an attempt is made to delete the physical device to logical device association. The Web service detects the association does not exist and returns success. The events can also happen in reverse.

Deletion of a Physical Port

If a physical port, a child of an equipment, exists in UIM, but it is not discovered, you should see Entity-. Resolution of the Entity- executes such that the physical port is deleted.

Note:

The physical port does not exist in isolation. It must exist under a parent object.
Deletion of an Equipment Holder

If an equipment holder, a child of an equipment, exists in UIM, but it is not discovered, you should see Entity-. Resolution of the Entity- executes such that the equipment holder is deleted.

Note:

The equipment holder does not exist in isolation. It must exist under a parent object.
Deletion of a Device Interface

If a device interface, a child of a logical device or a device interface, exists in UIM, but it is not discovered, you should see Entity-. Resolution of the Entity- executes such that the device interface is deleted.

Note:

The device interface does not exist in isolation. It must exist under a parent object.
Removal of an Equipment from a Physical Device Tree

If an equipment, child of another equipment or physical device, exists in UIM, but is not discovered, you should see Entity-. Resolution of the Entity- executes such that the equipment is unlinked from the parent.

Note:

Equipment do exist in isolation. This equipment continues to exist in UIM until an administrator manually deletes it.

Mismatched Data Scenarios

The following fields are ignored:

  • Id is not a discovered field

  • nativeEmsName is used for matching objects and is not treated for mismatch

  • DeviceInterfaceConfigurationItem exists only in Network Integrity, and not in UIM

The following sections describe mismatched data scenarios:

Mismatch of Logical Device Data

If a logical device in UIM has data that does not match the data discovered, you should see Mismatch.

Resolution updates the mismatched logical device attribute in UIM, setting the UIM value to the discovered value.

Mismatch of Device Interface Data

If a device interface in UIM has data that does not match the data discovered, you should see Mismatch.

Resolution updates the mismatched device interface attribute in UIM, setting the UIM value to the discovered value.

Mismatch of Logical Device Data

If a logical device in UIM has data that does not match the data discovered, you should see Mismatch.

Resolution updates the mismatched device interface attribute in UIM, setting the UIM value to the discovered value.

Mismatch of Physical Device Data

If a physical device in UIM has data that does not match the data discovered, you should see Mismatch.

Resolution updates the mismatched physical device attribute in UIM, setting the UIM value to the discovered value.

Mismatch of Equipment Data

If an equipment in UIM has data that does not match the data discovered, you should see Mismatch.

Resolution updates the mismatched equipment attribute in UIM, setting the UIM value to the discovered value.

Mismatch of Equipment Holder Data

If an equipment holder in UIM has data that does not match the data discovered, you should see Mismatch.

Resolution updates the mismatched equipment holder attribute in UIM, setting the UIM value to the discovered value.

Mismatch of Physical Port Data

If a physical port in UIM has data that does not match the data discovered, you should see Mismatch.

Resolution updates the mismatched physical port attribute in UIM, setting the UIM value to the discovered value.

Working with Foreign IDs

Working with foreign IDs is almost the same as working with Network Integrity-generated IDs. However, there are a few caveats to resolution behavior.For mismatch scenarios, there is no distinction between working with foreign IDs or Network Integrity-generated IDs. For any teardown scenarios (Entity- or Assoc-), there is no distinction between working with foreign IDs or Network Integrity-generated IDs.For creation scenarios (Entity+, Assoc+), there are caveats to creating objects if those objects must have associations to preexisting objects in UIM with foreign IDs. The following sections highlight the caveats and resolution behavior.

Working with Foreign IDs: Scenario 1

In this scenario, discovery discovers a logical device (LD) tree and physical device (PD) tree and builds the associations.

Discovery assigns Network Integrity generated IDs to all objects (where E is equipment; DI is device interface; PP is physical port):

LD (x) ------- PD (y)

DI (x1) E (y1)

DI (x2) ------- PP (y2)

Import imports only the physical device tree; the logical device tree does not exist. The physical device tree uses foreign IDs.

PD (z) E (z1) PP (z2)x and xN ID is generated by Network Integrityy and yN ID is generated by Network Integrityz and zN ID is generated by UIM (foreign ID)

Discrepancy detection generates:

  • Entity+ for missing logical devices in UIM

  • Assoc+ for missing associations between physical devices and logical devices in UIM

  • Assoc+ for missing associations between physical ports and device interfaces in UIM

Use Case 1:

In this use case, if you submit Entity+ only for treatment, the following steps take place:

  1. Network Integrity creates the logical device, using the Network Integrity generated ID of x.

  2. Network Integrity attempts to create the association between the logical device (x) and physical device (y) as part of step 1. The discrepancy object being treated only has knowledge of LD(x) and PD(y). Network Integrity attempts to create this association, but PD(y) does not exist in UIM. The Entity+ resolution is marked partial fail. PD(z) is not accessible in the discrepancy object at the time of resolution and so cannot be accounted for

  3. Network Integrity attempts to create DI(x1) and succeeds.

  4. Network Integrity attempts to create DI(x2). Creation of DI(x2) succeeds, the association to PP(y2) fails for same reason cited in step 2. A partial failure occurs.

  5. The resolution on the Entity+ is marked fail (Entity+ creates the root object and all children).

  6. The logical device tree now exists in UIM without the associations to the physical device tree. The failure or partial failure is valid

  7. If you run another round of import, discovery, resolution, the Assoc+ is treated and the trees are synchronized.

Use Case 2:

In this use case, if you submit Entity+ and Assoc+ together for treatment, the following steps take place:

  1. Network Integrity creates the logical device, using the Network Integrity generated ID of x.

  2. Network Integrity attempts to create the association between the logical device (x) and physical device (y) as part of step 1. The discrepancy object being treated only has knowledge of LD(x) and PD(y). Network Integrity attempts to create this association, but PD(y) does not exist in UIM. The Entity+ resolution is marked partial fail. PD(z) is not accessible in the discrepancy object at the time of resolution and so cannot be accounted for.

  3. Network Integrity attempts to create DI(x1) and succeeds.

  4. Network Integrity attempts to create DI(x2). Creation of DI(x2) succeeds, the association to PP(y2) fails for same reason cited in step 2. A partial failure occurs.

  5. The resolution on the Entity+ is marked fail (Entity+ creates the root object and all children).

  6. Network Integrity treats the Assoc+ on the PD(z). Network Integrity succeeds in associating the physical device to the logical device.

  7. Network Integrity treats the other Assoc+ on the PP(z2). Network Integrity succeeds in associating the physical port to the device interface.

  8. The two Assoc+ are marked successful.

  9. The logical device tree now exists in UIM with the associations to the physical device tree. The trees are correct. The failure on the Entity+ is now a false positive failure. Treatment by the Assoc+ completed the tree lineage.

  10. If you do another round of import, discovery, resolution, you should get no discrepancies.

Working with Foreign IDs: Scenario 2

The same use cases are true if the logical device and physical device scenarios outlined in "Working with Foreign IDs: Scenario 1" are revered.

In general, handling of foreign IDs is feasible, but may take up to two passes of import, discovery, and resolution to fully synchronize Network Integrity with UIM. If handling of foreign IDs in a single pass is required, resolution should be modified to take the auxiliary object (associated object) into account.

Swapping Cards

This section outlines the swapping of cards on physical device tree. This is a super set of several events listed above.

The following details show how this is observed in Network Integrity and UIM, and what you must be aware of. Generally speaking, this is not supported “out of the box”, but could be carried out with custom handling.

Step 1:

Two trees are discovered:A, (1) B, (2) F, (6)D, (4) E, (5) C (3):

The trees are created in UIM.

Step 2:

A user swaps two cards on the device, C and F, such that a new discovery should look like:

A, (1)

B, (2)

F, (6)

D, (4)

E, (5)

C (3)

Step 3:

  • The user imports data from UIM.

  • The user runs discovery

  • The user gets two pairs of discrepancies

    • Entity- on B (indicating card C is missing in discovery, but is present in import)

    • Entity+ on B also (indicating card F is present in discovery, but is missing in import)

    • Entity - on E (indicating card F is missing in discovery, but present in import)

    • Entity + on E (indicating card C is present in discovery but missing in UIM)

  • The user submits resolutions

  • Entity- is prioritized before Entity+

  • Entity- causes F (6) and C (3) to be unlinked from parent and F(6) and C(3) sit orphaned in UIM

  • Entity- succeeds

  • Entity+ attempts to create C3 and F6.

  • Entity + aborts or fails because a check is first carried out to see whether 3 and 6 exist. Because they do, the ids required are occupied. Entity+ fails

Step 4:

  • The user does another round of import, discovery, resolution

  • Discrepancy detection shows a pair of Entity+

  • The user submits resolutions

  • Entity+ attempts to create C3 and F6.

  • Entity + aborts or fails because a check is first carried out to see whether 3 and 6 exist. Because they do, the ids required are occupied. Entity+ fails

Step 5:

  • Resolution does not work

  • The user must delete C(3) and F(6) from UIM manually

  • The user must run another round of import, discovery, resolution

  • This time, resolution succeeds in creating C(3) and F(6), and links them into the tree.

Step 6:

At this point, custom handling is required. Typically, a systems integrator can modify the resolution handling to search for objects by name/nativeEmsName before they are created. If the objects are found, they can be adopted, instead of creating them.

See "Creation of a Logical Device and Physical Device" for further information.

Running Multiple Scenarios in Parallel

All of the above scenarios depict individual discrepancies and how they are treated. In reality, you could have multiple discrepancies. If you selected all discrepancies for resolution, Network Integrity and UIM incorporate prioritization to ensure ordering is correct and execute all selected events in the following order:

  • Mismatch

  • Assoc-

  • Entities-

  • Entities+

  • Assoc+

If you select a batch of discrepancies, you must ensure that dependencies between the discrepancies in the selected batch can be met. If a dependency is not met, then resolution may fail.For example, if an equipment exists in an equipment holder, but does not belong there, you must unlink it (Entity-) before you can create and link the correct one (Entity+). Attempting the latter action without doing the former results in failure.

Running Multiple Scenarios in Parallel

The name/nativeEmsName and Id field play pivotal roles in import and resolution. Table 5-9 summarizes the view of these fields from the discovery perspective.

Table 5-9 View of nameEmsName and Id field from Discovery

Entity Name NativeEmsName Field ID field

Physical Device

sysName

sysName

MgmtIPAddress::sysName::"0"::"PhysicalDevice"

Equipment

entPhysicalDescr

entPhysicalDescr:: [absRelativePosition]

MgmtIPAddress::sysName::[absRelativePosition]::"Equipment.Rack|Shelf|Card"

Equipment Holder

entPhysicalDescr

and

entPhysicalParentRelPos

entPhysicalParentRelPos (also known as Slot#)

MgmtIPAddress::sysName::[absRelativePosition]::"EquipmentHolder"

Physical Port

entPhysicalDescr

and

entPhysicalParentRelPos

entPhysicalParentRelPos (also known as Port#)

MgmtIPAddress::sysName::[absRelativePosition]::"PhysicalPort"

Logical Device

sysName

sysName

MgmtIPAddress::sysName::"LogicalDevice"

Device Interface

ifDescr

ifDescr

MgmtIPAddress::sysName::ifDescr::ifName::"MediaInterface"


If you want to change this naming and ID convention, this convention can be modified by adding a new processor to the discovery chain and walking the tree, renaming or generating new IDs of the objects as required.