Skip Headers
Oracle® Communications Network Integrity Developer's Guide
Release 7.1

E23701-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

19 Extensibility SDK

This chapter provides information about the extensibility SDK for Oracle Communications Network Integrity.

About Extensibility Scenarios

Cartridges and Actions in Network Integrity are extensible using Design Studio for Network Integrity. The productized and sample cartridges provided by Network Integrity are designed to be completely extensible and re-usable. The following sections are step-by-step examples of some common extensibility scenarios.

Each of the scenarios follows a detailed example but is meant to demonstrate the many extensibility features and methods within Network Integrity cartridge development. The following concepts are being demonstrated in the scenarios:

  • Re-using existing Actions

  • Conditional Execution using Conditions

  • The use of Specifications and Characteristics to extend the model

  • The use of input and output parameters

  • The use of UI parameters

  • Using filters to modify default discrepancy detection behavior

  • What extension points are available in productized cartridges

The extensibility scenarios are:

Extending MIB II SNMP Discovery for Updated Vendor and Interface Type

This scenario describes the steps required to update the vendor number and interface type mapping tables in the MIB II SNMP Discovery cartridge. The vendor number table translates an enterprise object identifier number to a vendor name. The interface type table translates an ifType value into a human readable name. These mapping tables are created by the MIB II Properties Initializer, and are made available to the following processors by its output parameters. Although the properties were up to date at the time of cartridge creation, the industry updates them from time to time with additions or changes.

The following tasks are performed in this example:

  • adds a new interface type (#333, ”tachyonEther”),

  • adds a new vendor number (#90210, ”West Beverly Hills School District”), and

  • changes an existing vendor name (#34416, from ”Ottawa Area Intermediate School District” to ”Ottawa Area Middle School District”.)

The following high-level steps are involved:

  • Creating a new Network Integrity Cartridge Project

  • Creating a new Discovery Action that re-uses the MIB II SNMP discovery action

  • Creating a new Discovery Processor inside the new Action to update the mapping tables.

Prerequisites:

  • The following cartridges are loaded into the Design Studio workspace and are building without errors

    • Address_Handlers

    • MIB_II_Model

    • MIB_II_SNMP_Cartridge

  • The above cartridge projects can be loaded by importing the MIB II SNMP Cartridge ZIP file into Design Studio. For instructions on importing cartridge zip files, refer to "Exporting and Importing Cartridges".

Creating a New Project, Discovery Action, and Discovery Processor

Figure 19-1 shows the Discovery Action created in this scenario:

Figure 19-1 Discovery Action

Illustrates discover action

To update and discover the MIB II SNMP Discovery cartridge, use the following procedure:

  1. Use the following steps:

    1. Create a cartridge to hold the new discovery action.

    2. Create a Network Integrity Cartridge Project called Vendor_Type_Update_Cartridge.

    3. See "Creating a Cartridge" to for instructions on how to create a Network Integrity Cartridge Project.

  2. Create a Discovery Action called Discover Updated MIB II SNMP. Refer "Working with Discovery Actions and Processors" for instructions on creating a new Discovery Action, and extending existing Discovery Actions.

  3. On the Processor tab of the new Discovery Action select Add and add the Discover MIB II SNMP action. This adds all the processors from theDiscover MIB II SNMP action.

  4. Now a new Discovery Processor is required to make updates to the two mapping tables. Use the following steps:

    1. Select New to add a new Discovery Processor called, for example, MIB II Properties Updater.

    2. Select Move Up to move the new processor up to row 2, below MIB II Properties Initializer and above MIB II SNMP Collector.

    3. Refer to "Creating Discovery Processors" for instructions on how to create a Discovery Processor, and how to move a processor.

  5. Open the editor for the MIB II Properties Initializer Updater Discovery Processor and select the snmpIfTypeMap and snmpVendorNameMap output parameter from the MIB II Properties Initializer as input parameters. Refer to "About Context Parameters" for instructions on how to add input parameters to a processor.

  6. Create the implementation class for this discovery processor. Refer to "About Processor Implementation" for instructions on how to add an implementation class to a processor.

  7. Add the implementation code into the body of the invoke() method of the discovery processor implementation class, similar to the following:

    // Rename 34416 from "Ottawa Area Intermediate School District"
    //   to "Ottawa Area Middle School District"
    // Add a new vendor ID 90210 = West Beverly Hills School District
    //
    Map<String, String> vendorNameMap = request.getSnmpVendorNameMap();
    vendorNameMap.put("34416", "Ottawa Area Middle School District");
    vendorNameMap.put("90210", "West Beverly Hills School District");
     
    // Add a new interface type 333 as tachyonEther.
    //
    Map<String, String> ifTypeMap = request.getSnmpIfTypeMap();
    ifTypeMap.put("333", "tachyonEther");
    

Extending the Existing Cartridge to Discover and Reconcile New Characteristics

This scenario describes the steps required to extend an existing cartridge to discover new data from a device and reconcile this data with an Inventory system.

The following high-level steps are involved:

  • Create a Network Integrity Cartridge Project

  • Create Specifications and Characteristics for the new data

  • Create a Discovery Action that re-uses existing discovery action

  • Configure the SNMP discovery of this data

  • Map this data to the Oracle Communications Information Model

  • Create a Discrepancy Detection and Discrepancy Resolution Actions that re-use existing actions

  • (optional) Create a Import Action that re-uses existing import action

For this scenario the following data is discovered and stored on the Physical Device:

  • Running Configuration Last Saved Date

  • Running Configuration Last Modified Date

  • Startup Configuration Last Modified Date

Prerequisites:

  • The following cartridge projects are loaded into the Design Studio workspace and are building without errors:

    • Base_Detection_Cartridge

    • Address_Handlers

    • Cisco_Model

    • Cisco_SNMP_Cartridge

    • Cisco_UIM_Cartridge

    • Cisco_UIM_Model

    • MIB_II_Model

    • MIB_II_SNMP_Cartridge

    • MIB_II_UIM_Cartridge

  • The above cartridge projects can be loaded by importing the Cisco SNMP Cartridge, MIB II UIM Cartridge, and Cisco UIM Cartridge ZIP files into Design Studio. For instructions on importing cartridge zip files refer to "Exporting and Importing Cartridges".

Creating Project, Discovery Action with Processors, and Adding Characteristics and Specifications

To perform an extended discovery action, use the following procedure:

Figure 19-2 shows the Extended Discovery Action created in this scenario:

Figure 19-2 Discovery Action (Extended)

Illustrates extended discovery action
  1. In the Design Studio Cartridge View create a Network Integrity Cartridge Project, for example named Extensibility_Cartridge. Refer to "Creating a Cartridge" for instructions on creating a Network Integrity Cartridge Project.

  2. Copy the existing specifications and add the new characteristics. Use the following steps:

    1. Double-click cisco3640Router. This is the data dictionary in the Cisco_UIM_Model.

    2. Right-click cisco3640 structure and select Copy To -> Extensibility_Cartridge.

    3. Double-click cisco6509Router data dictionary.

    4. Right-click cat6509 structure and select Copy To -> Extensibility_Cartridge.

    5. Double-click cisco7206VXRRouter data dictionary.

    6. Right-click cisco7206VXR structure and select Copy To -> Extensibility_Cartridge.

  3. Rename the copied specifications and have new characteristics added to them. Double-click Extensibility_Cartridge to open the data dictionary.

  4. Because specification names have to be unique in the system, the name of the cisco3640 specification needs to be changed to support new characteristics. To rename the specification use the following steps:

    1. Right-click the cisco3640 structure.

    2. Select Rename (or press F2).

    3. Give the specification a new name, for example add the word Custom to the end of the name.

    4. Refer to "Model Extension Using Specifications" for more details about specifications and characteristics.

  5. Add the new characteristics to the new specification to hold the data that is discovered from the device. To add the new characteristics:

    1. Right-click the cisco3640Custom structure.

    2. Select Add Child Element.

    3. Specify a name for the characteristic, for example runningConfigLastSavedDate.

    4. Right-click the cisco3640Custom structure.

    5. Select Add Child Element.

    6. Specify a name for the characteristic, for example runningConfigLastChangedDate.

    7. Right-click the cisco3640Custom structure.

    8. Select Add Child Element.

    9. Specify a name for the characteristic, for example startupConfigLastChangedDate

  6. Repeat steps 4 and 5 for structures cisco7206VXR and cat6509 in the Extensibility_Cartridge data dictionary.

  7. A model collection entity is required to indicate which specifications this cartridge uses. Create a Model Collection called Extensibility Model Collection in the Extensibility_Cartridge project. Refer to "Model Extension Using Specifications" for instructions on how to create a Model Collection and add specifications to it.

  8. Add the Physical Device specifications cisco3640Custom, cisco7206VXRCustom and cat6509Custom (created and modified in the steps above) to the new Model Collection.

  9. Save all changes.

  10. Now a new Discovery Action is required in the Cartridge Project that discovers the device and models the new fields. To do this create a Discovery Action, for example called Discover Extended Cisco. Refer to "Creating a Discovery Action" for instructions on how to create a Discovery Action and how to extend existing Discovery Actions.

  11. On the Processor tab of the new Discovery Action select Add and add the Discover Enhanced Cisco SNMP action. This adds all the processors from the Discover Enhanced Cisco SNMP action.

  12. A new SNMP Processor is required to retrieve the new fields from the device. To create a SNMP processor select New and add a new SNMP Processor, for example called Custom Cisco Collector. Refer to "Creating an SNMP Processor" for instructions on how to create a SNMP Processor.

  13. Perform a web search for the CISCO-CONFIG-MAN-MIB, download a copy of the MIB and manually copy the CISCO-CONFIG-MAN-MIB to the MIB directory (specified in Windows then Preferences then Oracle Design Studio then Network Integrity).

  14. The new Custom Cisco Collector needs the CISCO-CONFIG-MAN-MIB file. Load the CISCO-CONFIG-MAN-MIB into the SNMP Processor MIB browser. Refer to "Supporting New MIBs" on how to add a new MIB file to Design Studio.

  15. The new MIB also needs to be added to the server side. Copy CISCO-CONFIG-MAN-MIB file to the SNMP Adapter on the Network Integrity server side. Refer to "Extending the SNMP JCA Resource Adapter" section for details.

  16. Add the following MIB Objects from CISCO-CONFIG-MAN-MIB.private.enterprises.cisco.ciscoMgmt.ciscoConfigManMIB.ciscoConfigManMIBObjects.ccmHistory:

    • ccmHistoryRunningLastChanged

    • ccmHistoryRunningLastSaved

    • ccmHistoryStartupLastChanged

  17. Save all changes.

  18. Now a new Discovery Processor is required that maps the newly discovered fields to the specifications and characteristics defined earlier in the scenario. To do this click New and add a new Discovery Processor, for example called Custom Cisco Modeler. Refer to "Creating Discovery Processors" for instructions on how to add a new Discovery Processor.

  19. Select the input parameter physicalDevice that is output by the Cisco SNMP Physical Modeler. Refer to "About Context Parameters" for instructions on how to add input parameters to a processor.

  20. Select the output document of the Custom Cisco Collector as an input parameter

  21. Create the implementation class for this discovery processor. Refer to "About Processor Implementation" for instructions on how to add an implementation class to a processor.

  22. Add the following implementation code into the invoke() method that was auto-generated:

    Note:

    Import statements are required to successfully compile the following code, the imports should all be resolvable by Eclipse with the existing classpath. No classpath changes are necessary.
    // Get the running config and startup config values from the SNMP response document
    // Keep the values in local variables
    CiscoConfigManMibMib configMib = request.getCustomCiscoCollectorResponseDocument().getDiscoveryResult().getCiscoConfigManMibResults();
    String runningConfigChanged = Long.toString(configMib.getCcmHistoryRunningLastChanged());
    String runningConfigSaved = Long.toString(configMib.getCcmHistoryRunningLastSaved());
    String startupConfigChanged = Long.toString(configMib.getCcmHistoryStartupLastChanged());
     
    if (request.getPhysicalDevice() != null) {
       // Get the physical device.
       PhysicalDevice physicalDevice = request.getPhysicalDevice();
     
       // Get the specification name on the physical device
       String specName = physicalDevice.getSpecification().getName();
       if (specName != null) {
          
          // Change the specification to the custom specification type 
          // and set the new fields
          if (specName.equals(Cisco3640.SPEC_NAME)) {
             Cisco3640Custom custom = new Cisco3640Custom(physicalDevice);
             custom.setRunningConfigLastChangedDate(runningConfigChanged);
             custom.setRunningConfigLastSavedDate(runningConfigSaved);
             custom.setStartupConfigLastChangedDate(startupConfigChanged);
          } else if (specName.equals(Cat6509.SPEC_NAME)) {
             Cat6509Custom custom = new Cat6509Custom(physicalDevice);
             custom.setRunningConfigLastChangedDate(runningConfigChanged);
             custom.setRunningConfigLastSavedDate(runningConfigSaved);
             custom.setStartupConfigLastChangedDate(startupConfigChanged);
          } else if (specName.equals(Cisco7206VXR.SPEC_NAME)) {
             Cisco7206VXRCustom custom = new Cisco7206VXRCustom(physicalDevice);
             custom.setRunningConfigLastChangedDate(runningConfigChanged);
             custom.setRunningConfigLastSavedDate(runningConfigSaved);
             custom.setStartupConfigLastChangedDate(startupConfigChanged);
          }
       }
    }
    

Creating a Discrepancy Detection Action with Processors

Figure 19-3 shows the Discrepancy Detection Action created in this scenario:

Figure 19-3 Discrepancy Detection Action

Illustrates discrepancy detection action
  1. Create a Discrepancy Detection Action called Detect Extended Cisco Discrepancies. Refer to "Working with Discrepancy Detection Actions and Processors" for instructions on how to create a Discrepancy Detection Action and how to extend existing Discrepancy Detection Actions.

  2. On the Result Source tab, click Add and add the Discover Extended Cisco action. This indicates that the extended Discrepancy Detection action applies to extended discovery results.

  3. On the Processor tab of the new Discrepancy Detection Action select Add and add the Detect Enhanced Cisco Discrepancies action. This adds all the processors from the Detect Enhanced Cisco Discrepancies action.

Creating a Discrepancy Resolution Action with Processors

Figure 19-4 shows the Discrepancy Resolution Action created in this scenario:

Figure 19-4 Discrepancy Resolution Action

Illustrates discrepancy resolution action
  1. Create a Discrepancy Resolution Action called Resolve Extended Cisco in UIM. Refer to "Working with Discrepancy Resolution Actions and Processors" for instructions on how to create a Discrepancy Resolution Action, and how to extend existing Discrepancy Resolution Actions.

  2. On the Details panel, select Correct in UIM as the Resolution Action Label. This indicates that discrepancies are corrected in the UIM inventory system.

  3. On the Result Source tab, click Add and add the Discover Extended Cisco action. This indicates that the extended Discrepancy Resolution action applies to extended discovery results

  4. On the Processor tab of the new Discrepancy Resolution Action select Add and add the Resolve Cisco in UIM action. This adds all the processors from the Resolve Cisco in UIM action.

  5. Create UIM Physical Device specifications that match the cisco3640Custom, cisco7206VXRCustom and cat6509Custom specifications already created for Network Integrity. Refer to the UIM document, Understanding Unified Inventory Management, Release 7.1, for details on how to use Design Studio to create and deploy UIM specifications.

  6. Each UIM specification should contain the Information Model characteristics and the three new custom characteristics (runningConfigLastSavedDate, runningConfigLastChangedDate, and startupConfigLastChangedDate).

    1. Each UIM specification should set the same parent child and cardinality relationship as the original UIM specifications cisco3640, cisco7206VXR, and cat6509. (The first child needs to be set to the chassis, and inherits the remaining cascade relationships).

    2. Select the existing specification, copy, paste with rename, and add the new characteristics.

Creating and Import Action with Processors (Optional)

Figure 19-5 shows the option Import Action created in this scenario:

Figure 19-5 Import Action (Optional)

Illustrates import action

This is an optional section. The existing Import Cisco from UIM action available in the Cisco UIM Cartridge is used to import the extended devices types with new characteristics. Create this import action if you want to deploy the Extensibility Cartridge without also deploying the Cisco UIM Cartridge.

  1. Create a Import Action called Import Extended Cisco from UIM. Refer to "Working with Import Actions and Processors" for instructions on how to create a Import Action, and how to extend existing Import Actions.

  2. On the Processor tab of the new Import Action select Add and add the Import Cisco from UIM action. This adds all the processors from the Import Cisco from UIM action.

Extending the MIB II SNMP Discovery to Change Interface Name Value

This scenario describes the steps required to extend the MIB II SNMP Discovery Action to map the ifName to the interface name rather than the interface description. In addition, this scenario exposes a UI parameter that the end-user can use to control the behavior of the interface name mapping.

Note:

Changing how the name field is mapped has repercussions on how generic discrepancy detection looks up import entities because the lookup is done using name field (this can be modified using discrepancy detection filters, refer to "About Filters" for details). If the interface name field is modified for discovery, but is not modified on the import data many &rsquor;extra entity' discrepancies are produced because discrepancy detection is unable to find the interface of the import side.

This problem can be avoided by ensuring that the name field for discovery and import are identical, or by using a different field other than name to look up the interface on the import side. An example of using a different field is in the Detect MIB II UIM Discrepancies Discrepancy Detection Action in the MIB_II_UIM_Cartridge. This action overrides the default lookup to use the NativeEMSName instead of the name field.

Step 16 in this scenario describes how the Detect MIB II UIM Discrepancies Discrepancy Detection Action can be re-used in this extensibility scenario.

The following high-level steps are involved in this scenario:

  • Create new Network Integrity Cartridge Project

  • Create new Discovery Action that re-uses existing discovery action

  • Configure new UI Parameter

  • Add new processor to change mapping of interface name

Prerequisites:

  • The following cartridges are loaded into the Design Studio workspace and are building without errors:

    • Address_Handlers

    • MIB_II_Model

    • MIB_II_SNMP_Cartridge

  • The above cartridge projects can be loaded by importing the MIB II SNMP Cartridge ZIP file into Design Studio. For instructions on importing cartridge ZIP files, refer to "Exporting and Importing Cartridges".

Creating a Discovery Action with Processor

Figure 19-6 shows the Discovery Action created in this scenario:

Figure 19-6 Discovery Action

Illustrates discovery action
  1. Create a cartridge to hold the new discovery action. Create a Network Integrity Cartridge Project called InterfaceName_Cartridge. Refer to "Creating a Cartridge" for instructions on how to create a Network Integrity Cartridge Project.

  2. Create a Discovery Action called Discover Custom MIB II SNMP. Refer to "Configuring a Discovery Action" for instructions on how to create a Discovery Action and how to extend existing Discovery Actions.

  3. On the Processor tab of the new Discovery Action click Add and select the Discover MIB II SNMP action. This adds all the processors from the Discover MIB II SNMP action.

  4. On the UI Parameters tab click New and add a new UI Parameter structure called MIBIICustomParameters. Refer to "Working with UI Parameters" for instructions on creating and configuring UI Parameters.

  5. Double-click the MIBIICustomParameters UI parameter structure to open the data dictionary.

  6. In the data dictionary create a top-level element called mapIfDescToInterfaceName. Use the following steps:

    1. Right-click the data dictionary.

    2. Select Add Element.

    3. Enter mapIfDescToInterfaceNamefor the element name.

    4. Click OK.

  7. Add two enumeration values to this element by clicking the Enumerations tab and then clicking the Add button. Add the enumerations true and false.

  8. Then add a child element to the MIBIICustomParameters structure called mapIfDescToInterfaceName and select the type mapIfDescToInterfaceName created in step 6.

    Note:

    Enumerations in specifications must be added as described in steps 7 and 8. If the enumeration values are added directly on the Child Element, the enumeration values are not generated correctly in the generated UI Parameters page.
  9. Open the Cartridge Editor for the InterfaceName_Cartridge and click the UI Hints Tab.

  10. Find the MIBIICustomParameters structure and click the child mapIfDescToInterfaceName element.

  11. Select Create Scan page on the right pane.

  12. Change the Label to 'Map Description to Interface Name'.

  13. Change Control Type to Choice.

  14. Change Default Value to true.

  15. Save all changes.

  16. Open the editor for Discover Custom MIB II SNMP discovery action and select the Processors tab.

  17. Select New and add a new Discovery Processor called Custom Interface Name Modeler. Refer to "Creating Discovery Processors" for instructions on how to create a Discovery Processor.

  18. Open the editor for the Custom Interface Name Modeler Discovery Processor. Choose the Context Parameters tab and select the output parameter logicalDevice from the MIB II SNMP Modeler as an input parameter. Refer to "About Context Parameters" for instructions on how to add input parameters to a processor.

  19. Select the Details tab and create the implementation class for the discovery processor.

  20. Add the implementation code similar to the following:

    Note:

    Import statements are required to successfully compile the following code, the imports should all be resolvable by Eclipse with the existing classpath, no classpath changes are necessary.
    @Override
    public void invoke(DiscoveryProcessorContext context,
          CustomInterfaceNameModelerProcessorRequest request)
          throws ProcessorException {
     
       // if the user specified they do not want the ifDesc as the name of the interface
       // then use the ifName instead
       if ("false".equalsIgnoreCase(request.getMibiiCustomParameters().getMapIfDescToInterfaceName())) {
          List<DeviceInterface> deviceInterfaces = request.getLogicalDevice().getDeviceInterfaces();
          changeInterfaceNameToIFName(deviceInterfaces);
       }
    }
     
    private void changeInterfaceNameToIFName(List<DeviceInterface> deviceInterfaces) {
       // loop through every interface and change the mapping.
       for (DeviceInterface deviceInterface : deviceInterfaces) {
          // the Discover MIB II SNMP Discovery Action is inserting the ifName into the 
          // VendorInterfaceNumber so the following code copies that to the name field
          deviceInterface.setName(deviceInterface.getVendorInterfaceNumber());
          // Change interface name on any sub-interfaces as well
          changeInterfaceNameToIFName(deviceInterface.getSubInterfaces());
       }
    }
    
  21. To register Discrepancy Detection and Discrepancy Resolution on the new Discover Custom MIB II SNMP Discovery Action, add new Result Sources to the Detect MIB II UIM Discrepancies and Resolve MIB II in UIM in the MIB_II_UIM_Cartridge that register for results from the Discover Custom MIB II SNMP Discovery Action. Refer to "Working with Discrepancy Detection Actions and Processors" for details. (Alternatively, the Detect MIB II UIM Discrepancies and Resolve MIB II in UIM Actions could be extended in the InterfaceName_Cartridge. Refer to "Extending the Existing Cartridge to Discover and Reconcile New Characteristics" Extensibility Scenario for details on doing this).

Multiple Vendor SNMP Discovery

This scenario describes the steps required to extend an existing cartridge to discover data from devices from multiple vendors.

There are multiple scenarios, depending on the user's objectives.

One scenario is that a user wants to discover devices from a single vendor, for example, Huawei. The user should extend the MIBII SNMP cartridge by reusing the Discover MIB II SNMP Action and adding a Huawei SNMP Collector and a Huawei SNMP Modeler. The Huawei SNMP Collector polls Huawei specific MIBs and the Huawei SNMP Modeler models the Huawei devices based on the collected Huawei SNMP OIDs.

Another scenario is the user wants to discover Juniper devices in addition to Cisco devices. The user should extend the Enhanced Cisco SNMP Action in the Cisco UIM cartridge. This scenario is detailed in this section

Prerequisites:

  • The following cartridges are loaded into the Design Studio workspace and are building without errors:

    • Base_Detection_Cartridge

    • Address_Handlers

    • Cisco_Model

    • Cisco_SNMP_Cartridge

    • Cisco_UIM_Cartridge

    • Cisco_UIM_Model

    • MIB_II_Model

    • MIB_II_SNMP_Cartridge

    • MIB_II_UIM_Cartridge

  • The above cartridge projects can be loaded by importing the Cisco SNMP Cartridge, MIB II UIM Cartridge, and Cisco UIM Cartridge ZIP files into Design Studio. For instructions on importing cartridge zip files, refer to "Exporting and Importing Cartridges".

Use the sysObjectId from RFC1213MIB to determine a vendor of devices. For example, Cisco devices have the sysObjectId value that starts with 1.3.6.1.4.1.9., and Juniper device have the sysObjectId value starting with 1.3.6.1.4.1.2636.. Set up a range of IP addresses and scan those IP addresses by polling the sysObjectId. Based on the sysObjectValue returned, configure two Conditions: one returns true if the sysObjectId value starting with 1.3.6.1.4.1.9. (meaning it is a Cisco device), or return false if otherwise; the other return true if the sysObjectId value starting with 1.3.6.1.4.1.2636. (meaning it is a Juniper device), or return false if otherwise.

The Cisco UIM Cartridge contains the Discover Enhanced Cisco SNMP Action. Create a Discovery Action by reusing this Discover Enhanced Cisco SNMP Action, which gives this new Discovery Action all the functions to discover the enhanced Cisco devices (including the MIB II SNMP discovery). Extend this Discovery Action to support Juniper devices by creating a Juniper SNMP collector and a Juniper modeler to this Discovery Action. The two conditions determine when to execute the Cisco related collectors and modelers and when to execute the Juniper collector and modeler based on the device type.

Create a Discovery Action with Processors and Conditions

Figure 19-7 shows the Discovery Action created in this scenario:

Figure 19-7 Discovery Action

Illustrates discovery action, multi-vendor
  1. Manually copy the JUNIPER-MIB to the MIB directory. The new Juniper SNMP collector needs this JUNIPER-MIB file. Please refer to "Supporting New MIBs" for information on adding a new MIB file to Design Studio.

  2. Copy this JUNIPER-MIB file to the SNMP Adapter on Network Integrity server side. Refer to "Extending the SNMP JCA Resource Adapter".

  3. Create a Discovery Action, for example Discover Multi-Vendor, by reusing the sample Discover Enhanced Cisco SNMP Action. Refer to "Adding an Existing Action" for information on reusing an existing Action).

  4. Create a Juniper SNMP Collector and add the new SNMP Discovery Processor to the Discover Multi-Vendor Discovery Action as the last processor.

  5. Add the OID, jnxBoxDescr (from JUNIPER-MIB), to this Juniper SNMP Processor. In realistic scenario, more OIDs are polled from this JUNIPER-MIB to model a Juniper device. In this example, only the description field is polled. Refer to "Creating an SNMP Processor" for information on creating and configuring an SNMP Discovery Processor.

  6. Create a Juniper modeler and add this new Discovery Processor to the Discover Multi-Vendor Discovery Action after the Juniper SNMP collector. This new processor takes the SNMP output parameter from the Juniper SNMP collector as its input parameter. Refer to "Creating Discovery Processors" for information on creating and configuring this Discovery Processor. Implement this Discovery Processor by implementing the invoke method. In this example, only the description field for the Juniper device is logged. In a realistic scenario, the complete model the Juniper device would exist in this invoke method.

    The following is the Java snippet for the invoke method.

    @Override
     public void invoke(DiscoveryProcessorContext context,
     JuniperProcessorProcessorRequest request) throws ProcessorException {
    logger.log(Level.INFO, "Processing Juniper device " + request.getScopeAddress());
    JuniperSNMPCollectorResponseType responseDoc = request.getJuniperSNMPCollectorResponseDocument();
    DiscoveryResultType result = responseDoc.getDiscoveryResult();
    JuniperMibMib juniperMibResults = result.getJuniperMibResults();
    if(juniperMibResults != null) {
    logger.log(Level.INFO, "Juniper Device Description: " + juniperMibResults.getJnxBoxDescr());
    }
     }
    
  7. Create a Cisco Condition, that checks the sysObjectId to determine whether a device is a Cisco device or not. This Cisco Condition takes the mibiisnmpCollectorResponseDocument (an output parameter from MIB II SNMP Collector) as the input parameter. Refer to "Applying Conditions to Processors" for information on creating a Condition. The following is a Java snippet for this Cisco Condition:

    public class CiscoConditionImpl implements CiscoCondition {
     private static final String CISCO_PREFIX = "1.3.6.1.4.1.9.";
    @Override
    public boolean checkCondition(DiscoveryProcessorContext context,
    CiscoRequest request) throws ProcessorException {
    MIBIISNMPCollectorResponseType snmpResponse = request
    .getMibiisnmpCollectorResponseDocument();
    logger.log(Level.INFO, "GPE CiscoConditionImpl "
    + context.getProcessorName());
    if (snmpResponse != null
    && snmpResponse.getDiscoveryStatus() == DiscoveryStatus.SUCCESS) {
    logger.log(Level.INFO, "GPE CiscoConditionImpl discovery succeeded");
    if (snmpResponse.getDiscoveryResult().getRfc1213MibResults() != null) {
    String sysObjectId = snmpResponse.getDiscoveryResult()
    .getRfc1213MibResults().getSysObjectID();
    logger.log(Level.INFO, "GPE CiscoConditionImpl raw sys object id: " + sysObjectId);
    if (sysObjectId != null) {
    if (sysObjectId.startsWith(".")) {
    sysObjectId = sysObjectId.substring(1);
    }
    return sysObjectId.startsWith(CISCO_PREFIX);
    }
    }
    }
    return false;
    }
    }
    
  8. Create a Juniper Condition, that checks the sysObjectId to determine whether a device is a Juniper device. This Juniper Condition takes the mibiisnmpCollectorResponseDocument (an output parameter from MIB II SNMP Collector) as the input parameter. Refer to "Applying Conditions to Processors" for information on creating a Condition. This Juniper Condition is similar to the Cisco Condition that was created in step 5. The difference is that the sysObjectId for Juniper device starts with 1.3.6.1.4.1.2636..

  9. Apply the Cisco Condition to the following Cisco Processors and set Equals to true:

    1. Cisco SNMP Logical Collector

    2. Cisco SNMP Physical Collector

    3. Cisco SNMP Logical Modeler

    4. Cisco SNMP Physical Modeler

    5. Cisco Enhanced Modeler

    Refer to "Applying Conditions to Processors" for information on applying Conditions to Processors. By applying the Cisco Condition to those Processors (listed above), those Processors are invoked if the Cisco Condition returns true, which means it is a Cisco device.

  10. Apply the Juniper Condition to the following two Juniper Processors and set Equals to true:

    1. Juniper SNMP Collector

    2. Juniper Processor

Note:

In this example, only a single Juniper OID is collected and the value of the collected Juniper OID in the Juniper SNMP Modeler is logged. In a realistic scenario, several Juniper OIDs are collected to model a Juniper device. Refer to "Extending the Existing Cartridge to Discover and Reconcile New Characteristics" on how to map new SNMP OIDs to new Characteristics and how to update UIM related Actions for importing, discrepancy detection and resolution with the new Characteristics.

Multiple Protocol Discoveries

This scenario describes the steps required to extend an existing cartridge to discover data using multiple protocols.

Prerequisites:

  • The following cartridges are loaded into the Design Studio workspace and are building without errors:

    • Base_Detection_Cartridge

    • Address_Handlers

    • Cisco_Model

    • Cisco_SNMP_Cartridge

    • Cisco_UIM_Cartridge

    • Cisco_UIM_Model

    • MIB_II_Model

    • MIB_II_SNMP_Cartridge

    • MIB_II_UIM_Cartridge

  • The above cartridge projects can be loaded by importing the Cisco SNMP Cartridge, MIB II UIM Cartridge, and Cisco UIM Cartridge ZIP files into Design Studio. For instructions on importing cartridge zip files, refer to "Exporting and Importing Cartridges".

In this scenario, a range of devices can be discovered. Some devices are SNMP-enabled; some devices support an alternate protocol (for example, TL1). With a list of IP addresses for each of these devices, the Discovery Action can dynamically discover a device using either SNMP or the alternate protocol.

The Cisco UIM Sample cartridge contains the sample Discover Enhanced Cisco SNMP Action. Create a Discovery Action by reusing this Discover Enhanced Cisco SNMP Action. This gives the new Discovery Action all the functions to discover an enhanced Cisco device (including the MIB II SNMP discovery). This Discovery Action can be extended to support the alternate protocol by creating a Discovery Processor that implements the alternate protocol to this Discovery Action. To use a JCA resource adapter for this alternate protocol, refer to "JCA Resource Adapters".

Create a Condition, that checks whether the SNMP polling to a device is successful or not. If a device supports SNMP, this Condition returns true; otherwise if the device supports the alternate protocol, this Condition returns false. By applying this Condition to the Processors, the Discovery Action can dynamically discover a device using either SNMP or the alternate protocol.

Create a Discovery Action with Processors and Conditions

Figure 19-8 shows the Discovery Action created in this scenario:

Figure 19-8 Discovery Action

Illustrates discovery action, multiprotocol
  1. Create a Discovery Action, Discover MultiProtocol, by reusing the sample Discover Enhanced Cisco SNMP Action (refer to "Adding an Existing Action" for information on reusing an existing Action).

  2. Create a Discovery Processor, for example Alternate Protocol Collector, which implements the alternate protocol to discover a device and add this new Discovery Processor to the Discover MultiProtocol Discovery Action as the last Processor. Refer to "Working with Processors", and "Working with Discovery Actions and Processors" for information on creating and configuring this Discovery Processor. Implement this Discovery Processor by implementing the invoke method. In this example, one line is logged indicating that this Processor implements an alternate protocol. In a realistic scenario, implement the alternate protocol to discover a device in this invoke method. The following is the Java snippet for the invoke method.

    @Override
        public void invoke(DiscoveryProcessorContext context,
        AlternateProtocolCollectorProcessorRequest request)
        throws ProcessorException {
    logger.log(Level.INFO, "SNMP Failed - using alternate protocol to discover device " + request.getScopeAddress());
        }   
    
  3. Create an SnmpSucceeds Condition, that checks the SNMP results from MIB II Collector to determine whether the SNMP discovery on a device is successful or not. This SnmpSucceeds Condition takes the mibiisnmpCollectorResponseDocument (an output parameter from MIB II SNMP Collector) as the input parameter. Refer to "Applying Conditions to Processors" for information on creating a Condition. The following is a Java snippet for this SnmpSucceeds Condition:

    public class SnmpSucceedsConditionImpl implements SnmpSucceedsCondition {
        @Override
        public boolean checkCondition(DiscoveryProcessorContext context,
        SnmpSucceedsRequest request) throws ProcessorException {
    MIBIISNMPCollectorResponseType snmpResponse = request.getMibiisnmpCollectorResponseDocument();
    return snmpResponse != null && snmpResponse.getDiscoveryStatus() == DiscoveryStatus.SUCCESS;
        }
    }
    
  4. Apply the SnmpSucceeds Condition to the following Processors and set the Equals to be true:

    1. MIB II SNMP Modeler

    2. Cisco SNMP Logical Collector

    3. Cisco SNMP Physical Collector

    4. Cisco SNMP Logical Modeler

    5. Cisco SNMP Physical Modeler

    6. Cisco Enhanced Modeler

    Refer to "Applying Conditions to Processors" for information on applying Condition to Processors. By applying the SnmpSucceeds Condition to those Processors (listed above), those Processors are invoked if the SnmpSucceeds Condition returns true, which means it is an SNMP-enabled device.

  5. Apply the SnmpSucceeds Condition to the following Processor and set the Equals to be false:

    1. Alternate Protocol Collector

    By applying the SnmpSucceeds Condition to the Processor (listed above), the Processor is invoked if the SnmpSucceeds Condition returns false, which means it is not an SNMP-enabled device and therefore supports an alternate protocol.

Note:

In this example, only the message is logged to indicate that an alternate protocol is used in the Alternate Protocol Collector Processor. In a realistic scenario, the alternate protocol would be implemented and the network data collected using this protocol and model the collected network data. Refer to "Extending the Existing Cartridge to Discover and Reconcile New Characteristics" section on how to map the collected network data (in that section, the network data is SNMP OID) to new Characteristics and how to update UIM related Actions for importing, discrepancy detection and resolution with the new Characteristics.