Vendor Certification XML Structure

A vendor certification uses XML to map vendor- and device-specific data to performance metrics and configuration data that are defined in a metric family. Mapping this data from various sources to the "normalized" metric family values helps Data Aggregator uniformly report on this data, regardless of the device vendor.
capm350
HID_Vendor_Cert_XML_Structure
A vendor certification uses XML to map vendor- and device-specific data to performance metrics and configuration data that are defined in a metric family. Mapping this data from various sources to the "normalized" metric family values helps Data Aggregator uniformly report on this data, regardless of the device vendor.
When you extend a vendor certification, do not edit restricted tags or attributes. For more information, see Restricted XML Tags.
2
Example:
This example of a custom vendor certification XML supports Frame-Relay PVC. The example custom metric family, frPVCInfo, is included in the ExpressionGroup section:
If you view the vendor certification XML in a browser, certain tags are hidden. For this reason, copy and paste the vendor certification XML only from a REST client
<?xml version="1.0" encoding="UTF-8" ?> 
<!-- Auto-generated by the type catalog local manager.--> 
<DataModel namespace="http://im.ca.com/certifications/snmp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="SNMPCertificationFacet.xsd"> 
  <Author>Custom</Author>
  <Version>1.0</Version>
  <FacetType name="frPVCInfoCustom" descriptorClass="com.ca.im.core.datamodel.certs.CertificationFacetDescriptorImpl"> 
    <Documentation>Frame Relay PVC Vendor Certification</Documentation> 
    <FacetOf namespace="http://im.ca.com/core" name="Item" /> 
    <AttributeGroup name="AttributeGroup" external="true" list="true"> 
      <Documentation /> 
      <Attribute name="INDEX" type="ObjectID"> 
      <Documentation /> 
      <Source>1.3.6.1.2.1.10.32.2.1.4</Source> 
      <IsIndex>true</IsIndex> 
      <IsKey>false</IsKey> 
      <NeedsDelta>false</NeedsDelta> 
    </Attribute> 
    <Attribute name="frCircuitReceivedBECNs" type="Long"> 
      <Documentation /> 
      <Source>1.3.6.1.2.1.10.32.2.1.5</Source> 
      <IsIndex>false</IsIndex> 
      <IsKey>true</IsKey> 
      <NeedsDelta>true</NeedsDelta> 
    </Attribute> 
    <Attribute name="frCircuitSentFrames" type="Long"> 
      <Documentation /> 
      <Source>1.3.6.1.2.1.10.32.2.1.6</Source> 
      <IsIndex>false</IsIndex> 
      <IsKey>true</IsKey> 
      <NeedsDelta>true</NeedsDelta> 
    </Attribute> 
    <Attribute name="frCircuitSentOctets" type="Long"> 
      <Documentation /> 
      <Source>1.3.6.1.2.1.10.32.2.1.6</Source> 
      <IsIndex>false</IsIndex> 
      <IsKey>true</IsKey> 
      <NeedsDelta>true</NeedsDelta> 
    </Attribute> 
    <Attribute name="frCircuitReceivedFrames" type="Long"> 
      <Documentation /> 
      <Source>1.3.6.1.2.1.10.32.2.1.8</Source> 
      <IsIndex>false</IsIndex> 
      <IsKey>true</IsKey> 
      <NeedsDelta>true</NeedsDelta> 
    </Attribute> 
    <Attribute name="frCircuitReceivedOctets" type="Long"> 
      <Documentation /> 
      <Source>1.3.6.1.2.1.10.32.2.1.9</Source> 
      <IsIndex>false</IsIndex> 
      <IsKey>true</IsKey> 
      <NeedsDelta>true</NeedsDelta> 
    </Attribute> 
  </AttributeGroup> 
  <Protocol>SNMP</Protocol> 
  <DisplayName>Frame Relay PVC Certification</DisplayName> 
  <Expressions> 
    <ExpressionGroup destCert="{http://im.ca.com/normalizer}
frPVCInfo
" name="frPVCInfoDS"> 
      <Expression destAttr="Indexes">INDEX</Expression> 
      <Expression destAttr="Names">"Frame Relay " + INDEX</Expression> 
      <Expression destAttr="FECNIn">frCircuitReceivedFECNs</Expression> 
      <Expression destAttr="BECNIn">frCircuitReceivedBECNs</Expression> 
      <Expression destAttr="FramesIn">frCircuitReceivedFrames</Expression> 
      <Expression destAttr="FramesOut">frCircuitSentFrames</Expression> 
      <Expression destAttr="BytesIn">frCircuitReceivedOctets</Expression> 
      <Expression destAttr="BytesOut">frCircuitSentOctets</Expression> 
    </ExpressionGroup> 
  </Expressions> 
  <MIB>RFC1315-MIB</MIB> 
 </FacetType> 
</DataModel>
Basic Properties
The basic properties of your custom vendor certification help to distinguish it from other custom vendor certifications you create. Also, these properties indicate from which vendor MIB you are collecting metric data.
Consider the following restrictions when you determine basic properties:
  • The FacetType/name and FacetType/DisplayName properties must be unique for each vendor certification.
  • The Protocol tag is either SNMP or EMS.
    • /typecatalog/certifications/snmp
       support only SNMP certifications. In this case, the only value that is supported is SNMP.
    • /typecatalog/certifications/camm
       support only CAMM certifications. In this case, the only value that is supported is EMS.
  • Set the FacetType/descriptorClass property and all DataModel and FacetOf properties as shown in the example XML in the previous illustration.
  • FacetType/name
    Uniquely identifies a vendor certification.
    Recommendation:
    Conform to "<MibName><TableName>Mib."
    Can be updated:
    No
    Possible values:
    Alphanumeric and underscore. Dot and dash are not permitted.
The FacetType section manifests a particular vendor certification. The same XML document can contain multiple FacetType sections when those vendor certifications expose various aspects of the vendor-specific device such as TCP and UDP statistics from a MIB-2 implementation.
The FacetType section contains some basic properties. For example, this section contains the name of the vendor MIB, followed by one or more AttributeGroup sections. These AttributeGroup sections define which attributes this certification uses from the MIB. One or more ExpressionGroup sections map attributes from the AttributeGroup sections to the metrics specified in a metric family.
All of the following items can be updated and support plain text.
  • FacetType/Documentation
    Describes what is certified with the vendor certification.
    Recommendation:
    Include the details about the vendor, MIB name, and table name.
    Effect of updating:
    None
  • FacetType/MIB
    Specifies the name of the MIB, which the DEFINITIONS clause defines in the ASN.1 file.
    Recommendation:
    Conform to "<MibName>”
    Effect of updating:
    Change to the “SNMP MIB Name” column in the Vendor Certification tab of the Administrator user interface.
    When does the update take effect:
    Immediately
    Required actions for updates to take effect:
    Refresh the user interface.
  • FacetType/DisplayName
    Specifies the name of the vendor certification as it displays in CA
    Performance Center
    .
    Recommendation:
    Start with the vendor name and include the MIB and functionality information.
    Effect of updating:
    A change to the name in the Administrator user interface.
    When does the update take effect:
    Immediately
    Required actions for updates to take effect:
    Refresh the user interface.
    Ensure that the DisplayName property is unique to the vendor certification.
AttributeGroup
The following example illustrates the AttributeGroup section of your custom vendor certification. This section identifies the attributes (variable OIDs) of a particular table in the vendor MIB that are used to map raw device data. This data is mapped to the performance metrics and the configuration data that is defined in a metric family.
You set the AttributeGroup/list and AttributeGroup/external properties to true, as shown in the example XML in the previous illustration. These properties specify that each attribute represents a list of values that is obtained from an external source (a MIB table). The following information summarizes the XML elements to customize. 
All of the following items can be updated and support plain text. The update does not affect performance.
  • AttributeGroup/name
    Specifies the attribute group name.
    Recommendation:
    Conform to "<FacetType/name>Group."
  • Documentation
    (Optional) Specifies the description for the attribute group.
  • UseIndex
    Specifies the name of the attribute to be used as the index for this attribute group for joining multiple MIB tables.
    Recommendation:
    Set to the value of the AttributeGroup/name property.
General Attributes
The general attributes for all vendor certifications are as follows:
Unless specified otherwise, the update takes effect immediately and no actions are required to trigger the update. All entries in this list can be updated.
  • Attribute/name
    Specifies the attribute name.
    Recommendation:
    Set to the MIB variable name, which the OBJECT-TYPE clause defines in the ASN.1 file.
    Possible values:
    Alphanumeric and underscore. Dot and dash are not permitted.
    Effect of updating:
     Update any expressions that reference this attribute.
  • Attribute/type
    Specifies the data type of the attribute.
    Recommendation:
    Use the attribute type that best matches the variable type that the SYNTAX clause defines in the ASN.1 file.
    Possible values:
    Boolean, Int, Long, Double, BigInteger, String, DateTime, IPAddress, MACaddress, IPSubnet, OctetString, ObjectID
    Effect of updating:
    Polled SNMP data is converted to this type.
    When does the update take effect:
    Next poll
  • Documentation
    (Optional) Specifies the description for the attribute, which documents the semantics (such as the unit) of the MIB variable.
    Recommendation:
    Use the descriptions that are taken from the MIB ASN.1 file.
    Possible values:
    Plain text
    Effect of updating:
    None
  • IsKey
    (Optional) Uses a flag to indicate whether the MIB variable is key for determining support for a table. When multiple fields are specified as keys, all of the fields are considered together as a compound key.
    You cannot use
    IsKey
    and
    VCSupportExpression
    in the same vendor certification. Vendor certifications that contain both
    IsKey
    and
    VCSupportExpression
    do not discover anything.
    Default:
    false
    Recommendation:
    Set to true if it is a key MIB object for component discovery. If the contents of the MIB attributes are necessary to determine support, use
    VCSupportExpression
    instead.
    Possible values:
    true, false
    Effect of updating:
    Components could change to a new vendor certification.
    When does the update take effect:
    After component rediscovery.
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
  • IsIndex
    (Optional) Uses a flag to indicate whether this variable is an index to the MIB table.
    Default:
    false
    Recommendation:
    Set to true for an index attribute.
    Possible values:
    true, false
    Effect of updating:
    Component indexing could change.
    When does the update take effect:
    After component rediscovery.
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
  • NeedsDelta
    (Optional) Uses a flag to indicate whether to delta (that is, store the difference between current and last poll for Counters) the MIB variable.
    Default:
    false
    Recommendation:
    Set to true if the variable is defined as a Counter, Counter32, Counter64, or TimeTicks quantity in the MIB.
    Possible values:
    true, false
    Effect of updating:
    The polled data changes.
    When does the update take effect:
    Next poll
  • Source
    Specifies the ObjectID of the attribute.
    Recommendation:
    Set to the fully qualified MIB variable OID that the OBJECT-TYPE defines.
    Possible values:
    Dot-separated numbers (for example, 1.3.6.1.4.1…)
    Effect of updating:
    Data is polled from the specified OID.
    When does the update take effect:
    Next poll
  • Version
    Specifies the version of the vendor certification. Update this attribute when you update the certification. You cannot decrease the Version value.
    Possible values:
    Floating point or decimal number Example: 1.0 or 1.01
  • Author
    Specifies the creator of the vendor certification.
    Default:
    "Custom"
    Possible values:
    Any alphanumeric string.
    Effect of updating:
    The author attribute is updated.
  • UsesDynamicIndex
    (Optional) Enables dynamic ObjectID values for IPSLA polling.
    Default:
     False
    Possible
    values
    : true, false
     
The list of attributes specifies the set of data that a metric family collects when supported by this vendor certification. Typically, this data falls into two categories:
  • Configuration data of the device component (such as name or indexes) that is collected only at discovery time.
  • Performance data that is collected every poll cycle.
Configuration Data Attributes
An attribute with the name INDEX and type ObjectID is mapped to the Indexes attribute of the target metric family. You can set the value for the Source tag to any variable OID. However, you typically use one of the variables that are listed in the INDEX clause of the table. For example, consider ifIndex in the interfaces table of MIB-2. This variable serves as the index for the other variables in the same MIB table. In addition, the
IsIndex
tag (and typically also the
IsKey
tag) for this attribute is set to true.
In this example, attributes such as ifDesc or ifType provide more configuration information about an interface. Therefore, these attributes are useful for the Names and Description attributes of the target metric family.
Performance Data Attributes
These attributes provide the raw data for performance metrics in the target metric family. Consider the following points:
  • You can directly map one of these attributes to a metric family performance metric, or
  • You can use the attribute in an expression with other attributes to compute a value for the metric.
ExpressionGroup
The ExpressionGroup maps attributes as follows:
  • From the AttributeGroup (that defines how to get a metric from an SNMP MIB)
  • To the metrics specified in a metric family (that defines how an attribute is stored in the database)
You can store a MIB value in the database as it is received from the device or after some normalization operations are performed. For example, normalization operations include dividing or multiplying with 1024 to transform to/from kilobytes.
Unless specified otherwise, the update takes effect immediately and no actions are required to trigger the update. All entries in this list can be updated.
  • ExpressionGroup/name
    (Optional) Specifies the expression group name.
    Possible values:
    Plain text
    Effect of updating:
    None 
  • ExpressionGroup/destCert
    Specifies the metric family that contains the destAttrs to populate.
    Possible values:
    Any valid metric family
    Effect of updating:
    Changes the permissible expression destAttr.
  • ExpressionGroup/Filter
    (Optional) Specifies which components are discovered. Using the Filter reduces the number of components that are managed.
    The expression group filter 
    does not
    exclude the specified components. The filter selects the specified components and excludes components that do not match the criteria.
    Possible values:
    Boolean MVEL expression using available Attributes
    Effect of updating:
    Changes which components are discovered.
    When does the update take effect:
    After component rediscovery.
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
  • VariableGroup
    Defines variables that are used in the ExpressionGroup.
    Possible Values:
    Calculated vendor certification values.
    Effect of updating:
    Changes which components are discovered.
    When does the update take effect:
    After component rediscovery.
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
    The Juniper and Cisco/Standard High Speed Interface vendor certifications include the UtilizationMaxPercent variable. This variable defines the percentage at which to drop the data for the utilization metric. Dropped data preserves the integrity of rollup data for the interface and results in a gap in views and reports.
  • VCSupportExpression
    (Optional) Extracts and calculates the MIB attribute values to determine whether the VC is supported.
    You cannot use
    IsKey
    and
    VCSupportExpression
    in the same vendor certification. Vendor certifications that contain both
    IsKey
    and
    VCSupportExpression
    do not discover anything.
    Possible values:
    Boolean MVEL expression using available Attributes
    Effect of updating:
    Changes which components are discovered.
    When does the update take effect:
    After component rediscovery.
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
  • Expression
    Converts vendor certification attribute values to normalized attribute values.
    Possible values:
    Normalized attribute value
    Effect of updating:
  • SetExpression
    Converts normalized attribute values to vendor certification attribute values.
    Possible values:
    Vendor certification attribute value
    Effect of updating:
    Changes which components are discovered.
    When does the update take effect:
    After component rediscovery.
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
ExpressionGroup Filter Examples
Filters limit the device components that a vendor certification discovers and polls. Discovery occurs only if all the criteria in the filter are true. If any of the specified attributes in the filter criteria cannot be evaluated for a given component, the component is discovered because the complete filter criteria could not be evaluated. The most common reason an attribute cannot be evaluated is that the component has no value for that attribute.
Example 1:
<Filter>(ifType!=24) &amp;&amp; (ifType!=1)</Filter>
CA Performance Management
does not poll the device component if the ifType value is 1 or 24. Interfaces with no value for ifType are discovered and polled.
Example 2:
<Filter> hrStorageType.toString() == "1.3.6.1.2.1.25.2.1.4" &amp;&amp; 
         hrStorageSize != 0
</Filter>
CA Performance Management
discovers and polls the device component if the the StorageType is hrStorageFixedDisk (1.3.6.1.2.1.25.2.1.4) and the size is not 0. However, if a component has no value for the hrStorageSize, that component is discovered. If this behavior is not intended, extend the filter to use the
isdef
function to verify that the attribute has a valid value.
<Filter> hrStorageType.toString() == "1.3.6.1.2.1.25.2.1.4" &amp;&amp; 
        
isdef (hrStorageSize)
&amp;&amp; hrStorageSize != 0
</Filter>
CA Performance Management
discovers and polls the device component if the the StorageType is hrStorageFixedDisk and the size is not 0. Only components with a specified value for hrStorageSize are discovered and polled.
Example 3:
<Filter> (rttMonCtrlAdminRttType==9) &amp;&amp; 
         ( !(rttMonCtrlAdminOwner.toString() contains "Network Health") )
</Filter>
CA Performance Management
discovers and polls the device component if the rttMonCtrlAdminRttType is 9 and the rttMonCtrlAdminOwner.toString does not contain Network Health.
Expression/destAttr Metrics
The following information describes the Expression/destAttr metrics. You can update all of these metrics:
Unless specified otherwise, the update takes effect immediately and no actions are required to trigger the update.
  • Indexes
    Specifies to use the vendor certification attributes of the ObjectID to define the MVEL expression to provide the value for the Indexes metric family attribute.
    Recommendation:
    Set to INDEX.
    Possible values:
    Any attribute that has <IsIndex>true</IsIndex>.
    Effect of updating:
    Component indexing could change.
    When does the update take effect:
    After component rediscovery
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
  • Names
    Specifies to use the vendor certification attributes to collect configuration data. This configuration data helps define the MVEL expression to provide the value for the Names metric family attribute.
    Recommendation:
    Include as much information as necessary to identify an instance uniquely.
    Possible values:
    String MVEL expression using available Attributes
    Effect of updating:
    Component name change
    When does the update take effect:
    After component rediscovery
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
  • Descriptions
    (Optional) Specifies to use the vendor certification attributes to collect configuration data. This configuration data helps define the MVEL expression to provide the value for the Descriptions metric family. Not all metric families support a Descriptions attribute.
    Recommendation:
    Include as much information that is available to describe an instance.
    Possible values:
    String MVEL expression using available Attributes
    Effect of updating:
    Component description change
    When does the update take effect:
    Component rediscovery
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
  • Other Metrics
    Specifies to use the vendor certification attributes to collect configuration or performance data. This data is used to define the MVEL expression to provide the value for the metric family attribute.
    Can be added:
    Yes, if the destAttr exists in the metric family.
    Possible values:
    MVEL expression using available Attributes, producing a value that matches the type of the destination attribute.
    Effect of updating:
    Polled value changes
    When does the update take effect:
    Next poll
The metric family exposes URIs (such as, {http://im.ca.com/normalizer}
FamilyName
.
AttributeName
), which are separately referred to in the ExpressionGroup. The ExpressionGroup/destCert property is set to the URI (for example, {http://im.ca.com/normalizer}
FamilyName
)
,
and the Expression/destAttr is set to
AttributeName
.
Speed Override
Vendor certifications for interfaces include variables in the ExpressionGroup that can override the SpeedIn and SpeedOut values. The SpeedInOverride and SpeedOutOverride variables let you override the SpeedIn and SpeedOut values in the UI. The following example shows how to use the override variables:
<VariableGroup>
   <Variable name="SpeedInOverride" providedBy="override"/>
   <Variable name="SpeedOutOverride" providedBy="override"/>
   <Variable name="RawIfSpeed">ifSpeed</Variable>
   <Variable name="CalculatedSpeedIn">
      isdef(SpeedInOverride) ? SpeedInOverride : RawIfSpeed
   </Variable><Variable name="CalculatedSpeedOut">
      isdef(SpeedOutOverride) ?  SpeedOutOverride : RawIfSpeed
   </Variable>
   <Variable name="CalculatedIfInOctets">ifInOctets <= 786432000 ? ifInOctets : null</Variable>
   <Variable name="CalculatedIfOutOctets">ifOutOctets <= 786432000 ? ifOutOctets : null</Variable>
</VariableGroup>
HierarchyList
The following list defines the hierarchy behavior:
For these items, the following criteria apply to all: 
  • All entries in this list can be updated.
  • The update changes the hierarchy construction.
  • The update takes effect after component rediscovery
  • For the updates to take effect, update the metric family or change the vendor certification priority.
  • Hierarchy/ParentFacet
    Specifies the QName of the facet that is used to find the candidate parent items.
    Possible values:
    Any valid facet
  • Hierarchy/ParentAttribute
    Specifies the QName of the attribute that is used to identify the specific parent item.
    Possible values:
    Any valid attribute QName
  • Hierarchy/ChildAttribute
    Specifies the QName of the attribute on the child item that is used to match the ParentAttribute on the parent item.
    Possible values:
    Any valid attribute QName
IndexTagList
To poll attributes from multiple MIB tables, we need an attribute group per MIB table containing these attributes. The index tag list provides a mechanism to relate two attribute groups (or MIB tables) with different indexes. The groups are related such that one item (row) of one table is linked to a corresponding row in a second table.
For these items, the following criteria apply to all: 
  • All entries in this list can be updated.
  • The update changes indexing.
  • The update takes effect after component rediscovery
  • For the updates to take effect, update the metric family or change the vendor certification priority.
  • PrimaryTag
    References the primary Attribute group (that is, the group that defines an index attribute with the ObjectID type). The value of this element must equal the 'UseIndex' tag of the attribute group for the primary group.
    Possible values:
    The ‘UseIndex’ tag of the attribute group corresponding to the primary attribute group.
  • IndexTag
    Defines how to relate rows of the primary group (or MIB table) to rows in the secondary group. This element relates the rows by specifying attributes of both groups that must match.
  • IndexTag/Name
    References the secondary group (or MIB table). The value of this element must equal the 'UseIndex' tag of the secondary attribute group that you are trying to relate with the primary one.
    Possible values:
    The ‘UseIndex’ tag of the secondary attribute group.
  • IndexTag/PrimaryKeyExpression
    Specifies an MVEL expression containing attributes of the primary attribute group or an attribute group corresponding to any of the previously defined IndexTag. The calculated value is matched up with the 'ThisTagKeyExpression'. If there is a match, the rows of both attribute groups (or MIB tables) are linked. Then, these attributes can be used together in an 'Expression' backing a destAttr (or Metric).
    Possible values:
    A valid MVEL expression
  • IndexTag/ThisTagKeyExpression
    Specifies an MVEL expression containing attributes of the secondary attribute group. The calculated value is matched up with the 'PrimaryKeyExpression'. If there is a match, the rows of both groups (or MIB tables) are linked. Then, these attributes can be used together in an 'Expression' backing a destAttr (or Metric).
    Possible values:
    A valid MVEL expression