Download - Modeling Gateway Toolkit Guide (5069)
Modeling GatewayToolkit Guide
Document 5069
Modeling GatewayToolkit Guide
Page 2
Document 5069
NoticeCopyright Notice Copyright © 2002-Present by Aprisma Management Technologies, Inc. All rights reserved worldwide. Use, duplication, or disclosure by the United States government is subject to the restrictions set forth in DFARS 252.227-7013(c)(1)(ii) and FAR 52.227-19.
Liability Disclaimer Aprisma Management Technologies, Inc. (“Aprisma”) reserves the right to make changes in specifications and other information contained in this document without prior notice. In all cases, the reader should contact Aprisma to inquire if any changes have been made.
The hardware, firmware, or software described in this manual is subject to change without notice.
IN NO EVENT SHALL APRISMA, ITS EMPLOYEES, OFFICERS, DIRECTORS, AGENTS, OR AFFILIATES BE LIABLE FOR ANY INCIDENTAL, INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING BUT NOT LIMITED TO LOST PROFITS) ARISING OUT OF OR RELATED TO THIS MANUAL OR THE INFORMATION CONTAINED IN IT, EVEN IF APRISMA HAS BEEN ADVISED OF, HAS KNOWN, OR SHOULD HAVE KNOWN, THE POSSIBILITY OF SUCH DAMAGES.
Trademark, Service Mark, and Logo Information SPECTRUM, IMT, and the SPECTRUM IMT/VNM logo are registered trademarks of Aprisma Management Technologies, Inc., or its affiliates. APRISMA, APRISMA MANAGEMENT TECHNOLOGIES, the APRISMA MANAGEMENT TECHNOLOGIES logo, MANAGE WHAT MATTERS, DCM, VNM, SpectroGRAPH, SpectroSERVER, Inductive Modeling Technology, Device Communications Manager, SPECTRUM Security Manager, and Virtual Network Machine are unregistered trademarks of Aprisma Management Technologies, Inc., or its affiliates. For a complete list of Aprisma trademarks, service marks, and trade names, go to:
http://www.aprisma.com/manuals/trademark-list.htm.
All referenced trademarks, service marks, and trade names identified in this document, whether registered or unregistered, are the intellectual property of their respective owners. No rights are granted by Aprisma Management Technologies, Inc., to use such marks, whether by implication, estoppel, or otherwise. If you have comments or concerns about trademark or copyright references, please send an e-mail to [email protected]; we will do our best to help.
Restricted Rights Notice (Applicable to licenses to the United States government only.)This software and/or user documentation is/are provided with RESTRICTED AND LIMITED RIGHTS. Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR 52.227-14 (June 1987) Alternate III(g)(3) (June 1987), FAR 52.227-19 (June 1987), or DFARS 52.227-7013(c)(1)(ii) (June 1988), and/or in similar or successor clauses in the FAR or DFARS, or in the DOD or NASA FAR Supplement, as applicable. Contractor/manufacturer is Aprisma Management Technologies, Inc. In the event the government seeks to obtain the software pursuant to standard commercial practice, this software agreement, instead of the noted regulatory clauses, shall control the terms of the government's license.
Virus Disclaimer Aprisma makes no representations or warranties to the effect that the licensed software is virus-free. Aprisma has tested its software with current virus-checking technologies. However, because no antivirus system is 100-percent effective, we strongly recommend that you write protect the licensed software and verify (with an antivirus system with which you have confidence) that the licensed software, prior to installation, is virus-free.
Contact Information Aprisma Management Technologies, Inc., 273 Corporate Drive, Portsmouth, NH 03801 USA
Phone: 603.334.2100U.S. toll-free: 877.468.1448Web site: http://www.aprisma.com
Modeling GatewayToolkit Guide
Page 3
Document 5069
Contents
Notice ........................................................................................... 2
Preface ......................................................................................... 9
Intended Audience ..................................................................... 9
How to Use This Guide ................................................................ 9
Additional References ................................................................10
Text Conventions ......................................................................10
Document Feedback ..................................................................11
Online Documents .....................................................................11
Overview .................................................................................... 12
Prerequisites for Developers .......................................................12
A SPECTRUM Gateway for Topology Data .....................................12
Modeling Gateway Architecture .................................................. 14
Using the Modeling Gateway Toolkit ........................................... 18
Formatting the Data in an Input File ............................................18
Creating an XML Input File ....................................................18
Hierarchical Views ...........................................................19
Models and Model Types ..................................................19
SPECTRUM Attributes ......................................................20
Intelligent Models and Management Views ..........................21
XML Input File Syntax ...........................................................21
The Root Element ...........................................................21
Model-Oriented Elements .................................................22
Task-Oriented Elements ...................................................24
Creating Information .......................................................24
Representing the Same Device in Multiple Views .................27
Synchronizing Information between SPECTRUM and the Third-Party Database ............................................................28
Connections ...................................................................29
Modeling GatewayToolkit Guide
Page 4
Document 5069
Updating Information ......................................................31
Destroying Information ....................................................32
The tirc.xml Resource File .....................................................33
Working with a Comma-Delimited Input File ............................33
Importing the Input File .............................................................34
Moving the topimport Tool .....................................................35
Running the topimport Tool ...................................................35
Viewing Import Information ........................................................36
The Modeling Gateway View ..................................................36
Events and Alarms ...............................................................38
The Error Log and the Debug Log ...........................................38
Appendix A: Element Definition .................................................. 39
Connection ...............................................................................41
Syntax ...............................................................................41
Usage .................................................................................41
Attribute Definitions .............................................................41
Correlation ...............................................................................42
Syntax ...............................................................................42
Usage .................................................................................42
Attribute Definitions .............................................................42
CorrelationDomain ....................................................................43
Syntax ...............................................................................43
Usage .................................................................................43
Attribute Definitions .............................................................43
CustomerManager .....................................................................44
Syntax ...............................................................................44
Usage .................................................................................44
Attribute Definitions .............................................................44
Destroy ...................................................................................45
Syntax ...............................................................................45
Usage .................................................................................45
Attribute Definitions .............................................................45
Modeling GatewayToolkit Guide
Page 5
Document 5069
Device .....................................................................................46
Syntax ...............................................................................46
Usage .................................................................................46
Attribute Definitions .............................................................46
EventModel ..............................................................................48
Syntax ...............................................................................48
Usage .................................................................................48
Attribute Definitions .............................................................48
GenericView .............................................................................50
Syntax ...............................................................................50
Usage .................................................................................50
Attribute Definitions .............................................................50
GenericView_Container ..............................................................52
Syntax ...............................................................................52
Usage .................................................................................52
Attribute Definitions .............................................................53
Import ....................................................................................55
Syntax ...............................................................................55
Usage .................................................................................55
Attribute Definition ...............................................................55
List_Value ................................................................................56
Syntax ...............................................................................56
Usage .................................................................................56
Attribute Definitions .............................................................56
Location ..................................................................................57
Syntax ...............................................................................57
Usage .................................................................................57
Attribute Definitions .............................................................57
Location_Container ...................................................................58
Syntax ...............................................................................58
Usage .................................................................................58
Attribute Definitions .............................................................59
Model_Attr ...............................................................................61
Modeling GatewayToolkit Guide
Page 6
Document 5069
Syntax ...............................................................................61
Usage .................................................................................61
Attribute Definitions .............................................................61
MonitorPolicy_Attr .....................................................................62
Syntax ...............................................................................62
Usage .................................................................................62
Attribute Definitions .............................................................62
Port ........................................................................................63
Syntax ...............................................................................63
Usage .................................................................................63
Attribute Definitions .............................................................64
RTM_Test ................................................................................66
Syntax ...............................................................................66
Usage .................................................................................66
Attribute Definitions .............................................................66
Schedule .................................................................................67
Syntax ...............................................................................67
Usage .................................................................................67
Attribute Definitions .............................................................67
SM_AttrMonitor ........................................................................70
Syntax ...............................................................................70
Usage .................................................................................70
Attribute Definitions .............................................................70
SM_Customer ...........................................................................72
Syntax ...............................................................................72
Usage .................................................................................72
Attribute Definitions .............................................................72
SM_CustomerGroup ..................................................................75
Syntax ...............................................................................75
Usage .................................................................................75
Attribute Definitions .............................................................75
SM_Guarantee ..........................................................................76
Syntax ...............................................................................76
Modeling GatewayToolkit Guide
Page 7
Document 5069
Usage .................................................................................76
Attribute Definitions .............................................................76
SM_LatencyMon ........................................................................78
Syntax ...............................................................................78
Usage .................................................................................78
Attribute Definitions .............................................................78
SM_Service ..............................................................................79
Syntax ...............................................................................79
Usage .................................................................................79
Attribute Definitions .............................................................79
SM_ServiceMgr .........................................................................81
Syntax ...............................................................................81
Usage .................................................................................81
Attribute Definitions .............................................................81
SM_SLA ...................................................................................82
Syntax ...............................................................................82
Usage .................................................................................82
Attribute Definitions .............................................................82
Topology .................................................................................83
Syntax ...............................................................................83
Usage .................................................................................83
Attribute Definitions .............................................................83
Topology_Container ..................................................................84
Syntax ...............................................................................84
Usage .................................................................................84
Attribute Definitions .............................................................85
Update ....................................................................................87
Syntax ...............................................................................87
Usage .................................................................................87
Attribute Definitions .............................................................87
Appendix B- XML Examples ........................................................ 88
Example 1: Importing into the Topology View ...............................88
Modeling GatewayToolkit Guide
Page 8
Document 5069
Example 2: Creating Connections ................................................89
Example 3: Updating and Destroying ...........................................90
Example 4: Creating, Updating and Destroying .............................92
Index .......................................................................................... 97
Modeling GatewayToolkit Guide
Page 9
Document 5069
Preface
In this section:
Intended Audience [Page 9]
How to Use This Guide [Page 9]
Additional References [Page 10]
Text Conventions [Page 10]
Document Feedback [Page 11]
Online Documents [Page 11]
Intended Audience
This guide is intended for SPECTRUM developers and VARs (Value Added Resellers) who want to import network topology information into the SpectroSERVER database. This document focuses primarily on the use of the SPECTRUM Modeling Gateway toolkit for accepting network topology information from a third-party database via an XML file.
How to Use This Guide
This guide describes how to use the SPECTRUM Modeling Gateway toolkit to integrate third-party management systems with SPECTRUM. It is organized as follows:
• Overview: This section gives an overview of the capabilities of the SPECTRUM Modeling Gateway toolkit.
• Modeling Gateway Architecture: This section illustrates how the components of a SPECTRUM Modeling Gateway toolkit work together to bring network topology data into SPECTRUM.
• Mechanics of Integration: This section walks through each step necessary to complete the integration. The following topics are discussed:
- Creating an XML input file.
- Creating a comma-delimited input file.
- Importing the input file.
Modeling GatewayToolkit Guide
Page 10
Document 5069
- Viewing import results in the SpecroGRAPH.
• Appendix A: This section is a full reference for all elements and attributes included in the Document Type Definition file.
• Appendix B: This section has several sample XML files for your reference.
• Appendix C: This section contains the Document Type Definition.
• Appendix D: This section contains the tirc.xml resource file.
Additional References
• The Integrator Guide (5068): An overview of all of SPECTRUM’s integration points.
• SPECTRUM Concepts Guide (0647): An overview of SPECTRUM’s functionality and terminology.
Text Conventions
The following text conventions are used in this document:
Element Convention Used Example
User-supplied parameter names
Courier and italic in angle brackets <>.
The user needs to type the password in place of <password>.
On-screen text Courier The following line displays:path=”/audit”
User-typed text Courier Type the following path name: C:\ABC\lib\db
Cross-references Underlined and hypertext-blue
See Document Feedback [Page 11].
References to SPECTRUM documents (title and number)
Italic SPECTRUM Installation Guide (0675)
Functionality enabled by SPECTRUM Alarm Notification Manager (SANM)
SANM in brackets []. [SANM] AGE_FIELD_ID
Modeling GatewayToolkit Guide
Page 11
Document 5069
Document Feedback
Please send feedback regarding SPECTRUM documents to the following e-mail address:
Thank you for helping us improve our documentation.
Online Documents
SPECTRUM documents are available online at:
http://www.aprisma.com/manuals
Check this site for the latest updates and additions.
Modeling GatewayToolkit Guide
Page 12
Document 5069
Overview
In this section:
Prerequisites for Developers [Page 12]
A SPECTRUM Gateway for Topology Data [Page 12]
Prerequisites for Developers
Before using a programmatic on non-programmatic toolkit (including the SPECTRUM Modeling Gateway toolkit), developers should have significant exposure to the SPECTRUM product, and should read the SPECTRUM Concepts Guide (0647)to familiarize themselves with the underlying concepts of SPECTRUM. In addition, this document assumes a working knowledge of XML and the concept of a Document Type Definition (DTD). A detailed understanding of the network topology to be imported is also assumed. An ability to use the UNIX or Windows NT operating system to navigate through the file system, copy and delete files, and create and edit text files is necessary.
A SPECTRUM Gateway for Topology Data
The SPECTRUM Modeling Gateway toolkit allows integrators to import network topology data from an existing database into the SPECTRUM knowledge base. The toolkit includes a Document Type Definition (DTD) that defines XML elements and attributes. Using the DTD elements, you can create an XML file that describes devices, ports, and connections on your network. This XML file can create new topology data in SPECTRUM, update existing data, or destroy data that is no longer correct. Additionally, the elements and attributes used in the XML syntax can be expanded and customized to suit the needs of most integrations.
The toolkit also provides the capability to use comma-delimited ASCII text files to import information specifies Frame Relay and/or ATM connections. You can also import this connection information using the XML functionality mentioned above.
Once the network topology data exists in SPECTRUM, you can manage these devices like any other models created manually or by AutoDiscovery. You can view the results of the import, as well as any diagnostic information about each import.
Modeling GatewayToolkit Guide
Page 13
Document 5069
Populating SPECTRUM with dynamic network topology information on an ongoing basis was previously a difficult task. Neither AutoDiscovery nor manual modeling is suited to the constant updates necessary in a changing environment. Modeling connectivity using AutoDiscovery can also be a challenge with various physical infrastructures like those found in a cable MSO, ATM, or Frame Relay environment. SPECTRUM Modeling Gateway is an effective solution for these problems.
Modeling GatewayToolkit Guide
Page 14
Document 5069
Modeling Gateway Architecture
The SPECTRUM Modeling Gateway toolkit has several components that function together to import your network data. The first component is a source for the network topology data. This source is often a third-party database, such as a provisioning database, that stores the network topology data you would like to represent in SPECTRUM.
During the integration process, you take data from the third-party database and create an input file. Depending on the content, this input file may be an XML file or a comma-delimited ASCII file. The XML input file gives you the widest range of import options and is the main focus of this document. The comma-delimited file allows you to create connections for Frame Relay and ATM circuits.
When creating an XML input file, you must work with the provided Document Type Definition (DTD) file and the tirc.xml file. The DTD defines the XML elements, attributes and their associated syntax rules. The tirc.xml file shows which SPECTRUM model types and attributes are available for use. This file relates the SPECTRUM model type names and other attribute names with the unique hexadecimal identifier that SPECTRUM uses for that model type or attribute. The tirc.xml file can be customized to suit the needs of a specific integration. Additions to the tirc.xml file will need to be added to the DTD.
Once you create the first input file, it can act as a template for multiple data sets representing the same type of input. For example, if you create an XML file for importing devices, you can use this file over and over again by substituting the device specific topology data.
The import tool is a command line utility that reads network topology information from the input file and sends the data to the SpectroSERVER database. The tool is able to import data for display in the SPECTRUM Location and Topology view. You can also import data into a customized view tailored to fit the needs of your integration. With the data from the XML file, the import tool can create, destroy, and update connections, devices, and container models.
The SPECTRUM Modeling Gateway also provides mechanisms to ensure the safety and accuracy of each database import, such as maintaining an audit trail that includes a record of each creation, deletion, association, and update made. You can view information about the import within a GIB view in the SpectroGRAPH. If any type of critical failure occurs during the import process, SPECTRUM generates an event that reports the error. All errors
Modeling GatewayToolkit Guide
Page 15
Document 5069
and their possible causes are logged in an error log file. You can also turn on a debug log that helps you locate the source of problems or inaccuracies.
The first figure below illustrates the use of an XML file for importing data. Data flows from the third-party database and is formatted in the XML file, using the DTD and tirc.xml for syntax purposes. The import tool then interprets the XML file and sends data into SPECTRUM through SPECTRUM’s CORBA interface.
Modeling GatewayToolkit Guide
Page 16
Document 5069
The next figure illustrates the use of a comma-delimited ASCII text file to import Frame Relay and/or ATM connection information.
XMLFile
ResourceFile
DTD
Third Party
Database
Element Definition
Enumerationof Model Typesand Attributes
FormattedTopologyData
XML
DataTopology
T C IO NR TB EA R F A C E
TopologyData
OPIMPORT
TOOL
SpectroSERVER
Modeling GatewayToolkit Guide
Page 17
Document 5069
Third Party
DatabaseDataComma
DelimitedASCIIFile
C IO NR TB EA R F A C E
ATM/FrameRelay ConnectionData
ConnectionATM/Frame
Comma
Relay
Data
Delimited
Connection SpectroSERVER
TOPI
MPORT
TOOL
Modeling GatewayToolkit Guide
Page 18
Document 5069
Using the Modeling Gateway Toolkit
In this section:
There are four main tasks to complete when using the Modeling Gateway Toolkit.
1. Extracting Topology Data
The first step is to extract the network topology data from the third-party database. Since each database system is different, you should refer to the documentation for the database you are working with to complete this step.
2. Formatting the Data in an Input File [Page 18]
In this step you will create the either an XML or a comma-delimited input file to format the data for the import tool.
3. Importing the Input File [Page 34]
Once the input file is created, use the import tool to send the data into SPECTRUM.
4. Viewing Import Information [Page 36]
You are able to see the progress and results of the import in the Modeling Gateway view in SpectroGRAPH.
Formatting the Data in an Input File
There are two types of input files used to import data with the Modeling Gateway, XML files and comma-delimited files. XML input files can be used to create or destroy models and connections, and update attribute values and connectivity information. The syntax in the document type definition provided with the Modeling Gateway defines the elements to be used in the XML input file. Comma-delimited files can only be used to create ATM and Frame Relay connections. The sections below outline how to create each of the types of input files.
Creating an XML Input File
To understand the elements that are used to create an XML input file, you must be familiar with how SPECTRUM models a network infrastructure. The following section gives you an overview of this philosophy and how it
Modeling GatewayToolkit Guide
Page 19
Document 5069
applies to the XML elements used in an XML input file. If you are comfortable with these concepts, you may want to skip this section and proceed to the XML Input File Syntax [Page 21] section.
Hierarchical Views
A view in SPECTRUM is a way to organize data so it can be displayed or manipulated. There are two main types of views, management views and hierarchical views. Management views focus on various ways to represent data concerning a specific device. The hierarchical views represent ways to structure your network data. When you structure your network data in the XML file, you choose from elements that represent each of the hierarchical views. There are two types of hierarchical views, Topology and Location.
The Topology view is really an abstraction of networking components. When working with this view, you represent the physical or logical components of your network and group these components with logical connectivity in mind. You can choose to graphically represent connections using pipes that show how devices are connected at the port or device level.
The Location view organizes your network data by physical location. Using this view you can depict your network in terms of geography. You can start with your global offices and go right to the wiring closet on each floor of each building in each region where your offices are located.
Models and Model Types
There are numerous model types that have been predefined in SPECTRUM. When model types are instantiated in the SPECTRUM interface to represent a specific network entity, they are referred to as models. There are two major categories of model types, intelligent model types and container model types. Intelligent model types can be instantiated to represent actual devices that operate on the network. They have IP and MAC addresses and SPECTRUM can communicate directly with these devices using SNMP. Container model types are instantiated into models that act primarily as a way of grouping models together.
Models can be grouped together based on the type of hierarchical view being used. For example, if you were using the Topology view, you might create a LAN model to group together certain devices on a segment of your network. If you were using the Location view, you might create a Room model to group the devices in one room of your building.
A container model may contain other container models, intelligent models, or both, depending on the specific model type. For example, a network
Modeling GatewayToolkit Guide
Page 20
Document 5069
container model could contain an intelligent model that represents a router, and it can also contain a LAN container model that represents a range of IP addresses. On the other hand, a Building model can only contain container models- a Floor, a Section, or a Room.
The elements defined in the DTD let you depict your network topology using any of the hierarchical views and their respective container model types. You can also use any of the instantiable intelligent model types. Intelligent model types are not dependent on the type of hierarchical view used.
Note that not all model types defined in the SPECTRUM knowledge base can actually be used to create a model in the SpectroGRAPH. Some are used as base model types from which other model types are derived. For more information on this subject, please refer to the SPECTRUM Concepts Guide (0647).
There are two methods used to model devices in SPECTRUM. The first method is to use the IP address or the DNS name of the device. With this information, SPECTRUM contacts the device and creates a model using the model type that best represents the functionality of the device.
The second method is to choose the model type to base the model on. You still must provide an IP address or a DNS name so SPECTRUM can communicate with the device, however the model type you choose is instantiated regardless of SPECTRUM’s assessment of the device’s functionality.
To create a container model, you select the model type since there is no physical device for SPECTRUM to communicate with.
SPECTRUM Attributes
Each model type has a set of attributes associated with it. Each attribute describes the model type in some way. When a model is instantiated, the attributes take on values that reflect the device that the model represents and describes the model’s current state. For example, the model type Host_Sun has the attribute IPAddress. If a model of the type Host_Sun is instantiated, the value of this attribute reflects the IP address of the device that the model represents.
It is important to note that XML syntax also uses the term “attribute.” XML attributes describe additional information about an element. In SPECTRUM Modeling Gateway XML syntax, some XML attributes are used to give value to SPECTRUM attributes. For clarity, attributes defined by SPECTRUM are
Modeling GatewayToolkit Guide
Page 21
Document 5069
referred to as SPECTRUM attributes, XML attributes are referred to simply as attributes.
Intelligent Models and Management Views
As mentioned above, a model representing an SNMP-compliant device within the SpectroGRAPH, must have either an IP Address or a DNS name to identify that device. Once the device model is created, SPECTRUM communicates with the device and gathers device-specific information about MIB variables, ports, and applications. This information can be viewed in one of several different management views, which provide current network device status information and records of network events.
For example, the Device Topology (DevTop) view represents a device in terms of its ports and port connections. You can use the DevTop view to examine existing connections to a device or make new connections to other devices. The Application view contains application models that SPECTRUM automatically creates to monitor a device’s applications. Other views include information on performance, configuration, and SPECTRUM attribute values.
When you use the XML elements to create your device model, SPECTRUM automatically creates management views along with application models and ports based on the type of model you have instantiated, and interaction with the physical device through querying SNMP MIB objects. You have the ability to create connections between these ports and modify SPECTRUM port attribute information using an XML input file.
XML Input File Syntax
Use the syntax rules defined in the DTD file to generate the XML file. Below is an overview of the functionality of each of the DTD elements. The following explanations and examples do not cover all attributes of each element. For a complete reference on each element and its attributes, see Appendix A: Element Definition [Page 39].
The Root Element
The elements defined in the DTD exist in a hierarchical structure that parallels the network representation within SPECTRUM. The root element that must be used with each XML import file is the Import element. XML syntax rules specify that the root element is the outermost element and denotes the beginning and end of the XML file. Therefore, the Import element surrounds the rest of the XML elements used in your document.
Modeling GatewayToolkit Guide
Page 22
Document 5069
Model-Oriented Elements
The model-oriented elements define physical or logical components of your network. They are listed below:
· Topology_Container
· Location_Container
· Device
· Schedule
· Port
· Connection
· GenericView_Container
The container-type elements are used to create models that define logical ways of grouping network elements based on the type of SPECTRUM hierarchal view they are in. Each of these container-type elements can exist in one of the specific hierarchical views.
The Topology_Container element creates a model that groups other models according to physical or logical connectivity. Since the Topology_Container element creates container models, you must use the model_type attribute to identify the specific container you would like to use. There is an enumeration of possible model_type values in the DTD. A LAN is an example of a Topology_Container model_type value. You specify the name of the Topology_Container using the name attribute. The name and model_type attributes uniquely identify the model created.
Note: By default, the name and model_type attributes give values to the SPECTRUM attributes Model_Name and Modeltype_Name. However, you can change which SPECTRUM attribute the name attribute gives value to by editing the .tirc.xml file. Whatever new SPECTRUM attribute is chosen, (along with model type) is used to uniquely identify the container. This would allow 2 containers to have the same model name.
Topology_Containers can contain other Topology_Container elements, devices, or connections. Topology_Container models are always placed in SPECTRUM’s topology view.
The Location_Container element groups other models according to physical or geographical location. A Building and a Room are both examples of Location_Container element model type values. Since the
Modeling GatewayToolkit Guide
Page 23
Document 5069
Location_Container element creates container models, you must use the model_type attribute to identify the specific container you would like to use. There is an enumeration of possible model_type values in the DTD. You specify the name of the Location_Container using the name attribute. The name and model_type attributes uniquely identify the model created.
Note: By default, the name and model_type attributes give values to the SPECTRUM attributes Model_Name and Modeltype_Name. However, you can change which SPECTRUM attribute the name attribute gives value to by editing the .tirc.xml file. Whatever new SPECTRUM attribute is chosen, (along with model type) is used to uniquely identify the container. This would allow 2 containers to have the same model name.
The Device element defines a device on the network. It is used with other elements to create, update, or destroy an instance of a device model in SPECTRUM. If you are working with an SNMP device, you must provide a valid, unique IP address or DNS name to uniquely identify the device using the ip_dnsname attribute. This allows SPECTRUM to communicate with the device and select the most appropriate model type based on the device’s functionality. If SNMP communication with the device is either not supported or not allowed, the is_managed attribute should be set to false. The ip_dnsname must be set to a unique string, but it does not need to be a valid IP address or DNS name. In this case, the model_type attribute must be set so SPECTRUM knows which model type to use to represent the device. Possible model_type values for devices are enumerated in the tirc.xml resource file.
The Schedule element defines when a device model will be put into maintenance mode. When a device model is in maintenance mode, management traffic to the device and its components is suspended. This prevents SPECTRUM from generating any events or alarms on the device model while you are performing maintenance on the device.
Ports are automatically created for a device when you create the device model. The Port element lets you modify some SPECTRUM port attribute values, or specify a port-level connection. You can specify different kinds of ports, including a Frame Relay or ATM circuit. You must provide values for the identifier_name and identifier_value attributes to identify the port on the device. The possible values for identifier_name are enumerated in the DTD. The identifier_value should be the value of the identifier chosen by the identifier_name attribute. A Port element must always be specified as a child of a device element.
Modeling GatewayToolkit Guide
Page 24
Document 5069
The Connection element defines a physical or logical connection between two devices and therefore must contain two device child elements. If a Port element is specified in the Device element, the connection is resolved on the port level for that device. When using the Connection element, you can choose whether or not to create pipes that graphically represent these connections within the SpectroGRAPH. Connections can only be created in the Topology view.
Task-Oriented Elements
The rest of the elements defined in the DTD are task-oriented elements. These elements and their attributes help define the type of action the input file generates. It is possible to create new topology information, update, overwrite or delete existing topology information. An individual input file may use zero or one of each of these elements, with the exception of the Connection element. As many Connection elements as necessary can be utilized.
• Topology
• Location
• GenericView
• Connection
• Update
• Destroy
Creating Information
Task-oriented elements define what action you would like to take with your XML file. The Topology and Location elements are used when you would like to create new network topology data in SPECTRUM. These elements define the hierarchical view where you would like to create the data. You can then use the corresponding model elements as child elements to create models for the network entities. Use the GenericView element to customize a view for specific integration needs.
Topology View
To import your network data into SPECTRUM’s Topology view, construct your XML file using the Topology element inside the Import root element. The Topology element can contain:
• Topology_Container elements to create a specific kind of container model
Modeling GatewayToolkit Guide
Page 25
Document 5069
• Device elements to create a specific type of device model
• Connection elements to create connections between two devices
Using the hierarchy and syntax rules outlined in the DTD definition, you can accurately express your network’s physical and logical connectivity.
The following is a basic example that shows a LAN container created in the Topology view and a device within that container. For information on creating connections, see the Connections [Page 29] section.
<?xml version = “1.0” standalone = “no” ?>
<!DOCTYPE Import SYSTEM “.import.dtd”>
<Import>
<Topology>
<Topology_Container model_type = “LAN” name = Sample_LAN” security_string = “public”subnet_address= “10.253.9.0” subnet_mask = “255.255.255.0”>
<Device ip_dnsname= “10.253.9.18” community_string=“public”/>
</Topology_Container>
</Toplogy>
</Import>
The Import element is the root element and is always contained in the input file.
The Topology element indicates that you are going to create models in the Topology view.
The Topology_Container element creates a container model. Since this model is a logical component rather than a physical component of the network, SPECTRUM does not have the ability to contact it and define the model type using an IP address or a DNS name. To indicate the type of contain model to create, you must provide a value for the model_type attribute. The possible model_type attribute values are listed in the DTD and under the Topology_Container listing in Appendix A. The name attribute is required and must specify a unique name for the model. The other attributes specified are optional.
The Device element creates a model inside the LAN Topology_Container model. The ip_dnsname attribute is a required attribute for the Device element. If the device can be contacted by SPECTRUM, the IP Address or the DNS name is used to find the device. When SPECTRUM locates the device, it determines the appropriate model type to use to create the
Modeling GatewayToolkit Guide
Page 26
Document 5069
model. If the device is not SNMP compliant, assign any string value to the ip_dnsname attribute, and use the model_type attribute to define what type of model SPECTRUM should create.
For a complete reference of these elements and their possible attributes, see Appendix A: Element Definition [Page 39].
Location View
To create your topology information in the Location View of SPECTRUM, construct your XML file using the Location element inside the Import root element. The Location element can contain Location_Container elements to create a specific kind of container model, or Device elements to create a specific type of device model.
The following is a basic example that shows a Site container created in the Location view and a device within that container.
<?xml version = “1.0” standalone = “no” ?>
<!DOCTYPE Import SYSTEM “.import.dtd”>
<Import>
<Location>
<Location_Container model_type = “Site” name = “My_Town” >
<Device ip_dnsname= “10.253.9.18” community_string=“public”/>
</Location_Container>
</Location>
</Import>
The Import element is the root element and is always contained in the input file.
The Location element indicates that you are creating models in the Location view.
The Location_Container element creates a container model. Since this model is a logical component rather than a physical component of the network, SPECTRUM does not have the ability to contact it and define the model type using an IP address or a DNS name. To indicate the type of contain model to create, you must provide a value for the model_type attribute. The possible model_type attribute values are listed in the DTD and under the Location_Container element definition in Appendix A. The name attribute is required and must specify a unique name for the model.
Modeling GatewayToolkit Guide
Page 27
Document 5069
The Device element creates a model inside the Site Location_Container model. The ip_dnsname attribute is a required attribute for the Device element. If the device can be contacted by SPECTRUM, the IP Address or the DNS name is used to find the device. When SPECTRUM locates the device, it determines the appropriate model type to use to create the model. If the device is not SNMP compliant, assign any string value to the ip_dnsname attribute, and use the model_type attribute to define what type of model SPECTRUM should create.
For a complete reference of these elements and their possible attributes, see Appendix A: Element Definition [Page 39].
Representing the Same Device in Multiple Views
It is possible to create an XML file that represents a device in multiple views. When doing this, it is highly recommended that each of the Device elements used to create a model of this device have identical attributes and attribute values. If they are not identical, the import tool will attempt to merge all of the attributes and values of these Device elements to create a set of consistent attributes and values. If an attribute is specified in each of these Device elements, but different values are used, the value used by the last Device element listed in the XML file will override all previous values for that attribute in the other Device elements used to create a model of that device.
It is important to remember that some attributes have default values. For example, the default value of the attribute community_string is public. Therefore, if you specify an attribute and value in one Device element used to represent device A, it is recommended that you specify it in any other Device element used to represent device A to ensure that a default value for that attribute is not used to override the previously specified value.
In the example below device 10.253.9.16 is created in the Topology and Location views. Note that the attributes and values used to describe the device is the same for both views.
<?xml version = “1.0” standalone = “no” ?>
<!DOCTYPE Import SYSTEM “.import.dtd”>
<Import>
<!-- Topology View import -->
<Topology discover_connections="false" complete_topology="false">
<Device ip_dnsname="10.253.9.16" community_string="zippo" />
</Topology>
Modeling GatewayToolkit Guide
Page 28
Document 5069
<!-- Location View import -->
<Location complete_topology="true">
<Location_Container model_type="Site" name="Durham">
<Device ip_dnsname="10.253.9.16" community_string=”zippo”/>
</Location_Container>
</Location>
</Import>
Synchronizing Information between SPECTRUM and the Third-Party Database
The Topology, Location, Topology_Container, and Lan_Container elements have an attribute called complete_topology. If you set the value of this attribute to true, then you are indicating that the XML file defines all of the models and connections that SPECTRUM needs to know about. When the XML file is imported into SPECTRUM, any models that exist in that SPECTRUM view, but are not represented in the XML file, are sent to the lost and found. If there are sub-containers in the view, SPECTRUM refers to the value of the complete_topology attribute set in the element specifying the sub-container. If the complete_topology attribute value is not specified in the sub-container element, the value is inherited from the parent element. Thus, if the parent element has a complete_topology setting of true and the sub-container element does not specify a setting for complete_topology, the complete_topology value for the sub-container is also true. When SPECTRUM imports the XML file, all models that exist either directly in the view you are importing into or in the sub-container of that view, but do not exist in the XML file, will be sent to the lost and found. This attribute is useful when synchronizing the data in your third-party database with the data in SPECTRUM.
In the example below, complete_topology is set to true within the Topology element. Except for models specified in this input file, all existing models in the Topology view would be sent to the lost and found. With this sample input file there are only two models specified, the LAN Topology Container and the device at IP address 10.253.9.18. If these models did not exist, they would be created. If they already existed, SPECTRUM would update their SPECTRUM attribute values based on the attribute values in the input file. Any other model existing in the Topology view (with the exception of the VNM) would be sent to the lost and found.
<?xml version = “1.0” standalone = “no” ?>
<!DOCTYPE Import SYSTEM “.import.dtd”>
<Import>
Modeling GatewayToolkit Guide
Page 29
Document 5069
<Topology complete_topology=“true”><Topology_Container model_type = “LAN” name =“Sample_LAN”
security_string = “public” subnet_address= “10.253.9.0”subnet_mask = “255.255.255.0”>
<Device ip_dnsname= “10.253.9.18” community_string=“public”/>
</Topology_Container>
</Toplogy>
</Import>
If the complete_topology attribute were used in the Topology_Container element instead of the Topology element, SPECTRUM would only remove unspecified models from that Topology_Container down through the hierarchy.
Connections
A SPECTRUM connection represents a physical or logical link between two devices. It is possible to create connections two different ways in the XML input file. The first method makes use of SPECTRUM’s AutoDiscovery function. This is done via the discover_connections attribute of the Topology element. When this attribute is set to true, AutoDiscovery runs on the newly created device models and connectivity for these devices is established. For more information on AutoDiscovery, see the AutoDiscovery User’s Guide (0727).
<?xml version = “1.0” standalone = “no” ?>
<!DOCTYPE Import SYSTEM “.import.dtd”>
<Import>
<Topology discover_connections= “true”>
<Topology_Container model_type = “LAN” name = “Sample_LAN”security_string = “public” subnet_address= “10.253.9.0”subnet_mask = “255.255.255.0”>
<Device ip_dnsname= “10.253.9.18” community_string=“public”/>
<Device ip_dnsname= “10.253.9.20” community string=“public”/>
</Topology_Container>
</Toplogy>
</Import>
The second way to create connections is to use the Connection element, which connects devices that are already created. Connections can be specified between two ports, between a device and a port, or between two
Modeling GatewayToolkit Guide
Page 30
Document 5069
devices. Connectivity information allows SPECTRUM to properly detect and diagnose faults on your network.
Specifying connectivity between devices allows SPECTRUM to isolate faults to the device, but specifying port level connections is preferred. Port level connections are a finer grade of connectivity allowing SPECTRUM to resolve the connections and analyze faults at the port level. If you specify a connection between two devices, but do not specify either one or both ports used in the connection, SPECTRUM will automatically attempt to determine these ports. If this process is successful, SPECTRUM resolves the connection to the port level.
If SPECTRUM is unable to determine both ports used in the connection, and if at least one of these devices is a manageable device, SPECTRUM will generate an error indicating a connection failure. This error will be written to the error log file (see The Error Log and the Debug Log [Page 38]).
If SPECTRUM is only able to determine one of the ports, then the connection will only be resolved to the port level on one side of the connection, the other side will remain resolved to the device level.
If both devices are unmanageable devices, SPECTRUM will establish the connection at the device level.
The following example creates a connection between two existing ports; each port belonging to a different device. The Connection element identifies both the Port and Device elements to be linked. The connection is resolved at the port level for both devices because a Port element is specified within each Device element. The Connection element has an optional attribute called create_pipes. When create_pipes is set to true, a graphical representation of the connection is created in the SpectroGRAPH. By default create_pipes is set to true. Set create_pipes to false for circuit link connections to avoid having a large number of connections crowd the view. In this example, connect_pipes is set to false, so a graphical representation of the connection is not created in SPECTRUM.
<?xml version = “1.0” standalone = “no” ?>
<!DOCTYPE Import SYSTEM “.import.dtd”>
<Import>
<Connection create_pipes= “false”>
<Device ip_dnsname= “172.19.57.93”>
<Port identifier_name = “frCircuitTableInstance” identifier_value=”4.161”/>
Modeling GatewayToolkit Guide
Page 31
Document 5069
</Device>
<Device ip_dnsname = “192.168.125.161”>
<Port identifier_name= “frCircuitTableInstance” identifier_value= “2.861”/>
</Device>
</Connection>
</Import>
This example above specifies a connection between DLCI ports. Since the value of the identifier_name attribute is frCircuitTableInstance, the port is identified using the OID instance value from the frCircuitTable object in the MIB. The OID instance value is specified using the identifier_value attribute.
The Connection element be been contained within a Topology element or a Topology_Container element to indicate the hierarchical placement of the devices. This does not change the results of the input file.
Note: Modeling Gateway will not report an error if you attempt to import an XML file that contains multiple Connection elements using the same Port element. It is not possible for a single port to have multiple connections. If the same port is specified in multiple Connection elements, the last Connection element in the XML file will override all previous Connection elements specifying that port.
Updating Information
The Update element is used to update SPECTRUM attribute information for existing models. The Update element can enclose Container elements and/or Device elements. The value of Port attributes is updated using the appropriate Device element. Below is an example of an update input file where two different attributes for two separate models are updated.
<?xml version = “1.0” standalone = “no” ?>
<!DOCTYPE Import SYSTEM “.import.dtd”>
<Import>
<Update>
<Topology_Container model_type=“LAN” name=“Sample” model_name = “newLAN”/>
<Device ip_dnsname= “Test1” poll_interval= “1108”/>
</Update>
</Import>
Modeling GatewayToolkit Guide
Page 32
Document 5069
The first updated attribute is the model_name attribute of the LAN container model. The model name is changed from Sample to newLAN. Note the use of the attributes name and model_name. Both of these attributes exist to change the SPECTRUM attribute Model_Name. Use the name attribute with the current name as the value to identify the container model. Then use the model_name attribute to specify the new name of the container model.
Next, the example changes the value of the poll interval for the device from Test1 to 1108. Assigning a new value to the poll_interval attribute overwrites the old value.
Note that the Topology_Container element and the Device element are not nested and do not represent any sort of hierarchy. The only hierarchy that can be specified within the Update element is the hierarchy of a Device and a Port. Nesting a Container and a Device within an Update element processes syntactically, but produces irregular results.
Destroying Information
The Destroy element deletes container models, device models, and connections. When you destroy a device, all port and application models associated with the device are also destroyed. In the example below, the LAN topology container called newLAN is destroyed. Note that all models within this container are sent to the SPECTRUM lost and found, unless they are specified to be destroyed. This example also destroys a connection between two devices (Test1 and Test2), which is specified at the port level.
<?xml version = “1.0” standalone = “no” ?>
<!DOCTYPE Import SYSTEM “.import.dtd”>
<Import>
<Destroy>
<Topology_Container model_type=“LAN” name=“newLAN”/>
<Connection>
<Device ip_dnsname= “Test1” >
<Port identifier_name= “ifIndex” identifier_value= “1”/>
</Device>
<Device ip_dnsname= “Test2”>
<Port identifier_name=“ipAddress” identifier_value = “10.253.8.18”/>
</Device>
</Connection>
Modeling GatewayToolkit Guide
Page 33
Document 5069
</Destroy>
</Import>
The Topology_Container and Connection are not nested in the example above. The only hierarchy that should be expressed in the Destroy element is the Connection, Device, and Port hierarchy necessary to delete connections at the port level. An example of this hierarchy is shown above where the connection between a port on Test1 and a port on Test2 is deleted. The actual devices, Test1 and Test2, are not deleted.
To destroy a model representing a device that has already been removed from the network, use the IP address of the device rather than the DNS name when specifying the ip_dnsname attribute of the Device in the Destroy element of an XML file. This is important because once the device has been removed from the network, the DNS entry for that device will no longer exist, and the Modeling Gateway cannot identify the appropriate model to delete.
The tirc.xml Resource File
The Topology_Container, Location_Container, and Device elements have a model_type attribute that must have a value equal to a valid SPECTRUM model type. SPECTRUM uniquely identifies model types using a hexadecimal number. These hexadecimal values have been enumerated in the resource file tirc.xml. This file pairs and a text value for the model type with the unique hexadecimal identifier. The text values are then shown in the DTD.
Many of the attributes defined in the DTD correspond to SPECTRUM attributes. SPECTRUM attributes are uniquely identified in SPECTRUM using a hexadecimal number. Rather than use these hexadecimal values in the DTD or in the XML file, the tirc.xml file pairs the SPECTRUM attributes’ hexadecimal identifiers with more intuitive text-based names.
Both the ModelType element and the Attribute element of the tirc.xml file can be customized.
Working with a Comma-Delimited Input File
In addition to specifying ATM and Frame Relay connectivity via an XML input file, the Modeling Gateway toolkit can accept ATM and Frame Relay connectivity information via a comma-delimited ASCII text file. This file can be used to import information about connections between two ATM circuits, two Frame Relay circuits, or an ATM and a Frame Relay circuit. You have the option to specify that a live pipe be created in the SpectroGRAPH
Modeling GatewayToolkit Guide
Page 34
Document 5069
to represent the connection. Multiple connections can be specified in the same input file. The device models involved in these connections must already exist in SPECTRUM.
Following is the format for the input file:
<Device_IP>, <OID>, <Device_IP>, <OID>, <CircuitName>, <CircuitID>, <Pipe>
Device_IP is the IP address of each device involved in the connection. This parameter is required for each device.
OID is the OID instance of frCircuitTable, atmVclTable or atmVplTable to specify the circuit link on the device. This parameter is required for each device.
CircuitName is an optional parameter specifying the name of the circuit involved.
CircuitID is an optional parameter specifying the ID of the circuit involved.
Pipe is an optional parameter with two possible values, CREATE_PIPE or NO_CREATE_PIPE. If the value is set to CREATE_PIPE, live pipes will be created between the connections specified. If the value is set to NO_CREATE_PIPE, live pipes will not be created between the connections specified. If no value is specified for this parameter, a default value of CREATE_PIPE is assumed.
The following example shows an input file that specifies the connection between two frame relay circuits. There will be a live pipe created between these two ports.
172.19.57.93, 4.161, 192.168.125.161, 2.161, FR_Circuit_Name, Circuit_Id_123, CREATE_PIPE
Importing the Input File
Once you have set up the input file, use the import tool to send the network data into the SpectroSERVER database. The import tool is a command line utility that is located in SPECTRUM’s SS-Tools directory and can be run on a SpectroSERVER or on another host machine. If you would like to run the tool on another machine, you must move the tool and all of its support files to that machine.
Modeling GatewayToolkit Guide
Page 35
Document 5069
Moving the topimport Tool
The Modeling Gateway toolkit provides a script that packs up the topimport tool so that it can be sent via FTP to another machine. The script ensures that the relative directory structure of the tool and its support files is retained when the files are moved.
The following steps show you how to move these files:
1. On the SpectroSERVER, check to make sure the environmental variable SPECROOT is set to the SPECTRUM installation directory path.
2. Run the script that packs up the tool and its support files. The script can be found in SPECTRUM’s SS-Tools directory and is called packtool.pl.
To run the script from the Bash shell or other Unix shell, type:
<Spectrum_Installation_Path>/SS-Tools/packtool.pl topimport
Where <Spectrum_Installation_Path> is the directory structure where SPECTRUM is installed on your SpectroSERVER.
3. The script generates an executable file called topimport_bundle (Unix) or topimport_bundle.exe (Windows) that contains the topimport tool and all of its support files.
4. On the third-party host, create a new directory to unpack the topimport tool and its support files, i.e. /disk/Spectrum.
5. FTP the topimport_bundle or topimport_bundle.exe file from the SpectroSERVER to the third-party host, and place it in the directory created in step 4. Be sure to use binary mode during the FTP process.
6. Once the file is on the third-party host, execute the file from the DOS, Bash, or other Unix shell. The topimport tool and its support files will unpack into the appropriate directory structure. The topimport tool can now be run from this host machine.
Note: Both servers involved in this process must be running the same operating system. You cannot pack the tool on a Windows server and unpack it on a Unix machine or vise versa.
Running the topimport Tool
In order to run the topimport tool from a machine other than the SpectroSERVER, you must set the SPECROOT (Unix) or SPECPATH (Windows) environmental variable on this machine equal to the path to the
Modeling GatewayToolkit Guide
Page 36
Document 5069
directory where you placed the topimport_bundle or topimport_bundle.exe file.
For example, if you are working in the Unix environment and placed the topimport_bundle file in /disk/Spectrum as in step 4 in Moving the topimport Tool [Page 35], then you must set SPECROOT=/disk/Spectrum. If you are working in the Windows environment and placed the topimport_bundle.exe file in C:\disk\Spectrum, then you must set SPECPATH=C:\disk\Spectrum.
The syntax to run the tool is outlined below. It takes 4 arguments, two are required and two are optional.
topimport -vnm <vnm_name> -i <input_file> [-o <outputfile>] [-debug]
The vnm_name argument is the name of the SpectroSERVER host. This argument is required.
The input_file is the name of the XML or comma-delimited input file containing the necessary input information. This argument is required.
The -o argument logs the error information to the file named in the outputfile parameter. If this option is not used, the error information is logged to a file named inputfile.log, where inputfile is the name of the XML file.
The debug argument indicates that you would like to create a debugging output file during the import process. This argument is optional.
Viewing Import Information
The SPECTRUM Modeling Gateway also provides mechanisms to ensure the safety and accuracy of each database import. SPECTRUM Modeling Gateway maintains an audit trail that includes a record of each creation, deletion, association, and update made. You can view data about the import within a Modeling Gateway view available in the SpectroGRAPH. You can also track information on import problems in the error and debug logs.
The Modeling Gateway View
To bring up the Modeling Gateway view, right click on the VNM model and select Configuration. The Landscape Configuration dialog becomes active. In the Configure/Information box, select ModelingGatewy and then click OK.
Modeling GatewayToolkit Guide
Page 37
Document 5069
The bottom half of the Modeling Gateway view shows the a report that gives you information about recent imports. The number of import files listed is controlled by the Max Records box in the upper right portion of the screen.
There are three buttons on the left hand side of the screen, just below the horizontal rule. The Sort button arranges the list of files alphabetically based on the name in the Import File field. The Find button lets you search for a particular Import File name. The Update button refreshes the screen, so you can check the status of an import as it is being processed.
The Topology import report displays the following information:
Import File: This field shows the name of the import file.
Log File: This field shows the name of the log file.
Start Time: This field indicates when the topology import process began.
End Time: This field indicates when the topology import process completed.
Progress: The progress field shows the status of the topology import if it has not yet finished. The possible values for this field are:
• Initializing
• Identifying Models
• Creating Models
• Activating Models
• Mapping Connectivity
• Placing Models
• Creating Connections
• Updating Models
• Destroying Models
• Complete
• Disconnected
Errors: This field shows the number of errors generated during the import process.
Mdls Created: This field shows the number of models created during the import process.
Modeling GatewayToolkit Guide
Page 38
Document 5069
Mdls Destroyed: This field shows the number of models eliminated during the import process.
Connections Created: This field shows the number of connections created during the import process.
Connections Destroyed: This field shows the number of connections destroyed by the import process.
Events and Alarms
The top half of the Modeling Gateway view shows information about the TopologyImport model. This model is never instantiated in the SpectroGRAPH; it is only used as a basis for this view or as the basis for an alarm in the Alarm Manager application.
If any type of critical failure occurs during the import process, SPECTRUM generates an IMPORT_ERROR event reporting that error. To alert the user to this error, the event generates a minor alarm that indicates an error occurred for that import session. If the Modeling Gateway view indicates that an error occurred, right-click in the view and choose Model Alarm from the menu. This brings up the Alarm Manager and shows the details of the alarm. Within the event tab, you can identify the import file, the output file, and the user id involved in creating the alarm.
The Error Log and the Debug Log
All errors and their possible causes are logged in an error log file. By default, the import tool creates an error log called<nameofimportfile>.log where <nameofimportfile> is the name of your import file. You can also specify a particular name for your log file using the syntax specified in the section on the import tool. When the import is complete, the log file appears in the SS-Tools directory. The log file records the number of successful creations, deletions, and updates of models and connections, as well as each single failure that occurred during the importing process.
When using the import tool, you also have the option of turning on a debug log that helps you locate the source of problems or inaccuracies. Once the import is complete, the debug file can be found in the SS-Tools directory. This file is named TIDebug.txt, and file gives you a textual explanation of each step that has taken place in the import process.
Modeling GatewayToolkit Guide
Page 39
Document 5069
Appendix A: Element Definition
The purpose of this appendix is to explain the functionality and context of each element defined in the Document Type Definition, not the syntax used in the DTD. Refer to an XML reference for this information.
In this section:
Connection [Page 41]
Correlation [Page 42]
CorrelationDomain [Page 43]
CustomerManager [Page 44]
Destroy [Page 45]
Device [Page 46]
EventModel [Page 48]
GenericView [Page 50]
GenericView_Container [Page 52]
Import [Page 55]
List_Value [Page 56]
Location [Page 57]
Location_Container [Page 58]
Model_Attr [Page 61]
MonitorPolicy_Attr [Page 62]
Port [Page 63]
RTM_Test [Page 66]
Schedule [Page 67]
SM_AttrMonitor [Page 70]
SM_Customer [Page 72]
SM_CustomerGroup [Page 75]
SM_Guarantee [Page 76]
Modeling GatewayToolkit Guide
Page 40
Document 5069
SM_LatencyMon [Page 78]
SM_Service [Page 79]
SM_ServiceMgr [Page 81]
SM_SLA [Page 82]
Topology [Page 83]
Topology_Container [Page 84]
Update [Page 87]
Modeling GatewayToolkit Guide
Page 41
Document 5069
Connection
Syntax
Usage
The Connection element specifies a connection between two devices, a port and a device, or two ports. The Connection element must always contain two device elements and each of these Device elements can contain zero or one Port elements. If ports are specified, the connection is resolved at the port level.
If the Connection element is used as a child of the Destroy element, the connection specified is destroyed. If the connection is used in any other context, the connection is created.
Attribute Definitions
Parent Elements: Import, Topology, Topology_Container, Destroy
Child Elements Rule
Device The Connection element must contain two device elements.
Attribute Data Type
Required Default Value
Possible Values
Definition
create_pipe Boolean No True NA This attribute indicates whether or not a graphical representation of the specified connection is shown in the SpectroGRAPH. It is recommended that you set this attribute to FALSE when specifying a Frame Relay or ATM connection.
Modeling GatewayToolkit Guide
Page 42
Document 5069
Correlation
Syntax
Usage
This element represents a Correlation Manager model and is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
There are no attributes for the Correlation element.
Parent Elements: Import
Child Elements Rule
Correlation_Domain This element can contain any number of child elements.
Modeling GatewayToolkit Guide
Page 43
Document 5069
CorrelationDomain
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: Correlation
Child Elements Rule
Device, Port, Model_Attr This element can contain any number of child elements.
Attribute Data Type
Required Default Value
Possible Values
Name Character Data
Yes NA NA
Modeling GatewayToolkit Guide
Page 44
Document 5069
CustomerManager
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: Import
Child Elements Rule
SM_Customer, SM_CustomerGroup
This element can contain any number of child elements.
Attribute Data Type
Required Default Value Possible Values
name Character Data
Yes NA NA
containment_relation
Character Data
No Groups_Customers NA
model_type Character Data
No CustomerManager NA
Modeling GatewayToolkit Guide
Page 45
Document 5069
Destroy
Syntax
Usage
Use the Destroy element to remove container models, device models, and connections. You cannot nest elements in the Destroy element to express hierarchies or destroy hierarchies. The only hierarchy allowed in the Destroy element is the Connection-Device-Port hierarchy, which specifies at the port level the connection that should be destroyed. If you destroy a container model without destroying the device models or other container models contained inside it, the remaining models are placed in the lost and found within SPECTRUM.
Attribute Definitions
The Destroy element does not have any attributes.
Parent Elements: Import
Child Elements Rule
Topology_Container, Location_Container, GenericView_Container, Device, Connection
The Destroy element can contain as many of each of these child elements as necessary. There are no required child elements.
Modeling GatewayToolkit Guide
Page 46
Document 5069
Device
Syntax
Usage
Use the device element to create, destroy, or update a device model. The Device element lets you define the device model based on ether an IP address or a DNS name.
Attribute Definitions
Parent Elements: Topology, Location, Topology_Container, Location_Container, GenericView, GenericView_Container, Connection, Update, Destroy, SM_Service, SM_AttrMonitor
Child Elements Rule
Port If a Device element is contained within a Connection element, only one port element is allowed. If a Device element in contained within an Update element to update ports, more than one port element is allowed. If a Device element is contained in a View, Container, or Destroy element, the ports are ignored.
Schedule The Device element can contain one Schedule element.
Attribute Data Type
Required Default Value
Possible Values
Definition
ip_dnsname CharacterData
Yes NA NA The IP address or DNS name of the device. If the device does not support SNMP communication, a unique string can be used here.
community_string
Character Data
No Public NA The community name of the device.
Modeling GatewayToolkit Guide
Page 47
Document 5069
model_type CharacterData
No NA Any intelligent model type define in the tirc.xml resource file.
The SPECTRUM model type used to model your device. If you have provided an IP address or DNS name, this field need not be specified.
is_managed Boolean No True True/False If set to True, it indicates that the model is SNMP compliant and can be contacted by SPECTRUM.
poll_interval CharacterData
No NA NA The time interval, in seconds, that the SpectroSERVER will read all attributes of the device model that are flagged as POLLED.
log_ration CharacterData
No NA NA The number of SpectroSERVER polls of a device that occur prior to logging the poll results in the database.
poll_status Boolean No NA True/False Lets you to disable the SpectroSERVER polls of a device by setting the polling status to False.
model_name CharacterData
No NA NA The name of the model.
DeviceType Character Data
No NA NA The Device Type of the model. See the Generic SNMP Device Management User and Toolkit Guide (1316) for more information.
Modeling GatewayToolkit Guide
Page 48
Document 5069
EventModel
Syntax
Usage
Use the EventModel element to import EventModel models for use with a Southbound Gateway integration. For more information on Southbound Gateway, see the Southbound Gateway Toolkit Guide (5066).
Attribute Definitions
Parent Elements: Topology_Container
Child Elements Rule
None NA
Attribute Data Type
Required Default Value
Possible Values
Definition
model_name Character Data
Yes NA NA The unique name of the model instantiated or identified.
unique_id Character Data
Yes NA NA The identifier used to uniquely define the event source that this EventModel model represents. For more information see the Southbound Gateway Toolkit Guide (5066).
manager_name
Character Data
No 0 0 = Default1= NetMentor2= SSM3= Omni2000
The name of the third-party application that is using the Southbound Gateway. If the application is not one of the choices noted in the Possible Values column, 0 for Default should be chosen.
Modeling GatewayToolkit Guide
Page 49
Document 5069
security_string Character Data
No public no The security string for the EventModel.
Modeling GatewayToolkit Guide
Page 50
Document 5069
GenericView
Syntax
Usage
Use the GenericView element to create a customized hierarchical view other than the Topology view and Location view. You can modify this element to meet the needs of your integration.
Attribute Definitions
Parent Elements: Import
Child Elements Rule
GenericView_Container, Device
The GenericView element can contain any number of these child elements.
Attribute Data Type
Required Default Value
Possible Values
Definition
containment_relation
CharacterData
Yes NA Must be a SPECTRUM containment relation.
This is a relation handle that defines which SPECTRUM relation defines the containment relationship within this view.
model_type Character Data
Yes NA NA This model type represents the top container model defined for this view. This model_type needs to be specified with its model handle in the tirc.xml file.
name CharacterData
Yes NA NA This is the unique name of the instantiated container model highest in the GenericView hierarchy.
Modeling GatewayToolkit Guide
Page 51
Document 5069
complete_toplogy
Boolean No NA NA When this attribute is set to True, any unspecified, existing container and device model in the GenericView view, or sub containers of that view, are destroyed during the import.
Modeling GatewayToolkit Guide
Page 52
Document 5069
GenericView_Container
Syntax
Usage
Use the GenericView_Container element to create a container model in the Generic View. Both the GenericView and GenericView_Container elements are used to create a customized view. Therefore, the integrator decides when or how to use this container.
Parent Elements: Generic View
Child Elements Rule
GenericView_Container, Device
The GenericView_Container element can contain any number of child elements.
Modeling GatewayToolkit Guide
Page 53
Document 5069
Attribute Definitions
Attribute Data Type
Required Default Value
Possible Values
Definition
name CharacterData
Yes NA NA The name of the model instantiated or identified. The model_type and the name attribute are required to uniquely identify the GenericView_Container.
By default, this attribute is used to set the value of the SPECTRUM model name attribute (attr id 0x1006e). However, this can be changed to any other attribute in the .tirc.xml file. If you change the .tirc.xml so that name maps to a different attribute, that new attribute will be used (along with model type) to identify the container. This would allow 2 containers to have the same model name.
model_type CharacterData
Yes NA NA The SPECTRUM model type used to create the model. This model_type needs to be specified with its model handle in the tirc.xml file. The model_type and the name attribute are required to uniquely identify the GenericView_Container.
Modeling GatewayToolkit Guide
Page 54
Document 5069
containment_relation
Character Data
No NA NA The name of the SPECTRUM relation that will exist between the Generic_Container and the models within the container. If no value for this attribute is specified, the parent model’s containment relationship is inherited.
Modeling GatewayToolkit Guide
Page 55
Document 5069
Import
Syntax
Usage
The Import element is the root element, and must be included in each input file.
Attribute Definition
Parent Elements: None
Child Elements Rule
Topology, Location, GenericView, Update, Destroy, Connection,SM_ServiceMgr,Correlation,CusomerManager
The Import element can contain one of each of these elements. No child elements are required elements.
Attribute Data Type
Required Default Value
Possible Values
Definition
model_activation_time
CharacterData
No 5 minutes
NA The maximum number of minutes allowed for each device model activation.
Modeling GatewayToolkit Guide
Page 56
Document 5069
List_Value
Syntax
Usage
Use the List_Value element to specify a SPECTRUM list attribute value.
Attribute Definitions
There are no attributes for the List_Value element.
Parent Elements: Model_Attr
Modeling GatewayToolkit Guide
Page 57
Document 5069
Location
Syntax
Usage
Use the Location element to specify that you would like to create models in the Location View of the SpectroGRAPH.
Attribute Definitions
There are no attributes for the Location element.
Parent Elements: Import
Child Elements Rule
Location_Container, Device The Location element can contain any number of child elements.
Modeling GatewayToolkit Guide
Page 58
Document 5069
Location_Container
Syntax
Usage
Use the Location_Container element to create or specify a Location_Container model used to group models and other location containers in the Location view. Possible model types are listed below in the model_type section.
Parent Elements: Location, Location_Container
Child Elements Rule
Location_Container, Device The Location_Container element can contain any number of child elements.
Modeling GatewayToolkit Guide
Page 59
Document 5069
Attribute Definitions
Attribute Data Type
Required Default Value
Possible Values
Definition
name CharacterData
Yes NA NA The name of the model instantiated or identified. The model_type and the name attribute are required to uniquely identify the Location_Container.
By default, this attribute is used to set the value of the SPECTRUM model name attribute (attr id 0x1006e). However, this can be changed to any other attribute in the .tirc.xml file. If you change the .tirc.xml so that name maps to a different attribute, that new attribute will be used (along with model type) to identify the container. This would allow 2 containers to have the same model name.
model_type Enumera-tion
Yes NA CountryRegionSiteBuildingFloorSectionRoom
Indicates the type of model you want to create. The choices are enumerated in the Possible Values column. The model_type and the name attribute are required to uniquely identify the Location_Container.
Modeling GatewayToolkit Guide
Page 60
Document 5069
security_string CharacterData
No NA NA Defines the requirements for access to a model by SPECTRUM users. Each security string consists of one or more Security Community entries and are assigned to models.
model_name CharacterData
No NA NA To change the name of the model, use the name and the model_name attributes. The name attribute specifies the old name and the model_name attribute specifies the new name.
model_modify_author
Character Data
No NA NA Writes data to the SPECTRUM attribute mdl_modfy_athr.
complete_topology
Boolean No False True/False When set to True, any unspecified, existing containers and device models in the Location view, or any sub containers, are destroyed during the import.
Modeling GatewayToolkit Guide
Page 61
Document 5069
Model_Attr
Syntax
Usage
Use the Model_Attr element to specify SPECTRUM attributes whose values contain multiple lines of text or a list values.
Attribute Definitions
Parent Elements: Correlation Domain
Child Elements Rule
List_Value The Model_Attr element can contain any number of child elements.
Attribute Data Type
Required Default Value
Possible Values
Definition
attr_id Character Data
Yes NA NA Indicates the SPECTRUM attribute ID of the attribute you are specifying.
Modeling GatewayToolkit Guide
Page 62
Document 5069
MonitorPolicy_Attr
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
There are no attributes for this element.
Parent Elements: SM_Service, SM_AttrMonitor
Child Elements Rule
None NA
Modeling GatewayToolkit Guide
Page 63
Document 5069
Port
Syntax
UsageThe Port element is used to specify connections at the port level or to update port attributes. When updating, the parent Device element is contained within an Update element. When specifying a connection, the parent device element is contained within a Connection element.
Parent Elements: Device, SM_Service, SM_AttrMonitor
Child Elements Rule
None NA
Modeling GatewayToolkit Guide
Page 64
Document 5069
Attribute Definitions
Attribute Data Type
Required Default Value
Possible Values Definition
identifier_name
Enumera-tion
Yes NA ifIndexipAddressifPhysAddressifNameifAliasmodel_nameportDescriptionportIDfrCircuitTableInstanceatmVclTableInstanceatmVplTableInstance
Works with the identifier_value attribute to uniquely identify the port. The identifier_name can be any one of the MIB OID names listed in the Possible Values column.
The portID value can be used to identify a port by its Component_OID attribute (0x1006a). Note that this cannot be used with subinterfaces.
If the Port element represents a Frame Relay virtual circuit, use frCircuitTableInstance.
If the Port element represents an ATM virtual channel or path link, use atmVclTableInstance.
identifier_value
CharacterData
Yes NA NA The value of the identifier_name selection
model_name
Character Data
No NA NA The name of the model you are updating
circuit_id Character Data
No NA NA Used with an ATM or Frame Relay connection to identify the circuit involved.
Modeling GatewayToolkit Guide
Page 65
Document 5069
circuit_name
Character Data
No NA NA The circuit_name attribute is used with an ATM or Frame Relay connection to name the circuit involved.
log_ratio Character Data
No NA NA The number of SpectroSERVER device polls that occur before logging the poll results in the database.
poll_interval
Character Data
No NA NA The time interval, in seconds, that the SpectroSERVER reads all attributes of the device model flagged as POLLED.
poll_status
Boolean No NA True/False Allows an administrator to disable SpectroSERVER device polls by setting polling status to False.
Modeling GatewayToolkit Guide
Page 66
Document 5069
RTM_Test
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: SM_Service, SM_AttrMonitor,
Child Elements Rule
None NA
Attribute Data Type
Required Default Value
Possible Values
name Character Data
Yes NA NA
model_type Character Data
No RTM_Test NA
Modeling GatewayToolkit Guide
Page 67
Document 5069
Schedule
Syntax
Usage
Use the Schedule element to create a maintenance mode schedule for a particular device model.
Attribute Definitions
Parent Elements: Device
Child Elements Rule
None N/A
Attribute Data Type
Required Default Value
Possible Values Definition
Name Character Data
Yes NA NA The name of the schedule.
SCHED_Recurrence
Character Data
Yes 1 1 = Always (24 X 7)2 = Daily3 = Weekly4 = Monthly5 = Yearly
How often the device model will be put into maintenance mode.
SCHED_Start_Hour
Character Data
No NA 0-23 The hour the device will go into maintenance mode.
SCHED_Start_Minute
Character Data
No NA 0-59 The minute the device will go into maintenance mode.
Modeling GatewayToolkit Guide
Page 68
Document 5069
SCHED_Start_DoW
Character Data
No NA 0 = Sunday1 = Monday2 = Tuesday3 = Wednesday4 = Thursday5 = Friday6 = Saturday
The day of the week the device will go into maintenance mode.
SCHED_Start_DoM
Character Data
No NA 1-31 The day of the month the device will go into maintenance mode.
SCHED_Start_Month
Character Data
No NA 0 = January1 = February2 = March3 = April4 = May5 = June6 = July7 = August8 = September9= October10 = November 11 = December
The month the device will go into maintenance mode.
SCHED_Duration
Character Data
No 0 NA The length of time the device will be in maintenance mode, defined in seconds.
SCHED_Recurrence_Multiplier
Character Data
No 1 NA Number of recurrence units (days, weeks, months, years) that determine the length of time between the start of each scheduled maintenance mode.
Modeling GatewayToolkit Guide
Page 69
Document 5069
SCHED_Daily_Repeat_Limit
Character Data
No NA NA Number of consecutive days to repeat scheduled maintenance (specified by SCHED_Start_Hour and SCHED_Start_Minute) during each recurrence period. This attribute is only applicable to a weekly, monthly or yearly recurrence.
Modeling GatewayToolkit Guide
Page 70
Document 5069
SM_AttrMonitor
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: SM_Service, SM_AttrMonitor, SM_Guarantee
Child Elements Rule
SM_Service, SM_AttrMonitor, SM_LatencyMon, SM_ConnectMon, Device, Port, Topology_Container, RTM_Test, MonitorPolicy_Attr
The SM_ServiceMgr element can contain any number of child elements.
Attribute Data Type
Required Default Value
Possible Values
name Character Data
Yes NA NA
containment_relation
Character Data
No NA SLMMonitorsSLMWatchesContainer
AttrToWatch Character Data
No NA NA
MonitorPolicy_ID
Character Data
No NA NA
is_managed Boolean No NA TrueFalse
Modeling GatewayToolkit Guide
Page 71
Document 5069
Generate_Service_Alarms Boolean No NA TrueFalse
model_type Character Data
No SM_AttrMonitor
NA
Modeling GatewayToolkit Guide
Page 72
Document 5069
SM_Customer
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: SM_CustomerGroup, SM_CustomerManager
Child Elements Rule
SM_Service, SM_SLA This element can contain any number of child elements.
Attribute Data Type
Required Default Value
Possible Values
name Character Data
Yes NA NA
containment_relation
Character Data
No NA SlmAgreesToSlmUses
Security_String Character Data
No NA NA
CustomerID Character Data
No NA NA
Criticality Character Data
No NA NA
CustomerField4 Character Data
No NA NA
CustomerField5 Character Data
No NA NA
CustomerField6 Character Data
No NA NA
Modeling GatewayToolkit Guide
Page 73
Document 5069
CustomerField7 Character Data
No NA NA
Contact_Name Character Data
No NA NA
Contact_Title Character Data
No NA NA
Contact_Location Character Data
No NA NA
Email_Address Character Data
No NA NA
Phone_Number Character Data
No NA NA
Mobile_Phone_Number Character Data
No NA NA
Pager_Number Character Data
No NA NA
Fax_Number Character Data
No NA NA
User_Defined_1 Character Data
No NA NA
User_Defined_2 Character Data
No NA NA
User_Defined_3 Character Data
No NA NA
User_Defined_4 Character Data
No NAS NA
Secondary_Contact_Name CharacterData
No NA NA
Secondary_Contact_Location
Character Data
No NA NA
Secondary_Email_Address Character Data
No NA NA
Secondary_Phone_Number Character Data
No NA NA
Secondary_Mobile_Phone_Number
Character Data
No NA NA
Secondary_Pager_Number Character Data
No NA NA
Modeling GatewayToolkit Guide
Page 74
Document 5069
Secondary_Fax_Number Character Data
No NA NA
Secondary_User_Defined_1 Character Data
No NA NA
Secondary_User_Defined_2 Character Data
No NA NA
Secondary_User_Defined_3 Character Data
No NA NA
Secondary_User_Defined_4 Character Data
No NAS NA
model_type Character Data
No SM_Customer
NA
Modeling GatewayToolkit Guide
Page 75
Document 5069
SM_CustomerGroup
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: SM_CustomerManager, SM_CustomerGroup
Child Elements Rule
SM_CustomerGroup, SM_Customer
This element can contain any number of child elements.
Attribute Data Type
Required Default Value Possible Values
name Character Data
Yes NA NA
containment_relation
Character Data
No Groups_Customers NA
model_type Character Data
No SM_CustomerGroup
NA
Modeling GatewayToolkit Guide
Page 76
Document 5069
SM_Guarantee
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: SM_SLA
Child Elements Rule
SM_Service, SM_AttrMonitor, SM_LatencyMon, SM_ConnectMon
This element can contain any number of child elements.
Attribute Data Type
Required Default Value Possible Values
name Character Data
Yes NA NA
containment_relation
Character Data
No SlmIsMeasuredBy NA
is_managed Boolean No NA TrueFalse
DegradedTimeViolationLevel
Character Data
No NA NA
DegradedTimeWarningLevel
Character Data
No NA NA
DownTimeViolationLevel
Character Data
No NA NA
Modeling GatewayToolkit Guide
Page 77
Document 5069
DownTimeWarningLevel
Character Data
No NA NA
LorTimeViolationLevel
Character Data
No NA NA
LorTimeWarningLevel
Character Data
No NA NA
model_type Character Data
No SM_Guarantee
NA
Modeling GatewayToolkit Guide
Page 78
Document 5069
SM_LatencyMon
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: SM_Guarantee, SM_AttrMonitor, SM_Service
Child Elements Rule
Topology_Container, MonitorPolicy_Attr
This element can contain any number of child elements.
Attribute Data Type
Required Default Value
Possible Values
name Character Data
Yes NA NA
containment_relation Character Data
No NA SlmMonitorsSlmWatchesContainer
is_managed Boolean No NA TrueFalse
DefaultMaxRTT Character Data
No NA NA
DefaultMeasureInterval Character Data
No NA NA
model_type Character Data
No SM_LatencyMon
NA
Modeling GatewayToolkit Guide
Page 79
Document 5069
SM_Service
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: SM_Service, SM_ServiceMgr, SM_AttrMonitor, SM_Guarantee, SM_Customer
Child Elements Rule
SM_Service, SM_AttrMonitor, SM_LatencyMon, SM_ConnectMon, Device, Port, Topology_Container, RTM_Test, MonitorPolicy_Attr
This element can contain any number of these child elements.
Attribute Data Type
Required Default Value
Possible Values
name Character Data
Yes NA NA
Criticality Character Data
No NA NA
containment_relation Character Data
No NA SlmMonitorsSlmWatchesContainer
AttrToWatch Character Data
No NA NA
MonitorPolicy_ID
Character Data
No NA NA
Modeling GatewayToolkit Guide
Page 80
Document 5069
is_managed Boolean No NA TrueFalse
Generate_Service_Alarms Boolean No NA TrueFalse
Security_String Character Data
No NA NA
model_type Character Data
No SM_Service
NA
Modeling GatewayToolkit Guide
Page 81
Document 5069
SM_ServiceMgr
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: Import
Child Elements Rule
SM_Service This element can contain any number of child elements.
Attribute Data Type
Required Default Value Possible Values
Name Character Data
No NA NA
containment_relation Character Data
No SlmContains NA
model_type Character Data
No SM_ServiceMgr NA
Modeling GatewayToolkit Guide
Page 82
Document 5069
SM_SLA
Syntax
Usage
This element is used with SPECTRUM’s Service Manager. See the Service Manager User Guide (5155) for usage details.
Attribute Definitions
See the Service Manager User Guide (5155) for attribute definitions.
Parent Elements: SM_Customer
Child Elements Rule
SM_Service, SM_Guarantee This element can contain any number of child elements.
Attribute Data Type
Required Default Value
Possible Values
name Character Data
Yes NA NA
containment_relation Character Data
No SlmContains
NA
is_managed Boolean No NA TrueFalse
Security_String Character Data
No NA NA
model_type Character Data
No SM_SLA
NA
Modeling GatewayToolkit Guide
Page 83
Document 5069
Topology
Syntax
Usage
Use the Topology element to create models in the Topology View of the SpectroGRAPH.
Attribute Definitions
Parent Elements: Import
Child Elements Rule
Topology_Container, Device, Connection
The Topology element can contain any number of child elements.
Attribute Data Type
Required Default Value
Possible Values
Definition
complete_topology
Boolean No False True/False When set to true, any unspecified, existing container and device model in the Topology view, and any sub containers of that view, are destroyed during the import.
discover_connections
Boolean No False True/False When set to true, SPECTRUM’s AutoDiscovery runs on any newly created device models to automatically map the models’ connectivity.
Modeling GatewayToolkit Guide
Page 84
Document 5069
Topology_Container
Syntax
Usage
Use the Topology_Container element to create or specify a Topology_Container model used to group models and other topology containers in the Topology View. Possible model types are listed below in the model_type section.
Parent Elements: Topology, Topology_Container, SM_Service, SM_AttrMonitor
Child Elements Rule
Topology_Container, Device, EventModel, Connection
The Topology_Container element can contain any number of these child elements.
Modeling GatewayToolkit Guide
Page 85
Document 5069
Attribute Definitions
Attribute Data Type
Required Default Value
Possible Values
Definition
name CharacterData
Yes NA NA The name of the model instantiated or identified. The model_type and the name attribute are required to uniquely identify the Topology_Container.
By default, this attribute is used to set the value of the SPECTRUM model name attribute (attr id 0x1006e). However, this can be changed to any other attribute in the .tirc.xml file. If you change the .tirc.xml so that name maps to a different attribute, that new attribute will be used (along with model type) to identify the container. This would allow 2 containers to have the same model name.
model_type enumera-tion
Yes NA NetworkLANIPClassAIPClassBIPClassCLAN_802_#LAN_803_5ATM_Network
Indicates the type of model you want to create. The choices are enumerated in the Possible Values column. The model_type and the name attribute are required to uniquely identify the Topology_Container.
security_string Character Data
No NA NA The assigned SPECTRUm security level for the model.
Modeling GatewayToolkit Guide
Page 86
Document 5069
subnet_address
Character Data
No NA NA Specifies the subnet address of the device.
network_address
Character Data
No NA NA This is only used for EventAdmin models. it specifies the IP address of the device that the EventAdmin model represents.
subnet_mask CharacterData
No NA NA Specifies the mask that determines what subnet the device IP address belongs to
model_name Character Data
No No NA Specifies a model name for the container model.
complete_topology
Boolean No False True/False When set to True, any unspecified, existing container and device model in this Topology_Container and, any sub containers, are destroyed during the import.
discover_connections
Boolean No No True/False Specifies if SPECTRUM should discover and model devices that are connected to this model.
Modeling GatewayToolkit Guide
Page 87
Document 5069
Update
Syntax
Usage
Use the Update element to update attributes for any device, container, or port sub-elements. Note that hierarchical specifications are not allowed when using this element, with the exception of using the Port element within the Device element.
Attribute Definitions
There are no attributes for the Update element.
Parent Elements: Import
Child Elements Rule
Topology_Container, Location_Container, GenericView_Container,Device
The Update element can contain any number of child elements.
Modeling GatewayToolkit Guide
Page 88
Document 5069
Appendix B- XML Examples
Note: Note that element names in each example are highlighted in bold. This is done to make the examples easier to read, and is not intended to imply formatting necessary for the XML input file.
Example 1: Importing into the Topology View
This example shows a basic input file that imports information into the SPECTRUM Topology view. This file creates a Network container model in the Topology view. In the Network container, a LAN container model is created. Within the LAN container two devices are created. One device is identified by the DNS name deadlock and the other device is identified with an IP address.
Since the Topology element’s attribute complete_topology is set to False, SPECTRUM respects other models that already exist in the Topology view. Consequently, this file only looks to create models for entries listed in the XML file. The models created are placed in the Topology hierarchy. Models that already exist in the Topology hierarchy are unaffected.
<?xml version="1.0" standalone="no"?>
<!DOCTYPE Import SYSTEM ".import.dtd">
<Import>
<!-- ************************************* --><!-- This part is for Topology view import --><!-- ************************************* -->
<Topology complete_topology="false">
<Device ip_dnsname="10.253.9.17" model_type="GnSNMPDev" community_string="public"/>
<Device ip_dnsname="nmcss52-5" />
<Topology_Container model_type="Network" name="My Network" security_string="public" subnet_address="10.253.0.0" subnet_mask="255.255.0.0">
<Topology_Container model_type="Lan" name="Lan1" security_string="public" subnet_address="10.253.9.0" subnet_mask="255.255.255.0">
<Device ip_dnsname="deadlock" />
<Device ip_dnsname="10.253.9.18" poll_interval="333" />
Modeling GatewayToolkit Guide
Page 89
Document 5069
</Topology_Container>
</Topology_Container>
</Topology>
</Import>
Example 2: Creating Connections
This example shows the creation of a connection between two ATM circuits and the creation of a connection between two Frame Relay circuits. It also shows a connection between a FrameRelay DLCI port and an ATM VCL port.
<?xml version="1.0" standalone="no"?>
<!DOCTYPE Import SYSTEM ".import.dtd">
<Import>
<Connection create_pipe="false">
<Device ip_dnsname="10.253.32.225">
<Port identifier_name="atmVclTableInstance"identifier_value="5.0.5" circuit_name="ATM Link1" circuit_id = "ATM 5017" />
</Device>
<Device ip_dnsname="134.141.52.25">
<Port identifier_name="atmVclTableInstance"identifier_value="3.0.12" circuit_name="ATM Link1" circuit_id = "ATM 5017" />
</Device>
</Connection>
<Connection>
<Device ip_dnsname="10.253.9.18">
<Port identifier_name="frCircuitTableInstance" identifier_value="2.27"/>
</Device>
<Device ip_dnsname="nmcss52-5">
<Port identifier_name="frCircuitTableInstanceidentifier_value="4.161"/>
</Device>
</Connection>
<!-- ********************************************* --><!-- Connection between a FrameRelay DLCI port and --><!-- an ATM VCL port. --><!-- ********************************************* -->
Modeling GatewayToolkit Guide
Page 90
Document 5069
<Connection>
<Device ip_dnsname="10.253.9.18">
<Port identifier_name="frCircuitTableInstance" identifier_value="2.27"/>
</Device>
<Device ip_dnsname="10.253.32.225"> <Port identifier_name="atmVclTableInstance"
identifier_value="5.0.17"/>
</Device>
</Connection>
<Connection >
<Device ip_dnsname="nmcss52-5">
<Port identifier_name="ifIndex" identifier_value="3"/>
</Device>
<Device ip_dnsname="10.253.9.17"> <Port identifier_name="ifPhysAddress"
identifier_value="0:4:27:C:91:C0"/>
</Device>
</Connection>
</Import>
Example 3: Updating and Destroying
The following example illustrates the use of the Update and the Destroy elements.
The Update element contains a Location_Container element. This example updates the model name by using the name and model_name attributes of the Location_Container element. The name attribute is set equal to the current name and identifies the model to be updated. The model_name attribute updates the value of the name attribute to Peace2.
The Update element also contains a Device element and Port element. The attributes identifer_name and identifier_value are used to identify the port to be updated. The other attributes specified are those whose values are updated. The port model name is changed to port 2 and the poll_status is changed to False.
The Destroy element eliminates the device model deadlock. Any connections or ports associated with deadlock are automatically destroyed. The Building container model Durham is also eliminated. Any models
Modeling GatewayToolkit Guide
Page 91
Document 5069
contained within the Durham building container are sent to the lost and found.
The Destroy element also removes the connection between the specified port on device nmcss52-5 and the specified port on nmcss52-3.
<?xml version="1.0" standalone="no"?>
<!DOCTYPE Import SYSTEM ".import.dtd">
<Import>
<!-- ************************************************ --><!-- Model update.....................................--><!-- ************************************************ -->
<Update>
<!-- *********************************************** --><!-- Change container Peace's model name from Peace to--> <!-- Peace2 ..................................... ....--> <!-- *********************************************** -->
<Location_Container model_type="Building" name="Peace"model_name="Peace2"/>
<!-- ****************************************** --><!-- Update port ifIndex=2 on device nmcss52-5 --><!-- ****************************************** -->
<Device ip_dnsname="nmcss52-5">
<Port identifier_name="ifIndex" identifier_value="2"model_name="port 2" poll_status="false" />
</Device>
</Update>
<!-- ******************************* --> <!-- Destroy models and connections. --> <!-- ******************************* -->
<Destroy>
<Device ip_dnsname="deadlock"/>
<Location_Container model_type="Building" name="Durham" />
<Connection>
<Device ip_dnsname="nmcss52-5">
<Port identifier_name="ifIndex" identifier_value="1"/>
</Device>
<Device ip_dnsname="10.253.9.17">
<Port identifier_name="ipAddress" identifier_value="10.253.8.18"/>
</Device>
Modeling GatewayToolkit Guide
Page 92
Document 5069
</Connection>
</Destroy>
</Import>
Example 4: Creating, Updating and Destroying
The following XML file illustrates most of the functionality of the elements contained within the DTD. This file creates data in both the Topology and Location views, creates connections, updates attributes, and destroys models and connections.
The first section of the XML file creates models and connections between these models in the Topology view. The section begins with the Topology element, <Topology...>. The container and device models are created first and then connections are established. This section ends when the Topology element closes </Topology>
After the Topology element is closed, there is a section where an additional connection is created. This section illustrates that you can create connections without nesting the Connection element within the Topology element.
The next section of the file begins with the Location element, <Location...>. This section demonstrates creating a container and device models in the Location view. This section ends when the Location element closes, </Location>.
The next section begins with the Update element, <Update>. In this section, attribute values of a container, a device and a port are modified. Since you cannot know the current attribute values of each of the elements represented by looking at the XML file, it is not easy to discern which elements are being updated. In general, each element contains an attribute that uniquely identifies the model or port to be updated. The rest of the attributes are generally specified in order to update their values. For example, the first element is the Location_Container element. The name attribute uniquely identifies the model. The model_type attribute is specified in order to update its value, perhaps from Region to Building. The only hierarchy that can be defined in the Update element is the Device/Port hierarchy used to specify the port you would like to update. This section ends when the Update element closes </Update>.
The last section of this file utilizes the Destroy element. The Destroy element eliminates the device at 10.253.9.19, the container model Durham
Modeling GatewayToolkit Guide
Page 93
Document 5069
and the connection between the specified ports on device nmcss52-5 and the device at 10.253.9.17.
<?xml version="1.0" standalone="no"?>
<!DOCTYPE Import SYSTEM ".import.dtd">
<Import>
<!-- ************************************* --><!-- This part is for Topology view import --><!-- ************************************* -->
<Topology discover_connections="false" complete_topology="false">
<Device ip_dnsname="10.253.9.109" model_type="GnSNMPDev" community_string="public" is_managed="false"/>
<Device ip_dnsname="10.253.9.17" poll_interval="333" log_ratio="11"/>
<Device ip_dnsname="10.253.9.19" community_string="public"/>
<Device ip_dnsname="nmcss52-5" />
<Topology_Container model_type="Network" name="My Network"security_string="public" subnet_address="10.253.0.0"subnet_mask="255.255.0.0" complete_topology="true">
<Topology_Container model_type="Lan" name="MyLan" security_string="public" subnet_address="10.253.9.0" subnet_mask="255.255.255.0">
<Device ip_dnsname="10.253.9.18"community_string="public" poll_interval="333"log_ratio="5"/>
</Topology_Container>
</Topology_Container>
<Topology_Container model_type="IPClassC" name="my_net"subnet_address="172.19.57.0">
<Device model_type="Pingable" ip_dnsname="172.19.57.91"/>
<Device model_type="Fanout" ip_dnsname="1.2.3.4"/>
<Device ip_dnsname="10.253.9.16" community_string="public"/>
</Topology_Container>
<Topology_Container model_type="Lan" name="lan2"security_string="public" subnet_address="10.253.7.0"subnet_mask="255.255.255.0" complete_topology="true">
<Device ip_dnsname="10.253.7.17" community_string="public"poll_interval="333" log_ratio="11"/>
<Device ip_dnsname="10.253.32.101"/>
Modeling GatewayToolkit Guide
Page 94
Document 5069
<Device ip_dnsname="192.168.125.161" model_type="GnSNMPDev"/>
</Topology_Container>
<Device ip_dnsname="172.19.57.92" />
<Device ip_dnsname="172.19.57.93" />
<Device ip_dnsname="10.253.32.225" model_type="M46_04"/>
<Connection>
<Device ip_dnsname="172.19.57.93">
<Port identifier_name = "frCircuitTableInstance" identifier_value="4.161"/>
</Device>
<Device ip_dnsname="192.168.125.161">
<Port identifier_name ="frCircuitTableInstance"identifier_value="2.161"/>
</Device>
</Connection>
<Connection create_pipe="false">
<Device ip_dnsname="10.253.32.101">
<Port identifier_name ="atmVclTableInstance" identifier_value="3.1.52"/>
</Device>
<Device ip_dnsname="10.253.32.225">
<Port identifier_name ="atmVclTableInstance"identifier_value="5.0.68" circuit_name="ATM 68" circuit_id ="ATM ID 68"/>
</Device>
</Connection>
<Connection>
<Device ip_dnsname="nmcss52-5">
<Port identifier_name="ifIndex" identifier_value="1"/>
</Device>
<Device ip_dnsname="10.253.9.17">
<Port identifier_name="ipAddress" identifier_value="10.253.8.18"/>
</Device>
</Connection>
</Topology>
<Connection>
Modeling GatewayToolkit Guide
Page 95
Document 5069
<Device ip_dnsname="172.19.57.92">
<Port identifier_name="ifPhysAddress" identifier_value="0:E0:63:7C:19:61"/>
</Device>
<Device ip_dnsname="10.253.9.17">
<Port identifier_name="ipAddress" identifier_value="10.253.8.65"/>
</Device>
</Connection>
<!-- ************************************* --><!-- This part is for Location view import --><!-- ************************************* -->
<Location complete_topology="true">
<Location_Container model_type="Country" name="USA" security_string="whatever">
<Location_Container model_type="Region" name="New Hampshire complete_topology="false">
<Location_Container model_type="Site" name="Durham">
<Device ip_dnsname = "10.253.32.10"/>
<Device ip_dnsname = "172.19.57.93" />
</Location_Container>
</Location_Container>
</Location_Container>
<Location_Container model_type="Building" name="Durham"security_string="public">
<Location_Container model_type="Room" name="my_room"security_string="hahaha">
<Device ip_dnsname="10.253.9.16" community_string="public"/>
<Device ip_dnsname="10.253.9.17" />
<Device ip_dnsname = "10.253.9.18"/>
</Location_Container>
</Location_Container>
<Location_Container model_type="Building" name="Peace" security_string="aprisma">
<Location_Container model_type="Room" name= "Lab 1">
<Device ip_dnsname="10.253.7.17" community_string="public"/>
<Device ip_dnsname="192.168.125.161"/>
Modeling GatewayToolkit Guide
Page 96
Document 5069
</Location_Container>
</Location_Container>
</Location>
<!-- ***************************************** --><!-- This part is for model update --><!-- ***************************************** -->
<Update>
<Location_Container model_type="Building" name="Peace"model_modify_author="ltang"/>
<Device ip_dnsname="172.19.57.93" poll_interval="101"model_name="haha" />
<!-- ***************************************** --> <!-- This part is to update the port ifIndex=2 --> <!-- on device nmcss52-5 --> <!-- ***************************************** -->
<Device ip_dnsname="nmcss52-5">
<Port identifier_name="ifIndex" identifier_value="2" model_name="port 2" poll_interval="1103" poll_status="false" log_ratio="12"/>
</Device>
<Topology_Container model_type="Lan" name="lan2" security_string="top secret"/>
</Update>
<!-- ********************************************** --><!-- This part is for model and connection deletion --><!-- ********************************************** -->
<Destroy>
<Device ip_dnsname="10.253.9.19"/>
<Location_Container model_type="Building" name="Durham"/>
<Connection>
<Device ip_dnsname="nmcss52-5">
<Port identifier_name="ifIndex" identifier_value="1"/>
</Device>
<Device ip_dnsname="10.253.9.17"> <Port identifier_name="ipAddress"
identifier_value="10.253.8.18"/>
</Device>
</Connection>
</Destroy>
</Import>
Modeling GatewayToolkit Guide
Page 97
Document 5069
Index
AAlarms [38]ATM [14]AutoDiscovery [29]
Ccomma-delimited ASCII file [14]complete_topology [28]Component_OID
identifying a port by [64]Connection [22], [24]connection [29]Container model types [19]create_pipes [30]
Ddebug argument [36]Debug Log [38]Destroy [24]Destroying Information [32]Device [22]Device element [23]discover_connections [29]Document Type Definition [14]
EError Log [38]EventModel [48]Events [38]
FFrame Relay [14]
Modeling GatewayToolkit Guide
Page 98
Document 5069
GGenericView [24]GenericView_Container [22]
HHierarchical Views [19]
IImport element [21]import tool [14], [34]IMPORT_ERROR [38]input file [14]Intelligent model types [19]is_managed [23]
LLocation [24]Location View [26]Location view [19]Location_Container [22]
Mmanagement views [21]model types [19]Modeling Gateway View [36]Model-Oriented Elements [22]
PPort [22]Port element [23]
RRoot Element [21]
Modeling GatewayToolkit Guide
Page 99
Document 5069
SSchedule [22], [23]
TTask-Oriented Elements [24]tirc.xml [14], [33]topimport [36]Topology [24]Topology View [24]Topology view [19]Topology_Container [22]TopologyImport model [38]
UUpdate [24]Updating Information [31]