Friday, March 16, 2012

How to Build or Modify Groups in NPC by using XML

In a previous post, I discussed how to build application reporting groups using dynamic system groups.  While this strategy is the recommended way of building application reporting groups, it can become tedious to actually copy and paste all the system groups into your application group.  Especially if you have the most recent version of SuperAgent and it has discovered a ton of applications and networks.  Luckily, there is an unpublished easier way: XML.  NPC has the ability to use XML to modify the group structure.  This includes the ability to put referential copies of system groups into custom application reporting groups.

The following is an excerpt from some documentation I wrote about how to use the web service to modify various portions of the NetQoS systems:

Group management in NPC is performed through the AdminCommand web service (found at PortalWebService/AdminCommandWS.asmx?WSDL ).  Adding or removing groups and adding or removing members from groups is accomplished by invoking the UpdateGroups operation (found at PortalWebService/AdminCommandWS.asmx?op=UpdateGroups).  Three main parameters are required: (1)useIDs, (2)allowDeletes, and (3) XML defining the groups (the groups to be added/removed/updated).  Groups themselves are defined explicitly in the XML while membership of groups is managed by a set of rules applied to each group.  Managed objects that match the rules are included as members of the group, objects that don’t match are excluded.  
The first two parameters are global and don’t change often.  The parameter useIDs instructs the operation whether or not to use the group ID values from the XML definition when identifying the group to be updated.  The useIDs parameter will need to be set to ‘true’ to ensure the correct groups are updated.  The only time a value of false would be used is when a single XML file is being used to import a group structure from one NPC system to another.

The second parameter, allowDeletes, instructs the web service to delete any groups or rules not explicitly defined within the XML.  The allowDeletes attribute must also be added (and set to ‘true’) to the parent group of any groups that are to be removed.  The allowDeletes attribute is present by default in the Rules tag and set to ‘false’ by default.  Setting this value to ‘true’ in combination with a value of ‘true’ in the allowDeletes parameter when calling the web service will result in the deletion of any rules not explicitly defined within the XML.  To delete groups from the root, add the allowDeletes attribute to the GroupTree tag .
The XML to be imported can be built from scratch or based on existing XML which can be obtained by invoking the ListGroups operation in the AdminCommand web service on the NPC server.  The operation can be found at /PortalWebService/AdminCommandWS.asmx?op=ListGroups.  The path to an existing group (i.e. /All Groups) is an optional parameter; if it is omitted, the service assumes “/All Groups”.  The path specified in the export will be the insertion point of any groups defined in the updated XML when importing back into NPC through the UpdateGroup operation.

For example, the following XML:
<?xml version="1.0" encoding="UTF-8"?>
<GroupTree id="1" inheritDefault="true" path="/All Groups">
<Group desc="" type="user group" inherit="false" name="All Applications">
<Group desc="" type="user group" inherit="true" name="Application 1"/>
<Group desc="" type="user group" inherit="true" name="Application 2"/>
<Group desc="" type="user group" inherit="true" name="Application 3"/>
<Group desc="" type="user group" inherit="true" name="Application 4"/>
<Group desc="" type="user group" inherit="true" name="Application 5"/>
</Group>
</GroupTree>


Would return the following results:
<?xml version="1.0" encoding="utf-8"?>
<GroupTree path="/All Groups" inheritDefault="true" id="1">
<Group result="Added" desc="" type="user group" inherit="false" name="All Applications" location="" id="1530">
 <Group result="Added" desc="" type="user group" inherit="true" name="Application 1" location="" id="1531" />
 <Group result="Added" desc="" type="user group" inherit="true" name="Application 2" location="" id="1532" />
 <Group result="Added" desc="" type="user group" inherit="true" name="Application 3" location="" id="1533" />
 <Group result="Added" desc="" type="user group" inherit="true" name="Application 4" location="" id="1534" />
 <Group result="Added" desc="" type="user group" inherit="true" name="Application 5" location="" id="1535" />
</Group>
</GroupTree>
The XML request shown above resulted in this group structure 
As stated before, this XML can be generated manually or it can be obtained from the ListGroup operation.  If it is generated manually and existing groups are to be updated, the group IDs must be obtained from within NPC.  It is recommended to use the ListGroup operation to obtain the XML to use as a starting point.
If you are uncomfortable using web services, the NetQoS team built a command line tool that can be used to invoke the web service.  As long as your path variable was set right during installation, just look for NPCCmd.exe.  Run it with no arguments to see the syntax required for group export and import.

So, when trying to build your application groups, instead of copying and pasting in the GUI, you might be able to save yourself some time by exporting the current group structure, manually modifying the XML (copying and pasting the corresponding XML snippets from one place to the other), and importing the XML back into NPC.  Just be prepared, when you import an XML file, you will get the results of the XML import echoed back to the CLI interface (which may be extensive if you're importing a large XML file).