Manage Groups in DX NetOps Portal using REST web services

Products

CA Performance Management - Usage and Administration DX NetOps

Issue/Introduction

This article covers the available methods for the following Group management tasks in DX NetOps Portal web server using REST web services.

List all known Groups
List a specific known Group
Create a new empty Group
Add items to a new or existing Group
Add or modify Rules for Groups

Environment

All supported DX NetOps releases

Cause

Need Group Management options to utilize with DX NetOps that are independent of the Portal web UI.

Resolution

NOTE: Where ever URLs are seen in this article, ensure <PORTAL_HOST> is replaced with the host name or IP address of the actual PORTAL host when launching them locally. If running SSL, replace the HTTP with HTTPS and 8181 with the configured SSL port in use.

We should start here with the PORTAL REST Group Documentation:

http://<PORTAL_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://<PORTAL_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://<PORTALC_HOST>:8181/pc/center/rest/groups/xsd

If we are adding items to an existing Group we'll need to look up the Groups ID value, or we can also simply use the existing 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 go to:

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

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

http://<Portal_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://<PORTAL_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 see the ID for the group named Router_Test is 11714.

The first step in setting up the REST POST call to add items 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://<PORTAL_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 the groupItemId or the groupPath values. Valid URLs might look like:

http://<PORTAL_HOST>:8181/pc/center/webservice/groups/groupItemId/<groupID_value>/items
or:
http://<PORTAL_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://<PORTAL_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://<PORTAL_HOST>:8181/pc/center/webservice/groups/groupPath/Router_Test/items

If the group isn't yet created, a simple quick way to create one 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://<PORTAL_HOST>:8181/pc/center/webservice/groups/false/true

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

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 Portal web UI or REST client. This is important to be aware of as we need to use ItemID values known to Portal, not a specific Data Source such as the Data Aggregator.

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

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

That will list out all devices known to Portal.

In the output of a Support 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:

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

http://<PORTAL_HOST>:8181/pc/center/webservice/groups/groupItemId/11714/items
or:
http://<PORTAL_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 Portal after refreshing it, or we can use REST GET calls. To use the UI simply log in and review the members of the Group involved via the Manage Groups page. 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://<Portal_HOST>:8181/pc/center/webservice/groups/groupItemId/11714/items
or:
http://<Portal_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" type="device" subType="other" addedBy="BY_USER"/>
<item id="309" name="Router_DEF" description="Cisco Internetwork Operating System Software" type="device" subType="router" addedBy="BY_USER"/>
<item id="308" name="Router_ABC" description="Cisco IOS Software, 7200 Software (C7200-ADVENTERPRISEK9-M)" 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.

Adding Rules to Groups via REST is best done leveraging an existing Group and it's Rule, created through the Portal web UI, as an example. The Rule will be showing when listing the Group details. Create a Rule in the Portal web UI, review it via a REST call for that specific Group. Modify it as needed for the new Group and test it. Check membership results and edit again as needed to obtain the desired results.