Command actions performed in web services

This topic shows sample code for some of the common actions that are performed in web services. The sample code does very little error handling. The code performs the following actions:

1. Import the required classes.
2. Authenticate a user and establish a web service session.
3. Retrieve a set of devices based on a device filter.
4. For each device returned, run a snapshot action on the device. Each snapshot will have the same change ID.
5. Send an email of the Job Summary Report for the change ID.
6. Log out and end the web service session.

Declarations

The following import statements are required for the example code. All the import statements refer to classes that are included in the .jar files in the bcan-ws-clientapi-v.r.mm.zip distribution file.

import org.apache.axis2.AxisFault;
import com.bmc.bcan.dto.*;
import com.bmc.bcan.shared.util.ReportConstants;
import com.bmc.bcan.shared.network.jobs.ActionConstants;
import com.bmc.bcan.ws.client.*;
import com.bmc.bcan.ws.shared.*;

The following variables are used throughout the sample code:

// URL of the bca-networks server
String webappUrl = "https://localhost/";
// User for the web service authentication
String username = "sysadmin";
// Password for the web service authentication
String password = "sysadmin_pw";
// Default timeout for web service calls
long timeout = ServiceFactory.DEFAULT_TIMEOUT_MILLIS;
// User session token that will be used in all web service calls
String userToken = null;

Back to top

Login

The following sequence creates an instance of the authentication service and then logs on the user and establishes a session. The doLogin() command returns a user session token that is used in all the subsequent web service calls.

// Create instance of the authentication service
AuthenticationService authService =
ServiceFactory.createAuthenticationService(webappUrl, timeout);
// Login to bcan and obtain the user token to use for
// Subsequent webservice calls

userToken = authService.doLogin(username, password);

Back to top

Retrieve a set of devices

The following sequence retrieves a set of devices based on procurve, a device filter. The Javadoc for DeviceFitlerDTO documents all the available filter fields and flags. The getDevices() call returns an array of DeviceDTO objects.

// Create instance of the device service
DeviceService deviceService =
ServiceFactory.createDeviceService(webappUrl, timeout);
// Create a device filter
DeviceFilterDTO deviceFilter = new DeviceFilterDTO();
deviceFilter.setNameMatch("*procurve*");
// Retrieve the devices
DeviceDTO[] devices = deviceService.getDevices(userToken,
deviceFilter);

Back to top

Run a snapshot on each device

The code snippet in this section loops through each of the device DTO objects returned in the preceding section and performs a snapshot on the device. In a real deployment, it would have been more efficient to execute a single snapshot on a filtered set of devices. However, in this case, we wanted several snapshot jobs having the same change ID to be rolled up into a single report shown in the succeeding section. The Job Parameters DTO which is created contains an annotation, the device key, and the change ID. This DTO object is passed to the doBackup() web service method.

The doBackup() call returns the job ID of the job that executed the snapshot. The span action results of this snapshot job can be obtained by calling doSpanActionResults(jobID).

The Span Action Results DTO object returned from the doSpanActionResults() call contains status information, transcripts, error messages, and captured results from the span action.

// Unique change ID used to associate the snapshot jobs for reporting
String change ID = "WS11232";
// Create instance of the span action service
SpanActionService spanActionService =
ServiceFactory.createSpanActionService(webappUrl, timeout);
// Loop through each device returned from the getDevices() call above
// and run a snapshot of the device. Note, we could have run a single
// snapshot on a filtered group of devices, but for example purposes
// we are running the snapshot on each device individually.
for (DeviceDTO device : devices) {
  JobParamsDTO jobParamsDTO = new JobParamsDTO();
  jobParamsDTO.setAnnotation("Device Snapshot from webservice client");
  jobParamsDTO.setSpanKey(device.getKey());
  jobParamsDTO.setChangeId(changeId);
// Execute the snapshot for this device
// note the boolean parameter value 'true' indicates the call
// should wait for job execution to complete before returning.
// the span action results are hence available for immediate retrieval
  String jobID =
  spanActionService.doBackup(userToken, jobParamsDTO, true);
  SpanActionResultsDTO actionResults =
  spanActionService.getSpanActionResults(userToken, jobID);
// If snapshot status is not successful, then display an error
if (actionResults.getStatus() != ActionConstants.RESULT_SUCCESS) {
System.out.println("Snapshot of device " + device.getName() + " failed");
 }
}

Back to top

Email a Job Summary report

The code snippet in this section instructs the server to send a Job Summary report to a set of email addresses. The Report Email Parameter DTO object contains the parameters for the report, including the email addresses, format (HTML, PDF, RTF), whether to include a link to the dynamic report, and whether to include configuration difference details.

// Create instance of the report service
ReportService reportService =
ServiceFactory.createReportService(webappUrl, timeout);
// Create the report email parameters which includes the
// email addresses to which the report should be mailed.
ReportEmailParamsDTO emailParams = new ReportEmailParamsDTO();
emailParams.setUserNames(new String[] {"sysadmin"});
emailParams.setAdhocAddresses(new String[] {"abc@xyz.com"});
emailParams.setAttachmentFormat(ReportConstants.FORMAT_PDF);
emailParams.setLinkIncluded(true);
// Send the job summary report for all jobs with the the change ID
reportService.doSendJobSummaryReportEmail(userToken, changeId,
emailParams, true, true);

Back to top

Logout

The following code snippet closes the web service session and logs out the user. The userToken is set to null to prevent further usage because the session is now invalid.

// End the session and logout the user. Note that the authService
// was created above in the Login sequence.
authService.doLogout(userToken);
userToken = null;

Back to top

Error handling

A real application must perform error checking such as checking returned results and catching exceptions. All exceptions thrown by web service calls will be wrapped in an AxisFault. Each call should catch the AxisFault exception and handle it accordingly. Some common errors that will throw an AxisFault include:

• Authentication failure; failure to log in due to invalid user name or password
• Authorization failure; user is not authorized to make a particular web service call or access a specific resource
• Session failure; session timed out, was terminated, or the user session token is invalid

The returned values from web service should also be checked for errors. For example:

• The SpanActionService returns a SpanActionResultsDTO object when the getSpanActionResults() method is called. The SpanActionResultsDTO object has a getStatus() method to indicate whether the span action executed successfully. If the span action failed, other methods are available to retrieve device specific results and error messages.
• The AuthenticationService.doLogin() call returns a user session token. If the token is empty or null, the session is not valid.
• The EventService.log*Event() methods return a boolean to indicate whether the event was successfully logged.

Back to top

Related topic

Handling special characters