5 The XML Reference Cartridge

This chapter describes the functionality and design of the Oracle Communications Network Integrity XML Reference cartridge.

The XML Reference cartridge uses the XML File processing technology. The cartridge uses an Ericsson XML device file as its example.

The XML Reference cartridge is designed to be used on a standalone basis to display the physical device hierarchy in the Network Integrity UI. The XML Reference Cartridge provides no integration with other products but can be extended.

This section assumes that you are familiar with the following:

Modeling a Physical Device Hierarchy

Using a CLI command, Ericsson devices can deliver XML device inventory to the local file system. These XML device files can be transferred to Network Integrity for processing.

See Ericsson SMO CLI, Software Management, Organizer Command Line Interface, User Guide, 2/1553-APR 901 007 for reference.

The cartridge reads the XML device file and produces a physical device hierarchy that represents the discovered device and includes a physical device instance, equipment, and equipment holders. (PhysicalPorts are not rendered in the XML file and so are not supported.)

Figure 5-1 shows a sample discovered physical device hierarchy. This hierarchy is displayed in the Network Integrity user interface, in the Scan Result Detail page.

Figure 5-1 Sample Discovered Physical Device Hierarchy

Displays a sample discovered physical device hierarchy

Cartridge Dependencies

This section provides information about dependencies that the XML Reference cartridge has on other entities.

Run Time Dependencies

For the XML Reference cartridge to work at run time, you must deploy the Address_Handlers cartridge to Network Integrity.

Design-Time Dependencies

The XML Reference cartridge has the following dependencies:

  • Address_Handlers

  • NetworkIntegritySDK

  • ora_uim_model

Opening XML Reference Cartridge Files

This section provides information about downloading and opening the XML Reference Cartridge files in Design Studio. After you open the files, you can review and extend them.

You can download a ZIP file that contains the individual Design Studio files. You can open these files in Design Studio to review and extend the cartridge ZIP files.

Opening Files in Design Studio

To review and extend the XML Reference cartridge, download the Oracle Communications Network Integrity File Transfer and Parsing software from the Oracle software delivery website:

https://edelivery.oracle.com

The software contains the XML Reference cartridge ZIP file, which has the following structure:

  • \Network_Integrity_Cartridge_Projects\XML_Reference_Cartridge

For information about opening files in Design Studio, see the Design Studio Help and Network Integrity Developer's Guide.

Compiling and Deploying the Cartridge

This section provides information about compiling and deploying the XML Reference Cartridge.

To compile and deploy the XML Reference Cartridge:

  1. Import projects into Design Studio for Network Integrity.

  2. Clean and build the cartridge.

  3. Deploy the cartridge.

For more information about deploying and undeploying, see Network Integrity Developer's Guide.

About the Cartridge Components

The XML Reference cartridge contains the following actions:

Discover Ericsson Xml

The Discover Ericsson Xml action reads one or more XML device file instances, and provides multiple hierarchical device model instances. (XML device file instances could contain multiple devices.)

The Discover Ericsson Xml action contains the following processors run in the following order:

  1. Ericsson Xml Initializer

  2. Ericsson Xml File Collector

  3. Ericsson Xml File Parser

  4. Ericsson Xml Managed Element Collector

  5. Ericsson Xml Device Modeler

  6. Ericsson Xml Device Persister

Figure 5-2 illustrates the processor workflow of the Discover Ericsson Xml action.

Figure 5-2 Discover Ericsson Xml Action Processor Workflow

Surrounding text describes Figure 5-2 .

Ericsson Xml Initializer

The Ericsson Xml Initializer instantiates a helper class, and then makes it available to other processors in the chain.

Ericsson Xml File Collector

The Ericsson Xml File Collector processor is used to retrieve XML device files and make them available to the next processor in the chain.

Note:

This processor is automatically generated from Design Studio input data.

Ericsson Xml File Parser

The Ericsson Xml file parser processor is used to read the XML device files, validate them against a loaded schema, and convert the XML device file to an XML bean, making it available for parsing to the next processor.

Note:

This processor is automatically generated from Design Studio input data.

Ericsson Xml Managed Element Collector

The Ericsson Xml Managed Element Collector processor is used to process the XML device file and locate managed elements (MEs). These MEs are then inserted into a list for further processing.

Note:

One or more managed elements are contained within nested subNetworks in the XML device file. This processor is capable of finding all managed elements. SubNetworks are not modeled.

Ericsson Xml Device Modeler

The Ericsson Xml Device Modeler processor is used to model the data collected from the Ericsson Xml Managed Element Collector. Modeling includes building the hierarchical relationship of physical device and children equipment and equipment holders from an individual ME.

Ericsson Xml Device Persister

The Ericsson Xml Device Persister is used to persist the physical device tree to the Network Integrity database.

About Collected Data

This section shows a sample XML device file that is provided to the processor.

<?xml version="1.0" encoding="UTF-8"?>
<bulkCmConfigDataFile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.3gpp.org/ftp/specs/archive/32_series/32.615#configData ../../../eclipseWorkSpace/XMLReferenceCartridge/schemas/configData.xsd"
   xmlns="http://www.3gpp.org/ftp/specs/archive/32_series/32.615#configData"
   xmlns:xn="http://www.3gpp.org/ftp/specs/archive/32_series/32.625#genericNrm"
   xmlns:in="http://www.3gpp.org/ftp/specs/archive/32_series/32.695#inventoryNrm">
   <fileHeader fileFormatVersion="32.615 V6.3" vendorName="Ericsson AB"/>
   <configData dnPrefix="DC=150.132.36.75,SubNetwork=NRO_RootMo,ManagementNode=ONRM,IRPAgent=ONRM_IrpAgent">
      <xn:SubNetwork id="NRO_RootMo">
         <xn:SubNetwork id="RNC106">
            <xn:ManagedElement id="RNC106">
               <xn:attributes>
                  <xn:managedElementType>RNC</xn:managedElementType>
                  <xn:userLabel>RNC106</xn:userLabel>
                  <xn:vendorName>Ericsson AB</xn:vendorName>
               </xn:attributes>
               <in:InventoryUnit id="1B">
                  <in:attributes>
                     <in:inventoryUnitType>HW</in:inventoryUnitType>
                     <in:vendorUnitFamilyType>SUBRACK</in:vendorUnitFamilyType>
                     <in:vendorUnitTypeNumber>ROJ 605 107/3_R1A</in:vendorUnitTypeNumber>
                     <in:vendorName>Ericsson AB</in:vendorName>
                     <in:serialNumber>X911033101</in:serialNumber>
                     <in:dateOfManufacture>2005-10-22</in:dateOfManufacture>
                     <in:unitPosition>1B</in:unitPosition>
                     <in:manufacturerData>ProductName=CBM,SlotCount=28</in:manufacturerData>
                  </in:attributes>
                  <in:InventoryUnit id="0">
                     <in:attributes>
                        <in:inventoryUnitType>HW</in:inventoryUnitType>
                        <in:vendorUnitFamilyType>FAN</in:vendorUnitFamilyType>
                        <in:vendorUnitTypeNumber>BKV 301 487/1_R3A</in:vendorUnitTypeNumber>
                        <in:vendorName>Ericsson AB</in:vendorName>
                        <in:serialNumber/>
                     </in:attributes>
                  </in:InventoryUnit>
                  <in:InventoryUnit id="1">
                     <in:attributes>
                        <in:inventoryUnitType>HW</in:inventoryUnitType>
                        <in:vendorUnitFamilyType>PIU</in:vendorUnitFamilyType>
                        <in:vendorUnitTypeNumber>ROJ1192108/4_R2B</in:vendorUnitTypeNumber>
                        <in:vendorName>Ericsson AB</in:vendorName>
                        <in:serialNumber>TU87600308</in:serialNumber>
                        <in:dateOfManufacture>2005-12-01</in:dateOfManufacture>
                        <in:unitPosition>1</in:unitPosition>
                        <in:manufacturerData>ProductName=SCB3</in:manufacturerData>
                     </in:attributes>
                  </in:InventoryUnit>
                  <in:InventoryUnit id="2">
                     <in:attributes>
                        <in:inventoryUnitType>HW</in:inventoryUnitType>
                        <in:vendorUnitFamilyType>PIU</in:vendorUnitFamilyType>
                        <in:vendorUnitTypeNumber>ROJ1192109/3_R1B</in:vendorUnitTypeNumber>
                        <in:vendorName>Ericsson AB</in:vendorName>
                        <in:serialNumber>TU87153523</in:serialNumber>
                        <in:dateOfManufacture>2005-10-07</in:dateOfManufacture>
                        <in:unitPosition>2</in:unitPosition>
                        <in:manufacturerData>ProductName=SXB3</in:manufacturerData>
                     </in:attributes>
                  </in:InventoryUnit>
                  <in:InventoryUnit id="3">
                     <in:attributes>
                        <in:inventoryUnitType>HW</in:inventoryUnitType>
                        <in:vendorUnitFamilyType>PIU</in:vendorUnitFamilyType>
                        <in:vendorUnitTypeNumber>ROJ1192109/3_R1B</in:vendorUnitTypeNumber>
                        <in:vendorName>Ericsson AB</in:vendorName>
                        <in:serialNumber>TU87153427</in:serialNumber>
                        <in:dateOfManufacture>2005-10-07</in:dateOfManufacture>
                        <in:unitPosition>3</in:unitPosition>
                        <in:manufacturerData>ProductName=SXB3</in:manufacturerData>
                     </in:attributes>
                  </in:InventoryUnit>
               </in:InventoryUnit>
            </xn:ManagedElement>
         </xn:SubNetwork>
      </xn:SubNetwork>
   </configData>
   <fileFooter dateTime="2006-09-06T08:03:04+02:00"/>
</bulkCmConfigDataFile>

About Cartridge Modeling

This section provides information about modeling the XML Reference cartridge.

Figure 5-3 shows a Unified Modeling Language (UML) diagram depicting the object relationship.

Figure 5-3 XML UML Diagram

Shows an XML UML diagram

Hierarchy Mapping

The physical device object is established and seeded with data sourced by ManagedElement.

The Equipment object is established and seeded from InventoryUnit, where the vendorUnitFamilyType = PIU (Plug In Unit). All other InventoryUnits are discarded, that is (vendorUnitFamilyType = OTHER, FAN).

The EquipmentHolder object is established and seeded from InventoryUnit, where the vendorUnitFamilyType =SUBRACK.

Note:

Modeling limits InventoryUnit to two (2) levels deep. If an XML file instance has more than two levels of InventoryUnit below ManagedElement, the third to nth levels are ignored, and customization is required to model those levels.

Oracle Communications Information Model

All entities shown in Figure 5-3 (for example, physical device and equipment) are Information Model 1.0-compliant for static fields. The dynamic fields (sometimes referred to as characteristics) are application-specific.

Field Mapping

This section provides information about field mappings used in the cartridge.

  • Text: Implies Text [255].

  • static: The Information Model 1.0 defines this field to be static on the entity specification. The specification provides getters/setters for this field.

  • dynamic: This is a dynamic field where the entity specification treats the field as a name/value pair. The specification does not provide getter/setters but generically has a get/setCharacteristics method holding a HashSet of entries.

Table 5-1 Physical Device Mappings

Physical Device Information Model Support Xml Object Field Type

Id

static

N/A

Text

Name

static

id

Text

Description

static

xmlFile Source

Text

Specification

static

N/A

Programmatically set to EricssonCPPPhysicalDevice

discoveredVendorName

dynamic

vendorName

Text

modelName

dynamic

managedElementType

Text

nativeEmsName

static

userLabel

Text

Serial Number

yes

N/A

Text

Physical Location

yes

N/A

Text

Table 5-2 Equipment Mappings

Equipment Information Model Support XML Object Field Type

Id

static

N/A

Text

Name

static

manufacturerData

Text, Extract ProductName

Description

static

manufacturerData

Text

Specification

static

N/A

Programmatically set to EricssonCPPEquipment

discoveredModelNumber

dynamic

vendorUnityTypeNumber

Text

discoveredVendorName

dynamic

vendorName

Text

serialNumber

static

serialNumber

Text

nativeEmsName

static

manufacturerData + unitPosition

Text, Extract ProductName, append unitPosition which is occupied slot number

Physical Location

yes

N/A

Text

Table 5-3 EquipmentHolder Mappings

EquipmentHolder Information Model Support XML Object Field Type

Id

static

N/A

Text

Name

static

manufacturerData + slotNumber

Text

Specification

static

N/A

Programmatically set to EricssonCPPEquipmentHolder

nativeEmsName

static

slotNumber

Text

manufacturerData contains SlotCount. SlotCount is used to generate the required number of slots and slotNumber is a slot instance.

Description

yes

N/A

Text

Serial Number

yes

N/A

Text

Physical Location

yes

N/A

Text

Model Correction

This section provides 3GPP to Information Model correction information.

About Model Correction Code

Model correction occurs when the 3GPP information received through discovery does not conform to the Information Model and therefore cannot be persisted, as it is within Network Integrity. For information about supported hierarchy, see "About Cartridge Modeling".

The XML Reference Cartridge applies the model corrections as outlined below.

EquipmentHolder under physical device:

                   PhysicalDevice
      EquipmentHolder

The XML Reference Cartridge adds an equipment entity as follows:

                   PhysicalDevice
     Equipment-named Artificial Equipment
      EquipmentHolder

Design Studio Construction

This section provides information about using Design Studio to construct the XML Reference cartridge.

The XML Reference cartridge contains the following specifications:

  • EricssonCPPPhysicalDevice

  • EricssonCPPEquipment

  • EricssonCPPEquipmentHolder

  • EricssonXmlFileCollectorProperties

Table 5-4 Discover Ericsson Xml Action Construction

Result Category Address Handler Scan Parameter Groups Model Processors

Device

FileTransfer AddressHandler

ftaFileTransferType

ftaFilePattern

ftaPort

ftaUser

ftaPassword

ftaSessionTimeOut

ftaSourceFileManagement

ftaRenameSuffix

Ericsson CPP Model

Ericsson Xml Initializer

Ericsson Xml File collector

Ericsson Xml File Parser

Ericsson Xml Managed Element Collector

Ericsson Xml Device Modeler

Ericsson Xml Device Persister

Figure 5-4 shows the discover DiscoverEricssonXml action chain.

Figure 5-4 Discovery XML Action Chain

Shows a discovery XML action chain

In Figure 5-4, the chevrons that correspond to EricssonXmlFileCollector and EricssonXmlFileParser indicate the code-generated processors from Design Studio user input.

  • EricssonXmlFileCollector is an instance of the file transfer processor

  • EricssonXmlFileParser is an instance of the file parser processor

Table 5-5 Discover Ericsson Xml Action Processors

Processor Name Variable

Ericsson Xml Initializer

Input: N/A

Output:

  • physicalDeviceHelper

    The output is a helper class used in proceeding chain.

Ericsson Xml File Collector

Input: N/A

Output:

  • ericssonXmlFileCollectorFileCollection <java.util.Collecton>

    The output is a collection of files found in the path specified in the scope field.

Ericsson Xml File Parser

Input:

  • ericssonXmlFileCollectorFileCollection

    The input is a collection of files.

  • XmlSchema: schemas/configData.xsd

    The schema is used to validate XML file instances.

Output: N/A

Ericsson Xml Managed Element Collector

Input: XmlFile

Output:

  • managedElements <java.util.ArrayList>

    The output is a list containing the managedElements.

The processor is wrapped in a For each loop to execute this processor for each XML file.

Ericsson Xml Device Modeler

Input: ManagedElement, physicalDeviceHelper

Output: physicalDevice

The processor is wrapped in a For each loop to execute this processor for each ME.

This processor can be extended to enhance an individual physical device tree.

Ericsson Xml Device Persister

Input: N/A

Output: N/A

Context is persisted for performance.

Note:

configData.xsd is the root document of the XSD formed from documents configData.xsd, genericNrm.xsd, inventoryNrm.xsd, and sessionLog.xsd. These documents had to first be stitched and validated after retrieval from:

http://www.3gpp.org

See the "The ASCII Reference Cartridge" for 3GPP URLs. Stitching implies that schemaLocation had to be input into the configData.xsd and inventoryNrm.xsd. In addition, all unused namespaces are removed.

Design Studio Extension

This section provides information about Design Studio extensions to the XML Reference cartridge.

The source code to this cartridge is provided. You can change any part to customize this cartridge to fit your environment.

For more information on extensibility, see Network Integrity Developer's Guide.