AeXNSEvent NSE Generator

Article:HOWTO31200  |  Created: 2010-08-23  |  Updated: 2012-07-25  |  Article URL http://www.symantec.com/docs/HOWTO31200
Article Type
How To



Overview

The event generator provides an object model that can be used to easily create inventory event data without the necessity of having to deal with XML.

Benefits of using the event generator include:

  • A common framework for generating and sending NSEs
  • Prioritization of events
  • Batching of events (planned for a future release)
  • Hashing of events
  • Delta detection (planned for a future release)
  • Data validation (planned for a future release)

 

Object Model

 NSE Generator Object Model

AeXNSEvent

AeXNSEvent represents the overall event object. This object has methods to create resources, dataclasses, and datablocks; to generate the XML and hashes, and to send the event to the NS; and properties to manage the overall event.

When the object is serialized to XML, either to obtain the XML or send the XML to a server as an event, any special characters that have been added to the data are escaped.

Properties

Name Mode Type Description
To get/set string Guid or alias of the item that handles the event
Priority get/set int The priority of the event
Guid get GUID The GUID of the event. This is generated when the event is created.
DefaultResource get IAeXNSEvent* The default resource object, this represents the computer that the agent is running on. Requires the Altiris Agent be installed.
Xml get string Returns the event XML.
XmlBody get string Returns the body part of the event as XML, excluding the event envelope.
Hash get string Returns the hash for the entire event, excluding any data that is excluded from hashing.

Methods

Name Parameter Type Required Description
AddResource       Adds a new resource to the event.
  return IAeXNSEventResource*   The newly added resource.
  typeGuid GUID Required The type GUID of the resource.
  guid VARIANT Optional The GUID of the resource if it is known. If the GUID is not known it may be omitted, and keys should be added to the returned resource object.
AddDataClass       Adds a new dataclass to the event.
  return IAeXNSEventDataClass*   The newly added dataclass
  dataClassName VARIANT Required Either the name or GUID of the dataclass must be specified.
AddDataBlock       Adds a datablock to the event. A dataclass and resource must be specified. For simple dataclasses the name or GUID of the dataclass may be specified instead of adding a dataclass. If the data applies to the computer resource, the resource may be omitted.
  return IAeXNSEventDataBlock*   The newly added datablock.
  dataClass VARIANT Required The dataclass that the new data will be used to populate. This may be an AeXNSEventDataClass object, the name of the dataclass, or the GUID of the dataclass.
  resource VARIANT Optional The resource that the data applies to. If this is omitted the default resource (the computer) is used.
AddAssociation       Adds a resource association. Either resource GUIDs or resource objects may be specified to create the association.
  return IAeXNSEventAssociation*   The newly added association.
  type GUID Required The GUID of the resource association type.
  parent VARIANT Required The resource that is the parent of the association. This may be an AeXNSEventResource object or a GUID.
  child VARIANT Optional The resource that is the child of the association. This may be an AeXNSEventResource object or a GUID. If this parameter is omitted children must be added to the association.
Send       Sends the event to the server. Requires the Altiris Agent be installed.
  server VARIANT Optional The name of the server. If omitted the event is sent to the NS that the agent is reporting to.
SendQueued       Queues the event for the server. Requires the Altiris Agent be installed.
  server VARIANT Optional The name of the server. If omitted the event is sent to the NS that the agent is reporting to.

AeXNSEventResource

AeXNSResource represents a single resource that has data contained in the event. Using the resource object it is possible to manage resource keys.

Properties

Name Mode Type Description
Guid get GUID Returns the resource GUID, if it has been specified
TypeGuid get GUID Returns the resource type GUID.
Name get/set string The name of the resource, this will be used if the resource is created.
NumKeys get int The number of keys that have been added
KeyName get string The name of the indexed key
KeyValue get string The value of the indexed key
KeyType get KeyOperationMode The type of the indexed key, whether it is add or replace.
Deleted get/set bool Set this to true to delete the resource from the server.

Methods

Name Parameter Type Required Description
AddKey       Adds a key to the resource.
  name string Required The name of the key, such as "name.domain"
  value string Required The value of the key.
  operation KeyOperationMode Required The operation to be performed with the key, either KEYOP_ADD which will add new keys to the resource, or KEYOP_REPLACE which will replace existing keys on the resource with the new keys.
AddAssociation       Adds a new association with this resource being the parent. For a description of this method and it's parameters see IAeXNSEvent::AddAssociation ()

AeXNSEventDataClass

AeXNSDataClass represents a dataclass. Using the dataclass object it is possible to specify columns names for the dataclass, as well as which columns participate in hashing.

It is not strictly necessary to specify column names, since columns are represented in the event using the short names, and column names are only used when specifying data using column names, in order to look up the short name.

Any columns that do not participate in hashing should be specified to ensure that correct hashes are generated.

Properties

Name Mode Type Description
Name get string The name or GUID of the dataclass.
IgnoreHash get/set bool Controls whether the indexed column is excluded from hashing. This is the most common use of the dataclass object.
NumColumns get int The number of columns defined for the dataclass.
FirstColumn get/set int The short name index for the first column. This is usually either 0 or 1, representing short names of c0 and c1, respectively.

Methods

Name Parameter Type Required Description
AddColumn       Adds a named column to the dataclass, whether the column is hashed may also be specified.
  name string Required The name of the column.
  ignore VARIANT Optional A boolean indicating whether the column is ignored when hashing. If omitted this defaults to false.
SetColumn       Sets the name of the indexed column, whether the column is hashed may also be specified.
  index int Required The index of the column being specified.
  name string Required The name of the column.
  ignore VARIANT Optional A boolean indicating whether the column is ignored when hashing. If omitted this defaults to false.

AeXNSEventDataBlock

AeXNSDataBlock represents a block of data that applies to a particular resource, and is in the format described by a particular dataclass. This object has properties indicating whether the datablock should be used to perform a partial or full update; and methods that allow adding additional rows of data as well as inserting field data into the rows.

Properties

Name Mode Type Description
DataClass get IAeXNSEventDataClass* Returns the dataclass object which specifies the datablock schema.
Resource get IAeXNSEventResource* Returns the resource object that the data applies to.
PartialUpdate get/set bool Specifies whether the datablock should completely replace the existing data, or be appended.
Hash get string The hash of all of the data in the datablock.

Methods

Name Parameter Type Required Description
AddRow       Begins a new row, and returns a row object.
  return IAeXNSEventDataRow*   The newly added row.
  type VARIANT/RowType Optional The type of row. This may be REPLACE_ROW to replace the row, which is default if omitted; MERGE_ROW to merge rows with missing columns into the existing data (which is the default behaviour when fields are missing); and DELETE_ROW to delete rows if they already exist.

AeXNSEventDataRow

AeXNSEventDataRow represents a single row of data.

Properties

Name Mode Type Description
Hash get string The hash of all of the fields in the row.

Methods

Name Parameter Type Required Description
AddField       Adds a field to the current row.
  value VARIANT Optional The value of the field. This may be a string, a number, a GUID, a resource object to reference another resource defined in the event, NULL to represent a database NULL value, or omitted to represent the default value (the default value is specified for the column when the dataclass is configured on the NS.)
SetField       Sets the value of the indexed field.
  index VARIANT Required The index of the field to set, this may be an integer index or the name of the field.
  value VARIANT Optional The value of the field. This may be a string, a number, a GUID, a resource object to reference another resource defined in the event, NULL to represent a database NULL value, or omitted to represent the default value (the default value is specified for the column when the dataclass is configured on the NS.)

AeXNSEventAssociation

AeXNSEventAssociation represents an association between a resource and one or more other resources.

Properties

Name Mode Type Description
Mode get/set AssocMode Determines the action taken when the association is loaded into the database. This may be ASSOC_ADD (the default), which will add the child resources to any existing association; ASSOC_REPLACE which will replace any existing associated resources with the child resources; and ASSOC_DELETE which will remove the child resources from any existing associations.
Hash get string The hash of the association.

Methods

Name Parameter Type Required Description
AddChild       Adds a child resource to the association, this must be done if one is not specified when the association is created.
  child VARIANT Required The resource to associate with the parent. This may be the GUID of the resource or an AeXNSEventResource object.

Test Script

The following VB script exercises most of the functionality of the event generator.

    dim nse
    set nse = WScript.CreateObject ("Altiris.AeXNSEvent")


    ' Get the default computer resource
    dim dfltRes
    set dfltRes = nse.DefaultResource
    'wscript.echo "Default Resource: Guid=" & dfltRes.Guid & " TypeGuid=" & dfltRes.TypeGuid


    ' Get another computer resource
    dim compRes
    set compRes = nse.AddResource ("{493435F7-3B17-4C4C-B07F-C23E7AB7781F}", "{5CD75AAB-FFAF-42b8-852B-CB095F06DD41}")


    ' Add a user resource
    dim userRes
    set userRes = nse.AddResource ("{FD864F19-4437-4A4F-8709-58EB5E3AE0A4}")
    userRes.AddKey "name.domain", "jjoyce.altiris", 0
    userRes.Name = "Justin Joyce"
    'wscript.echo "User Resource: NumKeys=" & userRes.NumKeys & " KeyName[0]=" & userRes.KeyName (0) & " KeyValue[0]=" & userRes.KeyValue (0)


    ' Set the header data of the NSE
    nse.To = "{2BC8F8E5-01F2-43e9-B66B-666DB7D36DA8}"
    nse.Priority = 1
    'wscript.echo "NSE: To=" & nse.To & " Priority=" & nse.Priority & " Guid=" & nse.Guid


    ' Add some associations
    dim assoc
    set assoc = nse.AddAssociation ("{AE5935F6-4E68-4f57-A24C-1D0F67AFC7B4}", compRes, userRes)
    set assoc = nse.AddAssociation ("{AE5935F6-4E68-4f57-A24C-1D0F67AFC7B4}", dfltRes)
    assoc.AddChild userRes


    ' Add a data class and add some data to it
    dim dc1
    set dc1 = nse.AddDataClass ("{A65127E9-7899-46a6-9D57-8D8D4AAF7DF8}")
    dc1.FirstColumn = 4
    dc1.AddColumn "Column 1"
    dc1.AddColumn "Column 2", true
    dc1.SetColumn 6, "Column 3"
    dc1.IgnoreHash(3) = 1
    'wscript.echo "DataClass: Name=" & dc1.Name & " NumColumns=" & dc1.NumColumns & " IgnoreHash[3]=" & dc1.IgnoreHash (3)


    dim db1
    set db1 = nse.AddDataBlock (dc1, userRes)


    dim dr
    set dr = db1.AddRow ( 2 )
    dr.SetField "Column 2", "Delete Row - Field 2"


    set dr = db1.AddRow
    dr.AddField
    dr.AddField NULL
    dr.AddField compRes


    set dr = db1.AddRow
    dr.AddField "1"
    dr.AddField 2
    dr.AddField -3


    ' Add some data, without adding a data class, and use the default resource
    dim db2
    set db2 = nse.AddDataBlock ("{89ECF359-67DE-4f57-BEF8-75EF0392C4A0}")
    db2.PartialUpdate = 1
    'wscript.echo "DataBlock: DataClass Name=" & db2.DataClass.Name & " Resource TypeGuid=" & db2.Resource.TypeGuid & " PartialUpdate=" & db2.PartialUpdate


    set dr = db2.AddRow ( 0 )
    dr.AddField "Field 1"
    dr.AddField "Field 2"
    dr.AddField "Field 3"


    set dr = db2.AddRow ( 1 )
    dr.SetField 2, "Partial Row - Field 2"


    set dr = db2.AddRow ( 1 )
    dr.SetField 2, 2
    dr.SetField 3, userRes


    set dr = db2.AddRow
    dr.SetField 2
    dr.SetField 3, NULL


    wscript.echo "hash=" & nse.Hash & chr(13) & chr (10) & nse.xml


    nse.SendQueued


Sample Custom Inventory Script

The following VB script is a simple custom inventory script with all the basic requirements. 

 

 

Dim objWMIService 
Set objWMIService = GetObject("winmgmts:" & "{impersonationLevel=impersonate}!\\.\root\cimv2") 
Set objWMIResults = objWMIService.ExecQuery("SELECT * FROM CIM_processor") 


Dim objNSE 
Set objNSE = WScript.CreateObject ("Altiris.AeXNSEvent") 

objNSE.To = "{1592B913-72F3-4C36-91D2-D4EDA21D2F96}" 
objNSE.Priority = 1 

Dim objDataClass1 
Set objDataClass1 = objNSE.AddDataClass("{e8220123-4987-45be-bc39-ec6eaea312ef}")

Dim objDataBlock 
Set objDataBlock = objNSE.AddDataBlock (objDataClass1) 

For each wmiRow in objWMIResults 
    Dim objDataRow 
    Set objDataRow = objDataBlock.AddRow 

    objDataRow.SetField 0, objInfo.DeviceID 
    objDataRow.SetField 1, objInfo.L2CacheSize 
    objDataRow.SetField 2, objInfo.L2CacheSpeed 
Next 

Wscript.echo "NSE Contents" & nse.xml

objNSE.SendQueued 

 


 

 

 




Article URL http://www.symantec.com/docs/HOWTO31200


Terms of use for this information are found in Legal Notices