The purpose of this document is to walk you though the format and structure of the NSE files and how to use Custom NSE files to update Altiris.
What is an NSE?
An NSE file is simply a file that is written in XML format that is given to Altiris to process. Altiris reads the NSE file and makes updates to the database based on the information held in the file.
An NSE files will look something like this (note, they may look different depending on the process that was used to create them):
<?xml version='1.0'?>
<message>
<to>0baba5a1-b08e-4f76-8dfd-a541c7bf8f62</to>
<body>
<inventory>
<resources>
<resource typeGuid="493435f7-3b17-4c4c-b07f-c23e7ab7781f" ref="0" name="DENIT-7SF9P81" guid="740184d3-f507-47a9-b170-8bf2f81e099c"></resource>
</resources>
<resourceAssociations>
<resourceAssociation typeGuid="ed35a8d1-bf60-4771-9dde-092c146c485a" parentResourceRef="0" childResourceGuid="587d5246-1cec-42e1-a48e-d347ff14311b" />
<resourceAssociation typeGuid="05de450f-39ea-4aae-8c5f-77817889c27c" parentResourceRef="0" childResourceGuid="caf67688-3e13-44e9-96e6-204e9e7119da" />
<resourceAssociation typeGuid="3028166f-c0d6-41d8-9cb7-f64852e0fd01" parentResourceRef="0" childResourceGuid="0a0203a5-d2b6-49f1-a53b-5ec31a89437c" />
</resourceAssociations>
<inventoryClass guid="b9d54fd2-0863-4aa9-9909-ad2fab9bdaec">
<data>
<resource resourceRef="0">
<row c2="OptiPlex GX520" />
</resource>
</data>
</inventoryClass>
<inventoryClass guid="e3df7d38-3e01-45f9-ad17-32d4662ab262">
<data>
<resource resourceRef="0">
<row c1="mird" c2="2009-03-19 12:20:23" />
</resource>
</data>
</inventoryClass>
</inventory>
</body>
</message>
While that all looks very confusing at first glance, once you understand the structure and what Altiris is looking for in the file, it becomes much easier to read. A lot of it is static information and XML tags that are just repeated from one NSE to the next. Let's start at the top. We'll start by looking at this block of data:
<to>0baba5a1-b08e-4f76-8dfd-a541c7bf8f62</to>
The first piece we are concerned about is the <to> section.
<to>0baba5a1-b08e-4f76-8dfd-a541c7bf8f62</to> tells the message how it is getting into Altiris, in this case, the GUID refers to inventory forwarding. Although we aren't actually running an inventory forwarding job, this will make Altiris treat your import data as it would Inventory Forwarding data. To find out what your Inventory Forwarding GUID is, you can create a report or open query analyzer and run this SQL query:
Select Guid from Item where Name = 'Forwarded Inventory Capture Item'
The next piece we will look at is the data in the <resource...> section:
<resource typeGuid="493435f7-3b17-4c4c-b07f-c23e7ab7781f" ref="0" name="DENIT-7SF9P81" guid="740184d3-f507-47a9-b170-8bf2f81e099c"></resource>
This section contains the basic attribute information about an asset or item in your database. typeGuid="493435f7-3b17-4c4c-b07f-c23e7ab7781f" refers to the type of asset you are updating. For example, "493435f7-3b17-4c4c-b07f-c23e7ab7781f" in my environment translates into a computer.
Here are some SQL queries you can use to find some common asset type GUID for your environment:
- Computer
Select Guid from Item Where Name = 'Computer'
- Monitor
Select Guid from Item Where Name = 'Monitor'
- Network Printer
Select Guid from Item Where Name = 'Network Printer'
**Note: If one of these SQL Queries returns more than one GUID, you will need to verify which one is correct for that type of association. My monitor query for instance, returns three GUIDs. The GUID can be verified through the Altiris console by right clicking the asset type you want to retrieve the GUID from and selecting properties. Asset Types live here: Configuration > Resource Settings > Resource Types > Asset Types. If you prefer not to use SQL, you can locate all your Type GUIDs through this method.
ref="0" - is a number that is used to reference an asset throughout the rest of the NSE. You can always use 0 if you are only updating one asset. If you are updating more than one, you will need to increment this number for each asset you are referencing.
name="DENIT-7SF9P81" - refers to the name of the asset. Setting this name will set or change the name of the asset in your database.
Finally, guid="740184d3-f507-47a9-b170-8bf2f81e099c' - is the assets actual GUID that Altiris uses to keep track of it. If you are making updates to an asset, you need to make sure this matches the GUID of the asset you are updating. If you are creating a new asset, this can be any valid GUID. Several scripting languages, as well as .NET languages have GUID generation methods built in that can be used to create a new GUID.
We will now look at the piece of XML that sets the associations of the asset. Some examples of associations would be Owner, Location, and Status. You will need one resourceAssociation tag for each association you wish to make. You will notice in the sample XML, I am making three associations.
- <resourceAssociation typeGuid="ed35a8d1-bf60-4771-9dde-092c146c485a" parentResourceRef="0" childResourceGuid="587d5246-1cec-42e1-a48e-d347ff14311b" />
- <resourceAssociation typeGuid="05de450f-39ea-4aae-8c5f-77817889c27c" parentResourceRef="0" childResourceGuid="caf67688-3e13-44e9-96e6-204e9e7119da" />
- <resourceAssociation typeGuid="3028166f-c0d6-41d8-9cb7-f64852e0fd01" parentResourceRef="0" childResourceGuid="0a0203a5-d2b6-49f1-a53b-5ec31a89437c" />
typeGuid specifies the type of association that is being made. In this example, typeGuid="ed35a8d1-bf60-4771-9dde-092c146c485a" is referring to the Owners association.
Here are some SQL queries you can use to find the GUID for some common associations:
- Owner Association
Select Guid from Item Where Name = 'Owners'
- Location Association
Select Guid from Item Where Name = 'Location'
- Status Association
Select Guid from Item Where Name = 'Asset''s Status'
**Note: If one of these SQL Queries returns more than one GUID, you will need to verify which one is correct for that type of association. My location query for instance, returns three GUIDs. The GUID can be verified through the Altiris console by right clicking the association you want to retrieve the GUID from and selecting properties. Association Types live here: Configuration > Resource Settings > Resource Associations > Asset Association Types. If you prefer not to use SQL, you can locate all your Type GUIDs through this method.
The next piece is the childResourceGuid - This is the GUID of who or what the association is being made to. For example, if you are making an owner type association childResourceGuid="587d5246-1cec-42e1-a48e-d347ff14311b" would assign that asset to me. The GUID "587d5246-1cec-42e1-a48e-d347ff14311b" would translate into my User record.
The GUIDs that you want to make associations to will come from a variety of places. Again, like on the other steps, you can find them through the Atiris console or through SQL. Here are some SQL examples:
Now we begin the last section of the XML. The last part is where we update information in tables where the data is not assigned by an association. You need one <inventoryClass> section for each table you plan on updating. In this case, I am updating information in two tables.
<inventoryClass guid="b9d54fd2-0863-4aa9-9909-ad2fab9bdaec">
<data>
<resource resourceRef="0">
<row c2="OptiPlex GX520" />
</resource>
</data>
</inventoryClass>
<inventoryClass guid="e3df7d38-3e01-45f9-ad17-32d4662ab262">
<data>
<resource resourceRef="0">
<row c1="mird" c2="2009-03-19 12:20:23" />
</resource>
</data>
</inventoryClass>
Each table or Data Class has a GUID associated with it. The guid="b9d54fd2-0863-4aa9-9909-ad2fab9bdaec" in the inventoryClass tag tells Altiris what table it will be modifying. These GUIDs can also be found using SQL, but for these, I prefer to go through the console. Data classes are stored here: Configuration > Resource Settings > Data Classes, and all custom and user defined data classes are in the User Defined folder. Again, to get the GUID, you can right click and select properties.
The resourceRef="0" again, refers to the asset we are updating. It was set up in the resource tag at the top with the ref="0" tag. This will always be 0 unless you are updating multiple assets with one NSE, in which case, it will be incremented here just like you would do up top.
The final piece we need to make updates to is the row portion of the NSE for each inventory class. In each row tag there you will find a "c" tag. They will be followed by numbers i.e. "c1=", "c2=", etc. These are referring to the columns that you are updating in the table. If you do not want to update a certain column, you can leave it out. Notice in my first inventory class, I am not setting a value for c1. I begin with c2. This is our Manufacturer table. I am setting the model in column 2, but not the manufacturer information which lives in column 1. The second example is our Barcode Scanning table, where I am setting a value for both the last person to scan the asset (c1) and the date and time it was scanned (c2).
That about wraps it up. All the lines that I didn't touch on are static, meaning they will be the same from one NSE to the next.
So what is all this good for? We use custom NSE files for a few things.
First, we have Web forms that take information on hardware requests that we want to store in Altiris so we can tie it to other data, but we don't want all the end users to be in Altiris trying to add hardware data, so our web form takes the data from the user, generates an NSE on the fly, passes it up to the event queue on the Altiris server and the information is stored in a custom data class and ready to report on. We also use custom NSEs for our home grown barcode solution so scan data can be stored easily in Altiris without having to use the Altiris Barcode Solution. Finally, we use it in desktop applications we have written that allow PC support to set up asset associations quickly, again, without having to give them all access to the console.
Be creative and the sky is the limit on what you can automate and improve through the use of NSEs.
I hope this is helpful in unraveling the mysteries of Altiris.