Groups Web Service Example Syntax

Use Web Services to Manage Groups › Create Groups Programmatically › Groups Web Service Example Syntax

Groups Web Service Example Syntax

Issue the following call to see the parameters for the groups web service:

http://CA Performance Center Server IP Address:8181/pc/center/webservice/groups

Issue the following call to see a list of supported operations:

http://CA Performance Center Server IP Address: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://CA Performance Center Server IP Address:8181/pc/center/webservice/groups/
groupPath/All%20Groups

Note: 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://CA Performance Center Server IP Address: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://CA Performance Center Server IP address: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:

Note: The groupItemId of the default 'Inventory' group is 5.

http://CA Performance Center Server IP address: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. Therefore, we recommend testing with various rules that you create in the user interface and examining the syntax that is generated.

Site Group Syntax

The following XML in a POST command creates a site group (replace the example values with the desired values 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>

inherit

Indicates whether the group includes child items of group members. For example, if the "inherit" attribute is set to true, device interfaces are group members if the device has been added to the group.

type

Indicates the type of group. Accepts the following values:

custom group: A group that a user has created.
site group: A user-created group that represents a physical site.
system group: A predefined group that cannot be modified or deleted.
automatic group: A predefined group of items from a data source other than Data Aggregator that cannot be modified or deleted.

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 custom groups.

Group 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="DisplayName" type="device"/>
           <Value>Cisco*</Value>
   </Compare>
</Match>

AllowDeletes

Group deletion requires the 'allowDeletes' parameter to be set to 'true'. Apply this parameter to a container group when you want to delete a subgroup. For example, this XML deletes the following subgroup: All Groups\Texas\Austin:

<GroupTree path="/All Groups/Texas">
   Group name="USA" desc="Group to represent the entire
   United States" allowDeletes="true" type="custom group"/> 
</GroupTree>

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 Office" type="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, however, use a backslash character for a group path. Forward slashes are misinterpreted by the browser.