Extended attributes

In the old Common Data Model, extended attributes were used to manually define up to 100 attributes per CDM type to store the data. They were used to extend CDM types with attributes out of domain, for example server room number, and to expand the scope of the discovery of CIs. In the new Simplified Model, extended attributes are used to store all simple attributes of CDM classes that were previously present in the types lower in hierarchy.

For example, in the old model, the ExchangeServer type had the productID attribute of the string type defined. In the new model, the ExchangeServer type is stored in the following way:
SSoftwareServer sr = ModelFactory.newInstance(SSoftwareServer.class);
sr.setHierarchyDomain("app.messaging.exchange");
sr.setHierarchyType("Exchange");
sr.setOpenId(new OpenId().addId("serverName", "Exchange1122"));
The productID attribute cannot be stored because the SSoftwareServer type stores only essential attributes and cannot be extended. The extended attributes allow for storing such specific attributes.

Data model type

The following changes are introduced in the new data model:
  • Extended attributes are stored along with the CIs in the XA attribute of a new custom type ExtendedAttributesData. The data that is kept in separate objects of the UserData type is migrated into the XA attribute.
  • The limitation to store up to 100 attributes per CDM type was removed. The number of attributes that can be stored into a single object depends on the capacity of the database XML column type. Also, the -g option of the bulk load program can be used to store extended attributes.
  • Extended attributes have categories. If no category is selected, an attribute is stored in the default General category. All extended attributes present in the old data model were moved into the default General category.
  • Old attribute byte[] extendedAttributes is kept only to ensure compatibility with earlier versions and is deprecated. Public API methods setExtendedAttributes and getExtendedAttributes are deprecated as well.

Viewing extended attributes

After you run a discovery of a sensor, for which you specified the XA attribute, you can view extended attributes in Data Management Portal. Open the Details pane of a discovered object. There is no longer Extended Attributes tab, the information about extended attributes of the default category is displayed on the General tab. The extended attributes of a custom category are displayed on a custom tab. For example, extended attributes of Markers category are displayed on the Markers tab.

Example of usage in a sensor

The following example shows the ExtendedAttributesData type that is used to store extended attribute or attributes with a CI. The productID attribute is kept in a default category. A new category for physical location of a software server is created.
  SSoftwareServer sr = ModelFactory.newInstance(SSoftwareServer.class);
  sr.setHierarchyDomain("app.messaging.exchange");
  sr.setHierarchyType("Exchange");
  sr.setOpenId(new OpenId().addId("serverName", "Exchange1122"));

  ExtendedAttributesData xa = new ExtendedAttributesData();
  xa.addAttribute("productID", "ID12021");
  xa.addAttribute("Location", "buildingNo", "North23");
  xa.addAttribute("Location", "floorNo", "3");
  xa.addAttribute("Location", "roomNo", "15");
  xa.attachTo(sr);
Notes:
  • In TADDM 7.3.0, and 7.3.0.1, you can use two methods to store extended attributes. One of them is attachTo, and it is used in the preceding example. This method must be specified after all addAttribute() entries. The alternative way is to use the setXA method, for example:
      xa.addAttribute("Location", "roomNo", "15");
  xa.toXML();
  sr.setXA(xa);
    If you use the setXA method, you must also specify the toXML method to convert extended attributes into a layout that can be stored.
  • Fix Pack 2In TADDM 7.3.0.2, there is no difference between the attachTo, and the setXA methods. Neither of them requires using the toXML method.
The following attribute map is stored:
hierarchyType -> Exchange
isPlaceholder -> false
openId -> <openId><id><name>servername</name><value>Exchange1122</value></id></openId>
hierarchyDomain -> app.messaging.exchange
XA -> <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
  <attribute name="productID" category="taddm_global">ID12021</attribute>
  <attribute name="buildingNo" category="Location">North23</attribute>
  <attribute name="floorNo" category="Location">3</attribute>
  <attribute name="roomNo" category="Location">15</attribute>
</xml>

Partial update

A CI can be stored with the same naming rules values from different data sources, and as a result the values are merged into one object. To prevent that, partial update mechanism is used to merge two different XML-formatted XA attributes. For example, if one source is stored with object 1, and another source is stored with object 2, a CI that holds the merged attribute is created.
Object 1
SSoftwareServer sr = ModelFactory.newInstance(SSoftwareServer.class);
sr.setHierarchyDomain("app.messaging.exchange");
sr.setHierarchyType("Exchange");
sr.setOpenId(new OpenId().addId("serverName", "Exchange1122"));

ExtendedAttributesData xa = new ExtendedAttributesData();
xa.addAttribute("productID", "ID12021");
xa.addAttribute("internal", "ID1233");
xa.addAttribute("Location", "buildingNo", "North23");
xa.attachTo(sr);
Object 2
SSoftwareServer sr = ModelFactory.newInstance(SSoftwareServer.class);
sr.setHierarchyDomain("app.messaging.exchange");
sr.setHierarchyType("Exchange");
sr.setOpenId(new OpenId().addId("serverName", "Exchange1122"));

ExtendedAttributesData xa = new ExtendedAttributesData();
xa.addAttribute("productID", "ID12024");
xa.addAttribute("customID", "ID12333");
xa.addAttribute("Location", "floorNo", "3");
xa.addAttribute("Location", "roomNo", "15");
xa.attachTo(sr);
Merged attribute
hierarchyType -> Exchange
isPlaceholder -> false
openId -> <openId><id><name>servername</name><value>Exchange1122</value></id></openId>
hierarchyDomain -> app.messaging.exchange
XA -> <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
  <attribute name="customID" category="taddm_global">ID12333</attribute>
  <attribute name="internal" category="taddm_global">ID1233</attribute>
  <attribute name="productID" category="taddm_global">ID12024</attribute>
  <attribute name="buildingNo" category="Location">North23</attribute>
  <attribute name="floorNo" category="Location">3</attribute>
  <attribute name="roomNo" category="Location">15</attribute>
</xml>
All not overlapping attributes from the first object and the second object are present with their values in the merged attribute and the productId attribute has a value from the object that was stored as last. When the XA attribute of any model object is partially updated, both category type and attribute name are included in the process.

Cache for metadata and validation

Extended attributes are defined rarely. Therefore, a cache is created to keep the data. Every time a model object is placed in a persistence tool to be stored, the tool validates the XA attribute against meta definitions that are taken from this cache. Every category type and attribute name pair that is present in the XA attribute, but not defined in the meta cache is removed from the XA attribute before the model object is persisted. When the cache refresh process is disabled, meta information is taken from the persistence layer. When the process is enabled, the meta information is taken from Java memory.

You can control the frequency of the cache refresh process by using the com.ibm.cdb.ea.metaRefreshFrequency property in the collation.properties file. The default value is 20 and is expressed in seconds. If you want to disable the cache refresh process, set the value of this property to 0.
Note: When you are defining extended attributes, disable the cache refresh process and enable it when you finish.

MQL queries with EVAL operator (XA and XD attributes only)

Many CDM attributes are moved into XML content of the XA or XD attributes. Therefore, MQL syntax supports a new operator eval, which can be added in the where clause. The eval operator enables querying CIs by the values of extended attributes or extended instances.

Note: All MQL queries examples contain escaped quotation marks (\"value\") because it is assumed that the queries are run in the following manner:
./api.sh -u username -p password find "MQL query"
For example, the following query was run to find a computer system with the productID attribute set to 'prod1':
SELECT * FROM ComputerSystem WHERE productID == 'prod1'
The following equivalent query uses the eval operator:
SELECT * FROM ComputerSystem WHERE XA eval '/xml[attribute[@category=\"taddm_global\" and @name=\"productID\"]=\"prod1\"]'
The eval operator can be followed by any valid XPath expression that returns Boolean true or false value to enable the performance of correct SQL filtering by the persistence layer.
More examples
  • Find all ComputerSystems, which have any extended attribute with the val value:
    • MQL:
      SELECT * FROM ComputerSystem WHERE XA eval '/xml[attribute=\"val\"]'
    • SQL:
      SELECT * FROM compsys WHERE xmlexists('$c/xml[attribute="val1"]' passing compsys.xa_x as "c")
  • Find a ComputerSystem with the attr2 extended attribute, which has the category set to Other and value set to two:
    • MQL:
      SELECT * FROM ComputerSystem WHERE XA eval '/xml/attribute[@name=\"attr2\" and @category=\"Other\" and text()=\"two\"]'
    • SQL:
      SELECT * FROM compsys WHERE xmlexists('$c/xml/attribute[@name="attr2" and and @category="Other" and text()="two"]' passing compsys.xa_x as "c")