How to populate Group membership with REST

Document ID : KB000032066
Last Modified Date : 14/02/2018
Show Technical Document Details

Introduction

This article shall cover the method for directly adding known device elements to a group in CA Performance Center (CAPC) using the REST services. It shall briefly touch on group creation with a basic example.

 

Instructions

NOTE: Where ever URLs are seen in this article, ensure <CAPC_HOST> is replaced with the host name of the actual CAPC host when launching them locally.

We should start here with the CAPC REST Group Documentation:

http://<CAPC_HOST>:8181/pc/center/rest/groups/documentation

On that page we can see that we need to use the "Add Items" function which is defined as:

Add items

Adds list of items that are direct members to the specified group. The group can be specified by ID or by group path.

URL: http://<CAPC_HOST>:8181/pc/center/webservice/groups/{idName}/{idValue}/items

Where:

- {idName} is one of the property name values returned by the get id names method of this web service.

- {idValue} is a value for the property denoted by idName.

HTTP method = POST

XSD for the provided XML: http://<CAPC_HOST>:8181/pc/center/rest/groups/xsd

 

If we are adding elements to a group already created, we'll need to look up the groups ID value, or we can also simply use the already created groups known name. If the group does not exist yet, we'll first need to create the group.

Get a list of all groups in the system:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupPath/All Groups

Get the Group ID for a specific group whose name is known:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupPath/<groupName>

For example if a group name is "Router_Test" issue the URL as a REST GET call:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupPath/Router_Test

That URL GET results in:

<?xml version="1.0" encoding="UTF-8"?>

<GroupTree id="11714" inheritDefault="true" path="Router_Test"/>

We can now see the ID for the group name Router_Test is 11714.

 

The first step in setting up the REST POST call to add the elements to the group is configuring the URL we'll need to use. This is seen above in the "Add Items" definition. In it we can see we must use an idName and its value.

Possible idName values for the Add Items URL are seen using the following REST GET call for the URL:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/idNames

The results are:

<?xml version="1.0" encoding="UTF-8"?>

<idNames>

    <idName value="groupItemId"/>

    <idName value="groupPath"/>

</idNames>

The valid idNames values we can use are either groupItemId or groupPath. Valid URLs might look like:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupItemId/<groupID_value>/items

or:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupPath/<groupName/items

 

In this case we know the ID per the above details so the URL would be:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupItemId/11714/items

In this case with the Router_Test group name known an alternative URL would be:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupPath/Router_Test/items

 

If the group isn't yet created, a simple quick way is the following that was used to create the empty Router_Test group under the All Groups path.

Set the following URL in a REST client:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/false/true

Use a REST POST call for that URL with the following XML body set:

<GroupTree path="/All Groups"> 

<Group name="MikePollerTest" desc="This is a REST Group creation test" inherit="true" 

type="user group"/> 

</GroupTree>

 

Now that the group is created and/or we've figured out its name and/or ID value, next we need to identify the device items to add as members of the group. Note that when adding items to groups it is done via the CAPC web UI or REST client. This is important to be aware of as we need to use Item ID values known to CAPC, not a specific Data Source such as the Data Aggregator.

To see all devices known to CAPC including their device ID values (item ID) use a REST GET call with the URL:

http://<CAPC_HOST>:8181/pc/center/webservice/devices

That will list out all devices known to CAPC.

 

In the output on my test lab I selected these devices to add to the new group:

<itemId>308</itemId>

<name>Router_ABC</name>

<itemId>309</itemId>

<name>Router_DEF</name>

<itemId>310</itemId>

<name>Router_GHI</name>

Using that information we are able to develop an XML body list for the Add Items REST POST call that looks like:

<items>

<item id="308"/>

<item id="309"/>

<item id="310"/>

</items>

Using a REST POST call to one of these URLs, including the XML body with the list if item id values:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupItemId/11714/items

or:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupPath/Router_Test/items

 

That POST request returned a 200 OK success message and this XML output:

<?xml version="1.0" encoding="UTF-8"?>

<items>

    <item id="309" result="SUCCESS"/>

    <item id="308" result="SUCCESS"/>

    <item id="310" result="SUCCESS"/>

</items>

 

To validate these results we can check the UI in CAPC after refeshing it, or we can use REST again. To use the UI, simply log in and review the members of the group involved. Do the new items added via REST show up? To use REST to check the membership use a REST GET call against the same URL used to add the devices. In this example we can either use:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupItemId/11714/items

Or:

http://<CAPC_HOST>:8181/pc/center/webservice/groups/groupPath/Router_Test/items

The output shows us:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<group id="11714" name="Router_Test" description="This is a REST Group creation test" type="group" subType="user">

    <itemTypes>

        <itemType type="Devices">

            <items>

                <item id="310" name="Router_GHI" description="Cisco IOS Software, RSP Software (RSP-JSV-M), Version 12.4(10a), RELEASE SOFTWARE (fc2)  Technical Support: http://www.cisco.com/techsupport  Copyright (c) 1986-2006 by Cisco Systems, Inc.  Compiled Thu 12-Oct-06 03:23 by prod_rel_team" type="device" subType="other" addedBy="BY_USER"/>

                <item id="309" name="Router_DEF" description="Cisco Internetwork Operating System Software &#xD;&#xA;IOS (tm) C2600 Software (C2600-IK9O3S3-M), Version 12.3(9), RELEASE SOFTWARE (fc2)&#xD;&#xA;Copyright (c) 1986-2004 by cisco Systems, Inc.&#xD;&#xA;Compiled Fri 14-May-04 14:37 by dchih" type="device" subType="router" addedBy="BY_USER"/>

                <item id="308" name="Router_ABC" description="Cisco IOS Software, 7200 Software (C7200-ADVENTERPRISEK9-M), Version 12.2(33)SRE4, RELEASE SOFTWARE (fc2)&#xD;&#xA;Technical Support: http://www.cisco.com/techsupport&#xD;&#xA;Copyright (c) 1986-2011 by Cisco Systems, Inc.&#xD;&#xA;Compiled Mon 30-May-11 03:09 by prod_rel_team" type="device" subType="router" addedBy="BY_USER"/>

            </items>

        </itemType>

    </itemTypes>

</group>

 

Note we now see that group Router_Test has device elements in it that match the device element item ID values added via REST POST calls.