Integrator Guide. Document 5068

Transcription

1

2 Notice Copyright Notice Copyright 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 (c)(1)(ii) and FAR 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: 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 to spectrum-docs@aprisma.com; 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 (June 1987) Alternate III(g)(3) (June 1987), FAR (June 1987), or DFARS (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 USA Phone: U.S. toll-free: Web site: Page 2

3 Contents Notice... 2 Preface... 6 Intended Audience... 6 How to Use This Guide... 6 Further References... 7 Text Conventions... 7 Document Feedback... 8 Online Documents... 8 Overview... 9 Integrating Third-Party Applications with SPECTRUM... 9 Toolkits...10 CORBA API Toolkit...11 Command Line Interface...11 Benefits of Southbound Gateway and Modeling Gateway...13 Prerequisites for Developers...13 Developer ID...14 Purchasing the Required Tools...14 Sending Alert Data into SPECTRUM Southbound Gateway Model Types...15 Southbound Gateway Support Files...16 Integration Steps...18 Directing Alert Data to SPECTRUM...18 Mapping Alert Information to a SPECTRUM Event...18 Defining Support Files...20 Further References...21 Southbound Gateway Case Study Getting Started...22 Step 1: The AlertMap File...23 Page 3

4 Step 2: The EventAdmin EventDisp File...25 Step 3: The EventModel EventDisp File...26 Step 4: The Event Format file...27 Step 5: The Probable Cause File...28 Step 6: Packaging for Distribution...28 Sending Topology Data into SPECTRUM Architecture...29 Integration Mechanics...31 The Input File...31 The DTD...32 The tirc.xml File...32 The Import Tool...32 Viewing the Import Status and Import Errors...33 Further References...34 Modeling Gateway Case Study Step 1: Extracting Topology Data from your Database...35 Step 2: Formatting the Data with XML...35 Step 3: Importing the XML Input File...35 Step 4: Viewing the Import Results...36 Sample XML File...36 Extracting Alarm Data from SPECTRUM SPECTRUM AlarmNotifer...42 SPECTRUM Alarm Notification Manager (SANM)...43 Further References...44 Launching Applications Launching from the SpectroGRAPH Interface...45 Creating a Launch Point Visible from all Models...45 Creating a Launch Point Visible from a Specific Model Type...49 Launching an Application from the Alarm Manager...52 Launching an Application from the Search Manager...54 Launching a Web Address from a Specific Model Type...56 Page 4

5 Launching Applications with process daemon...56 Launching SpectroGRAPH Views with CsNewView...57 Further References...59 Creating New Management Modules Model Type Editor...60 mmbuild...61 GIB Editor...61 Event Configuration Files...61 SPECTRUM Extension Integration Toolkit...62 SpectroWATCH...62 Further References...62 Distributing Integration Files Creating an Index File...64 Running mkmm...65 Running mkcd...65 Further References...65 Using the Command Line Interface to Exchange Data with SPECTRUM CLI Components...66 CLI Commands...67 Further References...68 Extending SPECTRUM with the CORBA API An Overview of SPECTRUM s CORBA API...69 Further References...70 Index Page 5

6 Preface In this section: Intended Audience [Page 6] How to Use This Guide [Page 6] Further References [Page 7] Text Conventions [Page 7] Document Feedback [Page 8] Online Documents [Page 8] Intended Audience This guide is intended to provide in an overview of SPECTRUM s integration points. It is designed to be used as a road-map to guide developers to the toolkit(s) most appropriate for their customization goals. How to Use This Guide This book gives an overview of each of SPECTRUM S integration points. The guide is organized as follows: Overview: This section outlines all of the available integration points and discusses the benefits of using non-programmatic integration. Sending Alert Data Into SPECTRUM: This section gives an overview of the Southbound Gateway toolkit. Southbound Gateway Case Study: This section shows an example of a Southbound Gateway integration. Sending Topology Data into SPECTRUM: This section gives an overview of the Modeling Gateway. Modeling Gateway Case Study: This section shows and example of a Modeling Gateway integration. Extracting Alarm Data from SPECTRUM: This section gives an overview of SPECTRUM AlarmNotifier and SPECTRUM Alarm Notification Manager. Page 6

7 Creating New Management Modules: This section gives an overview the tools that are used to create a new management module. Launching Applications: This section gives an overview of where third-party applications can be started in SPECTRUM s client applications. Distributing Integration Files: This section gives an overview of the SPECTRUM Extension Integration toolkit (SEI). Using the Command Line Interface to Exchange Data with SPECTRUM: This section gives an overview of the Command Line Interface syntax and how it can be used. Extending SPECTRUM with the CORBA API: This section gives a brief overview of SPECTRUM s application programming interface. Further References The relevant reference guides for an integration point are listed at the end of the section pertaining to that integration point. For a general overview of SPECTRUM s terminology and functionality, developers should reference the SPECTRUM Concepts Guide (0647). 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 References to SPECTRUM documents (title and number) Underlined and hypertextblue Italic See Document Feedback [Page 8]. SPECTRUM Installation Guide (0675) Page 7

8 Element Convention Used Example Functionality enabled by SPECTRUM Alarm Notification Manager (SANM) SANM in brackets []. [SANM] AGE_FIELD_ID Document Feedback Please send feedback regarding SPECTRUM documents to the following address: Thank you for helping us improve our documentation. Online Documents SPECTRUM documents are available online at: Check this site for the latest updates and additions. Page 8

9 Overview In this section: Integrating Third-Party Applications with SPECTRUM [Page 9] Toolkits [Page 10] CORBA API Toolkit [Page 11] Command Line Interface [Page 11] Benefits of Southbound Gateway and Modeling Gateway [Page 13] Prerequisites for Developers [Page 13] Purchasing the Required Tools [Page 14] Integrating Third-Party Applications with SPECTRUM In your networked computing infrastructure, it is likely that you make use of several different applications to manage various aspects of your environment. There may be a number of cases where you wish to integrate some of your other management applications with SPECTRUM. The result of such an integration can be a powerful architecture that allows you to combine the automation of multiple management systems. The primary challenge in designing this type of a distributed automation architecture is deciding how each tool contributes to the overall solution and how each of these tools exchange the data necessary for each to work together. This guide is designed to assist you in deciding how to integrate third-party applications with SPECTRUM by showing you where and how you can exchange data with SPECTRUM. Typically an integrator wants to do one or more of the following: Send alert information into SPECTRUM. Send network topology information into SPECTRUM. Retrieve alarm information from SPECTRUM. Create new SNMP device management modules within SPECTRUM. Launch an external application from within a managed object context from one or more SPECTRUM application user interfaces. Package and distribute an integration. Page 9

10 Toolkits SPECTRUM has several toolkits that allow you to complete these tasks. This manual gives an overview of each of the toolkits listed below and provides references for further information. The Southbound Gateway allows alert data from third-party systems to be easily inserted into SPECTRUM. The third-party system and all of the sources for the appropriate alerts are automatically modeled in SPECTRUM giving the network administrator the ability to monitor this portion of their environment from the SPECTRUM interfaces. The Modeling Gateway imports network topology information into the SpectroSERVER database. An XML specification standardizes the information needed to create the topological information, and SPECTRUM can be set up to automatically check for updated information at given intervals. The AlarmNotifier and SPECTRUM Alarm Notification Manager (SANM) extract alarm data from SPECTRUM and pass it along to a user-defined application. The Model Type Editor and the GnSNMPDev model type allow you to derive new model types based on third-party MIBs, which can be used create new SNMP device management modules. Launching third-party applications from the SpectroGRAPH or the Alarm Manager can be accomplished by editing some of SPECTRUM's support files. Context data can be passed to the third-party application as it is launched. The SPECTRUM Extensions Integration Toolkit (SEI) provides a series of tools and files that allow the developer to package all of the components involved in an integration so that they can be installed on a SPECTRUM host system. All of these integration points provide the integrator with safe, stable mechanisms for integration. Customers need solutions that can be developed rapidly and remain stable as SPECTRUM continues to evolve. Aprisma also offers a programmatic interface to SPECTRUM; however this interface requires an in-depth understanding of SPECTRUM's knowledge base (information model). This knowledge base includes a large number of attributes, relations, and model types. Without a full understanding of how these components interact with each other, integrators risk making changes that have an overall negative impact on the operation of SPECTRUM. In addition, a tight programmatic integration makes it Page 10

11 necessary to continually update and maintain the integration code as SPECTRUM's technology evolves. For these reasons it is beneficial to both the developer and the end user for integrations to rely on the tools detailed in this guide whenever possible. These integration points reduce the developer's exposure to areas of SPECTRUM that could produce uncertain results, while still maintaining a flexible interface that can meet the needs of the integration. These solutions not only minimize the complexity of the integration task, but also enhance the viability of the solution. CORBA API Toolkit SPECTRUM's CORBA API is an advanced toolkit that allows you to develop C++ or Java based advanced extensions to SPECTRUM. It is used to create programs that integrate with the SpectroSERVER through an objectoriented remote method invocation interface. Programming with this API requires and in-depth knowledge of SPECTRUM and should only be used when absolutely necessary. The other toolkits covered in detail in this guide have been tailored to meet the needs of most integrators and should be used in most situations. Command Line Interface SPECTRUM also has a Command Line Interface (CLI) that allows you access to the data in the SPECTRUM knowledge base via a Unix shell environment or Windows NT command prompt. These commands can also be utilized in script files. With this interface you can view, create, modify and delete SPECTRUM data including information on models, alarms, events, and associations. CLI is a powerful tool, but it does not provide the safeguards that are present when using the SpectroGRAPH interface and should therefore only be used by integrators who are familiar with SPECTRUM and its modeling scheme. Also the integrator doing a CLI-based integration would be responsible for re-testing their integration with each new revision of SPECTRUM, to ensure that the intended behavior has been preserved. CLI can also be an effective tool to use before working directly with the CORBA API. Using CLI, you can prototype the logical framework of your code as it interacts with the SPECTRUM knowledge base. If the data you are interacting with behaves as you expect, you can then be more confident in your approach toward the CORBA API, although the risks of programmatic integration (discussed above) still apply. The following illustration shows all of SPECTRUM s integration points: Page 11

12 Non programmatic Interfaces Programmatic Interface Client Applications Implies Data Exchange Client Application AlarmNotifier and SANM extract alarm data to send to client applications Modeling Gateway imports topology data. Client Application C O R B A C O R B A Spectro SERVER New management modules CLI provides commands that allow you to access and manipulate SpectroSERVER data. Southbound Gateway accepts alert data from thirdparty applications. SEI packages integrations for distribution. Page 12

13 Benefits of Southbound Gateway and Modeling Gateway When integrating with pre-6.5 versions of SPECTRUM, you may have utilized various programmatic or non-programmatic toolkits. The Southbound Gateway and Modeling Gateway integration points were introduced with SPECTRUM 6.5, and are designed to expand the functionality of and eliminate many of the complexities associated with the older toolkits. Both provide well-defined integration points into the most common areas where third-party developers have a need to exchange data with SPECTRUM. In the past, representing a third-party management system in SPECTRUM would have required quite a bit of time and development. It would have been necessary to derive new model types and perhaps to develop new inference handlers to create needed functionality. This methodology is no longer necessary in many cases. The Southbound Gateway integration point has built-in model types and inference handlers specifically designed to handle the needs of a third-party alert source integration. You can further customize the Southbound Gateway integration by using the EventAdmin model type or the EventModel model type as a derivation point just as you would use the GnSNMPDev model type to derive a new model type. 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. The Modeling Gateway introduces an effective solution for these problems: a set of XML elements that lets you port data from a provisioning database or other network topology database. Additionally, the elements and attributes used in the XML syntax can be expanded and customized to suit the needs of most integrations. Prerequisites for Developers Before attempting to use any of SPECTRUM s integration points, 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. Page 13

14 Developer ID Developers who would like to distribute their integrations must have a Developer ID. For more information on how to obtain a Developer ID, refer to the SPECTRUM Concepts Guide (0647). Purchasing the Required Tools Many of the toolkits described in this manual are packaged/sold as separate components. The following chart shows you the toolkits and the associated components needed for integration. Toolkit/ Integration Point Southbound Gateway Modeling Gateway Alarm Notifier SPECTRUM Alarm Notification Manager (SANM) Creating a new management module Launch Point Integration SPECTRUM Extension Integration (SEI) CLI CORBA Components Needed Southbound Gateway Toolkit: Available as an add-on component depending on the SPECTRUM package you have purchased. SEI : Available as part of the Level I Toolkit. CORBA Toolkit: Optional component, only required if a programmatic Southbound Gateway integration is desired. Available as an add-on component depending on the SPECTRUM package you have purchased. Modeling Gateway Toolkit: Available as an add-on component depending on the SPECTRUM package you have purchased. Alarm Notifier Application: Included with all SPECTRUM packages. SANM Application: Available as an add-on component depending on the SPECTRUM package you have purchased. Model Type Editor: Available as part of the Level I Toolkit. GIB Editor: Included with all SPECTRUM packages. SpectroWATCH Editor: Available as an add-on component depending on the SPECTRUM package you have purchased. SEI: Available as part of the Level I Toolkit. None SEI: Available as part of the Level I Toolkit. CLI Application: Included with all SPECTRUM packages. CORBA Toolkit: Available as an add-on component depending on the SPECTRUM package you have purchased. Page 14

15 Sending Alert Data into SPECTRUM The Southbound Gateway integration point accepts alert data from third-party sources. Often these third-party sources are other management applications that specialize in monitoring a specific aspect of a computing infrastructure. Using Southbound Gateway you can centralize your infrastructure management, allowing SPECTRUM to capture and display data from other systems. Alert data is organized into SPECTRUM event and alarm data as appropriate and displayed within the SpectroGRAPH, the Alarm Manager, and other SPECTRUM viewing applications. Southbound Gateway can be used regardless of the setup of the incoming alert data stream. It provides a very simple, non-programmatic integration point for systems that can generate SNMP traps. It is also very useful for managing non-snmp environments. There are a variety of ways to import non-snmp alert data. The simplest method is to use the XML import tool provided with the Southbound Gateway toolkit. In this section: Southbound Gateway Model Types [Page 15] Southbound Gateway Support Files [Page 16] Integration Steps [Page 18] Further References [Page 21] Southbound Gateway Model Types SPECTRUM has two model types that are intended to manage incoming alert data from a Southbound Gateway integration: the EventAdmin and the EventModel. The EventAdmin model type is designed to represent a third-party system sending alerts to SPECTRUM. Each instantiated EventAdmin model represents an individual instance of a running external management application. Specific events that have come from the third-party application Page 15

16 are sent to the EventAdmin. The EventAdmin models have built-in functionality that receives the events and appropriately transfers that event data to EventModels, with optional alarm creation. EventAdmin models are also containers used to group one or more instantiated EventModel models. The EventModel model type represents a unique source of event data within the system managed by the EventAdmin s application. Each event that has been received through the Southbound Gateway contains information that uniquely identifies the source of that event. The EventAdmin receives the event, finds the unique event source, and passes the event to the EventModel representing this unique source. If no EventModel exists for the source, an EventModel model is automatically created to represent it. All new EventModel models are placed in the corresponding EventAdmin container model. It is possible to cut or copy EventModel models from an EventAdmin container model and paste them into other types of container models in the Topology, Location or Organizational view. It is also possible to cut or copy the EventAdmin model and paste it into the Topology, Location, or Organizational view. Southbound Gateway Support Files As the Southbound Gateway integrator, you create or add data to a number of support files that supply information to the EventAdmin and EventModel models. Here are the files you will be working with: AlertMap File: If the alert source sends SNMP traps, you create a text file that adds data to the EventAdmin s AlertMap file. These additions allow the AlertMap file to receive the SNMP traps and convert them to SPECTRUM events. XML File: If the alert source does not send SNMP traps, you create an XML file to send events to SPECTRUM. The syntax of this XML file follows the document type definition (DTD) provided with this toolkit. EventDisp file: You create text files that add data to the EventDisp files at the EventAdmin and EventModel level. These additions define how the events are processed. Event Format file: You create Event Format files to give supporting textual information about each event. Probable Cause file: You create Probable Cause files to give supporting textual information about each alarm. Page 16

17 The following diagram illustrates the flow of data from the third-party system into SPECTRUM via the Southbound Gateway. It shows the model types and support files working together to process the data. Alarm Specific Probable Cause Files Alarm Data For Views Event Specific Event Format Files Event Data For Views Create Alarms Log Events EventDisp EventDisp EventDisp EventModel EventModel EventModel Discover Unique Event Source and Disperse to EventModel Event Data Template Event Admin EventDisp Event Data Template AlertMap File for the EventAdmin Organized Event Organized Event XML File Unorganized SNMP Trap Third-Party Application Unorganized Alert Page 17

18 Integration Steps Three main steps are required to set up a Southbound Gateway integration. 1. Direct alert information from the third party system to SPECTRUM. 2. Map that alert information to a SPECTRUM event. 3. Define support files for that event. Directing Alert Data to SPECTRUM The method used to set up and configure a third-party system to send alert data to the Southbound Gateway is largely dependent upon the functionality of the individual system. The most important thing to determine is what type of alert the third-party system is sending. If the system you are working with is capable of sending SNMP traps to SPECTRUM, you should configure it to do so. The application should send the trap data to the host name and TCP port on which the SpectroSERVER is set up to listen. By default, the SpectroSERVER is configured to receive SNMP traps on port 162. When SPECTRUM receives a trap from your thirdparty application, this trap is processed in accordance with the AlertMap file associated with the EventAdmin model type. The AlertMap file translates the trap data into a SPECTRUM event. You create a text file that adds the appropriate data to the AlertMap file so that it can properly process the trap information that you are sending to it. If your application is not capable of sending SNMP alert data, you can import your data using the Southbound Gateway Import Tool. This tool expects your data to be formatted using the XML elements specified by the document type definition provided with the Southbound Gateway toolkit. Mapping Alert Information to a SPECTRUM Event In either case, you use the Southbound Gateway s Event Data Template to map the data from the trap or alert to the SPECTRUM event. This template, outlined in the table below, indicates how the alert variables should be organized and gives you the ability to specify variables that together constitute an identifier for the unique alert source. An event variable ID is assigned to variables contained in the alert. One of the most important components of the integration is being able to identify a unique alert source so that the event can be sent to the proper EventModel model. Event variables 1-6 designate the variable alert data used to uniquely Page 18

19 identify the alert source. Other variable alert data is mapped to the Event Data Template variable that matches its content. Variable ID Name Type Description Required/ Optional Unique ID 1 Unique ID 2 Unique ID 3 Unique ID 4 Unique ID 5 Unique ID 6 String/Integer String/Integer String/Integer String/Integer String/Integer String/Integer The Unique Identifier is a composite of up to 6 variable data items (1-6). The final unique identifier string is composed as follows: <1>_<2>_<3>_<4>_ <5>_<6> in that exact order. If one of the unique identifier components is not provided, it is not included within the composite unique identifier. 7 Target_Name String This field allows you to specify a SPECTRUM model by model name. Use this field if you want to send the event to a model other than an EventModel. Either one unique identifier or a Target_Name (field 7) or Target_Address (field 8) is required. 8 Target_Address Octet/Text String This field allows you to specify a SPECTRUM model by IP address. Use this field if you want to sent the event to a model other than an EventModel. 9 Reserved 10 Event Model Name String/Integer This gives the user the ability to give a model name that is different than the unique identifier. If this data is not provided, the composite unique identifier becomes the model name. Optional Page 19

20 Variable ID Name Type Description Required/ Optional 11 Model Class Integer Model class of the EventModel. 12 Date/Time Integer Timestamp indicating when the alert was generated. Optional Optional 13 Network Address Octet/Text String Network Address of the managed entities Optional 14 MAC Address Octet/Text String MAC Address of the managed entity Optional 15 Manufacturer String Manufacturer of the managed device Optional Reserved Any other variable ID greater than or equal to 100. Any Data Any Type This data is forwarded to the EventModel model unchanged. The data type and data are preserved. This data can be viewed within an event message. Optional Defining Support Files Once the alert has been translated into an event, you need to define information for the EventDisp files, Event Format files and Probable Cause files, so that the alert data is correctly processed and displayed. EventDisp files define how SPECTRUM should handle each event. There is one EventDisp file for the EventAdmin model type and another EventDisp file for the EventModel model type. The purpose of the EventAdmin s EventDisp file is to define what events are received from the external alert/ trap source. The purpose of the EventModel s EventDisp file is to give the events their desired properties. It indicates whether the event will be logged, the severity of the event and whether the event will become an alarm. Event Format files determine the contents of an event message when the event is displayed in the Event and Alarm Manager. The Event Format File can contain variable data from a specific occurrence of an event. This variable data is identified within the Event Format file by the assigned event variable ID from the Event Data Template. Page 20

21 Alarms that are generated as a result of the EventDisp file usually contain a probable cause as part of the alarm message. The text of this probable cause is defined in the Probable Cause file. Further References The following manuals contain further relevant information on working with the Southbound Gateway toolkit: SPECTRUM Concepts Guide (0647): This guide provides an overview of the underlying technology of SPECTRUM and the terminology used throughout SPECTRUM s documentation. Southbound Gateway Toolkit Guide (5066): This guide provides an indepth reference for using Southbound Gateway. SPECTRUM Extension Integration Developer s Guide (0623): This guide provides details on using SEI to package an integration for distribution. Event Configuration Files Guide (5070): This guide provides an in-depth look at AlertMap, EventDisp, Event Format, and Probable Cause files. Page 21

22 Southbound Gateway Case Study The following example walks you through an integration with a typical third-party management software that is capable of sending SNMP traps to SPECTRUM. In this section: Getting Started [Page 22] Step 1: The AlertMap File [Page 23] Step 2: The EventAdmin EventDisp File [Page 25] Step 3: The EventModel EventDisp File [Page 26] Step 4: The Event Format file [Page 27] Step 5: The Probable Cause File [Page 28] Step 6: Packaging for Distribution [Page 28] Getting Started The traps sent by this software have been directed to the SpectroSERVER and are received by Southbound Gateway. For the sake of simplicity we will assume that this application only sends one type of trap to the Southbound Gateway. The trap is an enterprise-specific trap with a number of variable bindings. Trap [Header] enterprise = generic trap type = 6 specific trap type = [Variable Bindings] Page 22

23 Step 1: The AlertMap File The trap information needs to be mapped to an event. This means you need to create an alert map entry for this trap. The most important thing to specify is the string that makes up the unique identifier for the EventModel. This unique ID can be comprised of up to six variable bindings using the variable IDs 1 through 6. This data can then be viewed within the event message. The below example shows the trap being mapped to an event in the alert map file. The variable bindings are being assigned a variable ID from the Event Data Template. All non-bold variable bindings have been mapped to the Any Data category of the Event Data Template. Note that these variable bindings have been given a variable ID that has not been assigned to a specific category in the Event Data Template. Page 23

24 Trap [Header] enterprise = generic trap type = 6 specific trap type = [Variable Bindings] GroupID ClientID EndTime AppID Status Comments Details Manufacturer ServerID Event Data Template variable ID Name 1 Unique ID 1 2 Unique ID 2 3 Unique ID 3 4 Unique ID 4 5 Unique ID 5 6 Unique ID 6 10 EventModel Name 11 Model Class 12 Date/Time 13 Network Address 14 MAC Address 15 Manufacturer Any other integer >= 100 Any Data Alert Map File x3c (1,0) Trap Event Code (2,0) (12,0) (3,0) (100,0) (101,0) (102,0) (15,0) (103,0) Variable Bindings with assigned variable ID Page 24

25 Step 2: The EventAdmin EventDisp File This is a sample of the EventAdmin EventDisp file. This EventDisp file lists all events generated by the third party system. Listing them here allows them to be received by the EventAdmin model. EventAdmin EventDisp File 0x3c8000 The events should be logged at the EventModel level rather than the EventAdmin level. For this reason, the only thing listed in this file is the event code. This syntax indicates that the event should be received, but not logged. After receiving the event, the EventAdmin model forwards it to the appropriate EventModel model. Page 25

26 Step 3: The EventModel EventDisp File This EventDisp file gives the event received at the EventModel its properties. This file is optional, but highly recommended. These events are the same as those in the EventAdmin s EventDisp file. EventModel EventDisp File 0x3c8000 E 50 A 1,0x3c8000 Obviously this file has more data than the EventAdmin EventDisp file. The E indicates that the event is logged. The event severity is indicated by the number 50, event severity ranges from 1 to 100, 100 being the most severe. The A indicates that the event generates an alarm. The number 1 indicates the severity of the alarm. Valid values for the alarm severity are 1 through 6. The hexadecimal number 0x3c8000 is the alarm code. Page 26

27 Step 4: The Event Format file The Event Format files define the event message seen in both the Event Log and Alarm Manager. Event Format File {d %w- %d%m-, %Y - %T } - Device {m} of type {t} The user s SMTP/POP3 mail transaction failed with error code 554. The event code is {e}. Other information: Group {S 1} Client {S 2} Application {S 3} End Time : {S12} Manufacturer: {S 15} Server: {S 103} Status: {S 100} Comments: {S 101} Details: {S 102} The items in parenthesis indicate that a variable value is placed in the event text message. The S indicates the data type (String) and the numeric value is the variable ID assigned in the AlertMap file representing the value that is placed there. Page 27

28 Step 5: The Probable Cause File The Probable Cause files defines the alarm title, symptoms, probable causes, and recommended actions. Probable Cause File MAIL TRANSACTION ERROR RECEIVED SYMPTOMS: The client's attempt to send mail failed. PROBABLE CAUSES: 1. Network connectivity. 2. The mail server. RECOMMENDED ACTIONS: 1. Check the network connectivity. 2. Check the mail server operation. Step 6: Packaging for Distribution Once you have created all the files necessary for the integration, you need to package these files so that they can be installed on a SpectroSERVER. Please refer to the distribution section of the Southbound Gateway Toolkit Guide (5068) and the Extension Integration Developer s Guide (0623) for specific instructions and examples. Page 28

29 Sending Topology Data into SPECTRUM The Modeling Gateway is the integration point that provides a standard way for you to import network inventory, topology, and organizational (containment) data from an existing database so that it can be displayed and managed by SPECTRUM. This data exchange is done via an input file and gives you the ability to create, delete, associate and update the modeling data within SPECTRUM. Users in a dynamic network environment with a large number of devices can use this tool instead of manually updating device status. Computing infrastructures that include devices that cannot easily be modeled by AutoDiscovery, because of the lack of management MIB data, can also make use of this tool. In this section: Architecture [Page 29] Integration Mechanics [Page 31] Further References [Page 34] Architecture There are two types of input files that can be used with the Modeling Gateway, an XML file and a comma-delimited ASCII text file. The commadelimited input file is specifically used for creating connections for Frame Relay and ATM circuits. The XML input file gives you a wider range of functionality. In addition to specifying Frame Relay and ATM circuit connections, you can also create, update, and destroy models and other types of connections. The following figure illustrates the process of integration. As the integrator you are responsible for creating the XML input file that structures the network data for import. If you have a thorough understanding of the given network topology, representing network data in XML format is a relatively simple process. SPECTRUM provides a DTD (Document Type Definition) file that defines the XML elements and their associated syntax rules. A second file, the tirc.xml file, shows you which SPECTRUM model Page 29

30 types and attributes are available for use. Once you have created the XML input file, you use the import tool (topimport) to import the data into the SpectroSERVER database. Resource File Enumeration of Model Types and Attributes Third Party Database Topology Data XML File Element Definition XML Formatted Topology Data T O PI M PO R T T O O L Topology Data C I O N R T B E A R F A C E Spectro SERVER DTD The figure below illustrates the process of using a comma-delimited ASCII text file to import Frame Relay and/or ATM connection information. For complete information on the syntax of the comma-delimited file, please refer to the Modeling Gateway Toolkit Guide (5069). Page 30

31 Third Party Database ATM/Frame Relay Connection Data Comma Delimited ASCII File Comma Delimited ATM/Frame Relay Connection Data T O PI M PO R T T O O L Connection Data C I O N R T B E A R F A C E Spectro SERVER Integration Mechanics The primary integration task is to create input files that allow you to format your network data so that it is understood correctly by the import tool (topimport). Once you create the first input file, this file 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. Note that a basic knowledge of XML and DTDs is assumed here. If you have not worked with XML before, you may want to become familiar with XML syntax before working with these files. The Input File During the integration process, you take your network data from a thirdparty database and create an input file. Depending on the content, this input file may be an XML file or a comma-delimited ASCII file. If you only need to import data concerning Frame Relay and/or ATM connections, you can use the comma-delimited file. To create this file you need to follow the syntax options outlined in the Modeling Gateway Toolkit Guide (5069). To import more complex topology information, you need to use an XML file. When creating an XML input file, you need to work with the provided Document Type Definition file and the tirc.xml file in order to properly Page 31

32 format the data. An overview of each of these files is provided below. Please refer to the case study for a sample XML file. The DTD The DTD, or Document Type Definition, is a file that outlines all of the elements and attributes that can be contained in the XML file. It shows you the structural hierarchy of elements (i.e., which elements can act as child elements for any given element) and indicates which attributes can be specified for each element. The root element in the DTD is the Import element. This element is required and specifies the type of import that will take place. Import has several possible child elements: Topology, Location, GenericView, Update, Destroy, and Connection. If you would like to import new models, you use the Topology, Location, or GenericView elements. The element that you choose determines the view that the imported data appears in within SpectroGRAPH. The Update element is used to change an existing collection of models, and the Destroy element is used to remove existing models. The Connection element is used to establish connections between ports or devices. These elements all have child elements that are used to define the components of the network. You can customize the DTD file to meet the needs of a specific integration. The GenericView element listed above allows you to create your own view to place container and device models. You can modify and add to the child elements of the GenericView element in order to define the contents of your customized view. The tirc.xml File All of the possible model types and attributes that can be used in the XML input file are defined in the tirc.xml file. This file lists a number of SPECTRUM model types and the model type handles that uniquely identify them. It also lists a number of SPECTRUM attributes and their attribute IDs. This file gives you the capability to use model type and attribute names in the XML file rather than their hexadecimal identifiers. This makes the XML file more intuitive to create and read. The tirc.xml file can be modified to include any instantiable, visible model type that exists in SPECTRUM and any attribute that is not a list attribute or an octet string. The Import Tool Once you have set up the input file, you use the Modeling Gateway import tool to import the network data to the SpectroSERVER database. The Page 32

33 import tool is a command line utility located in the SS-Tools directory. The import tool command takes four arguments: topimport -vnm <vnm_name> -i <input_file> [-o <output_file>] [- 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 any error information to the file named in the outputfile parameter. If this option is not used, any 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 the Import Status and Import Errors The Modeling Gateway also provides mechanisms to ensure the safety and accuracy of each database import. The Modeling Gateway maintains 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 SpectroGRAPH. To bring up this GIB view: 1. Right-click on the VNM model and select Configuration. 2. In the Configure/Information box, select ModelingGatewy and then click OK. This GIB view provides you with the details of the latest import. You will also see any errors that may have occurred during the import process. If any type of critical failure occurs during the import process, SPECTRUM generates an event reporting that error. This event generates one minor alarm to indicate at least one error occurred for that import session. All errors and their possible causes are logged in an error log file. This log file records the number of successful creations and deletions of models and connections. You also have the option of turning on a debug log that will help you locate the source of problems or inaccuracies. Page 33

34 Further References The following manuals contain further relevant information on the Modeling Gateway: SPECTRUM Concepts Guide (0647):This guide provides an overview of the underlying technology of SPECTRUM and the terminology used throughout SPECTRUM s documentation. Modeling Gateway Toolkit Guide (5069):This guide provides an indepth look at the Modeling Gateway toolkit and the syntax used in the DTD provided with the toolkit. Page 34

35 Modeling Gateway Case Study The following example walks you through a topology data import using the Modeling Gateway toolkit. The following example uses an XML file as the input file. This XML file contains the information to create, update, and destroy network topology data. In this section: Step 1: Extracting Topology Data from your Database [Page 35] Step 2: Formatting the Data with XML [Page 35] Step 3: Importing the XML Input File [Page 35] Step 4: Viewing the Import Results [Page 36] Sample XML File [Page 36] Step 1: Extracting Topology Data from your Database The first step in the integration process is for you to extract the appropriate network topology data from the database in which it currently exists. The methods for doing this depend on the database you are using and the data you wish to extract. Once you have the input data in ASCII text format, you must create an XML file that allows you to import this data as outlined in the next step. Step 2: Formatting the Data with XML The next step is to use the XML elements supplied in the Modeling Gateway document type definition to create an XML file. This XML file should define the data that will be imported into SPECTRUM. There is a sample XML file and a description of its functionality at the end of this case study. Step 3: Importing the XML Input File Once you have created the XML input file, you need to use the import tool to import this data into SPECTRUM. In this example TestInput is the file Page 35

36 name. This will be imported to the SPECTRUM host that resides on the machine TestServer. To import the input file, go to SPECTRUM s SS-Tools directory and type the following at the command prompt: topimport -vnm TestServer -i TestInput -o output.log -debug Step 4: Viewing the Import Results Once the import has taken place, you are able to see the results of the import in the Modeling Gateway view in SpectroGRAPH. The number of successful creations, deletions, and updates of models and connections, as well as each single failure that occurred during the import process is logged to the error log file. The error log file is found in the SS-Tools directory and is called <nameofimportfile>.log where <nameof importfile> is the name of your import file. If you turned on the debug option when running the import tool, the debug file can be found in the SS-Tools directory. It is called TIDebug.txt. Sample XML File 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. Note: Note that element names in the example are highlighted in bold. This has been done to make the example easier to read and is not intended to imply necessary formatting for the XML input file. 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. Page 36

37 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 following 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 , the container model Durham and the connection between the specified ports on device nmcss52-5 and the device at <?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=" " model_type="gnsnmpdev" community_string="public" is_managed="false"/> <Device ip_dnsname=" " poll_interval="333" log_ratio="11"/> <Device ip_dnsname=" " community_string="public"/> <Device ip_dnsname="nmcss52-5" /> <Topology_Container model_type="network" name="my Network" security_string="public" subnet_address=" " subnet_mask=" " complete_topology="true"> <Topology_Container model_type="lan" name="mylan" security_string="public" subnet_address=" " subnet_mask=" "> Page 37

38 <Device ip_dnsname=" " community_string="public" poll_interval="333" log_ratio="5"/> </Topology_Container> </Topology_Container> <Topology_Container model_type="ipclassc" name="my_net" subnet_address=" "> <Device model_type="pingable" ip_dnsname=" "/> <Device model_type="fanout" ip_dnsname=" "/> <Device ip_dnsname=" " community_string="public"/> </Topology_Container> <Topology_Container model_type="lan" name="lan2" security_string="public" subnet_address=" " subnet_mask=" " complete_topology="true"> <Device ip_dnsname=" " community_string="public" poll_interval="333" log_ratio="11"/> <Device ip_dnsname=" "/> <Device ip_dnsname=" " model_type="gnsnmpdev"/> </Topology_Container> <Device ip_dnsname=" " /> <Device ip_dnsname=" " /> <Device ip_dnsname=" " model_type="m46_04"/> <Connection> <Device ip_dnsname=" "> <Port identifier_name = "frcircuittableinstance" identifier_value="4.161"/> </Device> <Device ip_dnsname=" "> <Port identifier_name ="frcircuittableinstance" identifier_value="2.161"/> </Device> </Connection> <Connection create_pipe="false"> <Device ip_dnsname=" "> <Port identifier_name="atmvcltableinstance" identifier_value="3.1.52"/> </Device> Page 38

39 <Device ip_dnsname=" "> <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=" "> <Port identifier_name="ipaddress" identifier_value=" "/> </Device> </Connection> </Topology> <Connection> <Device ip_dnsname=" "> <Port identifier_name="ifphysaddress" identifier_value="0:e0:63:7c:19:61"/> </Device> <Device ip_dnsname=" "> <Port identifier_name="ipaddress" identifier_value=" "/> </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 = " "/> <Device ip_dnsname = " " /> </Location_Container> Page 39

40 </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=" " community_string="public"/> <Device ip_dnsname=" " /> <Device ip_dnsname = " "/> </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=" " community_string="public"/> <Device ip_dnsname=" "/> </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=" " poll_interval="101" model_name="haha" /> <!-- ***************************************** --> <!-- This part is to update the port ifindex=2 --> <!-- on device nmcss > <!-- ***************************************** --> <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 secrete"/> Page 40

41 </Update> <!-- ********************************************** --> <!-- This part is for model and connection deletion --> <!-- ********************************************** --> <Destroy> <Device ip_dnsname=" "/> <Location_Container model_type="building" name="durham"/> <Connection> <Device ip_dnsname="nmcss52-5"> <Port identifier_name="ifindex" identifier_value="1"/> </Device> <Device ip_dnsname=" "> <Port identifier_name="ipaddress" \ identifier_value=" "/> </Device> </Connection> </Destroy> </Import> Page 41

42 Extracting Alarm Data from SPECTRUM There are two programs that you can use to extract alarm data from SPECTRUM. These two programs work together. AlarmNotifier provides basic scripts to capture and forward alarm data. SPECTRUM AlarmNotification Manager (SANM) further defines and filters the alarm information to be forwarded. In this section: SPECTRUM AlarmNotifer [Page 42] SPECTRUM Alarm Notification Manager (SANM) [Page 43] Further References [Page 44] SPECTRUM AlarmNotifer SPECTRUM AlarmNotifier is a SpectroSERVER client application that provides a way to extract alarm information from SPECTRUM. The AlarmNotifier tool is launched from the command line and connects to a single SpectroSERVER. Once connected, it monitors alarm information generated by that server. When an alarm is set, updated, or cleared, the AlarmNotifier application extracts data from the alarm and delivers it to a terminal screen. AlarmNotifier utilizes three scripts to get data from the alarm: SetScript, ClearScript, and UpdateScript. AlarmNotifier receives information from the SpectroSERVER every time an alarm is set, cleared or updated. When it receives this information, AlarmNotifier invokes the relevant script. As a result of the script, the data from the alarm is displayed on the terminal screen. Each of these scripts can be customized so that the alarm data can be sent in an notification or to another third-party application such as a trouble ticketing system. You can also modify the number of parameters used by the script in order to reduce the amount of information displayed on the terminal or sent to other applications. These scripts are located in SPECTRUM s Notifier directory. Page 42

43 SPECTRUM Alarm Notification Manager (SANM) SANM enhances the capabilities of the AlarmNotifier application in several ways. SANM enables the AlarmNotifier to monitor alarm information from all landscapes in the SpectroSEVER s landscape map. Additionally, SANM provides more alarm data to be sent to the AlarmNotifier. When SANM has been installed on the SpectroSERVER, you will notice that SetScript, ClearScript, and UpdateScript all have additional parameters that represent additional alarm information. SANM gives you the ability to acknowledge and clear alarms from the terminal shell where the alarm data is displayed, and you can control the scope and volume of alarm data using SANM s Policy Administrator tool. The Policy Administrator is a configuration tool that enables you to create, save, and implement alarm notification filtering policies. You can create policies that enable you to specify the types of alarms you want an alarmprocessing application to receive, and you can filter out the alarms or specific alarm data that you consider unimportant. You can also schedule associations between policies and applications so that alarm data filtered through that policy is sent to the particular application during the specified time period. Policies can range from very simple to very complex. A simple policy might specify that SANM pass information about critical alarms for all routers to an application that is associated with the policy. A more complex policy might specify that SANM pass information about those critical and major alarms that remain unresolved for 10 minutes for a particular type of router and a particular type of switch that are not on a particular subnetwork. With the exception of the Policy Administrator tool, you will never work with SANM directly. SANM works directly with the AlarmNotifier to extend its functionality. You continue to work with the AlarmNotifier using the added SANM capability. The figure below illustrates the architecture of AlarmNotifier and SANM. Page 43

44 Further References For further information on working with AlarmNotifier and SANM, the following SPECTRUM manuals contain further relevant information: SPECTRUM Concepts Guide (0647): This guide provides an overview of the underlying technology of SPECTRUM and the terminology used throughout SPECTRUM s documentation. Alarm Notification Manager Guide (1308): This guide gives in-depth instruction on how to use SANM to enhance the capabilities of the AlarmNotifier. AlarmNotifier User s Guide (1503): This guide provides detailed instruction on how to use the AlarmNotifier and how to customize the scripts provided with the AlarmNotifier. Page 44

45 Launching Applications It is possible to launch an application or script from menus in SpectroGRAPH or Alarm Manager. To do this you need to add commands to various support files indicating the script or application you would like to launch. It is also possible to launch SpectroGRAPH views from a third-party application using the CsNewView executable. In this section: Launching from the SpectroGRAPH Interface [Page 45] Launching an Application from the Alarm Manager [Page 52] Launching an Application from the Search Manager [Page 54] Launching a Web Address from a Specific Model Type [Page 56] Launching Applications with process daemon [Page 56] Launching SpectroGRAPH Views with CsNewView [Page 57] Further References [Page 59] Launching from the SpectroGRAPH Interface When launching applications from SpectroGRAPH, it is possible to create a menu command that is visible from all models or it is possible to create a launch point that is specific to a certain model type. Creating a Launch Point Visible from all Models You can launch an application or script from the SpectroGRAPH interface by modifying the CsStdMenu file located in SPECTRUM s app-defaults directory. You can insert a command in this file to create a selection in the File, Edit (in Edit Mode), View, Tools, or Icon Subviews menus. The command can include variables to pass to the application or script. This menu selection is accessible no matter which model is currently selected. The CsStdMenu file is read when SpectroGRAPH is started, thus changes you make to the file are not visible until you restart SpectroGRAPH. You use the following syntax to create the menu selection command in the CsStdMenu file. Page 45

46 @MenuName: Label = NameonMenu = Path to Script -vnm{vnmname} - port{vnmsocket} -lh{landscape} -uilandscape {uilandscape} - rel{relation} - mhandle{modelhandle -mh{modelhandles} - uisocket{uisocket} -geo{geometry} -wsize{windowsize} -wid{window_id} uiname{uiname} This portion of the command indicates where the menu selection should be inserted. Listed below is the syntax for each menu Tools File Edit View _GROUP: Icon Subviews menu Label: This portion of the command shows the programmatic name for the line entry. NameonMenu: This portion of the command shows the name that appears on the menu. Path to Script: This portion of the command indicates the absolute path to the script or executable that you wish to launch. Variables: The next portion of the syntax shows the variables that can be passed to the script. These appear as name value pairs when referenced in a script (see example below). Each of the variables is an optional argument. Here are two examples. The first is appropriate for the Windows NT/2000 environment, the second for the Solaris environment. Each passes the name of the SpectroSERVER to the sample script. Windows NT/2000 "SAMPLE" = "Sample: C:/usr/SPECTRUM/SG-Support/ CsScript/Sample -vnm{vnmname} & " Solaris SAMPLE = SAMPLE: /usr/spectrum/sg-support/csscript/ Sample -vnm{vnmname} & If you are creating this file for use in Windows NT/2000, you must still use the forward slash / rather than the backslash \ in your path. Content of the script Sample: Page 46

47 #!/bin/sh exec 1> writefile echo $1 echo $2 Resulting Content of writefile for SPECTRUM host with the name jazz: -vnm jazz New Menu Option You can also create submenus. In the instance below, you have a menu selection on the Tools menu called Test. This selection has two submenus Test1 and Test2. Note that a new line must separate each submenu entry. Windows "TEST" = "Test: (Test1: C:/MyFiles/MyTest.bat & Test2: C:/MyFile/MyTest2.exe & )" "TEST" = "Test: (Test1: /MyFiles/MyTest & Test2: /MyFile/MyTest2 & )" Page 47

48 Sub Menu If you would like to make one of the letters in the menu command a keyboard shortcut to the menu selection, place the $ before that letter. In the example below a is the keyboard shortcut. Windows "SAMPLE" = "S$ample: C:/usr/SPECTRUM/Sample & " "SAMPLE" = "S$ample: /usr/spectrum/sample & " Page 48

49 Keyboard Shortcut If there are spaces in the Windows NT path statement, as in the example below, you must place single quotes around the path "SAMPLE" = "Sample: C:/Program Files/Myapplication & " Creating a Launch Point Visible from a Specific Model Type If you would like the menu item to appear only when specific model types are selected, you must edit several of the Icon Information Block (IIB) files particular to that model type. IIB files define a number of characteristics of a model type icon, including the files that can be launched from that icon s icon subviews menu. All IIB files are located in the SG-Support/CsIib/<modeltype> directory, where <modeltype> is the name of the model type you are working with. The content of an IIB file can be edited using any text editor. You must add a command to all of the following files that are available for the model type you are working with: Page 49