Product Documentation

Java SDK

Dec 18, 2015

Command Center NITRO APIs are categorized based on the actions that can be performed on the Command Center server. Each category is grouped into different packages which consists of classes that provide the APIs to perform the operations.

For example, APIs to discover devices are available in the com.citrix.cmdctr.nitro.resource.discovery package. Similarly, APIs to configure the Command Center are available in the com.citrix.cmdctr.nitro.resource.configuration package.

For detailed information on the APIs, refer to the API reference available in the <NITRO_SDK_HOME>/doc/api_reference folder.

Logging on to the Command Center Server

The first step towards using NITRO API is to establish a session with the server and then authenticate the session by using the administrator's credentials.

You must create an object of the com.citrix.cmdctr.nitro.service.nitro_service class by specifying the IP address of the Command Center server, the protocol to be used to connect to the server (HTTP or HTTPS), and the port number. You then use this object to log on to the server.

Note: You must have a user account on that server. The configuration operations that you perform are limited by the administrative roles assigned to your account.

The following sample code establishes a session with a Command Center server with IP address 10.102.29.9 and port 8443, by using HTTPS protocol:

//Specify the Command Center server IP address, protocol, and port 
nitro_service c = new nitro_service ("10.102.29.9",8443,"https"); 
 
//Specify the login credentials 
c.login ("admin","verysecret");
Note: You must use the nitro_service object in all further NITRO operations on the server.
Note: The default port for HTTP is 9090 and for HTTPS is 8443. You can modify the ports of the Command Center server by using the com.citrix.cmdctr.nitro.resource.admin.access_setting class.
Note: By default, the connection to the server expires after 30 minutes of inactivity. You can modify the timeout period by specifying a new timeout period (in seconds) in the login method. For example, to modify the timeout period to 60 minutes:
c.login("admin","verysecret",3600);

Adding Device Profiles

To discover devices on a Command Center server you must first configure a device profile that specifies the credentials and SNMP details of the device you want to discover. The APIs are provided by the com.citrix.cmdctr.nitro.resource.discovery.device_profile class.

Example: To add a device profile named "my_profile1" for a NetScaler appliance with username as "user1" and password as "secret".

device_profile dpTO = new device_profile(); 
device_profile_details details = new device_profile_details(); 
 
dpTO.set_name("my_profile1"); 
dpTO.set_device_family("NS"); 
dpTO.set_desc("NetScaler profile using NITRO API"); 
 
details.set_ssh_user_name("user1"); 
details.set_ssh_password("secret"); 
details.set_ssh_port("22"); 
details.set_ssh_retry_count("3"); 
details.set_ssh_timeout("5"); 
 
details.set_sftp_user_name("nsroot"); 
details.set_sftp_password("nsroot"); 
details.set_sftp_port("22"); 
details.set_sftp_timeout("5"); 
details.set_sftp_retry_count("5"); 
details.set_snmp_community("public"); 
details.set_snmp_port("161"); 
details.set_snmp_version("v2"); 
 
dpTO.set_prof_details(details); 
device_profile.add(c,dpTO);

Adding Devices

To add a device to a Command Center server you must specify the details of the device (IP address or hostname) and associate the device profile. The server automatically discovers the device by using the specified details.

The APIs to add a device are provided by the com.citrix.cmdctr.nitro.resource.discovery.device_discovery_data class.

Example: To add a NetScaler appliance with IP address 10.102.43.4 by using a profile named "my_profile1".

device_discovery_data discoveryData = new device_discovery_data(); 
discoveryData.set_devices("10.102.43.4"); 
discoveryData.set_profile_name("my_profile1"); 
device_discovery_data.discover(c,discoveryData);

Monitoring Services and Virtual Servers

You can monitor the services, service groups, and virtual servers across the Netscaler devices that are configured on the Command Center server by using APIs that are provided by the com.citrix.cmdctr.nitro.resource.monitoring package.

Example: To get the virtual servers available on configured NetScaler appliances.
//Get virtual servers 
options opts = new options(); 
opts.set_pagesize(20); 
opts.set_pageno(1); 
opts.set_ascending((new Boolean("true")).booleanValue()); 
opts.set_orderby("vsvr_name"); 
 
vserver vsvr[] = vserver.get(c,opts); 
 
//Get criteria-based virtual servers 
filtervalue[]  filterval= {new filtervalue("ns_ip","10.102.43.4")}; 
vserver vsvr1[] = vserver.get_filtered(c,filterval,opts);

Creating Performance Reports

The Command Center server stores performance data of the discovered devices. You can use this data to create reports that can help you analyze the performance of the devices.

You can create quick reports by using the APIs provided by the com.citrix.cmdctr.nitro.resource.reporting.quick_report_execdata class.

Example: To get a quick report of a device with IP address 10.102.43.4 for the current day.
quick_report_execdata qrExecData = new quick_report_execdata(); 
qrExecData.set_device_name("10.102.43.4"); 
qrExecData.set_group_name("nsIfStatsTable"); 
qrExecData.set_counter_name("rxRawBandwidthUsage"); 
qrExecData.set_counter_complete_name("nsIfStatsTable_rxRawBandwidthUsage"); 
 
qrExecData.set_exclude_zero(false); 
qrExecData.set_graph_type("LineGraph"); 
qrExecData.set_period("Today"); 
 
qrExecData = quick_report_execdata.execute(c,qrExecData); 
graph_details details = qrExecData.get_graph_details(); 
System.out.println("Report URL: " +details.get_image_url());

You can create custom reports by using the APIs provided by the com.citrix.cmdctr.nitro.resource.reporting.custom_report_execdata class.

Example: To get a custom report of CPU-memory utilization for the current day.
custom_report_execdata crExecData = new custom_report_execdata(); 
crExecData.set_custom_report_name("CPU-MemoryUtilization"); 
crExecData.set_custom_report_display_name("ResourceUtilization"); 
crExecData.set_device_names("10.102.43.4"); 
crExecData.set_exclude_zero(false); 
crExecData.set_graph_type("LineGraph"); 
crExecData.set_period("Today"); 
 
crExecData = custom_report_execdata.execute(c,crExecData); 
graph_details details = crExecData.get_graph_details(); 
System.out.println("Custom Report URL: " +details.get_image_url());

Managing Device Certificates

You can manage the certificates of the devices discovered on the Command Center server by using the APIs provided by the com.citrix.cmdctr.nitro.resource.certificate package.

Example: To retrieve details of the certificates of discovered devices.

certificate[] cer = certificate.get(service); 
long certcount = certificate.count(service); 
 
System.out.println("Total Number of Certificates displayed : " +certcount); 
 
for (int i=0; i< certcount;i++) 
{ 
    System.out.println("Agent: " +cer[i].get_agent()); 
    System.out.println("Cert Name : " +cer[i].get_cert_name()); 
    System.out.println("Certificate path : " +cer[i].get_cert_path()); 
    System.out.println("Key path : " +cer[i].get_key_path()); 
    System.out.println("Days to Expire: " +cer[i].get_days_to_expire()); 
    System.out.println("Device Label: " +cer[i].get_label()); 
}

Monitoring Configuration Changes

You can monitor configuration changes across devices by using audit policies on the Command Center server. The APIs for this are provided in the com.citrix.cmdctr.nitro.resource.changemgmt package.

Example: To execute an audit policy.
audit_policy_execdata apExecData = new audit_policy_execdata(); 
apExecData.set_device_selected(true); 
apExecData.set_policy_name("RunningVsSavedConfiguration"); 
apExecData.set_selected_devices(new String[] {"10.102.43.4"}); 
apExecData.set_operation("execute"); 
apExecData = audit_policy_execdata.execute(c,apExecData); 
 
//Audit report 
System.out.println("id:"+apExecData.get_auditreport_id()); 
ns_audit_report auditReport = ns_audit_report.get(c,apExecData.get_auditreport_id()); 
System.out.println("name:"+auditReport.get_report_id()); 
System.out.println("name:"+auditReport.get_instance_name()); 
System.out.println("Audit By:"+auditReport.get_exec_by()); 
System.out.println("Status:"+auditReport.get_status()); 
 
//Device-specific report 
ns_audit_report_device_details_info deviceDetails = ns_audit_report_device_details_info.get(c,apExecData.get_auditreport_id(),"10.102.43.4"); 
System.out.println("device details id:"+deviceDetails.get_report_id()); 
System.out.println("device:"+deviceDetails.get_device_name()); 
System.out.println("status:"+deviceDetails.get_status());
Example: To schedule an audit policy.
audit_policy_execdata apExecData = new audit_policy_execdata(); 
apExecData.set_device_selected(true); 
apExecData.set_policy_name("ConfigurationChangeHistory"); 
apExecData.set_selected_devices(new String[] {"10.102.43.4"}); 
apExecData.set_operation("schedule"); 
apExecData.set_ccevent_duration("10"); 
apExecData.set_ccevent_duration_condition("<="); 
apExecData.set_ccevent_duration_type(com.citrix.cmdctr.nitro.resource.AttributeNames.TIME_OPTION_IN_DAYS); 
 
//Set Scheduling details 
apExecData.set_scheduler_type(TaskConstants.SCHEDULER_TYPE_DAYBASED); 
apExecData.set_scheduled_days(new String[]{"5", "6"}); 
apExecData.set_scheduled_hours("11,12,20"); 
 
audit_policy_execdata.schedule(c,apExecData);

Using Tasks to Configure Managed Devices

You can configure the devices available on the Command Center server by using built-in tasks or by defining custom tasks. The APIs are available in the com.citrix.cmdctr.nitro.resource.configuration package.

Example: To add a custom task and to execute it.
ns_task nsTask = ns_task.get(c,"newtask"); 
System.out.println("nsTask="+nsTask); 
ns_task_execution_data nsExecData = new ns_task_execution_data(); 
nsExecData.set_task_name("newtask"); 
nsExecData.set_device_list(new String[]{"10.102.43.4"}); 
scheduler_data schedData = new scheduler_data(); 
schedData.set_recurr_type(TaskConstants.NO_RECURRING); 
nsExecData.set_scheduler_data(schedData); 
nsExecData.set_executed_by("root"); 
nsExecData.set_annotation("executing task using NITRO APIs"); 
 
Properties userInputProps = new Properties(); 
ns_task_variables nsTaskVariables[] = nsTask.get_task_variable_list(); 
 
if (nsTaskVariables != null)  
{ 
    for (int i=0;i<nsTaskVariables.length;i++) 
    { 
        userInputProps.setProperty("$UserInput$" + nsTaskVariables[i].get_name(),"xyz"); 
    } 
    nsExecData.set_user_input_props(userInputProps); 
} 
 
nsExecData = ns_task_execution_data.execute(c,nsExecData); 
 
int ids[] = nsExecData.get_execution_ids(); 
System.out.println("ids="+ids.length); 
Thread.sleep(5000); 
ns_task_status taskStatus = ns_task_status.get(c,ids[0]); 
System.out.println("taskStatus deviceId = "+taskStatus.get_device_id()); 
System.out.println("taskStatus status = "+taskStatus.get_status()); 
System.out.println("taskStatus annotation = "+taskStatus.get_annotation()); 
 
filtervalue[]  value= {new filtervalue("id",String.valueOf(taskStatus.get_taskexecution_id()))}; 
command_log cmdlog[] = command_log.get_filtered(c,value); 
for(int i=0;i<cmdlog.length;i++) 
{ 
	System.out.println("command = "+cmdlog[i].get_identifier()); 
	System.out.println("status = "+cmdlog[i].get_status()); 
}
Example: To schedule a custom task.
ns_task_execution_data nsExecData = new ns_task_execution_data(); 
nsExecData.set_task_name("newtask"); 
nsExecData.set_device_list(new String[]{"10.102.43.4"}); 
scheduler_data schedData = new scheduler_data(); 
schedData.set_recurr_type(TaskConstants.NO_RECURRING); 
long scheduleTime = new Date().getTime() + (24*60*60*1000); 
schedData.set_schedule_date_time(new Date(scheduleTime)); 
nsExecData.set_scheduler_data(schedData); 
nsExecData.set_executed_by("root"); 
nsExecData.set_annotation("Scheduling task using NITRO APIs"); 
 
ns_task_execution_data.execute(c,nsExecData);

Migrating NetScaler Configurations

You can port the configurations from a source NetScaler appliance to target NetScaler appliances using one of the following approaches, described in this section:

  • Directly from Source to Target
  • After Editing the Configurations

The APIs to migrate configurations are provided by the com.citrix.cmdctr.nitro.resource.configuration.configuration_template class.

Directly from Source to Target

In this approach, you specify the source NetScaler details and the details of the NetScaler to which you want to migrate the configurations.

Example: To migrate the configurations of NetScaler appliance with IP address "10.102.5.6" to NetScaler appliances with IP addresses "10.102.40.60" and "10.102.40.17".

configuration_template config = new configuration_template(); 
config.set_action("execute"); 
config.set_source_device("10.102.5.6"); 
config.set_configuration_period("LastOneWeek"); 
config.set_name("config_rest"); 
config.set_device_family("NS"); 
config.set_devices(["10.102.40.60","10.102.40.17"]); 
configuration_template.execute(c,config);

After Editing the Configurations

You must retrieve the NetScaler configurations. These configurations are saved as a text file in the <Command_Center_Home>\temp directory. Then, you can edit the configurations as required and port them to the target NetScaler appliances.

  1. Retrieve the NetScaler configurations.

    Example: To save the configurations of NetScaler appliance with IP address "10.102.5.6".

    configuration_template config = new configuration_template(); 
    config.set_action("save"); 
    config.set_source_device("10.102.5.6"); 
    config.set_configuration_period("LastOneWeek"); 
    config.set_name("Rest_Save_1 "); 
    config.set_device_family("NS"); 
    config.set_config_as_file (true); 
    configuration_template.execute(c,config);
    
  2. Edit the configurations as required.
  3. Migrate the updated configurations to the target NetScaler appliance.

    Example: To migrate the configurations to NetScaler appliances with IP addresses "10.102.40.60" and "10.102.40.17".

    configuration_template config = new configuration_template(); 
    config.set_action("load_execute"); 
    config.set_name("Rest_load_execute_1"); 
    config.set_profile_file_name("Rest_Save_1"); 
    config.set_device_family("NS"); 
    config.set_devices(["10.102.40.60","10.102.40.17"]); 
    configuration_template.execute(c,config);
    

Exception Handling

The status of a NITRO request is captured in the com.citrix.cmdctr.nitro.exception.nitro_exception class. This class provides the following details of the exception:

  • Error code. The status of the NITRO request. An error code of 0 indicates that the NITRO request is successful. A non-zero error code indicates an error in processing the NITRO request.
  • Error message. Provides a brief description of the exception.