Groups Web Service

The npc API provides web services to let you perform common group management tasks.
You can perform common group management tasks using the
groups
web service, such as creating and managing groups of monitored items. You can create new groups and can add items to them manually. You can also write rules to create and populate groups that are based on item attributes.
In this article:
Verify the Prerequisites
  • You have connected the REST client that you will use to invoke the PC web services to the PC RESTful web services.
  • You are a local admin user.
Access the groups Web Service Documentation
As a local admin user, issue the following call to see the parameters for the
groups
web service:
http://
PC_host
:8181/pc/center/webservice/groups
As a local admin user, issue the following call to see a list of supported operations:
http://
PC_host
:8181/pc/center/rest/groups/documentation
Look Up the ID of a Group
For most of the
NetOps Portal
API calls, you need the numeric groupItemId for a group. You can use any of the following three methods to look up these IDs:
  • groupItemId Lookup Service
    This service lets you look up the ID of a single group path using a simple HTTP GET.
    To look up the ID of "All Groups/Inventory", use the
    groupItemId
    parameter. The syntax is as follows:
    http://
    PC_host
    :8181/pc/center/webservice/groups/groupPath/All
    %20
    Groups
    %2F
    Inventory/groupItemId
    It is not mandatory to specify the entire path. For example, you can find the "
    All Groups/Tenants/Acme/Groups/Sites/Boston
    " group by searching for "
    groupPath/Acme%2FGroups%2FSites%2FBoston/groupItemId".
    When specifying the group path, use URL text encoding. Spaces must be replaced with %20 and the groups should be separated by %2F.
    The xml that is returned is as follows:
    <groupItemId>
    <groupItemId>5</groupItemId>
    </groupItemId>
    The search might match more than one group, but returns only one group.
  • Bulk Group Find Service
    This service lets you look up the ID of several groups with a single HTTP POST. The syntax is as follows:
    http://PC_host:8181/pc/center/webservice/groups/find
    The XML to POST is as follows:
    <groups> <group Path='/All Groups/Tenants/Acme/Groups/Sites/San Francisco'/> <group Path='/All Groups/Tenants/Acme/Groups/Sites/Austin'/> <group Path='/All Groups/Tenants/Acme/Groups/Sites/Boston'/> </groups>
    You can look up for any number of groups. For each group path that is found, the corresponding group ID and the group Name are returned. If a path does not match a group, no ID is returned.
    The XML that is returned for the above POST is as follows:
    <?xml version="1.0" encoding="UTF-8"?> <groups> <group ID="10503"Name="San Francisco" Path="/All Groups/Tenants/Acme/Groups/Sites/San Francisco"/> <group Path="/All Groups/Tenants/Acme/Groups/Sites/Austin"/> <group ID="10505"Name="Boston" Path="/All Groups/Tenants/Acme/Groups/Sites/Boston"/> </groups>
    The 'Austin' group does not exist, so no group ID is returned for this group.
  • groups Web Service
    This service lists all child groups of the specified group. This call takes several minutes to return a large group hierarchy. This method is the slowest as it returns more data.
    To look up the ID of "All Groups/Inventory", the syntax is as follows:
    http://PC_host:8181/pc/center/webservice/groups/groupPath/All%20Groups%2FInventory
    When specifying the group path, use URL text encoding. Spaces must be replaced with %20 and the groups should be separated by %2F.
Syntax for Site Group Management
To get a list of all groups under All Groups, use the
groupPath
parameter or the
groupItemId
parameter.
To use the
groupPath
parameter to identify the default group, issue the following call:
http://
PC_host
:8181/pc/center/webservice/groups/groupPath/All%20Groups
When using some REST clients, the ‘All Groups’ syntax is required rather than ‘All%20Groups’. But in general, blank spaces are not valid in URLs.
To get the identifier (siteId) for a site group, issue the following call:
http://
PC_host
:8181/pc/center/webservice/groups/groupItemId/siteId
The following XML shows an example of the return for the site ID:
<GroupTree siteId="118" inheritDefault="true" path="Austin, TX">
To get a list of all subgroups under a group that you specify, you have two options:
  • Use the
    groupPath
    parameter.
  • Use the
    groupItemId
    parameter.
Issue the following call to use the
groupPath
parameter to identify the group whose subgroups are listed in the XML that is returned:
http://
PC_host
:8181/pc/center/webservice/groups/groupPath/All%20Groups%2FInventory
To use the
groupItemId
parameter to identify the group whose subgroups are listed in the XML that is returned, issue the following call:
The
groupItemId
of the default Inventory group is 5.
http://
PC_host
:8181/pc/center/webservice/groups/groupItemId/5
The XML that is returned includes the syntax of any group rules that are applied to that group. Test with various rules that you create in the user interface, and examining the syntax that is generated.
Site Groups and Rules
Group rules support multiple comparisons, in addition to regular expressions. For example, use the following syntax in the XML to post a group rule that adds devices whose name begins with the word 'Cisco':
<Match> <Compare readOnly="true" using="MEMBER_OF"> <Property name="ItemID" type="device"/> <Value reference="/All Groups">1</Value> </Compare> <Compare readOnly="false" using="STARTS_WITH"> <Property name="AlternateName" type="device"/> <Value>Cisco*</Value> </Compare> </Match>
For group path syntax, forward-slash characters are appropriate for the XML documents that you post. This example assumes that you already have a group structure of “All Groups\Texas\Austin”:
<GroupTree inheritDefault="true" path="/All Groups/Texas/Austin"> <Group desc="" inherit="true" location="" name="CA Officetype="custom group"> <Group desc="" inherit="true" location="" name="Austin Lab" type="custom group"/> </Group> <Group desc="" inherit="true" location="" name="Austin Data Center" type="custom group"/> </GroupTree>
In the URL for the web service request, use a backslash character for a group path. Do not use forward slashes in the URL.
groups Web Service Example Syntax
Issue the following call to see the parameters for the
groups
web service:
http://
PC_host
:8181/pc/center/webservice/groups/idNames
Issue the following call to see a list of supported operations:
http://
PC_host
:8181/pc/center/rest/groups/documentation
To get a list of all groups under the highest-level group in the Groups tree (the default, 'All Groups'), you can use the
groupPath
parameter or the
groupItemId
parameter.
Issue the following call to use the
groupPath
parameter to identify the default group:
http://
PC_host
:8181/pc/center/webservice/groups/groupPath/All%20Groups
When using some REST clients, the ‘All Groups’ syntax is required rather than ‘All%20Groups’. But in general, blank spaces are not valid in URLs.
Issue the following call to use the
groupItemId
parameter to identify the default group (whose groupItemId value is 1):
http://
PC_host
:8181/pc/center/webservice/groups/groupItemId/1
Subgroup Syntax
To get a list of all subgroups under a group that you specify, you have two options:
  • Use the
    groupPath
    parameter.
  • Use the
    groupItemId
    parameter.
Issue the following call to use the
groupPath
parameter to identify the group whose subgroups are listed in the XML that is returned:
http://
PC_host
:8181/pc/center/webservice/groups/groupPath/All%20Groups%2FInventory
Issue the following call to use the
groupItemId
parameter to identify the group whose subgroups are listed in the XML that is returned:
The
groupItemId
of the default Inventory group is 5.
http://
PC_host
:8181/pc/center/webservice/groups/groupItemId/5
The XML that is returned includes the syntax of any group rules that are applied to that group. Test with various rules that you create in
NetOps Portal
, and examining the syntax that is generated.
Site Group Syntax
The basic URL to create a group is as follows:
http://
PC_host
:8181/pc/center/webservice/groups/useIds/allowDeletes
The
useIdsIndicates
and the
groupItemId
parameter is used to identify the group. Indicates whether the supplied id attribute of a group should be used to identify it. A value of
false
ensures that the groups web service does not try to use the IDs of the groups to create any new groups. Because they are internally assigned, the IDs are a less reliable way to identify groups that have been exported and reimported. In this example, the XML does not contain a group ID, so the value is 'false'.
  • allowDeletes
    Enables deletion of the group that you are creating. The groups web service can update the rules that are defined in the existing groups that are overwritten by this XML document.
Example
:
http://
PC_host
:8181/pc/center/webservice/groups/false/true
Follow these steps:
  1. As a local admin user, set the URL to the following:
    http://
    PC_host
    :8181/pc/center/webservice/groups/false/true
  2. Select
    POST
    for
    HTTP Method
    .
  3. Provide a valid
    Username
    and
    Password
    in the request header for a user account that has administrator access to
    NetOps Portal
    .
  4. Select
    application/xml
    as the
    'Body Content-type'
    .
  5. Add the following XML within the
    Body text
    section, replacing the values with the values that you want to use for the new site group:
    <GroupTree path="/All Groups"> <Group name="East Coast USA" desc="This is a site group" inherit="true" type="site group" location="North America" bHourID="99990" timeZone="EST"/> </GroupTree>
    • type
      Indicates the type of group. The following values are supported.
      Values:
      • user group
        (default)
        A group that a user has created.
      • site
        A user-created group that represents a physical site.
    • bHourID
      (Optional) The internally assigned identifier of the business-hour definition that you want to associate with this site group.
    • timeZone
      (Optional) The time zone to associate with this site group. Time zones can only be associated with site groups, not with user groups.
    • inherit
      Indicates whether the group includes child items of group members. For example, if you set this attribute to true, device interfaces are group members if the device has been added to the group.
    For example, supply the following XML:
    <Group name="East Coast" desc="Site group to represent the entire United States" inherit="true" type="site group" location="North America" bHourID="99990" timeZone="EST"/>
  6. Run the method.
    The USA site group is created under the default All Groups group in the Groups tree.
  7. Repeat the preceding steps until you have created as many site groups as you require.
  8. Use a similar procedure to create subgroups. Add the following XML within the
    Body text
    section:
    <GroupTree path="/All Groups/USA"> <Group name="Raleigh" desc="This is the group for managed items in Raleigh, NC" inherit="true" type="custom group"/> </GroupTree>
  9. Run the method.
    In this example, a new group, Raleigh, is added as a subgroup of the All Groups\USA group.
Group Rules
Group rules support multiple comparisons, in addition to regular expressions. For example, you want a group rule that adds devices in the Routers group whose name begins with 'Cisco'. The group ID of the Router group is 31. Use the following syntax in the XML:
<Match> <Compare readOnly="true" using="MEMBER_OF"> <Property name="ItemID" type="device"/> <Value reference="/All Groups/Inventory/All Items/Routers">31</Value> </Compare> <Compare readOnly="false" using="STARTS_WITH"> <Property name="AlternateName" type="device"/> <Value>Cisco*</Value> </Compare> </Match>
Scope group rules as narrowly as possible. Do not scope group rules to All Groups.
Group Deletion
Group deletion requires the
allowDeletes
parameter to be set to 'true'. When the
allowDeletes
parameter is set to 'true' for a group, groups under the
GroupTree path
are retained, unless they are excluded from the XML body. Groups under the
GroupTree path
that are excluded from the XML body are deleted. When the
allowDeletes
parameter is set to 'false' for a group, groups under the
GroupTree path
are retained regardless of whether they are included in the XML body.
Apply and set this parameter to 'true' for a container group when you want to delete a subgroup. For example, the following XML deletes any unlisted groups under Austin:
<GroupTree inheritDefault="true" path="/All Groups/Texas/Austin" allowDeletes=”true”>
<Group desc="" inherit="true" location="" name="CA Office" type="user group">
<Group desc="" inherit="true" location="" name="Austin Lab" type="user group"/>
</Group>
<Group desc="" inherit="true" location="" name="Austin Data Center" type="user group"/>
</GroupTree>
The following XML deletes any unlisted groups under Texas. For example, this XML would delete the Austin subgroup from the previous example.
<GroupTree path="/All Groups/Texas">
<Group name="USA" desc="Group to represent the entire
United States" allowDeletes="true" type="user group"/>
</GroupTree>
For group path syntax, forward-slash characters are appropriate for the XML documents that you post.
In the URL for the web service request, use a backslash (\) character for a group path. Do not use forward slashes (/) in the URL.