Cartridge projects and actions in Network Integrity are extensible using Oracle Communications Service Catalog and Design - Design Studio for Network Integrity. The productized and sample cartridges provided by Network Integrity are designed to be completely extensible and re-usable.

When you make a cartridge project dependent on another, you allow the dependent cartridge project access to the extensible elements from the base cartridge project.

The following sections are 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 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 scan parameter groups and characteristics to extend the Network Integrity UI

• Using filters to modify default discrepancy detection behavior

• What extension points are available in productized cartridges

The scenarios are made up of high-level steps. For more detailed steps, see Design Studio Modeling Network Integrity.

See the following extensibility scenarios:

• Extending MIB II SNMP Discovery for Updated Vendor and Interface Type

  Describes how to update the vendor number and interface type mapping tables in the MIB II SNMP Discovery cartridge.

• Extending the MIB II SNMP Discovery to Change Interface Name Value

  Describes how to extend the MIB II SNMP Discovery action to map the SNMP variable ifName to the interface entity name rather than the entity interface description.

• Multiple Vendor SNMP Discovery

  Describes how to extend an existing cartridge to discover device data from multiple vendors.

• Multiple Protocol Discoveries

  Describes how to extend an existing cartridge to discover data using multiple protocols.

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 and output by the MIB II Properties Initializer processor.

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")

• Changes an existing vendor name (#34416, from “Ottawa Area Intermediate School District" to “Ottawa Area Middle School District")

The following cartridges must be loaded in the Design Studio and not have any errors:

• Address_Handlers

• MIB_II_Model

• MIB_II_SNMP_Cartridge

This scenario is made up of high-level steps that are explained in greater detail in the Design Studio Modeling Network Integrity Help.

To extend the MIB II SNMP Discovery cartridge project for updated vendor and interface type information:

1. Create a Network Integrity cartridge project called Vendor_Type_Update. Make your cartridge project dependent on the MIB_II_SNMP_Cartridge cartridge project.

2. Create a discovery action called Discover Updated MIB II SNMP.

3. In Discover Updated MIB II SNMP, add the Discover MIB II SNMP action as a processor.

4. Create a discovery processor called MIB II Properties Updater and place it after the MIB II Properties Initializer processor. This processor will be used to update the two mapping tables.

5. Open the Processor editor Context Parameters tab for MIB II Properties Updater and add snmpIfTypeMap and snmpVendorNameMap as input parameters. These parameters are the output from the MIB II Property Initializer processor.

6. Create the implementation class for this discovery processor. See "Implementing a Processor" 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");
   

8. Build, deploy, and test your cartridge.

Figure 6-1 shows the processor workflow of the Discover Updated MIB II SNMP action and the placement of the MIB II Properties Updater processor.

This discovery action inherits all the processors from the Discover MIB II SNMP action. See "Overview" in MIB-II SNMP Cartridge Guide for more information.

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 scan parameter that the end-user can use to control the behavior of the interface name mapping.

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

• Create new Network Integrity cartridge project

• Create new discovery action that re-uses an existing discovery action

• Create new scan parameter groups with new characteristics

• Add new processor to change mapping of interface name

The following cartridges must be loaded in the Design Studio and not have any errors:

• Address_Handlers

• MIB_II_Model

• MIB_II_SNMP_Cartridge

This scenario is made up of high-level steps that are explained in greater detail in the Design Studio Modeling Network Integrity Help.

To extend the MIB II SNMP cartridge to change the interface name value:

1. Create a Network Integrity cartridge project called InterfaceName. Make your cartridge project dependent on the MIB_II_SNMP_Cartridge cartridge project.

2. Create a discovery action called Discover Custom MIB II SNMP.

3. In Discover Custom MIB II SNMP, add the Discover MIB II SNMP action as a processor.

4. Create a scan parameter group called MIBIICustomParameters. Add the scan parameter group to the Discover Custom MIB II SNMP action.

5. For MIBIICustomParameters, create a characteristic called mapIfDescToInterfaceName.

6. Add two enumeration values to mapIfDescToInterfaceName:

   1. Open the Data Schema editor for mapIfDescToInterfaceName.

   2. Click the Enumerations subtab.

   3. Add an enumeration called True and another called False.

   4. In the Default column, set True to be the default value.

7. On the Scan Parameter Group editor Layouts tab for MIBIICustomParameters, do the following:

   1. Select mapIfDescToInterfaceName.

      The UI Settings area displays the scan parameter values for mapIfDescToInterfaceName.

   2. In the Display Name field, enter Map Description to Interface Name.

      This is the name that will appear in the Network Integrity UI for the scan parameter.

8. Save all changes.

9. In the Discover Custom MIB II SNMP action, create a discovery processor called Custom Interface Name Modeler.

10. Open the Processor editor Context Parameters tab for Custom Interface Name Modeler and add logicalDevice as an input parameter. This parameter is the output from the MIB II SNMP Modeler processor.

11. On the Processor editor Details tab, create the implementation class for the discovery processor.

12. 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());
      }
    }
    

13. 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. See "About Discrepancy Detection Actions" and "About Discrepancy Detection Processors" for details.

    Figure 6-2 shows the processor workflow of the Discover Custom MIB II SNMP action and the placement of the Custom Interface Name Modeler processor.

    This discovery action inherits all the processors from the Discover MIB II SNMP action. See "Overview" in MIB-II SNMP Cartridge Guide for more information.

    Figure 6-2 Discover Custom MIB II SNMP Action

    
    Description of "Figure 6-2 Discover Custom MIB II SNMP Action"

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

The following cartridges must be loaded in the Design Studio and not have any errors:

• Address_Handlers

• ora_ni_uim_devices

• MIB_II_SNMP_Cartridge

• MIB_II_UIM_Cartridge

• Generic_SNMP_Model

• Generic_SNMP_Cartridge

• UIM_Integration_Cartridge

There are multiple scenarios, depending on your objectives.

One way is you want to discover devices from a single vendor. You should then extend the MIBII SNMP cartridge by reusing the Discover MIB II SNMP action and adding an SNMP Collector and an SNMP Modeler for the vendor. The SNMP Collector polls vendor-specific MIBs and the SNMP Modeler models the devices based on the collected SNMP OIDs.

Another way is you want to discover multiple vendor devices, for example, Cisco and Juniper devices. You should extend the Discover Generic SNMP action in the Generic_SNMP_Cartridge.

Use the sysObjectId from RFC1213MIB to determine a device vendor. 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 Generic_SNMP_Cartridge contains the Discover Generic SNMP action. Create a discovery action by reusing this Discover generic SNMP action, which gives this new discovery action all the functions to discover the generic SNMP 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 run the Cisco related collectors and modelers and when to run the Juniper collector and modeler based on the device type.

This scenario is made up of high-level steps that are explained in greater detail in Design Studio Modeling Network Integrity.

To extend a cartridge to discover devices from multiple vendors:

1. Create a Network Integrity cartridge project called Multi-Vendor. Make your cartridge project dependent on the Generic_SNMP_Cartridge cartridge project.

2. Create a discovery action called Discover Multi-Vendor.

3. In Discover Multi-Vendor, add the Discover Generic SNMP action as a processor.

4. Manually copy the JUNIPER-MIB to the MIB directory and to the SNMP adapter on the Network Integrity server. See "Supporting New MIBs" and "Extending the SNMP JCA Resource Adapter" for more information.

5. Create an SMMP processor called Juniper SNMP Collector and add it to Discover Multi-Vendor as the last processor.

6. In Juniper SNMP Collector, add the OID jnxBoxDescr (from JUNIPER-MIB).

   In a production environment, you would add more OIDs to poll and model more information.In this example, only the description field is polled.

7. Create an SNMP processor called Juniper SNMP Modeler and add it to Discover Multi-Vendor as the last processor. This processor takes the SNMP output parameter from Juniper SNMP Collector as its input parameter. Implement this 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 of 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());
     }
   }
   

8. Create an SNMP processor called Cisco SNMP Collector and add it to Discover Multi-Vendor as the last processor.

9. Add the OIDs from downloaded CISCO MIBS within Cisco SNMP Collector.

10. Create an SNMP processor called Cisco SNMP Modeler and add it to Discover Multi-Vendor as the last processor. This processor takes the SNMP output parameter from Cisco SNMP Collector as its input parameter. Implement this processor by implementing the invoke method. In this example, only the description field for the Cisco device is logged. In a realistic scenario, the complete model of the Cisco device would exist in this invoke method.

11. Create a Cisco condition that checks the sysObjectId to determine whether a device is a Cisco device or not. This condition takes the mibiisnmpCollectorResponseDocument (an output parameter from MIB II SNMP Collector) as the input parameter. 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, "CiscoConditionImpl"
     + context.getProcessorName());
     if (snmpResponse != null
     && snmpResponse.getDiscoveryStatus() == DiscoveryStatus.SUCCESS) {
     logger.log(Level.INFO, "CiscoConditionImpl discovery succeeded");
     if (snmpResponse.getDiscoveryResult().getRfc1213MibResults() != null) {
     String sysObjectId = snmpResponse.getDiscoveryResult()
     .getRfc1213MibResults().getSysObjectID();
     logger.log(Level.INFO, "CiscoConditionImpl raw sys object id:" + 
     sysObjectId);
     if (sysObjectId != null) {
     if (sysObjectId.startsWith(".")) {
     sysObjectId = sysObjectId.substring(1);
     }
     return sysObjectId.startsWith(CISCO_PREFIX);
     }
     }
     }
     return false;
     }
    }

12. 12. Create a Juniper condition, that checks the sysObjectId to determine whether a device is a Juniper device. This condition takes the mibiisnmpCollectorResponseDocument (an output parameter from MIB II SNMP Collector) as the input parameter. This Juniper condition is similar to the Cisco condition. The difference is that the sysObjectId for Juniper device starts with 1.3.6.1.4.1.2636.

13. Apply the Cisco condition to the following processors and set Equals to true:

    1. Cisco SNMP Collector

    2. Cisco SNMP Modeler

14. Apply the Juniper condition to the following Juniper processors and set Equals to true:

    1. Juniper SNMP Collector

    2. Juniper SNMP Modeler

Figure 6-3 shows the processor workflow of the Discover Multi-Vendor action and the placement of the Juniper SNMP Collector and Juniper Modeler processors.

This discovery action inherits all the processors from the Discover Generic SNMP action. See SNMP Discovery and UIM Integration Cartridge Guide for more information.

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

The following cartridges must be imported into the Design Studio and build without errors:

• Address_Handlers

• ora_ni_uim_device

• MIB_II_SNMP_Cartridge

• MIB_II_UIM_Cartridge

• Generic_SNMP_Model

• Generic_SNMP_Cartridge

• UIM_Integration_Cartridge

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 Generic_SNMP_Cartridge contains the sample Discover Generic SNMP Device action. Create a discovery action that reuses the Discover Generic SNMP Device action. 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, see "Working with 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.

This scenario is made up of high-level steps that are explained in greater detail in Design Studio Modeling Network Integrity.

To extend a cartridge to discover devices using multiple protocols:

1. Create a discovery action called Discover MultiProtocol and make it dependent on the Generic_SNMP_Cartridge cartridge project.

2. Create a discovery action called Discover Multi-Protocol.

3. In Discover Multi-Protocol, add the Discover Generic SNMP action as a processor.

4. Create a discovery processor called Alternate Protocol Collector to implement the alternate protocol to discover a device and add it to Discover Multi-Protocol as the last processor.

5. Implement Alternate Protocol Collector 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());
     }
   

6. Create a condition called SnmpSucceeds that checks the SNMP results from MIB II Collector to determine whether the SNMP discovery on a device is successful or not. This condition takes mibiisnmpCollectorResponseDocument (an output parameter from MIB II SNMP Collector) as the input parameter. 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;
     }
   }
   

7. Apply the SnmpSucceeds condition to the following processors and set the Equals to be true:

   • MIB II SNMP Collector

   • MIB II SNMP Modeler

   • Generic SNMP Logical Collector

   • Generic SNMP Logical Modeler

   • DI Name Remodeler

   • Generic SNMP Physical Collector

   • Generic SNMP Physical Modeler

   By applying the SnmpSucceeds condition, these processors are invoked only if the SnmpSucceeds condition returns true.

8. Apply the SnmpSucceeds condition to the Alternate Protocol Collector processor and set the Equals to be false.

Figure 6-4 shows the processor workflow of the Discover MultiProtocol action and the placement of the Alternate Protocol Collector processor.

This discovery action inherits all the processors from the Discover Generic SNMP action. See SNMP Discovery and UIM Integration Cartridge Guide for more information.