View source for Data eXchange Adapter Syntax and Uses

==Abstract==

While the EMC|SMARTS Domain Managers share a common structural model, ICIM - the InCharge Common Information Model, they also need a general way to transfer objects between servers. The mechanism used to accomplish this is the Data eXchange Adapter (DXA). The DXA is a powerful tool that can be used to refine existing flows of information or define new data to be brought into a custom Domain Manager. This article exposes the reasons for using the DXA as well as the configuration syntax available for more complicated tasks. 

==Overview==

The cooperative analysis done by EMC|SMARTS Domain Managers as well as the aggregation functionality provided by SAM has always been largely tied to a common set of topology exposed through the Object-Oriented Database that we call the Repository. That topology doesn't just manifest in those servers by accident or providence. It is controlled by the Data eXchange Adapter or DXA and manifests the EMC|SMARTS philosophy of having exactly the information you need to perform the analysis in question - no more and no less.

The DXA provides a rich set of configuration commands that allows anyone to describe exactly what topology needs to move from one server to another. With the advent of Dynamic Model and the general desire of users to extend both the capabilities of the Domain Managers as well as provide additional information that can be presented to users, the DXA can be a powerful feature to enable customizations.

Below, you can find an exhaustive description of the syntax of the DXA configuration files. There are extremely powerful but little known features that can help you present the right information to the right people regardless of the source of that data. 

==Configuration Syntax==

DXA configuration files determine what data should be transferred from a remote InCharge application to the local one. The data include topology and events. Configuration files are customized to specify data to be imported for different types of remote servers, AM, PM, AI, OI, etc.

In many cases, DXA may be used for topology transfer only. One InCharge analysis server imports certain instances and relationships from another analysis server or from a discovery server. The imported data also includes properties of the instances. Here is the syntax for topology import: 

   class  <remoteClassName>       [<localClassName>]
   attr   <remoteAttributeName1>  [<localAttributeName1>]
   attr       <remoteAttributeName2>  [<localAttributeName2>]
   rel       <remoteRelationName1>       [<localRelationName1>]
   rel       <remoteRelationName2>       [<localRelationName2>]

Above are the simplest entries for topology import specification. class indicates a starting of a block until another class is encountered. A block represents a class of target objects and all interested properties of those objects. attr keyword is used to list class attributes, and rel  is for relationship or relationshipset that are to be imported from the remote server. There is no limit to how many attributes and relationship that can be specified.

In some cases, the remote class may not exist in the local server. The class &lt;remoteClassName&gt; then can be mapped (defaulted) to a class &lt;localClassName&gt; that is locally available. If a remote class is not defined in the local server and a mapping is not provided, DXA prints a warning message and ignores that class entry block in the configuration file. Note that a locally existing remote class cannot be mapped to another local class.

Similarly, remote attributes and relationships can be mapped to local ones. Unlike class mapping, properties can be mapped even the remote property is available locally. However, the model definitions of a class property in both servers must be compatible in terms of type, access mode, etc. Note that the related class also should be imported so that the relationship can be established between two class instances. It is important to specify the given relationship from one class only, which is sufficient. For example, if class UnitaryComputerSystem lists ConnectedVia, then class ICIM_NetworkDeviceConnection should not list ConnectedSystems under it. Otherwise, the redundant entry will cause DXA to update the relationship unnecessarily, impacting overall performance.

class keyword may be replaced with proxy. When proxy is specified, all the instances of that remote class will be instrumented. That is, an accessor will continuously monitor instrumented attributes of the class instances and reflect changes in the local objects as they occur.

Certain attributes may require a function call to set its value instead of directly copying it, such as read-only attributes. Rattr is the keyword to achieve this:

   class  <className>
   attr   <attributeName1>
   Rattr  <attributeName2>  <operation>
   rel       <relationName>

The operation is passed the remote attribute value during the call. It is assumed that remote and local attribute names are the same.

Example (Set the attribute AccessMode of imported devices calling the function called setAccessMode, and by passing the remote value of the attribute):

   Rattr   AccessMode   setAccessMode

Uattr is similar to Rattr except that the operation does not take any parameters. It is specially implemented to compute a value and assign it to the given attribute in the local server. The syntax is similar too:

   class   <className>
   Uattr   <attributeName>   <operation>

Example (Set AgentAddressList attribute of SNMPAgent instances using the function called updateAgentAddressList):

  Uattr  AgentAddressList  updateAgentAddressList

oper is yet another keyword in importing certain attribute values of a given class where a simple read/write is not possible. Two function names are specified after the keyword: First, the remote function, and then the local function. It tells DXA to get the value that results in calling the remote function on the remote objects, and assign it to the local object by calling the local function on the local object.

   class  <className>
   oper       <remoteFunctionName>     <localFunctionName>   

Example (Set value from the remote call getManagedState and set it locally by calling setManagedState):

   oper   getManagedState   setManagedState   

Sometimes it may be required that the topology propagation be restricted. One keyword available to filter instances to be imported is peek. When peek is specified, the given attribute value in the remote server must match the value specified - in string format with glob. Here is the syntax for peek:

   class  <className>
   peek       <remoteAttributeName>       <remoteAttributeValue>   

Example (Bring in instances that are currently managed):

   peek   IsManaged   TRUE   

it is used to import instances that are related to remote instance(s) of a specified class:

   class  <className>
   in       <containerClassName>   <relationName>   

Example (Bring Cards only being part of Switch ComposedOf relationship from the remote server to the local server):

   class   Card
   in        Switch   ComposedOf   

A variation of "in" is when a specific instance name for the containing object is given in the entry:

   class   <className>
   in        <containerClassName>   <relationName>   <instanceName>   

Example (Bring Cards only being part of the Switch::10.16.1.1::ComposedOf relationship from the remote server to the local server):

   class   Card
   in        Switch   ComposedOf     10.16.1.1   

In case "local" keyword is used instead of an instance name, it means the InChargeDomain object in the remote server:

   class   Card
   in      TopoSplit_InChargeDomain   ConsistsOf   local   

The above entry in the DXA configuration file brings Card instances that are member of the domain instance in the remote server.

While in filters instances as members of a relationshipset, the keyword eq probes the instance in a given singleton relationship.

   class   <className>
   in        <relatedClassName>   <relationName>   
 
Example (Bring in the Card instances that are packaged in each the system in the remote server):

   class   Chassis
   eq      UnitaryComputerSystem   SystemPackagedIn   

There is a special implementation for importing a structure type attribute (SNMPAgent::TopologyUpdateInfo) in the DXA. From this attribute value, only certain entries are copied to the local object (where the first string field (system) of the entry contains "FAULT_DATA" or "FAULT". This functionality is triggered by the keyword struct:

   class   SNMPAgent
   struct  TopologyUpdateInfo   

'''Note that if the structure should be copied as is, this could be achieved by using the attr keyword instead of struct.'''

In case these filtering capabilities do not answer your needs, you can filter instances in an ASL hook script. The name of the ASL file must be specified within the class block for which the filtering will take place:

class   <className>
   hook    <aslName>    { [ param1=val1 [param2 = param2 ...]\|param2 = param2...]/] }

Optional parameters are listed after the file name. If a param is one of these 'special' names:

    filename = "foo"
            then a FileFE is built and connected to a file of the specified
            name "foo"
    trace = TRUE

then trace is enabled/disabled for the hookscript

ignoreclass or ignoreClass drops instances of the given class:

   ignoreclass   <className>   

prehook or preHook is good for executing any user actions just before the synchronization starts:

   prehook    <aslName>    { [ param1=val1 [http://param2 = param2 ...]\|http://param2%20=%20param2%20...]/] }   

Optional parameters are listed after the file name.

posthook or postHook is good for executing any user actions at the end of the synchronization:

   posthook    <aslName>    { [ param1=val1 [param2 = param2 ...]\|param2 = param2 ...]/] }   

Optional parameters are listed after the file name.

The local domain manager may be receiving topology from multiple sources. Occasionally, the same object may be managed by these multiple remote sources. Classification of the object in different sources may be different, especially for devices. The local server should be able to resolve conflicting information about the same device into one single instance in its repository. The keyword, lookup, is designed for this purpose:

   class UnitaryComputerSystem
   lookup findComputerSystemByAddress 

DXA will call the given function when it needs to find the instances of the class the function is specified for.

probe keyword allows post-processing scripts to be invoked within from DXA whenever a new instance was created.

 class &lt;className&gt;
 probe &lt;elementType&gt; 

Example (Run post-processing actions for each instance created of class SNMPAgent with the element type BGP):

 proxy SNMPAgent
 probe BGP 

conditionalprobe keyword is similar to probe. It behaves the same when a instance is created. Additionally, for existing instances, it compares the value of the specified attribute in the remote to local server. If the value was changed, the probe will take place even this is not a new instance. A method that is specified in the same section is used to find the relevant objects (e.g. system) that are elated to the remote to local instance, whose values to be compared:

 class &lt;className&gt;
 conditionalprobe &lt;elementType&gt; &lt;method&gt; &lt;remoteAttr&gt; &lt;localAttr&gt; 

Example

 proxy SNMPAgent
 probe MPLS
 conditionalprobe MPLS getSystem DiscoveredLastAt DiscoveredLastAtLocal 

server keyword is simply used to set the type of the domain server as the value in InChargeDomain::Type. This entry has no association with class blocks and stands out on its own:

Example:

 server INCHARGE-DM-TS 

When DXA is used in SAM servers, it can also receive and process events and notifications. In a hierarchical SAM or OI to SAM deployment, DXA can be configured to accept topology and notifications under specific groups in the underlying servers using the group keyword:

 group &lt;groupName1&gt;
 group &lt;groupName2&gt; 

The above means bring in objects that belong to one of the groups specified and the notifications occurred on them.

DXA does not copy EMS type attributes such as Acknowledgement, Owner. Those attributes can be imported from underlying SAM or OI server by listing them under the notification header:

 notification
 attr &lt;attributeName1&gt;
 attr &lt;attributeName2&gt; 

Event/notification subscriptions in SAM servers are configured within dxa configuration files using the sub keyword. Patterns (regular expressions) separated by "::" matche class name, instance name, and event name in the analysis server:

 sub &lt;classPattern&gt;::&lt;instancePattern&gt;::&lt;eventPattern&gt;/&lt;modifier(s)&gt; 

The modifiers for subscription syntax are: p=problems, a=aggregates, e=raw events, n=notification list.

Example (Subscribe to all problems):

 sub .*::.*::.*/p 

Example (Subscribe to symptom called DiscoveryError in all system objects):

 sub ICIM_UnitaryComputerSystem::.*::DiscoveryError/e 

Example (Subscribe to a notification list named "Default" in the underlying OI or SAM domain):

 sub Default/n 

Once events are subscribed from analysis servers, they can be categorized, assigned a severity value. Categories are numerous. Examples are Availability, Operational. Severity is an integer number between 1 and 5:

Severity values 1: Critical 2: Major 3: Minor 4: Unknown 5: Normal

The specification for severity and category values are made in lines that start with the keyword sev:

 sev &lt;className&gt; &lt;eventName&gt; &lt;categoryName&gt; &lt;severityNumber&gt; 

Examples:

 sev ICIM_UnitaryComputerSystem Down Availability 1
 sev ICIM_UnitaryComputerSystem DiscoveryError Discovery 3 

DXA event drivers (SAM and OI only) must subscribe to two attribute change in the underlying domains. The first is an attribute that indicates a topology change. It is by default:

 ICF_TopologyManager::ICF-TopologyManager::lastProbeFinishedAt 

which is updated in AM servers whenever a discovery occurs, or in other types of InCharge servers (AI, OI, SAM) when the topology has changed.

The seconds attribute change is used as heartbeats from the underlying domain. Since almost all InCharge applications has:

 SM_System::SM-System::uptime 

and it is updated periodically, it is subscribed by default.

However, in the event that another property should be used, DXA allows users to specify desired property name in the following format using keywords, topoUpdate and heartbeat:

 topoUpdate &lt;className1&gt;::&lt;instanceName1&gt;::&lt;attributeName1&gt;
 heartbeat &lt;className2&gt;::&lt;instanceName2&gt;::&lt;attributeName2&gt; 

Example:

 topoUpdate ICF_PersistenceManager::ICF-PersistenceManager::lastCheckpointFinishedAt
 heartbeat SM_System::SM-System::upTime 

filter is a special keyword that is not associated with any class. In fact, filter statements must appear before the first class statement appears. filter statements are used to reduce the amount of data being imported.

Example:

 filter host=&lt;host-expression&gt;
 filter host=lswk* 

In the above example, only hosts whose names begin with "lswk" will be imported to the target domain. In addition, any software services identified as being associated with hosts other than lswk will also be filtered out.

In addition to filtering by host, filtering can also be done by IP, display class name, and software name. Here are examples of the first two:

 filter ip=&lt;ip-expression&gt;
 filter ip=192.168.*.&lt;1-100&gt;
 filter displayclassname=&lt;display-name&gt;
 filter displayclassname=Router 

Just as filtering by host removed any related software services, filtering by IP or display class name also removes any non-related sofware services.

If the filter statement is filtering by software service, then non-related hosts are automatically filtered out during the import.

Example:

 filter software=&lt;softwareservice-expression&gt;
 filter software=*Apache* 

In addition to the options described above, a tilde character "~" can be used to define a "not" set of items to be filtered. For example,

 filter host=~lswk* 

means that I want all hosts whose names do not begin with "lswk".