2 About the Cartridge Components

This chapter provides information about the components of the Oracle Communications Network Integrity MSS Integration cartridge.

The MSS Integration cartridge contains the following actions:

Import from MSS Action
Detect Equipment Discrepancies Action
MSS Circuit Discrepancy Detection Action
Resolve in MSS Action

Import from MSS Action

The Import from MSS action connects to Oracle Communications MetaSolv Solution (MSS) to import specified inventory data. This import action writes the inventory information to materialized views and models it according to the Oracle Communications Information Model.

The Import from MSS action contains the following processors run in the following order:

Equipment DAOs Initializer
Page Initializer
Page Creator
Node Collector
Device Modeler
Equipment Hierarchy Collector
Equipment Hierarchy Modeler
Hierarchy Persister
STM Link Discoverer
VC4 Circuit Discoverer
VC3 VC12 LOP Discoverer

Figure 2-1 illustrates the processor workflow of the Import from MSS action.

Figure 2-1 Import from MSS Action Processor Workflow

Description of ''Figure 2-1 Import from MSS Action Processor Workflow''

Equipment DAOs Initializer

If Run MSS Extract is set to True in the Network Integrity UI, this processor refreshes the MSS materialized views.

Also, this processor reads the data source information from the Import System values and initializes the DAOLocator instance. The DAOLocator instance is used by other processors and actions to retrieve equipment and circuit data.

Page Initializer

This processor counts all the unique network nodes from the MSS extract views, according to the scope defined in the Network Integrity UI, and determines the number of pages needed to list all the nodes. By default, a page can contain 50 nodes. This processor produces a pageCountList iterable object.

Page Creator

This processor creates pages listing unique network node names imported from MSS matching the filtering criteria set in the Network Integrity UI. This processor outputs the node names list in a response object.

Node Collector

This processor collects all root equipment from MSS for each node on the node name list produced by the Page Creator processor. The collected root equipment are placed in the nodesMapByNodeName map, which indexes each node name and its value.

The output iterable object loops over nodeNamesSet, getting one node name per loop.

Device Modeler

This processor models each imported network node as PhysicalDevice and LogicalDevice entities and outputs a root equipment list for each modeled node.

Equipment Hierarchy Collector

This processor retrieves port information for the equipment hierarchy from EquipmentPositionHierDAO and EquipmentPortAddressDAO. This processor outputs a map listing port-to-card IDs.

Equipment Hierarchy Modeler

This processor models root equipment and its floating termination points (FTPs) from the map as physical port and media interface entities. Its associated ports are derived from the output map from the Equipment Hierarchy Collector processor and are modeled as physical port and media interface entities.

This processor builds the equipment hierarchy by parsing the equipment hierarchy string. Slots and subslots are modeled as EquipmentHolders entities, and cards as Equipment entities. This processor saves processed card IDs to an index object to avoid processing duplicate card IDs in a different hierarchy for the same parent.

Note:

The equipment hierarchy string in MSS must define the equipment type for equipment for this processor to successfully build the hierarchy.

Hierarchy Persister

This processor saves the logical and physical device trees and saves the modeled hierarchy for each network node.

STM Link Discoverer

This processor discovers synchronous transport module (STM) links from the list of ports produced by the Equipment Hierarchy Modeler processor.

This processor retrieves the STM Circuit information from CircuitExportDAO and CircuitPositionDAO and models each as DisPipe entities. The STM links are modeled with a valid VC4 channel index value.

This processor outputs a list of STM links in an stmSet object.

VC4 Circuit Discoverer

This processor retrieves the VC4 circuit information from the STM Link Discoverer processor. It verifies whether the circuit is a customer circuit. Customer circuits are modeled as E4 circuits with a VC4 display string. Non-customer circuits are modeled as transport pipes with a VC4 higher order transport display string.

This processor produces a list of CircuitExport DAOs for each transport pipe.

VC3 VC12 LOP Discoverer

This processor queries the lower order pipes (LOPs) from the vc4sForLops list and models them as E3 circuits with a VC3 display string or as E1 circuits with a VC12 display string, depending on the layer rate codes.

Detect Equipment Discrepancies Action

The Detect Equipment Discrepancies action compares discovered TMF814 data with the imported MSS data and returns a list of discrepancies.

This discrepancy detection action extends Discrepancy Detector action (from the NetworkIntegritySDK cartridge) and inherits all its processors. For information about the inherited processors, see Network Integrity Developer's Guide.

This action also extends the Auto Resolve Discrepancies action (from the NetworkIntegritySDK cartridge) to provide automatic discrepancy resolution. For information about the processors inherited from the Auto Resolve Discrepancies action, see Network Integrity Developer's Guide.

The Detect Equipment Discrepancies action contains the following processors run in the following order:

Equipment Filters Initializer
Discrepancy Detector (inherited)
Discrepancy Filter
Check Auto Resolve Selected (inherited)
MSS Auto Resolve Selected Discrepancies
Identify Auto Resolving Discrepancies (inherited)
Prepare Resolving Discrepancies (inherited)

Figure 2-2 illustrates the processor workflow of the Detect Equipment Discrepancies action.

Figure 2-2 Detect Equipment Discrepancies Action Processor Workflow

Description of ''Figure 2-2 Detect Equipment Discrepancies Action Processor Workflow''

Equipment Filters Initializer

This processor applies the equipment filters set in the Network Integrity UI on the Discrepancy Detection process. This processor also automatically filters out discrepancies that are not relevant to MSS equipment.

Discrepancy Filter

This processor collects the discrepancies generated by the Discrepancy Detector processor and sets the priority and status for discrepancies on physical ports.

Discrepancies on physical ports are labeled Manually correct in MSS, and Network Integrity sets the status to Ignored because Network Integrity cannot resolve this type of discrepancy.

MSS Auto Resolve Selected Discrepancies

This processor contains the Java class for the automatic discrepancy resolution manager. The Java implementation class determines the types of discrepancies to be automatically resolved and the resolution logic.

The MSS Integration cartridge also implements automatic discrepancy resolution with a properties file.

See Network Integrity Developer's Guide for more information about automatic discrepancy resolution.

MSS Circuit Discrepancy Detection Action

The MSS Circuit Discrepancy Detection action compares the results of an Assimilate Optical Circuits scan with the imported MSS data and returns a list of discrepancies. For more information about the Assimilate Optical Circuits scan action type, see Network Integrity Optical Circuit Assimilation Cartridge Guide.

This discrepancy detection action inherits all the processors from the Abstract Optical Circuit Discrepancy Detection action (from the Optical Circuit Assimilation cartridge). For information about the inherited processors, see Network Integrity Optical Circuit Assimilation Cartridge Guide.

The MSS Circuit Discrepancy Detection action contains the following processors run in the following order:

Circuit Discrepancy Name Filter Initializer (inherited)
Missing Entity Filter Initializer (inherited)
Partial Circuit Discrepancy Filter
Discrepancy Detector (inherited)

Figure 2-3 illustrates the processor workflow of the MSS Circuit Discrepancy Detection action.

Figure 2-3 MSS Circuit Discrepancy Detection Action Processor Workflow

Description of ''Figure 2-3 MSS Circuit Discrepancy Detection Action Processor Workflow''

Partial Circuit Discrepancy Filter

This processor collects the discrepancies generated by the Missing Entity Filter initializer processor.

Discrepancies on partial pipe entities with a name that begins with GENERATED_ are labeled Manually correct in MSS, and Network Integrity sets the status to Ignored because Network Integrity cannot resolve this type of discrepancy.

Resolve in MSS Action

The Resolve in MSS action resolves discrepancies between your network data and the imported data by updating equipment and circuit hierarchy in MSS.

This discrepancy resolution action inherits all the processors from the Resolve Abstract CORBA action (from the CORBA cartridge) and inherits all its processors. For information about the inherited processors, see Network Integrity CORBA Cartridge Guide.

The Resolve in MSS action contains the following processors run in the following order:

CORBA Property Initializer (inherited)
MSS CORBA Property Initializer
CORBA Connection Manager (inherited)
Resolution Framework Initializer
MSS Resolution Initializer
Resolution Framework Dispatcher

Figure 2-4 illustrates the processor workflow of the Resolve in MSS action.

Figure 2-4 Resolve in MSS Action Processor Workflow

Description of ''Figure 2-4 Resolve in MSS Action Processor Workflow''

MSS CORBA Property Initializer

This processor sets the common object request broker architecture (CORBA) object request broker (ORB) properties in the JacORB to establish CORBA connectivity with MSS.

Resolution Framework Initializer

This processor initializes the BaseResolutionElement resolution framework class used to register the handlers required to resolve discrepancies in MSS.

MSS Resolution Initializer

This processor registers the following entity handlers to the BaseResolutionElement class:

DeviceHandler
EquipmentHandler
PhysicalPortHandler
DeviceInterfaceHandler
CircuitHandler
PipeTerminationPointHandler
TrailPathHandler

Resolution Framework Dispatcher

This processor runs the BaseResolutionElement class to evaluate and treat discrepancies using the appropriate registered entity handlers.

About Discrepancy Detection

The MSS Integration cartridge extends the NetworkIntegritySDK cartridge project to detect discrepancies.

Table 2-1 lists the possible discrepancies that can be reported and the types of entities that each discrepancy can be found on.

Table 2-1 Discrepancy Types

Discrepancy Type	Entity Types
Extra Entity (Entity+)	Physical device, equipment, equipment holder, physical port, pipe (STM/HOT/LOP), pipe termination point, trail path, trail pipe
Missing Entity (Entity-)	Physical device, equipment, equipment holder, physical port, pipe (STM/HOT/LOP), pipe termination point, trail path, trail pipe
Attribute Value Mismatch (Attribute)	Physical device, logical device, equipment, equipment holder, pipe

For more information about discrepancy detection and automatic discrepancy resolution, see Network Integrity Developer's Guide.

About Discrepancy Resolution

The MSS Integration cartridge has two distinct discrepancy resolution actions: one for circuits and another for equipment. The cartridge communicates equipment resolution using a CORBA connection and communicates circuit resolution using an Enterprise JavaBean (EJB) connection.

This section lists the discrepancy types that the MSS Integration cartridge can resolve from Network Integrity. All other discrepancy types must be resolved manually in MSS.

This action automatically uses the correct handler depending on the type of discrepancy being resolved. Table 2-2 lists the discrepancy types and the handler used to resolve the discrepancy.

Table 2-2 Discrepancy Resolution Handlers

Handler	Handled Entity Types	Discrepancy Type
DeviceHandler	Physical device	Entity+
EquipmentHandler	Equipment, equipment holder	Entity+, Attribute value mismatch
PipeTerminationPointHandler	Pipe termination point	Entity+, Entity-
TrailPathHandler	Trail path	Entity+, Entity-
CircuitHandler	Pipe (customer circuit)	Entity+ (LOP, TrailPipe upload), Entity- (LOP, TrailPipe delete), Attribute value mismatch (for timeslot)
PhysicalPortHandler	Physical port	Entity+, Entity-

Each handler runs creation and removal operations to fully resolve discrepancies. For discrepancies on MSS equipment, the handlers run CORBA API methods and populate Java classes with the resolution information.

Network Integrity updates the status of discrepancies as they are being resolved:

Processed: Network Integrity successfully processed the discrepancy.
Failed: Network Integrity could not successfully process the discrepancy. The reasonForFailure field explains the cause of the failure. Network Integrity logs exceptions and failure reasons.
Ignored: Network Integrity does not support making this resolution in MSS. You must manually resolve this discrepancy in MSS.
Not Implemented: Network Integrity could not upload the resolution to MSS. You can manually resolve this discrepancy in MSS, or extend or develop a handler to resolve the discrepancy from Network Integrity.

For more information about discrepancy resolution, see Network Integrity Developer's Guide.

Extra Entity (Entity+) Discrepancy Resolution

Entity+ discrepancies occur when an entity exists in your network but is missing from the imported data. Network Integrity resolves this type of discrepancy by creating the missing entity in MSS.

Network Node Creation

Entity+ discrepancies occur on physical or logical devices when the corresponding network node does not exist in MSS. The MSS Integration cartridge resolves this discrepancy by doing the following:

Queries location_id using the MSS CORBA getLocationI API method. This method belongs to NetworkLocationSubSession of the InfrastructureSession interface.
Creates a network node in MSS in the location returned by the getLocation API by running the MSS CORBA createNetworkElement API method. This method belongs to NetworkElementSubSession of the EquipmentSession interface.
You must open the MSS UI and search for the created node, updating it with the type and manually associating it with the network system, which allows later resolution actions to create equipment and hierarchies under the new node.

Note:

Creating a network node can cause additional discrepancies on the next Discrepancy Detection action, such as new Entity+ discrepancies on MSS equipment or equipment hierarchy belonging to the new network node. This is normal.

Equipment Creation

Entity+ discrepancies occur on equipment when the corresponding rack, shelf, sub-shelf, or card does not exist in MSS. The MSS Integration cartridge resolves this discrepancy by doing the following:

Traverses the Information Model equipment hierarchy. For each equipment found, creates equipment in MSS using the MSS CORBA installEquipment API method. This method belongs to InstallationSubSession of the EquipmentSession interface.
For each root equipment, queries for its parent and obtains network_node_id using the CORBA getNetworkElement API method. This method belongs to NetworkElementSubSession of the EquipmentSession interface.
For each equipment, queries for EquipmentSpecification using the MSS CORBA queryEquipSpec_v2 API method and obtains equip_spec_id. This method belongs to SpecificationSubsession of the EquipmentSession interface. NativeEMSName, discoveredPartNumber, and modelName on modeled Information Model equipment are used to identify the equipment specification in MSS.

Ensure that the equipment specification for the equipment being created exists in MSS before uploading the equipment from Network Integrity. Port creation is determined by the card equipment specification.

Circuit Creation

Entity+ discrepancies occur on circuits when a circuit does not exist in MSS. You must resolve the discrepancies on equipment, HOTs, and STMs and reconcile the data again before you can upload the resolution for customer circuits. It is recommended that you limit your first discrepancy detection scan to equipment, HOTs, and STMs. Expand subsequent scans to detect all discrepancies.

The MSS Integration cartridge resolves this discrepancy by doing the following:

Uploads customer circuits to MSS by creating new end-to-end customer connections using the EJB createNewCustomerConnection API method. This method also assigns ports and channels to the uploaded circuit if the information is available.
If the channel information is not available, the MSS Integration cartridge builds the channel hierarchy at the given circuit position using the EJB autoBuild API method and updates the provisioning information. The method derives the circuit position based on the synchronous digital hierarchy (SDH).
Prepares the port and channel assignment containers for the circuit based on the traced circuit information.
Calls the EJB updateCircuit and updateProvisioningInfo API methods to pass updated circuit and provisioning information to MSS.

You can use a wrapper API to call multiple MSS methods in a single transaction.

You can also extend the circuit resolution handler to use custom logic.

STM links and higher-order transport (HOT) circuits cannot be uploaded to or corrected in MSS with API methods from Network Integrity. Discrepancies on STMs and HOTs must be corrected manually in MSS.

Because VC4 HOTs span across multiple links in a network, you should follow these guidelines while creating HOTs in MSS:

Create the facility connection for the VC4 rate code.
Using CLR/DLR design, assign the channel from the STM links to the HOT.
In the network system, create the connection spanning the entire VC4 HOT.
Associate the VC4 HOT to the network system.

Channel Assignment Creation on a Trail Pipe

Entity+ discrepancies occur on trail pipes when a circuit in MSS is missing its channel assignment. This discrepancy occurs when channel assignments were not assigned to the circuit in MSS or when a circuit is rerouted.

When dealing with unassigned channel assignments, the MSS Integration cartridge resolves this discrepancy by assigning the circuit to the channel in MSS.

You can identify a rerouted circuit when Network Integrity reports multiple Entity+ and Entity- discrepancies. By filtering on the circuit name, you can see that the discrepancies are all related.

The MSS Integration cartridge resolves rerouted circuits by creating or correcting the channel assignments on trail pipes in MSS.

TrailPath Assignment to a Circuit

Entity+ discrepancies on trail paths are resolved by assigning the trail path to a circuit and updating the provisioning information. The MSS Integration cartridge resolves this discrepancy by doing the following:

Calls the updateCircuit method to assign the entire trail path to the customer circuit.
Calls the updateProvisioningInfo method to pass and update the provisioning information on the customer circuit.

PipeTerminationPoint Assignment to a Circuit

Entity+ discrepancies on pipe termination points are resolved by assigning the pipe termination point to a circuit and updating the circuit with the provisioning information. The MSS Integration cartridge resolves this discrepancy by doing the following:

Assigns the pipe termination point to the circuit using the updateCircuit method.
Calls the updateProvisioningInfo MSS method with the PipeTerminationPoint information to update the circuit.

Missing Entity (Entity-) Discrepancy Resolution

Entity- discrepancies occur when an entity exists in the imported data and not in your network data. Network Integrity resolves this type of discrepancy by deleting the entity from MSS.

Take special care when resolving Entity- discrepancies, because there can be many underlying causes. Review the cause carefully, choosing to resolve the root cause (either from Network Integrity or manually in MSS).

Network Node Deletion

Entity- discrepancies occur on physical or logical devices when the corresponding network node does not exist in your network. The MSS Integration cartridge resolves this discrepancy by doing the following:

Queries the network node using the MSS CORBA getNetworkElement API method. This method belongs to NetworkElementSubSession of the EquipmentSession interface. This method may not return the network node if it was deleted while resolving another discrepancy.
Searches for root equipment. For each root equipment, traverses the hierarchy and deletes the lowest-level equipment. See "Equipment Deletion" for more information.
Deletes the parent network node after all child equipment are deleted. Network nodes are deleted using the MSS CORBA deleteNetworkElement API method.

Equipment Deletion

Entity- discrepancies occur on equipment when the corresponding rack, shelf, sub-shelf, or card does not exist in your network. The MSS Integration cartridge resolves this discrepancy by doing the following:

Queries the equipment using the MSS CORBA searchEquipmentInstall_v2 API method. This method belongs to InstallationSubSession of the EquipmentSession interface.
Uninstalls the equipment from MSS using the MSS CORBA uninstallEquipment API method at the location obtained from equipment_id.

Circuit Deletion

Entity- discrepancies occur on circuits when an additional circuit exists in MSS. The MSS Integration cartridge resolves this discrepancy by doing the following:

Locates the additional circuit in MSS and calls the MSS EJB deleteCircuit API method with a specific circuit ID or name.

Channel Assignment Deletion on a Trail Pipe

Entity- discrepancies occur on trail pipes when a trail pipe in the network is missing its channel assignment. This discrepancy occurs when a cross-connect is missing in the network or a customer circuit is down.

To resolve this discrepancy, you must repair the circuit in the network or release the circuit from MSS.

TrailPath Unassignment from a Circuit

Entity- discrepancies on trail paths are resolved by unassigning the trail path from a circuit and updating the provisioning information. The MSS Integration cartridge resolves this discrepancy by doing the following:

Calls the updateCircuit method to unassign the entire trail path from the customer circuit.
Calls the updateProvisioningInfo MSS method to update the circuit.

Note:

You must resolve Entity+ discrepancies on trail paths before resolving Entity- discrepancies on trail paths if the discrepancies are reported on the same circuit. Or, you can also resolve the Entity+ and the Entity- discrepancies at the same time and Network Integrity will fix them in the correct order.

PipeTerminationPoint Unassignment from a Circuit

Entity- discrepancies on pipe termination points are resolved by unassigning the pipe termination point from a circuit:

Unassigns the pipe termination point from the circuit using the updateCircuit method.
Updates the circuit using the updateProvisioningInfo MSS method.

Attribute Value Mismatch (Attribute) Discrepancy Resolution

Attribute discrepancies occur when an entity exists in the imported data and in your network data, but the attribute values in the two sets of information do not match. Network Integrity resolves this type of discrepancy by correcting the attribute values in MSS.

Equipment Mismatch

The MSS Integration cartridge resolves attribute discrepancies on equipment by running the MSS CORBA updateEquipment API method. This method belongs to NetworkElementSubSession of the EquipmentSession interface.

Circuit Channel Assignment Mismatch

This attribute discrepancy appears on trail pipes when a customer circuit is rerouted.

The MSS Integration cartridge resolves attribute discrepancies on circuits by identifying the timeslot on the circuit and using the following APIs:

To update a circuit entity attribute, calls the MSS EJB updateCircuit() API method.
To update a channel attribute, calls the MSS EJB updateProvisioningInfo() API method.

The MSS Integration cartridge also calls the necessary MSS APIs to unassign the circuit from its timeslot before setting the new attribute value.