A cartridge is a vendor-specific implementation of a set of services for a given family of device types running the same operating system. A cartridge is a set of files (shipped as a .jar file) used by the IP Service Activator Network Processor to implement these services.

Cartridges provide the required components for configuration to flow from the service model to the device for a particular service. The transforms required for the Network Processor to take the configuration from service model to device model, and annotated device model to CLI are included in the cartridge.

Cartridge components include:

• Device Model schema definition

• Service Model to Device Model transform

• Device Model validation

• Annotated Device Model to CLI transform

• Message (success/warning/error) pattern definitions

• Options definitions

• Audit command definitions

• Capabilities definitions

• Logging configuration

• Re-usable (shared library) definitions

• Java beans

• Uninstall information

Cartridges are built from a collection of source files generated by the SDK, which you then customize to implement the desired services.

Cartridge source files include:

• .xsd schema definition files

• .xml instance data files

• .xq (xQuery transformations) or .java (Java transformations)

There are two main types of cartridge: base and service cartridges.

Base cartridges provide a framework for allowing the Network Processor to perform basic communication functions with a device. These functions include logging in and out of the device, sending commands or configlets, performing audits, and interpreting responses from the device as successes, warnings, or failures.

Base cartridges do not contain implementations of services. Additional services targeting specific vendor device types are added through integrated service cartridges.

Refer to IP Service Activator SDK Base Cartridge Developer Guide for details about creating base cartridges.

A service cartridge provides the implementation of a logical service, such as a static route policy, for a specific vendor. The service cartridge also provides the ability to send commands related to its logical service. The service cartridge is also responsible for providing the necessary information to audit and interpret success, warning, or failure responses for commands it sends.

You can use the SDK to create service cartridges. Service cartridges are not independently deployable — they must be deployed as extensions to either a base or a core cartridge.

Refer to IP Service Activator SDK Service Cartridge Developer Guide for details about creating service cartridges.

A configuration policy provides a GUI form and a schema to collect data for a service. Configuration policies require service cartridges to implement the service on specific devices.

Refer to IP Service Activator SDK Configuration Policy Extension Developer Guide for details about creating configuration policies.

Cartridges are identified to the IP Service Activator Network Processor through registry files.

When the Network Processor starts up, it loads all the cartridge registries and internally creates a map of which cartridges administer which devices. Therefore, when a device is edited in the IP Service Activator client, the correct cartridge to administer that change can be called.

The driver type, device type and operating system version attributes in the registry entry allow the Network Processor to map particular devices to a cartridge. When a service, which a cartridge supports, is applied to a device, the Network Processor determines the correct cartridge to use to configure the service based on this registration.

The cartridge operation support files are identified to the Network Processor as entries in the registry files. These files are discussed in Cartridge Overview.

The registry files that identify cartridges to the Network Processor include:

• MIPSA_registry.xml: core cartridge registry file

• Registry.xml: base cartridge registry file

• Extension.xml: service cartridge registry file

• Customization.xml: registry file used to override certain entries in the Registry.xml or Extension.xml files. These are typically placed in Service_Activator_home\Config\networkProcessor\Custom\Registries.

• ConfigPolicyRegistry.xml: registry information for the configuration policy used to integrate it with a service cartridge.

  Note:

  The Network Processor will detect and process any files ending in .xml from this directory.

The Registry.xml file identifies a base cartridge instance to the Network Processor and further indicates when the resources provided by that cartridge (i.e. transforms, validation script) are to be invoked.

A sample Registry.xml follows:

<?xml version="1.0" encoding="UTF-8"?>
<registry 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://www.metasolv.com/service activator/networkprocessor/cartridgeregistry/"
  xmlns:cs="http://www.metasolv.com/service activator/networkprocessor/cartridgesubscription/">

  <cartridge>
    <name>cisco</name>
    <driverType>cisco</driverType>
    <transforms>
      <smToDm>com/metasolv/service activator/cartridges/cisco/transforms/sm2dm.xq</smToDm>
      <dmValidation>com/metasolv/service activator/cartridges/cisco/transforms/dmValidation.xq</dmValidation>
      <dmToCli>com/metasolv/service activator/cartridges/cisco/transforms/annotatedDm2Cli.xq</dmToCli>
    </transforms>
    <audit>
      <auditTemplate>
        <auditTemplateEntry>
          <auditTemplateFile>com/metasolv/service activator/cartridges/cisco/audit/auditTemplate.xml</auditTemplateFile>
            <appliesTo>
            <deviceTypes useRegex="true">Cisco.*</deviceTypes>
            <osVersions useRegex="true">.*</osVersions>
          </appliesTo>
        </auditTemplateEntry>                
      </auditTemplate>
    </audit>
    <messages>
      <success>com/metasolv/service activator/cartridges/cisco/messages/successMessages.xml</success>
      <warning>com/metasolv/service
activator/cartridges/cisco/messages/warningMessages.xml</warning>
      <error>com/metasolv/service activator/cartridges/cisco/messages/errorMessages.xml</error>
    </messages>
    <capabilities>
      <capabilitiesEntry>
        <capsFile>com/metasolv/service activator/cartridges/cisco/capabilities/empty_caps.xml</capsFile>
          <appliesTo>
            <deviceTypes useRegex="true">Cisco.*</deviceTypes>
            <osVersions useRegex="true">.*</osVersions>
          </appliesTo>
        </capabilitiesEntry>
      </capabilities>
    <options/>
  <commandExecutor>com.metasolv.service activator.networkprocessor.DefaultCommandExecutor</commandExecutor>
  </cartridge>
</registry>

The relevant sections are:

• Name: uniquely identifies a base cartridge instance

• DriverType: identifies to which family of devices this cartridge instance is applicable. The driverType value must be unique in an IP Service Activator Network Processor installation. For example, if a base cartridge is deployed to a Network Processor installation with an existing IP Service Activator core cartridge deployed, the driverType values must be different. The same is true if an additional base cartridge is deployed. The following driverType values are already assigned to existing core cartridges: Cisco, Huawei, Juniper, and CatOS. When base cartridge source files are generated, <sdk_global_deviceName> is assigned a lowercase version of <driverType> from the Registry.xml file. See the IP Service Activator online Help for further information.

• Transforms: identifies the location of transform and validation files

• Audit: identifies the location of the audit files. Indicates when an audit file is applicable using the appliesTo element, which specifies deviceType and osVersion characteristics.

• Messages: identifies locations of the success, warning and error message pattern files

• Capabilities: identifies the location of the capabilities file and indicates when this file is applicable, using the appliesTo element

• Options: identifies the location of the options file and indicates when this file is applicable, using the appliesTo element

• CommandExecutor: identifies the package location of the command executor

The above registry would apply to any device with the driver type cisco. The audit template specified will apply to any device types that begin with Cisco and any OS version because of the wildcard entry ‘.*'.

The Extension.xml file identifies a service cartridge instance to the Network Processor and indicates when the resources provided by that cartridge (i.e. transforms, validation scripts) are to be invoked.

A sample Extension.xml follows:

<?xml version="1.0" encoding="UTF-8"?>
<registry 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.metasolv.com/service activator/networkprocessor/cartridgeregistry/"
    xmlns:cs="http://www.metasolv.com/service activator/networkprocessor/cartridgesubscription/">
    <extension>
      <name>ciscoBanner</name>
      <subscriptions>
        <cs:configPolicyContentTypeList>
          <cs:configPolicyContentType>banners</cs:configPolicyContentType>
        </cs:configPolicyContentTypeList>
      </subscriptions>
      <transforms>
        <smToDm>com/metasolv/service activator/cartridges/ciscobanner/transforms/sm2dm.xq</smToDm>
        <dmValidation>com/metasolv/service activator/cartridges/ciscobanner/transforms/dm-validation.xq</dmValidation>
        <dmToCli>com/metasolv/service activator/cartridges/ciscobanner/transforms/annotated-dm2cli.xq</dmToCli>
        <dmMigration>com/metasolv/service activator/cartridges/ciscobanner/xquerylib/dm-migration.xq</dmMigration>
      </transforms>
      <audit>
        <auditTemplate>
          <auditTemplateEntry>
            <auditTemplateFile>com/metasolv/service activator/cartridges/ciscobanner/audit/auditTemplate.xml</auditTemplateFile>
            <appliesTo>
            <deviceTypes useRegex="true">Cisco.*</deviceTypes>
              <osVersions useRegex="true">.*</osVersions>
            </appliesTo>
          </auditTemplateEntry>								
        </auditTemplate>
      </audit>
      <messages>
        <success>com/metasolv/service activator/cartridges/ciscobanner/messages/successMessages.xml</success>
        <warning>com/metasolv/service activator/cartridges/ciscobanner/messages/warningMessages.xml</warning>
        <error>com/metasolv/service activator/cartridges/ciscobanner/messages/errorMessages.xml</error>
      </messages>
    </extension>
</registry>

The relevant sections are:

• Name: uniquely identifies a service cartridge instance

• Subscriptions: identifies a list of policy types that this cartridge will administer. In this case, this service cartridge provides an implementation of the banners configuration policy for cisco devices.

• Transforms: identifies the location of transform and validation files

• Audit: identifies the location of the audit files. Indicates when an audit file is applicable using the appliesTo element, which specifies deviceType and osVersion characteristics.

• Messages: identifies locations of the success, warning and error message pattern files

• Capabilities: identifies the location of the capabilities file and indicates when this file is applicable, using the appliesTo element

• Options: identifies the location of the options file and indicates when this file is applicable, using the appliesTo element

• VrfReductionStrategy: identifies location of a specific strategy file

A service cartridge extends a base cartridge by its placement in a child directory of the base cartridge called ServiceCartridges. The service cartridge does not contain an explicit reference indicating which base cartridge it extends.

The audit template specified in the example will apply to any device types that begin with 'Cisco' and any OS version because of the wildcard entry ‘.*'.

<subscriptions>
  <cs:definitionTypeList>
    <cs:definitionType>PolicingRuleDefinitionType</cs:definitionType>
  </cs:definitionTypeList>
</subscriptions>

. . .
  <subscriptions>
    <cs:configPolicyContentTypeList>
      <cs:configPolicyContentType>bannerSample</cs:configPolicyContentType>
    </cs:configPolicyContentTypeList>
  </subscriptions>
. . .

The ConfigPolicyRegistry.xml file identifies a configuration policy instance to the Network Processor.

A sample ConfigPolicyRegistry.xml looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<config_policy_registration
        xmlns="http://www.metasolv.com/serviceactivator/configurationpolicy">
    <name>bannersSample</name>
    <version>1.0</version>
</config_policy_registration>

The relevant sections are:

• Name: unique name to identify the policy

• Version: version number of this policy to distinguish this policy for upgrade purposes

The configuration policy is the GUI that the user would see. The administration of that GUI is handled within the service cartridge. So a given ConfigPolicyRegistration is only functional if there is a service cartridge that administers that config policy.