This chapter describes the components of Oracle Communications Network Integrity UIM Integration cartridge.
The UIM Integration cartridge is composed of the following actions, each containing processors:
The Abstract Import from UIM action imports data from Oracle Communications Unified Inventory Management (UIM). This is an abstract action without any scan parameters. Using various filter criteria, this action interacts with the UIM Integration web service to find devices and then to import and model logical devices and physical devices.
The Abstract Import from UIM action contains the following processors run in the following order:
Figure 2-1 shows the processor workflow of the Abstract Import from UIM action.
Figure 2-1 Abstract Import from UIM Action Processor Workflow
This processor outputs variable filters of type DeviceFilter with default values populated; uimImportContext of type UIMImportContext, which contains a context used by multiple processors; and uimLogicalDeviceIDs and uimPhysicalDeviceIDs of type Set.
Table 2-1 shows the available filter properties with default values. The Effective Type column indicates how the value is used, including whether wildcards are supported. Note that the value Text* in the Effective Type column is multi-value and a comma-separated list.
Property Name | Java Type | Effective Type | Default | Notes |
---|---|---|---|---|
logicalDeviceName |
String |
Text* |
N/A |
Supports comma-separated list for multiple values. |
physicalDeviceName |
String |
Text* |
N/A |
Supports comma-separated list for multiple values. |
logicalDeviceSpecification |
String |
Text |
N/A |
The specification name for a logical device. |
physicalDeviceSpecification |
String |
Text |
N/A |
The specification name for a physical device. |
logicalDeviceInventoryState |
String |
Enum |
N/A |
Available values:
|
physicalDeviceInventoryState |
String |
Enum |
N/A |
Available values:
|
networkLocationEntityCode |
String |
Text* |
N/A |
Supports comma-separated list for multiple values. This can be used to search for devices at a particular location, a specific device at a specific location, and all devices with a particular entity code across multiple network locations. |
queryLogicalDevices |
boolean |
Boolean |
true |
If false, it does not perform a logical device query. |
queryPhysicalDevices |
boolean |
Boolean |
true |
If false, it does not perform a physical device query. |
importRelatedPhysicalOrLogicalDevice |
boolean |
Boolean |
true |
If false, it imports devices that explicitly match filter criteria. It does not automatically import related device for a matched device. For example, if you want to import only logical devices, set Query Physical Devices to "false" and Import Related Physical or Logical Device to "false". |
logicalDeviceCharacteristics |
Map<String, String> |
Text, Text* (name, value) |
null |
A map of characteristic name to characteristic value.This allows searching on multiple, arbitrary characteristic name/value pairs. An extending action typically does not allow you to enter the name. The name is set internally for a field that specifies the value (for example, Mgmt IP Address). |
physicalDeviceCharacteristics |
Map<String, String> |
Text, Text* (name, value) |
null |
A map of characteristic name to characteristic value.This allows searching on multiple, arbitrary characteristic name/value pairs. An extending action typically does not allow you to enter the name. The name is set internally for a field that specifies the value (for example, Mgmt IP Address). |
This processor uses the filters uimImportContext, uimLogicalDeviceIDs, and uimPhysicalDeviceIDs as input parameters; performs one or more Logical Device find operations through the UIM web service API; and updates uimLogicalDeviceIDs and uimPhysicalDeviceIDs.
This processor uses the following filter properties:
logicalDeviceName
logicalDeviceSpecification
logicalDeviceInventoryState
networkLocationEntityCode
queryLogicalDevices
importRelatedPhysicalOrLogicalDevice
logicalDeviceCharacteristics
This processor uses the filters uimImportContext, uimLogicalDeviceIDs, and uimPhysicalDeviceIDs as input parameters; performs one or more physical device find operations through the UIM web service API; and updates uimLogicalDeviceIDs and uimPhysicalDeviceIDs.
This processor uses the following filter properties:
physicalDeviceName
physicalDeviceSpecification
physicalDeviceInventoryState
queryPhysicalDevices
importRelatedPhysicalOrLogicalDevice
physicalDeviceCharacteristics
This processor uses the filters uimImportContext, uimPhysicalDeviceIDs, and uimLogicalDeviceID (from uimLogicalDeviceIDs For loop) as input parameters; imports and models the specified device; and outputs ldev (the modeled logical device) and uimLDev (the UIM web service logical device).
Instead of using hardcoded specifications for logical device and device interface, the UIM specification name is mapped to a Network Integrity specification name.
When creating a device interface, this processor instantiates either DeviceInterface or MediaInterface based on the type received from UIM.
This processor uses the filters uimImportContext, uimPhysicalDeviceIDs, ldev, and uimLDev as input parameters; imports and models the specified physical device; outputs pdev (the modeled physical device).
Instead of using hardcoded specifications for physical entities, the UIM specification name is mapped to a Network Integrity specification name.
This processor removes the processed physical device from uimPhysicalDeviceIDs.
This processor stores the results associated with logical devices in Network Integrity.
This processor uses the filters uimImportContext and uimPhysicalDeviceID (from uimPhysicalDeviceIDs For loop) as input parameters, imports and models the specified physical device, and outputs pdev (the modeled physical device).
Instead of using hardcoded specifications for physical entities, the UIM specification name is mapped to a Network Integrity specification name.
This processor stores results associated with physical devices in Network Integrity.
The Import from UIM action extends the Abstract Import from UIM action by adding scan parameters. This action initializes filters from the scan parameters.
The import functionality is implemented to:
Retrieve all the logical device IDs that match the filter, and the physical device IDs of associated devices.
Retrieve all the physical device IDs that match the filter, and the logical device IDs of associated devices.
Iterate over each logical device ID to:
Retrieve and model the logical device
Retrieve and model the associated physical device (if any)
Persist the logical and physical device trees
Iterate over each physical device ID not already processed to:
Retrieve and model the physical device
Persist the logical and physical device trees
This import action extends the Abstract Import from UIM action and inherits all its processors. See "Abstract Import from UIM Action" for more information.
The Import from UIM action contains the following processors run in the following order:
Import UIM Initializer (inherited)
Logical Device UIM Finder (inherited)
Physical Device UIM Finder (inherited)
Logical Device UIM Importer (inherited)
Linked Physical Device UIM Importer (inherited)
Logical Device UIM Persister (inherited)
Physical Device UIM Importer (inherited)
Physical Device UIM Persister (inherited)
Figure 2-2 shows the workflow of processors of the Import from UIM action.
Figure 2-2 Import from UIM Action Processor Workflow
This processor uses filters as input parameters and sets filter values based on the scan parameters. For more information about the scan parameter groups associated with this action, see "Scan Parameter Groups".
The Abstract Detect UIM Discrepancies action detects discrepancies between discovered data and the data imported from UIM.This discrepancy detection action extends the Detect Discrepancies action (from the NetworkIntegritySDK cartridge) and inherits all its processors. For information about the inherited processors in this action, see Network Integrity Developer's Guide.
The Abstract Detect UIM Discrepancies action contains the following processors run in the following order:
Discrepancy Detector (inherited)
Figure 2-3 illustrates the processor workflow of the Abstract Detect UIM Discrepancies action.
Figure 2-3 Abstract Detect UIM Discrepancies Action Processor Workflow
This processor implements the following filters:
Ignore the ID field on all entities.
Treat Media Interface and Device Interface as the same objects.
Ignore DeviceInterfaceConfigurationItem.
Instead of the name field, use the nativeEMSName field as the comparator across all entities to determine whether the objects from discovery and import are same.
On a logical device, ignore the networkLocationEntityCode and deviceIdentifier fields.
The Abstract Resolve in UIM action resolves discrepancies between Network Integrity discovery data and UIM import data by constructing and updating logical device 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 ora_ni_uim_webservice to communicate with UIM.
In UIM, you can create an entity only if the specification on which the entity is based already exists. The NI discrepancy detection process uses entity specifications to discern information about entities based on them.
When modeling your inventory solution, Oracle recommends that you follow a consistent naming convention when defining entity specifications within both the Import and Discovery processors to allow the discrepancy resolution process to resolve entity discrepancies more efficiently.
The Network Integrity discrepancy resolution process creates the entities in a hierarchical fashion within UIM and each entity in the hierarchy is created using a separate transaction. If any failure occurs during the discrepancy resolution process, the process stops and displays an error message.
Table 2-2 lists the handlers called by BaseResolutionElement and their corresponding discrepancy types and definitions.
Table 2-2 Handler Discrepancy Types
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 Device Handler |
Entity+ Attribute Value Mismatch Assoc+ Assoc- |
Equipment Handler |
Entity+ Entity- Attribute Value Mismatch Assoc+ Assoc- |
Equipment Holder Handler |
Entity+ Entity- Attribute Value Mismatch Assoc+ Assoc- |
Physical Port Handler |
Entity+ Entity- Attribute Value Mismatch Assoc+ Assoc- |
The Abstract Detect UIM Discrepancies action contains the following processors run in the following order:
Figure 2-4 illustrates the processor workflow of the Abstract Resolve in UIM action.
Figure 2-4 Abstract Resolve in UIM Action Processor Workflow
The UIM Resolution Framework Initializer processor instantiates BaseResolutionElement and the web service connection class.
BaseResolutionElement evaluates discrepancies, which are then processed serially to UIM. Ordering is enforced to ensure, for example you create a Logical Device before you create a DeviceInterface.
This processor produces uimResolutionContext of type UimResolutionContext as output.
This processor configures a default specification mapper that does not map and return the specification name that is passed in.
Table 2-3 shows the order of execution of discrepancies.
Table 2-3 Discrepancy Execution Order
Discrepancy Type | Entity Type |
---|---|
Attribute Value Mismatch |
All |
Assoc- |
DeviceInterfacePhysicalPort |
Assoc- |
LogicalDevicePhysicalDevice |
Entity- |
DeviceInterface Equipment EquipmentHolder PhysicalPort |
Entity- |
LogicalDevicePhysicalDevice |
Entity+ |
LogicalDevicePhysicalDevice |
Entity+ |
DeviceInterface Equipment EquipmentHolder PhysicalPort |
Assoc+ |
LogicalDevice PhysicalDevice |
Assoc+ |
DeviceInterface PhysicalPort |
This processor registers the following handlers required for physical and logical device resolution:
LogicalDeviceHandler
PhysicalPortHandler
DeviceIntefaceHandler
PhysicalDeviceHandler
EquipmentHandler
EquipmentHolderHandler
This processor uses the registered entity handlers to trigger BaseResolutionElement to evaluate and treat discrepancies.
The entity handler creates a web service message and populates data into the body of the message. The entity handler connects to UIM. UIM receives the web service message. If a success message is returned, the discrepancy is marked Success. If a fail or exception message is returned, the discrepancy is marked Fail.
Note:
There is no transaction handling across the web service. If a discrepancy is successful, a subsequent discrepancy failure in the batch does not roll back the former. Each discrepancy is an independent event.The position of the object being treated in the hierarchy is significant. For example, for an Entity+ discrepancy on a logical device, you create a logical device and all child interfaces. Even if the creation of one of the child entities fails, the remaining entities continue to be created, but a Failed message is sent to the discrepancy resolution result.
For an Entity+ discrepancy on a device interface, the handler creates the device interface and all of its child sub device interfaces.
This section describes the following creation scenarios, which are supported in UIM:
Creation of an Association Between Logical Device and Physical Device
Creation of an Association Between Device Interface and Physical Port
If UIM does not contain pre-existing logical devices and physical devices, Network Integrity displays Entity+ for the root logical device and the root physical device.
Resolution of these two entities creates the entire logical device tree. The logical device tree attempts to create associations to the physical device tree (which does not exist), but the creation of association fails.
Resolution creates the physical device tree. The physical device tree creates associations to the logical device tree. The creation of the association is succeeds, and the tree is complete.
Creation of the logical device tree includes logical device and child device interfaces or sub interfaces.
Creation of the physical device tree includes physical device and child 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, then the object is not created. If any objects fail to be created, the root object which initiated the creation is marked Fail or Partial Fail in the log file. However, it is possible that some parts of the tree are completely created and available in UIM.
Successfully created objects are not rolled back when creation of an object fails because of an occupied ID. The subsequent import, discovery, and discrepancy detection actions indicate which objects exist and which objects do not exist, allowing you to continue resolution operations.
Before objects are created in UIM, no search is carried out to see if the object with the same name or nativeEmsName already exists in UIM. UIM does not validate uniqueness of name. When you find an object with the name you need and which does not have child objects, use it. Do not create a new object with the same name.
Custom handling is required when two objects are found with the same name; when an object is found with child objects, and when an object is found in a tree.
When a logical device is discovered, and when it does not exist in UIM, Network Integrity displays Entity+ for the logical device.
Resolution creates the logical device and child objects. As each object is created, it is associated to the physical device tree.
When a logical device exists in UIM without a device interface, Network Integrity displays Entity+ for the device interface.
Resolution creates the device interface and child objects. As each object is created, it is associated to the physical port object.
When a logical device tree exists in UIM, and when the physical device does not exist, Network Integrity displays Entity+ for the physical device.
Resolution creates the physical device and child objects. As each object is created, it is associated to the logical device tree.
When a parent of an equipment exists in UIM, but the equipment does not exist, Network Integrity displays Entity+ for the equipment.
Resolution creates the equipment and child objects. As each object is created, it is associated to the logical device tree.
When a parent (an equipment) of an equipment holder exists in UIM, but the equipment holder does not exist, Network Integrity displays Entity+ for the equipment holder.
Resolution creates the equipment holder and child objects of the equipment holder. As each object is created, it is associated to the logical device tree.
When a parent (an equipment) of a physical port exists in UIM, but the physical port does not exist, Network Integrity displays Entity+ for the physical port.
Resolution creates the physical port. The physical port is associated to the device interface.
When a logical device and physical device exist in UIM, but the association between them does not exist, Network Integrity displays two instances of Assoc+: one from the physical device and the other from the logical device.
Resolution of Assoc+ creates the logical-device-to-physical-device association. Resolution then creates the physical-device-to-logical-device association. The web service detects the association and returns a Success message.
When a device interface and physical port exist in UIM, but the association between them does not exist, Network Integrity displays two instances of Assoc+: one from the device interface and the other from the physical port.
Resolution of Assoc+ creates the device-interface-to-physical-port association. Resolution then creates the physical-port-to-device-interface association. The web service detects the association and returns a success message.
This section describes the following teardown, deletion, and removal scenarios, which are supported in UIM:
Teardown of Association Between Device Interface and Physical Port
Teardown of Association Between Logical Device and Physical Device
When a device interface and physical port exist in UIM with incorrect associations between them, Network Integrity displays two instances of Assoc-: one from the device interface and the other from the physical port.
Resolution of Assoc- creates the device-interface-to-physical-port association. Resolution then deletes the physical-port-to-device-interface association. The web service detects that the association does not exist and returns a Success message.
When a logical device and physical device exist in UIM with incorrect associations between them, Network Integrity displays two instances of Assoc-: one from the logical device and the other from the physical device.
Resolution of Assoc- creates the logical-device-to-physical-device association. Resolution then deletes the physical-device-to-logical-device association. The web service detects that the association does not exist and returns a Success message.
When a physical port (a child of an equipment) exists in UIM, but it is not discovered, Network Integrity displays Entity-.
Resolution of Entity- deletes the physical port.
Note:
A physical port does not exist in isolation. It must exist under a parent object.When an equipment holder (a child of an equipment) exists in UIM, but it is not discovered, Network Integrity displays Entity-.
Resolution of Entity- deletes the equipment holder.
Note:
An equipment holder does not exist in isolation. It must exist under a parent object.When a device interface (a child of a logical device or of a device interface) exists in UIM, but it is not discovered, Network Integrity displays Entity-.
Resolution of Entity- deletes the device interface.
Note:
A device interface does not exist in isolation. It must exist under a parent object.When an equipment (a child of another equipment or of a physical device) exists in UIM, but is not discovered, Network Integrity displays Entity-.
Resolution of Entity- unlinks the equipment from the parent.
Note:
An equipment can exist in isolation. This equipment continues to exist in UIM until an administrator manually deletes it.The following fields are ignored for mismatched data:
ID, which is not a discovered field
nativeEmsName, which is used for matching objects, and not treated for mismatch
DeviceInterfaceConfigurationItem, which exists only in Network Integrity, but not in UIM
The following sections describe mismatched data scenarios:
When a logical device in UIM has data that does not match the discovered data, Network Integrity displays Mismatch.
Resolution updates the mismatched logical device attribute in UIM and sets the value in UIM to the discovered value.
When a device interface in UIM has data that does not match the discovered data, Network Integrity displays Mismatch.
Resolution updates the mismatched device interface attribute in UIM and sets the value in UIM to the discovered value.
When a physical device in UIM has data that does not match the discovered data, Network Integrity displays Mismatch.
Resolution updates the mismatched physical device attribute in UIM and sets the value in UIM to the discovered value.
When an equipment in UIM has data that does not match the discovered data, Network Integrity displays Mismatch.
Resolution updates the mismatched equipment attribute in UIM and sets the value in UIM to the discovered value.
When an equipment holder in UIM has data that does not match the discovered data, Network Integrity displays Mismatch.
Resolution updates the mismatched equipment holder attribute in UIM and sets the value in UIM to the discovered value.
When a physical port in UIM has data that does not match the discovered data, Network Integrity displays Mismatch.
Resolution updates the mismatched physical port attribute in UIM and sets the value in UIM to the discovered value.
A foreign ID is an ID that is available in UIM, but it does not originate from Network Integrity. This ID is auto-generated in UIM. The ID can also be entered manually for an entity created in UIM, rather than through resolution.
For mismatch scenarios and teardown scenarios (Entity- or Assoc-), there is no distinction between working with foreign IDs and Network Integrity-generated IDs. For creation scenarios (Entity+ and Assoc+), there are precautions to creating objects if those objects must have associations to pre-existing objects in UIM with foreign IDs. The following sections describe the resolution behavior.
The discovery action discovers a logical device tree and physical device tree and builds the associations.
In the following example, LD indicates a logical device; PD indicates a physical device; E indicates an equipment; DI indicates a device interface; PP indicates a physical port.
Discovery assigns IDs generated by Network Integrity to all objects:
LD (x) and PD (y)
DI (x1) E (y1)
DI (x2) and PP (y2)
The import action, which uses foreign IDs, imports only the physical device tree; the logical device tree does not exist.
Network Integrity generates: PD (z), E (z1), PP (z2), x, xN ID, y, and yN ID.
UIM generates z and zN ID (foreign IDs).
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: Submitting Entity+ Discrepancies Only
When you submit only Entity+ discrepancies for treatment:
Network Integrity creates the logical device using the ID x it generated.
Network Integrity attempts to create the association between LD(x) and PD(y). Because 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.
Network Integrity attempts to create DI(x1) and succeeds.
Network Integrity attempts to create DI(x2) and succeeds. The association to PP(y2) fails. A partial failure occurs.
The resolution on the Entity+ is marked Fail (Entity+ creates the root object and all child objects).
The logical device tree exists in UIM without associations to the physical device tree. The failure or partial failure is valid.
Run the import, discovery, and resolution actions. Assoc+ is treated and the trees are synchronized.
Use Case 2: Submitting Entity + and Assoc+ Discrepancies Together
When you submit Entity+ and Assoc+ together for treatment:
Network Integrity creates the logical device using the ID x it generated.
Network Integrity attempts to create the association between LD(x) and PD(y). Because 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.
Network Integrity attempts to create DI(x1) and succeeds.
Network Integrity attempts to create DI(x2) and succeeds. The association to PP(y2) fails. A partial failure occurs.
The resolution on Entity+ is marked Fail (Entity+ creates the root object and all child objects).
Network Integrity treats Assoc+ on PD(z). Network Integrity succeeds in associating the physical device to the logical device.
Network Integrity treats Assoc+ on PP(z2). Network Integrity succeeds in associating the physical port to the device interface.
The two Assoc+ discrepancies are marked Successful.
The logical device tree is present in UIM with associations to the physical device tree. Treatment of Assoc+ completes the tree lineage.
Run the import, discovery, and resolution actions.
Network Integrity does not show any discrepancies.
This scenario is a reversal of Scenario 1. Use cases 1 and 2 described in Scenario 1 are true for this scenario if the logical device and physical device scenarios outlined in "Scenario 1: Physical Device Tree Uses Foreign IDs" are reversed.
In this scenario, the import action imports only the logical device tree; the physical device tree does not exist; the logical device tree uses foreign IDs; discrepancy detection generates Entity+ for the missing physical devices in UIM.
Handling of foreign IDs may take up to two passes of import, discovery, and resolution actions to completely synchronize Network Integrity with UIM. If you require handling of foreign IDs in a single pass, modify the resolution to consider the auxiliary object (associated object).
This section describes swapping cards on a physical device tree.
Swapping of cards is not supported out-of-the-box, but it can be done with custom handling. This example uses manual IDs so that creation of an entity with the same ID fails.
In this example, A(1), B(2), C(3), D(4), E(5) and F(6) represent cards on devices.
Discover the logical and physical trees for a and create them in UIM.
Swap two cards on the device: C(3) and F(6). Discovery shows devices in the following order:
A(1)
B(2)
F(6)
D(4)
E(5)
C(3)
Import data from UIM.
Discover the device again.
The following discrepancies are displayed:
Entity- on B (indicating card C is missing in discovery, but present in import)
Entity+ on B (indicating card F is present in discovery, but 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)
Submit resolutions.
Entity- is prioritized before Entity+.
Entity- unlinks F(6) and C(3) from the parent in UIM and succeeds.
Entity+ attempts to create C(3) and F(6).
Entity+ fails because C(3) and F(6) exist. Because C(3) and F(6) exist, the required IDs are occupied. Entity+ fails.
Run the import and discovery actions again.
Discrepancy detection displays a pair of Entity+ discrepancies.
Submit the resolutions.
Entity+ attempts to create C(3) and F(6).
Entity+ fails because C(3) and F(6) exist. Because C(3) and F(6) exist, the required IDs are occupied. Entity+ fails.
Delete C(3) and F(6) manually from UIM.
Run the import, discovery, and resolution actions.
Submit the identified discrepancies for resolution.
Resolution creates C(3) and F(6) and links them to the tree.
At this point, custom handling is required. Modify resolution handling to search for objects by name or by nativeEmsName before they are created. If the objects are found, use them. Do not create new objects.
See "Creation of a Logical Device and a Physical Device" for further information.
When you select all discrepancies for resolution, Network Integrity and UIM incorporate prioritization to ensure correct ordering, and create all selected events in the following order:
Mismatch
Assoc-
Entity-
Entity+
Assoc+
When you select a batch of discrepancies, ensure that dependencies between the discrepancies in the selected batch meet. If a dependency is not met, then resolution fails. For example, when an equipment exists in an equipment holder, but it does not belong there, unlink the equipment (Entity-) before you create, and link the correct one (Entity+).