• What is the Cisco License Manager Software Developer's Kit (SDK)?
• What can Cisco License Manager SDK do for me?
• What do I need to use Cisco License Manager SDK?
• What is in this cookbook?
What Is Cisco License Manager SDK?
Cisco License Manager SDK is a set of Java class libraries that can be linked with your Java application to invoke licensing functions provided by the Cisco License Manager server. These licensing functions include obtaining licenses from Cisco, deploying licenses to devices, and managing inventory of licenses and devices.
What Can Cisco License Manager SDK Do for Me?
Cisco License Manager SDK provides the same set of class libraries used by the Cisco License Manager GUI client program. By using the Cisco License Manager SDK in your Java application, you can integrate full functionality of Cisco License Manager into your own program.
What Do I Need to Use Cisco License Manager SDK?
Before you can start using Cisco License Manager SDK, make sure that:
• You have the Cisco License Manager server installed and running on your computer.
• You have the Cisco License Manager Java SDK installed on your computer.
• You have Java Version 1.6 or later for your Java development environment.
What Is in This Cookbook?
This cookbook covers the most common scenarios for using Cisco License Manager SDK and provides instructions on how to achieve them. You can read each chapter sequentially or independently of other chapters. If you read them independently, we recommend that you read the first three chapters before moving on to other chapters.
Chapter 2: Installation and Setup
• Install Cisco License Manager SDK on my computer
• How to set up my working environment
Installation
To install the Cisco License Manager SDK, complete these steps:
Step 1. Copy clm_java_sdk.zip from the CD to a local drive.
Step 2. Unzip the file.
The folder "CiscoLicenseManager_JAVA_SDK" is created on the local drive.
It contains these files:
– clm-sdk.jar
– clm_ssl_rmi.cert
– javadoc.zip
– conf, a folder containing the file ClmErrorMessages.properties
Setup
To begin using the SDK, complete these steps:
Step 1. Add clm-sdk.jar to the Java classpath when compiling and running the client program. You must use Java Version 6.0 to run Cisco License Manager Release 3.0 SDK.
<CLM_SDK_HOME> : the directory that holds the CLM SDK files.
Step 2. If the Cisco License Manager server has Secure Sockets Layer (SSL) enabled, run the following command to import the Cisco License Manager certificate file, clm_ssl_rmi.cer, to the trust store on your client system:
Step 3. Start the Cisco License Manager server. For details, see the User Guide for Cisco License Manager.
Step 4. Start the client program.
Chapter 3: Getting Started
• My first Cisco License Manager client program, "HelloCLMServer"
• Connect and log in to the Cisco License Manager server
• Compile my client program
• Run my client program
Solution
In this chapter, you create your first client program by using the Cisco License Manager SDK. Your first program, HelloCLMServer, connects and logs you in to the Cisco License Manager server. To achieve this, you complete the following processes in your programs:
Instantiate the LicenseManager Object
First, you create an instance of the LicenseManager class:
static LicenseManager lmInstance = new LicenseManager();
You usually declare the instance as static so that you can use it in other places of your program.
Log In to Cisco License Manager Server
Assume that you have installed Cisco License Manager server on the computer "johndoe-server," and you configured the Cisco License Manager server to use the default port 1099. Assume that you want to log in as "admin" user with password "cisco," and you do not want the connection to time out. This is your code snippet:
// Create an instance of signed EULA agreement.
EulaInfo eula = new EulaInfo(Calendar.getInstance().getTime(), true, true);
• For a more detailed description of the functions used in this program, see Chapter 16 of the Java API Reference Guide for Cisco License Manager.
• If you need to see logs for troubleshooting purposes, you can find them in <CLM_HOME>/log/clm.logfile, where <CLM_HOME> is the directory that holds the Cisco License Manager server installation.
Chapter 4: Device Discovery
• Discover licensable devices in my network
• What protocol should I choose?
• How do I organize discovered devices in groups?
• Schedule a periodic device discovery
Solution
In this chapter, you learn how to discover devices by using the network IP address and a network mask and also how to schedule periodic device discovery to add new devices.
Define and Instantiate a Callback Object
Cisco License Manager discovery runs asynchronously, which means that when this function is called, it runs on the server side and immediately returns a request ID. Therefore, before calling the discover function, you must define a callback function for the Cisco License Manager server to call when discover is complete.
To define your callback function, create your own IDStatusListener class and implement the onStatus function to handle the incoming data.
public class MyIDStatusListener implements IDStatusListener {
public void onStatus(String requestId, IDStatus status) {
For the subnet and subnet mask, you can enter either a network address or an individual IP address. Cisco License Manager converts it to a network address based on the subnet mask and calculates all possible IP addresses in this subnet.
• Grouping
You can organize your discovered devices in groups. There is a Default group already created for you. If you want to put a device in the Default group, just put null; otherwise, make sure the group is already created. Cisco License Manager rejects this call if there is no group found in Cisco License Manager Inventory.
To create a group, call the following API before calling this function:
public Status createDeviceGroup(UserToken token, String group)
throws RemoteException
Status _st=lmInstance.createDeviceGroup(token, "MyGroupName");
• Providing Discovery Authentication Information
You must provide the username and password pairs using the DiscoveryAuthInfo object. The class is defined as follows:
public class DiscoveryAuthInfo implements Serializable {
private UserPwd[] authpairs;
public DiscoveryAuthInfo(UserPwd[] auths){
authpairs = auths;
}
public UserPwd[] getUserPwdPairs(){
return authpairs;
}
}
public class UserPwd implements Serializable {
private String username = "";
private String passwd = "";
public UserPwd(String name, String pwd);
}
– To discover all devices in the subnet, you might want to enter all possible username and password pairs.
– The enable password also uses the same UserPwd class by assigning only the enable password as the password.
– Because Cisco License Manager uses all possible combinations of the username/password pairs, it might take a long time to complete if you enter too many username/password pairs.
• Choosing Protocols for Discovery
Cisco License Manager supports four different kinds of transport methods or protocols for discovery: HTTP, HTTPS, Telnet, and Secure Shell (SSH) Protocol. They are defined in the Device class as public enum values.
public enum TransportMethod {HTTP, HTTPS, TELNET, SSH};
1. You can specify any combination of the transport methods that you want to use for discovery.
2. If all of your network devices are license agent enabled, you can use only HTTP. Otherwise, you can use HTTP and Telnet.
3. Using all four transport methods results in longer discovery time.
4. If you have a network with a variety of devices using all sorts of protocols for access and different username/password/enable password, you might want to discover them in different discovery calls to reduce discovery time.
• Running a Policy
You can also run a policy after discovery by providing the policy IDs in the call. The policy should be created so that you can pass the policy ID. To learn how to create a policy, see Chapter 12: Policy Licensing.
Schedule a Discovery
You can schedule a device discovery by registering a discovery task into the Cisco License Manager Scheduler. The parameters of the scheduler are similar to those for regular device discovery plus the frequency of the discovery. Scheduled discovery allows you to enter more than one set of network addresses and masks.
public Status registerScheduler(UserToken token,
ClmTask taskName,
Schedule schedule )
throws RemoteException;
Where
• taskName is an enum value and should be defined as ClmTask.DISCOVER_DEVICES
• schedule object should contain the starting date, frequency of the discovery, discoverySettings, and policyIds
The Schedule class contains DiscoverySetting, which is designed to contain all the necessary parameters for running discovery. The attributes in the class definition are the same as the parameters used in asyncDiscoverDevices.
public class DiscoverySetting implements Serializable {
private TransportMethod[] transmethods;
private String devgroup;
private DiscoveryAuthInfo discoveryAuth;
private String netIpaddr;
private String netMask;
private String[] policyIds;
}
See the preceding bullet "Construct a Discovery Request" for the parameter details.
Calls to the asyncDiscoverDevices API will return right away with a unique request ID. You can query the CLM server with the request ID for the status of the task using the getAsyncOperationStatus API.
The while loop checks whether the listener callback has been called by CLM server and sets m_IDStatusListenerInvoked to true to break out of the loop.
• For more detailed descriptions of functions used in this program, see Chapter 5 of the Java API Reference Guide for Cisco License Manager.
Chapter 5: Adding Devices to Inventory
• How do I add new devices without going through discovery?
• Add new device by IP address
• Add new device by UDI
Solution
In this chapter, you learn how to create a device with a unique device identifier (UDI) or with an IP address.
Create Device by UDI
This API is mainly used in managing devices in an isolated network. See the "Two Stage Deployment" section of the following white paper for more information:
In a two-stage environment, you first create a device with its UDI and obtain a license with the UDI in a network that can access Cisco.com. In the second stage, you bring the server to a private network where the device resides, fill in device connection information, and poll or discover the device and deploy licenses obtained in the first stage. This chapter only covers the creation part. Obtaining licenses, polling licenses, and discovering devices are covered by other chapters.
Assume you already instantiated the LicenseManager object (licMgr), logged in to the server, and obtained a valid token. This example creates a device with a UDI "C3900-SPE100/K9:FHH13010044" in a group called "myGroup". The UDI is a unique ID used to identify a device and has the format of <ProductID>:<SerialNumber>. In this example, C3900-SPE100/K9 is the product ID, and FHH13010044 is the serial number.
• Create the group if it does not exist already.
licMgr.createDeviceGroup(token, group);
• Create a device with a given UDI.
String[] udis = { "C3900-SPE100/K9:FHH13010044" }
DeviceStatus status =
licMgr.createDevicesByUDI(token, udis, group);
• Check the top-level return value to see whether the operation is successful.
if (status.getErrorCode() != ClmErrors.SUCCESS) {
System.out.println("Operation failed, msg: " +
status.getErrorMessage());
return;
}
DeviceStatusItem[] items =
status.getDeviceStatusItems();
• Check the return value for the individual item. In this example, there is only one item.
Assume you already instantiated the LicenseManager object (licMgr), logged in to the server, and obtained a valid token.
This example creates a device with an IP address and login information.
• Set the device login credentials. This includes the username, password, and the enable password, if applicable. You can set multiple pairs, and the API tries all possibilities until it is successful.
UserPwd[] userpwds = new UserPwd[2];
userpwds[0] = new UserPwd("usr1", "pwd1");
userpwds[1] = new UserPwd("usr2", "pwd2");
DiscoveryAuthInfo authinfo = new
DiscoveryAuthInfo(userpwds);
• Set the transport method. The transport method is used to connect to a device. You can specify multiple transport methods to try. The TransportMethodInfo object contains a transport method and a port number. If a port is set to -1, it uses the default port for the specified protocol.
// check individual error status. There should only be
// one entry
if (items[0].getErrorCode()!=ClmErrors.SUCCESS) {
System.out.println("Operation failed for ip: " +
ipaddr + ", msg: " + items[0].getErrorMessage());
}
else {
Device dev = items[0].getDevice();
// continue process device
}
}
catch (Exception e) {}
}
}
See Also
• For detailed information on polling license information from a device, see Chapter 6.
• For detailed information on device discovery, see Chapter 4.
Chapter 6: Polling Licensing Information from a Device
• How do I get licensing information from a device?
• What licensable features are in a device?
• What licenses have been deployed for each feature?
Solution
In this chapter, the program CLMPollILicenseApp is developed to show how to poll licenses on a device and then read the license information from the Device object. To achieve this, your program will do the following:
- Log in to the Cisco License Manager server
- Poll license information
- Read license information
- Log out from the server
Poll Licenses
First, the program polls licenses on a device with UDI CISCO2821:FTX1201A29D.
The asynchronous call asyncPollDeviceLicenseInfo requests the server to perform a license poll. When the request is complete, the function onStatus() in the passed IDStatusListener object is called.
public void onStatus(String arg0, IDStatus arg1) {
// TODO Auto-generated method stub
if (arg1.getErrorCode() == ClmErrors.SUCCESS)
System.out.println("Poll license success");
else
System.out.println("Poll license error: code="
+ arg1.getErrorCode());
done = true;
}
The done flag causes the program to continue with the read licenses calls. After the poll license call is completed, the device object in the server has the up-to-date information.
Read Licenses
The device object is retrieved with the device identifier or UDI. The readDevices() call gets the device status, which has the device object in the DeviceStatusItem[].
Because download PAK is an asynchronous call, the Cisco License Manager server immediately returns a request ID. Your client program must set up a callback function for the Cisco License Manager server to call upon completion of the download operation. You must implement the onStatus function in your callback function:
public class MyIDStatusListener implements IDStatusListener {
public void onStatus(String requestId, IDStatus status) {
idSt = status;
idStatusListenerInvoked = true;
}
}
Download PAK Information from Cisco.com
Your user profile should have the Cisco.com username and password set correctly to download the PAK from Cisco.com.
String[] intenalIds = new String[1];
// get PAK internal ID, this ID is used as a key to identify PAK
System.out.println("return from downloadPAK demo");
System.exit(0);
} catch (RemoteException e) {
e.printStackTrace();
System.exit(-1);
}
}
}
See Also
• For getting started information, see Chapters 1, 2, and 3.
Chapter 8: Obtaining Licenses
• What are SKU and quantity in a PAK?
SKU stands for Stock Keeping Unit; software on Cisco.com is a "SKU." A SKU maps to one or more license features.
• How do I obtain licenses for a device?
You must retrieve SKU information from Cisco License Manager Inventory, construct a LicenseRequest object by using the SKU and the device, and call the asyncObtainLicense() API to obtain a license for a device.
Solution
In this chapter, you create a client program using the Cisco License Manager SDK to obtain licenses from the Cisco License Registration Server. The program, called ObtainLicenseDemo.java, connects and logs you in to the Cisco License Manager server, constructs LicenseRequest, and calls the asyncObtainLicense() API to obtain new licenses.
Write a Listener to Implement the IDStatusListener Callback Interface
The asyncObtainLicense() function runs asynchronously, which means that when this function is called, it runs on the server side and immediately returns a request ID. Therefore, before calling the asyncObtainLicense() function, you must set up a callback function for the Cisco License Manager server to call upon when asyncObtainLicense() completes.
public class MyIDStatusListener implements IDStatusListener {
IDStatus idSt = null;
boolean idStatusListenerInvoked = false;
public void onStatus(String request_id, IDStatus status) {
m_logger.debug("MyIDStatusListener for " + request_id + " invoked");idSt=status;
idStatusListenerInvoked = true;
}
public IDStatus getIDStatus() {
return idSt;
}
public boolean isIDStatusListenerInvoked() {
return idStatusListenerInvoked;
}
}
Create an Instance of the LicenseManager Class
static LicenseManager lm_instance = new LicenseManager();
Log In to the Cisco License Manager Server
// Create an instance of signed EULA agreement.
Calendar cldr = Calendar.getInstance();
EulaInfo eula = new EulaInfo(cldr.getTime(), true, true);
System.out.println("return from obtain licenses demo");
System.exit(0);
} catch (RemoteException e) {
e.printStackTrace();
System.exit(-1);
}
}
}
See Also
• For login functions to the Cisco License Manager server, see Chapter 3.
• For detailed descriptions of functions used in this program, see Chapter 16 of the Java API Reference Guide for Cisco License Manager.
Chapter 9: Deploying Licenses
• Where are my undeployed licenses?
When a license is marked as undeployed in Cisco License Manager Inventory, the license is still kept in Cisco License Manager but is cleared from the device. The license might still be valid, binding with that device.
• How do I deploy licenses to devices?
You can use the Cisco License Manager asyncDeployLicenses() API to deploy the license to the device if it is not read-only.
Solution
In this chapter, you create a client program using the Cisco License Manager SDK to deploy licenses to the device. The program, called DeployLicenseDemo.java, connects and logs you in to the Cisco License Manager server, and calls the asyncDeployLicenses() API to deploy licenses to the device.
Write a Listener to Implement the IDStatusListener Callback Interface
The asyncDeployLicenses() function runs asynchronously, which means that when this function is called, it runs on the server side and immediately returns a request ID. Therefore, before calling the asyncDeployLicenses() function, you must set up a callback function for the Cisco License Manager server to call upon when asyncDeployLicenses() completes.
public class MyIDStatusListener implements IDStatusListener {
IDStatus idSt = null;
boolean idStatusListenerInvoked = false;
public void onStatus(String request_id, IDStatus status) {
m_logger.debug("MyIDStatusListener for " + request_id + " invoked");
idSt=status;
IdStatusListenerInvoked = true;
}
public IDStatus getIDStatus() {
return idSt;
}
public boolean isIDStatusListenerInvoked() {
return idStatusListenerInvoked;
}
}
Create an Instance of the LicenseManager Class
static LicenseManager lm_instance = new LicenseManager();
Log In to the Cisco License Manager Server
// Create an instance of signed EULA agreement.
EulaInfo eula = new EulaInfo(Calendar.getInstance().getTime(), true, true);
System.out.println("return from deploy licenses demo");
System.exit(0);
} catch (RemoteException e) {
e.printStackTrace();
System.exit(-1);
}
}
}
See Also
• For login functions to the Cisco License Manager server, see Chapter 3.
• For detailed descriptions of functions used in this program, see Chapter 16 of the Java API Reference Guide for Cisco License Manager.
Chapter 10: Listening to Device Notifications
• How do I register a listener?
• What do I do with the incoming notifications from devices?
Solution
In this chapter, the program CLMRegisterNotificationApp is developed to show how to listen for device notifications. To achieve this, your program will do the following:
• Log in to the Cisco License Manager server
• Register for notifications
• Log out from the Cisco License Manager server
Register for Notifications
Use the call registerNotificationListener to register a listener for all notifications. Passed in the listener is a NotificationListener object. NotificationListener.onNotification() is invoked when a notification event arrives. The Notification object contains the detailed information.
Notification.Operation op = notification.getOperation();
String devId = null;
String licLineId = null;
System.out.println("Notification, type is: " + op.toString());
if (op.equals(Notification.Operation.EXPIRED)) {
devId = notification.getDeviceId();
licLineId = notification.getLiclineId();
if (devId != null)
System.out.println("Device id=" + devId);
System.out.println("Expired notification: ");
if (licLineId != null)
System.out.println("License line id=" + licLineId);
} else if (op.equals(Notification.Operation.INSTALL)) {
devId = notification.getDeviceId();
licLineId = notification.getLiclineId();
if (devId != null)
System.out.println("Device id=" + devId);
System.out.println("Deployed or installed notification: ");
if (licLineId != null)
System.out.println("License line id=" + licLineId);
}
}
The example NotificationListener.onNotification() looks for the license expired and license install notifications, and prints the device UDI and the license line ID associated with the notifications.
System.out.println("License line id=" + licLineId);
} else if (op.equals(Notification.Operation.INSTALL)) {
devId = notif.getDeviceId();
licLineId = notif.getLiclineId();
if (devId != null)
System.out.println("Device id=" + devId);
System.out.println("Deployed or installed notification: ");
if (licLineId != null)
System.out.println("License line id=" + licLineId);
}
}
});
} catch (RemoteException e) {
System.out.println(e.toString());
e.printStackTrace();
}
}
// main of the program.
public static void main(String[] args) {
CLMDeviceNotificationApp app = new CLMDeviceNotificationApp();
app.initServer();
app.registerNotification();
// wait forever until user terminates
while (!done) {
try {
Thread.sleep(100);
} catch (InterruptedException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
}
app.finiServer();
System.out.println("App ends");
}
}
See Also
• For login functions to the Cisco License Manager server, see Chapter 3.
• For detailed descriptions of functions used in this program, see Chapter 16 of the Java API Reference Guide for Cisco License Manager.
Chapter 11: Transferring Licenses
• How do I transfer (rehost) licenses from one device to another?
• What are permission tickets and rehost tickets?
• What licenses can be transferred?
Solution
In this chapter, you learn how to transfer licenses from one device to another by using the Cisco License Manager Java API. To transfer a license from a source device, you need a permission ticket from Cisco.com and a rehost ticket from the source device. A permission ticket is a certificate from the Cisco licensing back-end server to start a license transfer process. A rehost ticket is a certificate generated by the router for the Cisco licensing back-end server to confirm the revoke operation.
License transfer involves four major steps:
1. Getting the permission ticket from Cisco.com for the source device
2. Retrieving the rehost ticket from the source device
3. Sending the rehost ticket to Cisco.com to obtain licenses for the destination device
4. Deploying the newly obtained licenses to the destination device
Currently, you can transfer only permanent licenses.
Cisco License Manager provides APIs for transferring licenses by using a step-by-step approach as well as an atomic approach by using a single API. For the step-by-step approach, use the following four APIs in sequence:
• public Status initRehostLicense(UserToken token, RehostRequest rehostReq)
• public Status revokeLicenseForRehost(UserToken token, RehostRequest rehostReq)
• public Status obtainLicenseForRehost(UserToken token, RehostRequest rehostReq)
If the source and destination devices already exist in Cisco License Manager Inventory, use listAllDevices or listAllDevicesInGroup to get the source and destination device ID.
Construct the rehost request specifying the source device ID, the destination device ID, and the SKUs that you want to transfer from the source device to the destination device.
//Construct the RehostRequest, containing the source and destination device IDs and the SKU selection
RehostRequest rr = new RehostRequest();
//set the destination device ID
rr.setDestDeviceID(destDeviceID);
//set the source device ID
rr.setSourceDeviceID(srcDeviceID);
//set the SKUs to be transferred
rr.setSKUSelection(skus);
Rehost a License
Transfer the license. After the successful license transfer, the license is deployed to the destination device.
Status rehostStatus = lmInstance.rehostLicense(token, rr);
• For login functions to the Cisco License Manager server, see Chapter 3.
• For detailed descriptions of functions used in this program, see Chapter 7 of the Java API Reference Guide for Cisco License Manager.
Chapter 12: Policy Licensing
• What is rule-based licensing using a policy?
• How do I create a policy?
• How do I filter devices?
• How do I execute a policy?
Solution
In this chapter, you learn about rule-based licensing using a policy. You write a client program to create a policy by using the Cisco License Manager SDK. You also learn how to filter devices with the policy you created as well as how to run the policy by using the Cisco License Manager SDK.
The Cisco License Manager SDK supports rule-based policies. Policies are used to get licenses and deploy licenses to devices based on user-specified criteria (or rules). Policies provide an automated process that scans your network and adds features to your specified devices. A policy contains two rules:
• SKU rule that is used to select SKUs of interest
• Device rule that is used to select devices of interest
You can specify the following criteria to select SKUs of interest:
• PAK
• SKU
• Feature name
You can specify the following criteria to select devices of interest:
• Device group
• Device model
• Device IP address range
To create a policy, you will do the following in your program:
Create a Policy
First, you create a policy (for example, "policy_1"):
PolicyStatus status = lmInstance.createPolicy(token,
policy_1", null, null);
Set the SKU Rule
To set the SKU rule, you get the policy object you just created:
Policy policy = status.getPolicy();
Next, create a SKUFilter object with the desired feature name (for example, "ipservices") and set the SKUFilter:
SKUFilter skuFilter = new SKUFilter("ipservices");
policy.setSKUFilter(skuFilter);
You can find out all the available features in the Cisco License Manager database using the enumerateSKUFilterAttribute API:
String[] features = lmInstance.enumerateSKUFilterAttribute(
token, Policy.SKUAttribute.FEATURE_NAME);
After creating the SKUFilter object, you set SKUIdentifier, which contains the desired PAK and SKU information:
You can set all, some, or none of the device filter criteria. You can do the following in your program to set a device rule:
DeviceFilter deviceFilter = new DeviceFilter();
deviceFilter.setModel("3845");
deviceFilter.setGroup("Default");
deviceFilter.setIPLowerLimit("10.1.2.10");
deviceFilter.setIPUpperLimit("10.1.2.20");
policy.setDeviceFilter(deviceFilter);
Write the Policy
After setting up the SKU and device rules, you write the policy to the Cisco License Manager database in your program:
Status status = lmInstance.writePolicy(token, policy);
To execute a policy, you use the asyncExecutePolicy API in your program. The asyncExecutePolicy API is an asynchronous function, and you must provide a listener to find the status of this operation. The callback function of this listener is called when the policy execution is completed. The following is what you will do:
Here is the sample client program for creating, filtering, and executing a policy:
import com.cisco.nm.clm.sdk.*;
import com.cisco.nm.clm.common.*;
import java.rmi.RemoteException;
import java.util.Calendar;
public class CLMPolicyTest {
static protected LicenseManager lmInstance;
static protected UserToken token;
static protected Policy policy;
public CLMPolicyTest() {
}
/**
* Initialize and log in to LicenseManager
*/
public void init() {
lmInstance = new LicenseManager();
EulaInfo eula = new EulaInfo(
Calendar.getInstance().getTime(), true, true);
try {
token = lmInstance.login("admin", cisco",
"localhost", 1099, 0, eula);
} catch (RemoteException e) {
e.printStackTrace();
}
}
/**
* Log out from LicenseManager
*/
public void close() {
try {
lmInstance.logout(token);
} catch (RemoteException e) {
e.printStackTrace();
}
}
/**
* Create a policy
*/
public void createPolicy() {
try {
PolicyStatus status = lmInstance.createPolicy(token,
"policy_1", null, null);
if (status == null || status.getErrorCode()
!= ClmErrors.SUCCESS) {
System.out.println("Create policy failed!");
} else {
System.out.println("Create policy succeeded!");
policy = status.getPolicy();
}
} catch (RemoteException e) {
e.printStackTrace();
}
}
/**
* Set SKU rule
*/
public void setSkuRule() {
try {
SKUFilter skuFilter = new SKUFilter("gatekeeper");
policy.setSKUFilter(skuFilter);
SKUIdentifier[] allIdentifiers =
lmInstance.listFilteredSKUs(token, skuFilter);
SKUIdentifier[] identifierToUse = new SKUIdentifier[1];
identifierToUse[0] = allIdentifiers[0];
policy.setSKUsInUse(identifierToUse);
} catch (RemoteException e) {
e.printStackTrace();
}
}
/**
* Set Device rule
*/
public void setDeviceRule() {
DeviceFilter deviceFilter = new DeviceFilter();
deviceFilter.setModel("2821");
deviceFilter.setIPLowerLimit("172.19.205.70");
deviceFilter.setIPUpperLimit("172.19.205.80");
policy.setDeviceFilter(deviceFilter);
}
/**
* Write the policy
*/
public void writePolicy() {
try {
Status status = lmInstance.writePolicy(token, policy);
if (status == null || status.getErrorCode()
!= ClmErrors.SUCCESS) {
System.out.println("Write policy failed!");
} else {
System.out.println("Write policy succeeded!");
}
} catch (RemoteException e) {
e.printStackTrace();
}
}
/**
* Run a policy
*/
public void executePolicy() {
try {
MyIDStatusListener listener = new MyIDStatusListener();
String requestId = lmInstance.asyncExecutePolicy(
token, null, policy.getID(), listener);
System.out.println("Execute policy started,
the request ID is "+requestId);
} catch (RemoteException e) {
e.printStackTrace();
}
}
/**
* @param args
*/
public static void main(String[] args) {
CLMPolicyTest testApp = new CLMPolicyTest();
testApp.init();
testApp.createPolicy();
testApp.setSkuRule();
testApp.setDeviceRule();
testApp.writePolicy();
testApp.executePolicy();
testApp.close();
}
public class MyIDStatusListener implements
IDStatusListener {
public void onStatus(String requestId, IDStatus status) {
System.out.println("MyIDStatusListener for
request "+requestId+" callback invoked");
System.out.println("Policy executed,
returned error code "+status.getErrorCode());
}
}
}
See Also
• For detailed descriptions of functions used in this program, see Chapter 12 of the Java API Reference Guide for Cisco License Manager.
• For login functions to the Cisco License Manager server, see Chapter 3.
Chapter 13: Generating Reports
• What reports are supported?
• How do I generate a report?
• How do I read a report?
• How do I filter a report?
Solution
In this chapter, you learn what types of reports Cisco License Manager provides. You write a client program to generate and read reports by using the Cisco License Manager SDK. Furthermore, you learn how to filter a large report to find the desired information by using the Cisco License Manager SDK.
Cisco License Manager supports these types of reports:
• Audit Trail Report
• Device Summary Report
• Hardware End of Life and End of Sale Report
• License Discrepancy Report
• License Expiry Report
• Newly Discovered Device Report
• PSIRT Summary Report
• PSIRT Details Report
• Redeployable License Report
• RMA Discrepancy Report
• Software End of Life and End of Sale Report
• Undeployed License Report
Generate a Report
You need to generate a report before reading and viewing the report. To generate a report, you specify which type of report you are interested in by specifying the ReportSubject. This is what you do in your program:
Status status = lmInstance.generateReport(token,
ReportSubject.DEVICE_SUMMARY, null);
Read a Report
Reports are generated on the Cisco License Manager server in HTML format. You use the readReport API to find the URL of the generated report. You can then display the report in a browser or use it in other applications. To read a report, this is what you do in your program:
ReportStatus status = lmInstance.readReport(token,
ReportSubject.DEVICE_SUMMARY,
OutputFormat.HTML);
String reportURL = status.getContent();
Report Filters
You can filter a report to trim down its content if the report is too large. You can use these criteria to find matching devices for a report filter:
• Device model
• Device group
• Device IP address range
• Device license capability
• Software version on device
• Type of license on device
• Numbers of days to license expiration
• PAK name
• Feature name
To find the possible values for the device model or the device group, use the enumerateDeviceFilterAttribute API as follows in your code:
Possible values for device license capability are: Annotate, Deploy, Rehost, and Resend.
Possible values for the type of license on the device are: Evaluation, Extension, Permanent, Evaluation Subscription, Extension Subscription, Paid Subscription, Trial, and Unknown.
To find the possible values for PAK name, use the listAllPAKs API as follows:
