7 About Design Studio Extension

This chapter provides scenarios for the extensibility of Network Integrity using Oracle Communications Service Catalog and Design - Design Studio.

Adding a New Device Type under Generic

To discover and model a new device type:

  1. Collect all the YANG files supported by the device and place them in the YANG directory path set in Design Studio preferences.

  2. Generate the Restconf-yang-model-8.0.0.jar with new YANG files using the yang_sources_generator project and copy the JAR file to the Restconf_Network_Discovery_Cartridge/lib folder.

    For more information about generating the Restconf-yang-model, see About the RESTCONF YANG Model.

  3. Create a new processor of the type yangprocessor in the cartridge. Select all attributes that you want to be discovered from device.
  4. Create a new discoveryprocessor, which accepts yangprocessor output as input. Refer to the VendorRestconfDataDiscoveryProcessorImpl class to collect response from the device and generate Java objects.
  5. Update the Restconf Logical Device Modeler and Restconf Physical Device Modeler implementations to support modeling of the new device.

For more information regarding extensibility of cartridges, see Network Integrity Developer's Guide.

Fixing Known Issues in the RESTCONF Network Discovery Cartridge

This section provides information about known issues in the RESTCONF Network Discovery and UIM Integration cartridge.

Issues Occurring During Cartridge Runtime

This topic describes the issues occurring during the cartridge runtime and their fixes, as listed:
Generation of Duplicate Class Names in a YANG File

During cartridge runtime, the binding generator may generate classes with the same name in one YANG file.

Example:

The generator creates the same Java class for two similar containers in a YANG file: Cisco-ios-xe-native:mac-address-table/learning and Cisco-ios-xe-native:mac/address-table/learning. This happens because the binding generator treats both "-" and "/" in the paths as valid for creating packages, which results in the same class being genrated for both: 

org.opendaylight.yang.gen.v1.http.cisco.com.ns.yang.cisco.ios.xe._native.rev180522._native.mac.address.table.Learning

The duplication causes a conflict during creation of the runtime context and generates the following error:

Caused by: com.google.common.base.VerifyException: Conflict on runtime type mapping of org.opendaylight.yang.gen.v1.http.cisco.com.ns.yang.cisco.ios.xe._native.rev180522._native.mac.address.table.Learning

Fix: To fix this issue, delete any one of the similar containers in the YANG file and re-generate the bindings JAR file.

To apply the fix for the above described example.

  1. Identify the statement in the error that appears. The Java classes generated will be the same for both the statements. In this example, the statements are statement=EmptyContainerEffectiveStatement{argument=(http://cisco.com/ns/yang/Cisco-IOS-XE-native?revision=2018-05-22)learning}} and statement=EmptyContainerEffectiveStatement{argument=(http://cisco.com/ns/yang/Cisco-IOS-XE-native?revision=2018-05-22)learning}}
  2. Go to the reported module where the error originates, which is Cisco-IOS-XE-native and find statements with "learning" in them.
  3. Examine the absolute path of each node that contain "learning" and delete containers with matching paths so that only one of the matching nodes remains.
  4. Re-generate the binding JAR files.
  5. Use the regenerated JAR file in the RESTCONF Network Discovery and UIM Integration cartridge.
YANG Files with Deviation Statements May Not Be Processed

YANG files of a device may include deviation statements to define any features not supported by the device, or to describe how device implementation differs from the standard YANG model implementation. In some cases, the generator does not apply the changes specified in the deviation statements. This mismatch causes errors during runtime.

Even if the deviation removes support for a particular data path, the generator still creates Java classes for those nodes. This mismatch causes errors during runtime.

For example, if a schema correctly excludes the "Neighbor" node (as defined in the deviation statement), but the binding generator still creates a class for it, you will see an error like the following: 

<Failure in Processor Restconf Logical Data Modeller of Action DiscoverRestconfDevices (Exception: ProcessorException, Base Exception: IncorrectNestingException)>
<Jul 1, 2025, 9:58:02,354 AM Greenwich Mean Time> 
<Error>
<oracle.communications.integrity.scanCartridges.sdk.BaseController> <BEA-000000>
<Action failure: Node DefaultContainerRuntimeType{javaType=org.opendaylight.yang.gen.v1.urn.ietf.params.xml.ns.yang.ietf.ip.rev140616.interfaces._interface.Ipv4, statement=EmptyContainerEffectiveStatement{argument=(urn:ietf:params:xml:ns:yang:ietf-ip?revision=2014-06-16)ipv4}} does not have child named interface org.opendaylight.yang.gen.v1.urn.ietf.params.xml.ns.yang.ietf.ip.rev140616.interfaces._interface.ipv4.Neighbor>

This error is caused because the schema generator honors the YANG file's deviation statement, but the binding generator does not. This inconsistency leads to conflicts when the generated classes have the fields that the deviation statement has disabled but the schema has not.

Fix: To fix this issue, you must delete the deviation statement for the particular node and re-generate the bindings JAR file.

To apply the fix for the example:

  1. Open the relevant deviation YANG file, which is cisco-xe-ietf-ip-deviation.yang in this example.

  2. Locate the deviation statement for the node that is being disabled or modified which is:
     deviation /if:interfaces/if:interface/ip:ipv6/ip:neighbor {
 deviate not-supported;
 description "Not supported in IOS-XE 3.17 release.";
 }

  3. Delete the deviation statement.

  4. Re-generate the binding JAR files.
  5. Use the regenerated JAR file in the RESTCONF Network Discovery and UIM Integration cartridge.

Issues Occuring During Binding Generation

This topic describes the issues occurring during the cartridge runtime and their fixes, as listed:
Class and Package Names are Case-Sensitive and Do Not Work in Microsoft Windows

The generator sometimes creates classes for containers that have the same fully qualified name but use different cases (for example, ContainerA and containera). On Windows, file and folder names are treated as case-insensitive which leads to conflicts. As a result, some generated classes overwrite others, causing compilation errors when building the JAR file.

When this happens, you will see an error message like the following when compiling the JAR file:

Compilation fails during binding JAT files generation due to unable to resolve Type:
      ClassName

Fix: To fix this error:

  1. Navigate to the parent folder where this error is observed.
  2. Remove all the generated artifacts.
  3. Run this command as an administrator in Windows:
    fsutil.exe file setCaseSensitiveInfo path enable

    where path is the path of the parent folder.

  4. Re-generate the binding JAR files.
  5. Use the regenerated JAR file in the RESTCONF Network Discovery and UIM Integration cartridge.
Errors Resulting from Unsupported Use of XPATH 2.0

Some YANG files might use XPATH 2.0 which causes syntax errors.

Syntax Error: compare() function

Note:

This issue may occur during binding generation and cartridge runtime.

Use of the compare() function can generate an error like the following: 

org.opendaylight.yangtools.yang.parser.spi.source.SourceException: Argument "not (/ios:native/ios:router/ios-ospf:ospf/ios-ospf:vrf) or compare(/ios:native/ios:vrf/ios:definition/ios:name, /ios:native/ios:router/ios-ospf:ospf/ios-ospf:vrf) = 0 and /ios:native/ios:vrf/ios:definition/ios:rd" is not valid XPath string [at C:\cisco xe
      1691\Cisco-IOS-XE-ospf.yang:1999:7]

Fix: To fix this error, use "=" instead of the compare() function and ensure that each expression is enclosed in parentheses.

To fix this error:

  1. Open the YANG file mentioned in the error, which in this example is Cisco-IOS-XE-ospf.yang. The 1999:7 indicates the line number and column number where the syntax error occurs.
  2. Rewrite the argument by using the equals sign, for example:
    (/ios:native/ios:vrf/ios:definition/ios:name = /ios:native/ios:router/ios-ospf:ospf/ios-ospf:vrf)

    Ensure that the revised argument is enclosed in parentheses as shown.

  3. Re-generate the binding JAR files.
  4. Use the regenerated JAR file in the RESTCONF Network Discovery and UIM Integration cartridge.

Syntax Error: Use of Square Brackets

XPATH 2.0 allows the use of square brackets ( [ ] ). This can generate an error when used in YANG files, like the following:
org.opendaylight.yangtools.yang.parser.spi.source.SourceException: Argument "(count(..[pce]) = 1)" is not valid XPath string [at C:\cisco xe
    1691\Cisco-IOS-XE-mpls.yang:698:7]

Fix: To fix this syntax error, rewrite the container name without square brackets preceded by a forward slash.

In the example error above, you can rewrite 
when "(count(..[pce]) = 1)";
as 
when "(count(../pce) = 1)";

Once the syntax error is resolved, regenerate the binding JAR files and use them in the RESTCONF Network Discovery and UIM Integration cartridge.