Professional Documents
Culture Documents
Appendix, page 10
Americas Headquarters:
Cisco Systems, Inc., 170 West Tasman Drive, San Jose, CA 95134-1706 USA
SOAP/XML
SOAP/XML
WCS Server
LWAPP
W
Note
N
S
SNMP
LWAPP
N
S
LWAPP
W
N
S
LWAPP
W
N
S
270299
SNMP
Note
Extract the zip file onto the machine from which you want to access the APIs.
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
Note
Install Java 1.5.x and ensure that the JAVA_HOME variable is set correctly. Modify the sampleRun
script to point to the java location.
Create a user which has the required permissions to access "North Bound APIs" in WCS using WCS
GUI.
Compile and run the sample test program. The sampleCompile and sampleRun scripts are provided.
For UNIX platforms, the sampleCompile and sampleRun scripts can be run directly after
'ConfigTemplateTest' is changed to 'GuestUserTest'.
The sample test program provides a command line option that can be used to exercise each of the above
APIs.
To run the test program, include the following path:
c:\>java GuestUserTest <Service URL> <NBAPI username> <NBAPI password>
For example:
c:\>java GuestUserTest https://72.163.180.220/webacs/services wsuser wcs.1234
This process opens a connection to WCS and enable you to perform operations such as creating or
deleting guest users using the command line options provided by the sample test program.
Once the sample program (included in the zip file) is compiled and run, you can perform the following
guest-user-related operations:
Note
The sample test program code is also included in the Appendix and can be used as a reference by other
application developers.
Note
A guest user name can be up to 24 characters long and the name is case sensitive.
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
Configuration APIs
Configuration APIs
Before accessing the north bound APIs from a third party application, the administrator needs to create
a user on WCS who has the permissions to access north bound APIs.
The following WCS Soap based APIs are provided for the north bound functionality.
Note
See API Usage Sequence to determine in which order the APIs should be called to create or remove
guest users.
Note
createGuestUserTemplateThis API creates a Guest User Account Template in the WCS database.
Creating a guest user template object in the WCS database is the first step towards creating a
guest user on the WLC.
void createGuestUserTemplate(GuestUserTemplateWs
guestusertemplatews)
throws java.rmi.RemoteException,
com.cisco.ws.api.WSException
Note
This API does not automatically create the guest user on the controller. This API creates the
template that is stored in the WCS database. To create the guest user on a controller, use the
applyGuestUserTemplateToControllers.
Parameters:
guestusertemplatewsTemplate Object containing parameters (described below after the API
signatures).
Throws:
WSExceptionIf the template already exists or if the input parameters are null.
java.rmi.RemoteExceptionFor all other conditions.
Note
updateGuestUserTemplateThis API updates a guest user template object present in the WCS
database.
The modified template must be applied to the controller for the changes to take effect.
void updateGuestUserTemplate(GuestUserTemplateWs
guestusertemplatews)
throws java.rmi.RemoteException,
com.cisco.ws.api.WSException
Note
This can be used to modify the lifetime, password, user role, or description for the guest user.
Once the template is modified, you can apply it to the guest user.
Parameters:
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
Configuration APIs
Throws:
WSExceptionIf the template is not found or if the input parameters are null.
java.rmi.RemoteExceptionFor all other conditions.
deleteGuestUserTemplateThis API deletes the guest user from the WLC and also removes the
guest user template object from the WCS database.
void deleteGuestUserTemplate(java.lang.String
throws java.rmi.RemoteException,
com.cisco.ws.api.WSException
templateName)
Parameters:
templateNameName of the template that needs to be deleted
Throws:
WSExceptionIf the template is not found or if the input parameter is null.
java.rmi.RemoteExceptionFor all other conditions.
getGuestUserTemplatesThis API returns all of the guest user template objects stored in the WCS
database.
GuestUserTemplateWs[] getGuestUserTemplates()
throws java.rmi.RemoteException,
com.cisco.ws.api.WSException
Throws:
java.rmi.RemoteExceptionFor all other conditions.
com.cisco.ws.api.WSException
Note
If no controller IP is provided, the Guest User Template is applied to all controllers currently
being managed by the WCS.
Note
Prior to using this API, create the template in the WCS database by using the
createGuestUserTemplate API.
void applyGuestUserTemplateToControllers(java.lang.String
templateName, java.lang. String[] controllers)
throws java.rmi.RemoteException,
com.cisco.ws.api.WSException
Parameters:
templateNameName of the template which needs to be applied to controllers.
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
Configuration APIs
controllersString array containing IP addresses of the controllers to which the template needs
to be applied.
Throws:
WSExceptionIf the template is not found, if the controller with IP is not found, or if the input
listGuestUsersOnControllerThis API returns a list of all guest users that exist on a controller.
String[] listGuestUsersOnController(String controller)
throws java.rmi.RemoteException,
com.cisco.ws.api.WSException
Parameters:
controllersString containing the IP address of the controller from which the guest users are
to be retrieved.
Throws:
WSExceptionIf the controller with IP is not found or if the input parameter is null.
java.rmi.RemoteExceptionFor all other conditions.
getGuestUserDetailsThis API provides the details of a created guest user given the username and
the controller IP on which the user was created.
Map getGuestUserDetails(java.lang.String userName, java.lang.String
controllers)
throws java.rmi.RemoteException,
com.cisco.ws.api.WSException
Map<String,String> contains the following name value pairs:
user name
password
lifetime
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
Configuration APIs
description
User role
Profile name
WLAN ID
Remaining Lifetime
Parameters:
userNameName of the user whose details are sought.
controllerString containing the IP address of the controller from where the guest user details
are to be retrieved.
Throws:
WSExceptionIf the user name is not found, if the controller with IP is not found, or if the
getControllerWithProfileThis API provides a list of controllers which have the wlan profile
name configured.
This API can be used by third party applications to get the list of controllers known to WCS
on which a given profile name exists.
Note
Parameters:
profileNameName of the profile to be checked.
Throws:
WSExceptionIf the user name is not found, if the controller with IP is not found, or if the
getUserRolesOnControllerThis API lists all of the user roles that have been configured on the
controller. User roles are bandwidth contract templates provisioned on the device. The default user role
is default.
String[] getUserRolesOnCntroller (java.lang.String Controllerip)
throws java.rmi.RemoteException,
com.cisco.ws.api.WSException
Parameters:
controllersString containing IP addresses of the controller from which the user roles are to be
fetched.
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
WCS Notifications
Throws:
WSExceptionIf the controller with IP is not found or if the input parameter is null.
java.rmi.RemoteExceptionFor all other conditions.
In addition to the above APIs, two additional APIs are provided for third party applications to
programmatically log into WCS prior to using the above APIs and log out of WCS.
These APIs are detailed below:
String login(String in0, String in1) throws java.rmi.RemoteException,
com.cisco.ws.api.WSException; returns http session id.
boolean logout() throws java.rmi.RemoteException; true if successfully
logged out, false otherwise.
Refer to the sample test program in the Appendix for more details on their usage.
Step 2
To remove a guest user created from WCS and the controller, use the Delete Guest User Template API.
To modify a guest users parameters, follow these steps:
Step 1
Step 2
WCS Notifications
WCS can also send guest-user-related notifications to a north bound system. WCS currently supports
notification through an SNMP trap for north bound notifications.
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
WCS Notifications
WCS acts as a trap generator to send guest user related traps to third party applications. To receive
notifications from WCS, the third party application needs to be added as a notification receiver to WCS.
This screen is accessible from Adminsitration > Settings > Notification Receivers and is shown below.
Figure 2
In the following conditions, north bound SNMP traps from WCS are provided:
guestUserAddedWhen WCS receives a trap from a wireless LAN controller notifying that a guest
user has been added, it sends a trap north bound.
guestUserRemovedWhen WCS receives a trap from a wireless LAN controller notifying that a
guest user has been removed from the controller, it sends a trap north bound.
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
Appendix
cderMonitoredExceptionEvent NOTIFICATION-TYPE
OBJECTS {
cderExcepId,
cderExcepHostAddressType,
cderExcepHostAddress,
cderExcepPriorityDescription,
cderExcepTime,
cderExcepData,
cderExcepReportedBy
}
STATUS current
DESCRIPTION
"This notification is sent when an exception
is detected on the managed device. "
::= { cderMIBNotifications 1 }
This notification is defined as a part of the Cisco mib:
CISCO-DEVICE-EXCEPTION-REPORTING-MIB
In all of the above conditions, the generated trap is the same but the cderExcepData defines what type
of event has taken place.
For example, when a guest user is added, the data field resembles the following:
Guest user 'g45' created on the Controller '10.76.109.84'
Appendix
The following sample test program code can be used as a reference by other application developers.
Sample test program:
/**
*
*/
package com.cisco.ws.test;
import java.io.IOException;
import java.net.URL;
import java.rmi.RemoteException;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Set;
import java.util.StringTokenizer;
import com.cisco.ws.api.ClientApi;
import com.cisco.ws.api.ClientApiServiceLocator;
import com.cisco.ws.api.ConfigTemplateApi;
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
10
OL-15531-01
Appendix
import com.cisco.ws.api.ConfigTemplateApiServiceLocator;
import com.cisco.ws.api.ConfigTemplateApiStub;
import com.cisco.ws.api.GuestUserTemplateWs;
import com.cisco.ws.api.WSException;
import com.cisco.ws.api.ClientApiStub;
public class GuestUserTest {
public static void main(String[] args) throws Exception{
System.out.println("Please make sure that user is precreated on WCS and has
NorthBoundAPI group assigned to it");
if (args.length != 3) {
printUsage();
System.exit(0);
}
System.out.println("WCS IP: " + args[0]);
System.out.println("User Name: " + args[1]);
System.out.println("Password: " + args[2]);
String choice = "1";
ConfigTemplateApi configApi = null;
ConfigTemplateApiServiceLocator serviceLocator = new ConfigTemplateApiServiceLocator();
ClientApiServiceLocator clientserviceLocator = new ClientApiServiceLocator();
URL serviceURL = new URL(args[0] + "/ConfigTemplateApi");
URL clientserviceURL = new URL(args[0] + "/ClientApi");
ClientApi clientApi = null;
configApi = serviceLocator.getConfigTemplateApi(serviceURL);
clientApi = clientserviceLocator.getClientApi(clientserviceURL);
if (configApi == null )
return;
((ConfigTemplateApiStub) configApi).setMaintainSession(true);
configApi.login(args[1], args[2]);
System.out.println("\nUser " + args[1] + " successfully logged in ");
while ( !choice.equals("0")) {
System.out.println("\nYou have the following options\n\n" +
"1. List Existing Guest User templates\n" +
"2. Create NEW Guest Template\n" +
"3. Delete existing Guest template\n"+
"4. Update existing Guest template\n" +
"5. Apply Guest template to controllers\n" +
"6. List Guest Users on controller\n" +
"7. Show details of a guest user\n" +
"8. List controllers with profile\n" +
"9. List Logged in Guest Users on controller\n" +
"a. List User Roles on controller\n" +
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
11
Appendix
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
12
OL-15531-01
Appendix
}
}
clientApi.logout();
break;
//SHOW GUEST DETAILS
case '7':
((ClientApiStub) clientApi).setMaintainSession(true);
clientApi.login(args[1], args[2]);
System.out.println("-Enter Guest User name-");
String gUser1 = readInputString();
System.out.println("-Enter the IP address of the controller-");
String controllerIp1 = readInputString();
HashMap detailsHashmap = clientApi.getGuestUserDetails(gUser1, controllerIp1);
if(!detailsHashmap.isEmpty()){
Set properties = detailsHashmap.keySet();
Iterator It = properties.iterator();
while (It.hasNext()) {
String property = (String)(It.next());
System.out.println(property + " - " + detailsHashmap.get(property));
}
}
else {
System.out.println("Error in getting properties!");
}
clientApi.logout();
break;
//GET CONTROLLERS WITH PROFILE
case '8':
((ClientApiStub) clientApi).setMaintainSession(true);
clientApi.login(args[1], args[2]);
System.out.println("-Enter Profile name-");
String profile = readInputString();
String [] controllerIps =clientApi.getControllersWithProfile(profile);
if(controllerIps.length == 0){
System.out.println("Thre are no controllers with profile-> "+profile);
}
else{
System.out.println("The following cotrollers have the profile \""+profile+"\"
configured ");
for(int i=0; i<controllerIps.length; i++){
System.out.println(controllerIps[i]);
}
}
clientApi.logout();
break;
//GET LOGGED IN GUESTS
case '9' :
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
13
Appendix
((ClientApiStub) clientApi).setMaintainSession(true);
clientApi.login(args[1], args[2]);
System.out.println("-Enter controller IP-");
String controIp = readInputString();
String[] loggedGuests = clientApi.listLoggedInGuestUsersOnController(controIp);
if(loggedGuests.length == 0){
System.out.println("Thre are no Guest users Logged into controller "+controIp);
}
else{
System.out.println("The controller "+controIp+ " has the following Guest
Users-");
for(int i=0; i<loggedGuests.length; i++){
System.out.println(loggedGuests[i]);
}
}
clientApi.logout();
break;
//GET USER ROLES
case 'a' :
((ClientApiStub) clientApi).setMaintainSession(true);
clientApi.login(args[1], args[2]);
System.out.println("-Enter controller IP-");
String switchIP = readInputString();
String[] userRoles = clientApi.getUserRolesOnController(switchIP);
if(userRoles.length == 0){
System.out.println("Thre are no Guest users Logged into controller "+switchIP);
}
else{
System.out.println("The controller "+switchIP+ " has the following User
Roles-");
for(int i=0; i<userRoles.length; i++){
System.out.println(userRoles[i]);
}
}
clientApi.logout();
break;
default : break;
}
} catch (WSException e) {
System.out.println("Error " + e.getMessage());
}
}
configApi.logout();
System.out.println("User " + args[1] + " successfully logged out");
}
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
14
OL-15531-01
Appendix
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
15
Appendix
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
16
OL-15531-01
Appendix
guestUserTemplateWs.setUserPassword(passwd);
System.out.println("-Enter Profile to connect-");
String profile = readInputString();
guestUserTemplateWs.setProfile(profile);
System.out.println("-Enter Guest User Description-");
String desc = readInputString();
guestUserTemplateWs.setDescription(desc);
System.out.println("-Enter Guest Lifetime in timeticks(100th of a sec)-");
String lifeTimeStr = readInputString();
guestUserTemplateWs.setLifeTime(Integer.valueOf(lifeTimeStr));
System.out.println("-Enter Guest Role; Default role is 'default'-");
String roleStr = readInputString();
guestUserTemplateWs.setUserRole(roleStr);
guestUserTemplateWs.setEmailID("");
guestUserTemplateWs.setBuilding("");
guestUserTemplateWs.setCampus("");
guestUserTemplateWs.setConfigGroup("");
guestUserTemplateWs.setOutdoorArea("");
guestUserTemplateWs.setFloorArea("");
System.out.println("-- Creating Guest User template -- ");
configApi.createGuestUserTemplate(guestUserTemplateWs);
System.out.println("\nSuccessfully created Guest User Template ");
}
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
17
Appendix
CCVP, the Cisco logo, and Welcome to the Human Network are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and
Learn is a service mark of Cisco Systems, Inc.; and Access Registrar, Aironet, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, Cisco,
the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity,
Enterprise/Solver, EtherChannel, EtherFast, EtherSwitch, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient,
IOS, iPhone, IP/TV, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard, iQuick Study, LightStream, Linksys, MeetingPlace, MGX, Networkers,
Networking Academy, Network Registrar, PIX, ProConnect, ScriptShare, SMARTnet, StackWise, The Fastest Way to Increase Your Internet
Quotient, and TransPath are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries.
All other trademarks mentioned in this document or Website are the property of their respective owners. The use of the word partner does not imply
a partnership relationship between Cisco and any other company. (0711R)
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
18
OL-15531-01
Appendix
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
OL-15531-01
19
Appendix
WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration
20
OL-15531-01