The ASCII Reference Cartridge

4 The ASCII Reference Cartridge

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

The ASCII Reference cartridge uses ASCII file processing technology. The cartridge uses an Alcatel 1359IOO Remote Inventory Data as its example. This guide assumes that you are familiar with remote inventory data handoff in Alcatel 1359IOO Information Content Description.

About Alcatel 1359IOO Remote Inventory Data Handoff

Alcatel 1359IOO uses a TCP/IP connection to exchange a set of messages between EOS and a generic IOO agent.

For a discovery action, the focus is on the remote inventory data handoff. Remote Inventory Data Handoff (RIDH) allows the export of the main identification data relevant to hardware products (physical boards) installed into the network elements (NEs) managed by the EML. The identification data is stored in permanent memory devices (EEPROM) included in each product part list.

This IOO application enables the EOS to retrieve all the remote inventory data stored in the 1353NM.

RI_DATA_NOTIFICATION primitives provide the EOS with the list of hardware components currently installed in the Network Elements (NE), and notify a change if the remote inventory file is updated on the 1353NM. Each RI_DATA_NOTIFICATION primitive refers to a single board.

RI_DATA_NOTIF primitives are sent after all the RI_DATA_NOTIFICATIONs referring to the boards installed in a single network element, to give the EOS an End Of File indicator (the inventory of the NEX is completely uploaded).

This reference implementation deals only with RI_DATA_NOTIF, because the Alcatel 1359 IOO Information Content Description document does not show RI_DATA_NOTIFICATION in the sample Remote Inventory Data. The Alcatel 1359 IOO Information Content Description document only shows RI_DATA_NOTIF. RI_DATA_NOTIFICATION does not appear in the RI Data Handoff document.

RI_DATA_NOTIF primitives have different parameters for Q3 and QB3* NEs. In this reference implementation, QB3* NE is used as example.

The CSV format of RI_DATA_NOTIF is as follows (QB3* NE):

RI_DATA_NOTIF
[ <riDataList or riDataUnsol> |
<neName attribute value> |
<neLocationName attribute value> |
<protocolType attribute value> |
<blockNumber attribute value> |
<blockLabel attribute value> | (unique to SND NE's)
<alcatelCompany attribute value> |
<unitType attribute value> |
<unitPartNumber attribute value> |
<softwarePartNumber attribute value> |
<cleiCode attribute value> |
<manufacPlant attribute value> |
<serialNumber attribute value> |
<manufacDate attribute value> |
<operatorInvData attribute value> ]

The CSV format for the last notification received for each remote inventory file is as follows:

RI_DATA_NOTIF
[ <riDataList or riDataUnsol > |
<neName attribute value> |
<protocolType attribute value> |
{ <uploadTime attribute value> } |
< numberOfCards attribute value> ]

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

Modeling a Physical Device Hierarchy

The samples in this section do not directly deal with the TCP/IP protocol, as described in Alcatel 1359IOO document, to get the Remote Inventory Data. Instead, it is assumed that the remote inventory data is retrieved using the IOO protocol and stored as CSV files by an external process. The samples use the ASCII Reference Cartridge to retrieve the IOO CSV file, parse it, and model it into Oracle Communications Information Model. Each RI_DATA_NOTIF record contains one board for an NE. All the boards belonging to one NE must be aggregated as a list of child equipment of the NE (NE is modeled as Physical Device).

Figure 4-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 4-1 Sample Discovered Physical Device Hierarchy

Description of "Figure 4-1 Sample Discovered Physical Device Hierarchy"

Cartridge Dependencies

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

Run-Time Dependencies

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

Design-Time Dependencies

The ASCII Reference cartridge has the following dependencies:

Address_Handlers
NetworkIntegritySDK
ora_uim_model

Opening ASCII Reference Cartridge Files

This section provides information about downloading and opening the ASCII 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 ASCII Reference cartridge, you must first 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 ASCII Reference cartridge ZIP file, which has the following structure:

\Network_Integrity_Cartridge_Projects\ASCII_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 ASCII Reference cartridge.

To compile and deploy the ASCII Reference cartridge:

Import projects into Design Studio for Network Integrity.
Clean and build the cartridge.
Deploy the cartridge.

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

About the Cartridge Components

The ASCII Reference Cartridge contains the following actions:

Discover Alcatel 1359 IOO RI File

Discover Alcatel 1359 IOO RI File

The Discover Alcatel 1359IOO RI action reads one or more Alcatel 1359IOO RI CSV file instances in a directory, and from it provides hierarchical physical device model instances.

The Discover Alcatel 1359 IOO RI File action contains the following processors run in the following order:

Figure 4-2 illustrates the processor workflow of the Discover Alcatel 1359 IOO RI File action.

Figure 4-2 Discover Alcatel 1359IOO RI File Action Processor Workflow

Description of "Figure 4-2 Discover Alcatel 1359IOO RI File Action Processor Workflow"

Alcatel 1359IOO RI File Collector

The Alcatel 1359IOO RI File Collector processor is used to retrieve Alcatel 1359IOO RI CSV files, which are then made available to the next processor in the chain.

Note:

This processor is automatically generated from Design Studio input data.

Alcatel 1359IOO RI File Parser

The Alcatel 1359IOO RI File Parser processor is used to read the RI CSV files, parse the CSV file to get a list of RI records, and make them available to the next processor.

Each Alcatel IOO RI data record consists of multiple lines (refer to the sample IOO RI data in "About Collected Data"). To parse the multiple lines of record, each line must be defined as a sub-record. The last record in the IOO RI CSV file is the end of data record, which is configured as the trailer record. Like the data record, the trailer record, is a multi-line record, so each line is configured as a sub-record of the trailer record. See the Alcatel 1359IOO RI File Parser processor in Design Studio for information about how to configure the ASCII parsing rules for Alcatel 1359IOO RI CSV file.

The following diagram shows the ASCII parsing rules configuration tab of the Alcatel 1359IOO RI File Parser in Design Studio.

Figure 4-3 ASCII Parser in Design Studio

Description of "Figure 4-3 ASCII Parser in Design Studio"

Note:

This processor is automatically generated from Design Studio by configuring a set of proper ASCII parsing rules.

Alcatel 1359IOO RI Modeler

The Alcatel 1359IOO RI Modeler processor is used to model each individual RI record that is parsed by the Alcatel1359IOORIFileParser processor and aggregate all of them into a single physical device entity. This processor demonstrates how to do aggregation when modeling data in Network Integrity.

Alcatel 1359IOO RI Persister

The Alcatel 1359IOO RI Persister processor is used to persist the physical device tree to the Network Integrity database.

About Collected Data

This section shows a sample Alcatel 1359IOO RI CSV file that is provided to the Alcatel1359IOORIFileParser processor. This CSV file is generated by an external process, which uses the IOO protocol (TCP/IP connection) to get the RI records from EOS and save them to an ASCII file. This ASCII file is collected by the Alcatel1359IOORIFileCollector processor.

One ASCII file contains the information of all the boards for one NE. The ASCII file ends with the end of data record (the last record in the following sample ASCII file) to indicate that there are no more boards from that NE.

RI_DATA_NOTIF
[riDataList|
Palermo|
Zen|
QB3*|
1|
Palermo/r01sr1/board#01|
AITA|
A2S1|
3AL78818AAAC01|
--------------|
----------|
FA|
FA003650914|
00/08/31|
----------------------------------------------]

RI_DATA_NOTIF
[riDataList|
Palermo|
Zen|
QB3*|
8|
Palermo/r01sr1/board#08|
AITA|
PREA4ETH|
3AL79631AAAC03|
--------------|
----------|
FA|
FA024658237|
03/05/07|
----------------------------------------------]

RI_DATA_NOTIF
[riDataList|
Palermo|
Zen|
QB3*|
9|
Palermo/r01sr1/board#09|
AITA|
SYNTH1N|
3AL79090BAAA01|
--------------|
----------|
EZ|
EZ004150316|
00/10/06|
EXP RAM 32MB----------------------------------]

RI_DATA_NOTIF
[riDataList|
Palermo|
QB3*|
{2010/12/10 12:25:32}|
3]

About Cartridge Modeling

This section provides information about modeling the ASCII Reference cartridge.

Figure 4-4 shows a Unified Modeling Language (UML) diagram depicting the object relationship being rendered.

Figure 4-4 Information Model Entities UML Diagram

Description of "Figure 4-4 Information Model Entities UML Diagram"

Hierarchy Mapping

The physical device object is established and seeded with data sourced by "neName" attribute inside the RI record.

The Equipment object (board) is established and seeded from "blockLabel" attribute. Artificial chassis are created to the NE so that slot (equipment holder) can be created under.

The EquipmentHolder object is established and seeded from "blockNumber" attribute and modeled as slot: Block Number = Slot Number - 1.

Oracle Communications Information Model Information

All entities shown in Figure 4-4 (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 4-1 Physical Device Mappings

Physical Device	Information Model Support	RI Record Attribute	Field Type
Id	static	N/A	Text
Name	static	neName	Text
Description	static	N/A	Text
Specification	static	N/A	N/A, Programmatically set to Alcatel1359IOORIPhysicalDevice
neLocationName	static	neLocationName	Text
protocolType	dynamic	protocolType	Text
nativeEmsName	static	neName	Text
discoveredVendorName	dynamic	N/A	Text, hard-coded to be set to Alcatel
Serial Number	yes	N/A	Text
Physical Location	yes	N/A	Text

Table 4-2 Equipment Mappings

Equipment	Information Model Support	RI Record Attribute	Field Type
Id	static	N/A	Text
Name	static	blockLabel	Text, Extract the last part of blockLabel
Description	static	blockLabel	Text
Specification	static	N/A	N/A
alcatelCompany	dynamic	alcatelCompany	Text, Programmatically set to Alcatel1359IOORIPhysicalDevice
unitType	dynamic	unitType	Text
unitPartNumber	dynamic	unitPartNumber	Text
softwarePartNumber	dynamic	softwarePartNumber	Text
cleiCode	dynamic	cleiCode	Text
manufacPlant	dynamic	manufacPlant	Text
manufacDate	dynamic	manufacDate	Text
operatorInvData	dynamic	operatorInvData	Text
serialNumber	static	serialNumber	Text
nativeEmsName	static	blockLabel	Text
discoveredVendorName	dynamic	N/A	Text, hard-coded to be set to Alcatel
Physical Location	yes	N/A	Text

Table 4-3 EquipmentHolder Mappings

EquipmentHolder	Information Model Support	RI Record Attribute	Field Type
Id	static	N/A	Text
Name	static	blockNumber	Text, SlotNumber = blockNumber + 1
Specification	static	N/A	N/A, Programmatically set to Alcatel1359IOORIEquipmentHolder
nativeEmsName	static	blockNumber	Text, SlotNumber = BlockNumber +1
Description	yes	N/A	Text
Serial Number	yes	N/A	Text
Physical Location	yes	N/A	Text

Model Correction

This section provides Alcatel 1359IOO RI to Oracle Communications Information Model correction information.

About Model Correction Code

Model correction occurs when the Alcatel 1359IOO RI information received through discovery does not conform to Information Model and therefore cannot be persisted, as it is within Network Integrity. See "About Cartridge Modeling" for supported hierarchy.

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

EquipmentHolder under physical device:

		   PhysicalDevice
      EquipmentHolder

The ASCII Reference Cartridge adds an equipment entity as follows:

		   PhysicalDevice
     Equipment-named Alcatel 1359IOO RI Artificial Chassis
      EquipmentHolder

Design Studio Construction

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

The ASCII Reference cartridge contains the following specifications:

Alcatel1359IOORIPhysicalDevice
Alcatel1359IOOBoard
Alcatel1359IOORIEquipentHolder
Alcatel1359IOOArtificialChassis

Table 4-4 Discover Alcatel 1359IOO RI File Action Construction

Result Category	Address Handler	Scan Parameter Group Characteristics	Model	Processors
Device	FileTransfer AddressHandler	ftaFileTransferType ftaFilePattern ftaPort ftaUser ftaPassword ftaSessionTimeOut ftaSourceFileManagement ftaRenameSuffix	Alcatel 1326 IOO RI Model	Alcatel 1359IOO RI File Collector Alcatel 1359IOO RI File Parser Alcatel 1359IOO RI Modeler Alcatel 1359IOO RI Persister

Result Category

Address Handler

Scan Parameter Group Characteristics

Model

Processors

Device

FileTransfer AddressHandler

ftaFileTransferType

ftaFilePattern

ftaPort

ftaUser

ftaPassword

ftaSessionTimeOut

ftaSourceFileManagement

ftaRenameSuffix

Alcatel 1326 IOO RI Model

Alcatel 1359IOO RI File Collector

Alcatel 1359IOO RI File Parser

Alcatel 1359IOO RI Modeler

Alcatel 1359IOO RI Persister

In Figure 4-2 the first two chevrons indicate code-generated processors from Design Studio user input.

Alcatel 1359IOO RI File Collector is an instance of the file transfer processor
Alcatel 1359IOO RI File Parser is an instance of the file parser processor

Table 4-5 Action Conditions for Discover Alcatel 1359IOO RI File Action

Condition Name	Notes
checkPhysicalDevice	This condition returns a false result if the physical device from the Alcatel 1359IOO RI Modeler is null.

Table 4-6 Discover Alcatel 1359IOO RI File Action Processors

Processor Name	Variables
Alcatel 1359IOO RI File Collector	Input: N/A Output: alcatel1359IOORIFileCollectorFileCollection. java.util.Collecton A collection of files found in the path specified in the scope field.
Alcatel 1359IOO RI File Parser	Input: alcatel1359IOORIFileCollectorFileCollection Output: alcatel1359IOORIFileParserIterable An iterable to iterate over each discovered file.
Alcatel 1359IOO RI Modeler	Input: riFile Output: physicalDevice This processor can be extended to enhance an individual physical device tree. Any processor that uses its output parameter must check if this value is null before using it. The physical device is null if it does not contain information from all the boards.
Alcatel 1359IOO RI Persister	Input: N/A Output: N/A Context is persisted for performance

Design Studio Extension

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

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

The Alcatel 1359IOO RI Modeler aggregates the information for all the boards before completely modeling a physical device. Before a physical device is completely modeled, this processor outputs a null physical device. The action has a condition applied on the Alcatel 1359IOO RI Persister, which checks the physical device to determine whether it is null or not. The persister does not get invoked if PhysicalDevice is null (which means it is not completely modeled at that time). A new processor that is to further modify PhysicalDevice must apply the same condition (checkPhysicalDevice) to make sure that the physical device is ready and not null.

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