VMware Smart Assurance Network Configuration Manager API ...€¦ · programming with the API, the VMware Smart Assurance Network Configuration Manager Application Program Interface

VMware Smart Assurance NetworkConfiguration Manager APIProgrammer's Guide

VMware Smart Assurance 10.1.0

You can find the most up-to-date technical documentation on the VMware website at:

https://docs.vmware.com/

If you have comments about this documentation, submit your feedback to

[email protected]

VMware, Inc.3401 Hillview Ave.Palo Alto, CA 94304www.vmware.com

Copyright © 2019 VMware, Inc. All rights reserved. Copyright and trademark information.

VMware Smart Assurance Network Configuration Manager API Programmer's Guide

VMware, Inc. 2

https://docs.vmware.com/

mailto:[email protected]

http://pubs.vmware.com/copyright-trademark.html

Contents

1 Overview 5

2 Accessing the API Reference Guide (Javadoc) 6

3 Conventions 7

4 Installing the API 9

5 Getting Started 10Accessing Network Configuration Manager API 10

Samples 10

Using the J2EE Interface 10

Accessing the J2EE Interface 11

In the Web Service interface 13

In the J2EE interface 13

Using the Web Services Interface 13

Configuring WS API client 13

Obtaining the Interface Definition 14

Determine which Method to Use 15

6 API Naming 16Lookup By OID 16

Lookup By Name 17

Composite Names 17

Best Practices 19

7 API Usage 20API Usage in JAVA 20

Using the J2EE Interface 20

Using the Web Services Interface 21

API Usage in Perl 22

Include the SOAP::Lite module 22

Set the host, user and password values 22

SOAP: Lite needs to know the web service’s target URL, and default namespace 23

Create an instance of the SOAP::Lite object 23

Make your first SOAP call 23

API Usage in PHP 23

Include the Network Configuration Manager API definitions and support functions 23

VMware, Inc. 3

Set the host, user, and password values 23

Set the WSDL file location and the SOAP client options 24

Create an instance of VCSoapClient 24

Make your first SOAP call 24

8 Samples 25Sample - Creating a Network Using Perl 25

Sample - Assigning a Device Server to a Network Using Perl 26

Sample - Creating an Account Credential Using Perl 27

Sample - Creating a Community String Credential Using Perl 28


VMware, Inc. 4

Overview 1The VMware Smart Assurance Network Configuration Manager Application Program Interface (API)Javadoc Reference Guide is the “what”--and, this VMware Smart Assurance Network ConfigurationManager Application Program Interface (API) Programmer’s Guide is the “how”.

Use this guide to determine how to get those first few operations completed. After getting a feel forprogramming with the API, the VMware Smart Assurance Network Configuration Manager ApplicationProgram Interface (API) Javadoc Reference Guide will be more easily understood and usable.

There are two API interfaces available. One is a J2EE version, and the other is a Web Services version.Which one you use depends on your specific situation. Both have the same functionality.

n The J2EE version requires the client be written in Java.

n The Web Services version is required for cross-language support. It allows for Perl, C++, PHP, (andJava) clients to use the API by programming against the WSDL interface. All the code samples listedin this document use the Web Services interface.

VMware, Inc. 5

Accessing the API ReferenceGuide (Javadoc) 2The VMware Smart Assurance Network Configuration Manager Application Program Interface (API)Javadoc Reference Guide from the Network Configuration Manager server at the following URL.

https://SERVER_IP_ADDRESS:8880/Api/javadoc

Where SERVER_IP_ADDRESS is the IP Address of the machine where the API is installed.

Here is the online VMware Smart Assurance Network Configuration Manager Application ProgramInterface (API) Javadoc Reference Guide in javadoc format.

VMware, Inc. 6

Conventions 3The functionality in the API follows a number of conventions. When reading the documentation, watch forthe following conventions.

n For CRUD functions (create, read, update, delete), the functions start with either create, get, update,or delete respectively.

n Functions starting with build provide factory methods for creating complex objects. These are notpersisted, but are offered as a helper service to the client code.

n Data structures end with Info. These represent the domain objects in the system.

n Functions that do not follow the above conventions are either providing association between domainobjects, or executing some business logic.

n ResourceIdentityInfo is the identity object, which contains the unique identifier in the attributed key.This is the object identifier or primary key unique to every object in the system.

The architecture of the API is such that the Web Services interface uses the J2EE interface in thebackground. The VMware Smart Assurance Network Configuration Manager Application ProgramInterface (API) Javadoc Reference Guide is a document generated from the J2EE interface, causingsome discrepancies between the document and the code generated from Web Services tools, such asApache Axis.

That is because the Web Services Interface Definition (WSDL) is a translation. All the functions andparameters are the same in the J2EE version and the WSDL version, but the data structures of theparameters may differ slightly.

Note The WSDL is the interface definition for the web services interface, the javadoc serves todocument the functions.

If you are using the Web Services interface, you need to be using the WSDL as the precise definition foreach function. The VMware Smart Assurances Network Configuration Manager Application ProgramInterface (API) Javadoc Reference Guide is still a good reference document if you are using WebServices, but there are some differences between what you see in the guide and the actualimplementation of the code.

n Collections in the guide are Arrays in Web Services implementations.

n In some situations, the order of parameters can change between the WSDL and J2EE interface. Themost notable example is with ResourceIdentityInfo. Keep this in mind when programming, and checkthe generated objects (if applicable) if you suspect this.

n The java Date type is translated into a Calendar type for the WSDL interface.

VMware, Inc. 7

Finally, a note about LDAP-style name lookups. In the documentation, the name lookup capability isdetailed. Unfortunately, this is expensive. Some of the name lookups have been removed for performancereasons.

As a best practice, these lookup-style calls should only be used as an entry point to the API, before anyinternal Ids (OIDs or keys in the Resource Identity Info objects) have been obtained. Once theprogrammer has an entry point into the system, OIDs should always be used for API calls.

For best practices, keep in mind the load being put on the Network Configuration Manager system.Remember that a program can interact much faster with the application than users can. High volumetraffic through the API can simulate many concurrent users of the system.

Note Note the following when making decisions concerning multi-threading a client program:

n Technically, this is entirely possible, but is it a good thing to do from a system perspective?

n You might also consider running high volume operations against the API when there are a minimumof users on the system.


VMware, Inc. 8

Installing the API 4The Application Program Interface (API) is installed with the application by default.

API versions are named by the minor version number, and indicated stable API signatures for theduration of that version. For example, the 9.x API is the programmatic interface starting with version 9.x.The signatures present at that release remain unchanged throughout the life of the 9.x API. Additionalsignatures, if added during the 9.x.y release, remain stable during the lifetime of the 9.x API.

Note Backward compatibility with Version 4.x is not supported. Also, two different versions of an API in arelease is not supported.

VMware, Inc. 9

Getting Started 5This chapter includes the following topics:

n Accessing Network Configuration Manager API

n Samples

n Using the J2EE Interface

n Using the Web Services Interface

n Configuring WS API client

Accessing Network Configuration Manager API

There are two manifestations of the API available. One is a J2EE version, and one is a Web Servicesversion. Which one you use depends on your specific situation. Both have the same functionality, butcertain usage scenarios tend to lend themselves better to using one over the other.

Samples

The most valuable part of the documentation set to programmers is the extensive set of samples andexample code provided. You can access these samples at the following location on machine where NCMis installed:

[ProductDirectory]/ncmcore/webapps/ncm-webapp/samples

Download the samples directory to have all the example code on your local system.

Using the J2EE Interface

The J2EE interface is a service, or bean, called ApiService. The functions available on the API are allavailable through this service.

VMware, Inc. 10

A handle to the bean is obtained in Spring Application context lookup. Some other parameters arerequired. See the samples provided for an example of these settings. Each sample is standalone, andhas the settings to obtain a handle to the service. Many of the samples have assumptions about data, soit is important you read the code and understand your server environment (data you have available toyou).

Note You have to change the IP address, user name, and password in the sample before you can runthem against your server.

Accessing the J2EE InterfaceThis chapter provides you information on how to accedd the Java Interface.

To access the Java interface, download/get the J2EE folder from the server. This folder is located at thefollowing location:

[ProductDirectory]/ncmcore/webapps/ncm-webapp/samples/J2EE in the deploy folder of yourNCM installation.

The following table lists the jar files that must be in your client’s CLASSPATH for your Java clientapplication to work properly. As a convenience, all the required jar files, and a sample build file in thesamples directory have been included.

Filename Location

activation-1.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

activemq-client-5.14.5.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

activemq-broker-5.14.5.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

activemq-kahadb-store-5.14.5.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

activemq-protobuf-1.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

activemq-openwire-legacy-5.14.5.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

ant-1.5.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

antlr-2.7.6.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

aopalliance-1.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

axis-1.3.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

axis-ant-1.3.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

axis-jaxrpc-1.3.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

axis-saaj-1.3.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

axis-wsdl4j-1.5.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

backport-util-concurrent-3.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

bcprov-jdk15-1.45.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

castor-1.1.2.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

cglib-nodep-2.2.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

common-9.4.0.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib


VMware, Inc. 11

commons-beanutils-1.7.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

commons-codec-1.6.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

commons-collections-3.2.2.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

commons-digester-1.3.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

commons-discovery-0.5.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

commons-lang-2.4.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

commons-logging-1.0.4.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

core-9.4.0.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

cryptix32-1.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

cryptoj-6.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

dnsjava-1.5.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

dom4j-1.6.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

ehcache-1.5.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

hibernate-core-3.5.4-Final.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

hibernate-ehcache-3.5.4-Final.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

hsqldb-1.6.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

httpclient-4.2.3.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

httpcore-4.2.3.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

icu4j-2.6.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

jasperreports-0.6.7.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

javassist-3.15.0-GA.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

jaxen-1.1.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

jaxrpc-api-1.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

jdom-1.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

jradius-client-1.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

jsr107cache-1.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

jta-1.1.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

log4j-1.2.16.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

mail-1.4.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

org-netbeans-bootstrap-RELEASE701.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

org-openide-modules-RELEASE701.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

org-openide-util-lookup-RELEASE74.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

org-openide-util-RELEASE74.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

oro-2.0.8.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

OvLic-1.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

poi-2.0-final-20040126.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib


VMware, Inc. 12

postgresql-9.0-802.jdbc3.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

publicApi-9.4.0.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

security-9.4.0.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

services-9.4.0.0.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

slf4j-api-1.6.4.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

spring-aop-4.3.23.RELEASE.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

spring-beans-4.3.23.RELEASE.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

spring-context-4.3.23.RELEASE.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

spring-context-support-4.3.23.RELEASE.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

spring-core-4.3.23.RELEASE.jar <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/WEB-INF/lib

Note This document has been written from the perspective of using the Web Services Interface. As thissection indicates, there is also a J2EE interface that can be used.

The examples in this guide are using Java derived from the Web Services Interface. The VMware SmartAssurance Network Configuration Manager Application Program Interface (API) Javadoc ReferenceGuide, however, has been generated from the J2EE interface. The functions in the J2EE interface andWeb Services Interface are the same.

Occasionally, some parameters have been changed. Usually, it is a collection being expressed as anarray. The most notable example is that of the parameter order of the ResourceIdentityInfo.

In the Web Service interface

ResourceIdentityInfo (String resourceKey, String resourceName, String resourceType)

In the J2EE interface

ResourceIdentityInfo (String resourceKey, String resourceType, String resourceName)

Using the Web Services Interface

This section details how to use the Web Services Interface.

Configuring WS API client

Follow below steps to configure WS API client

1. Log in to the NCM host and copy "$VOYENCE_HOME/conf/bundle.p12" to the destination machinewhere the WS API client is configured (for example, /opt)

2. On the destination machine, type the following command as one line and press Enter: $JAVA_HOME/bin>keytool -changealias -keystore "/opt/bundle.p12" -alias 1 -destalias newalias –storetype pkcs12


VMware, Inc. 13

3. Enter keystore password. (This is the PassPhrase entered during the NCM server installation.)

4. On the destination machine, type the following command as one line and press Enter: $JAVA_HOME/bin>keytool -importkeystore -srckeystore "/opt/bundle.p12" -destkeystore "$JAVA_HOME/jre/lib/security/cacerts" -srcstoretype pkcs12

5. Enter the destination keystore password : changeit

6. Enter the source keystore password. (This is the PassPhrase entered during the NCM serverinstallation.)

7. These results should display:

Entry for alias newalias successfully imported. Import command completed: 1 entries successfullyimported, 0 entries failed or cancelled.

Note : If customer has 3rd party certificate installed instead of selfsigned certificate,Steps 1, 3, and 6 willbe different as follows:

1. Log in to the NCM host and copy "$VOYENCE_HOME/tools/ssl/server.p12" to the destination machinewhere the WS API client is configured (for example, /opt)(server.p12 will be generated while installing 3rdparty certificate using ssl utility for NCM)

3. Enter keystore password. (In case of 3rd party certificate, the same password has to be entered whichwas given during certificate installation)

6. Enter the source keystore password. (In case of 3rd party certificate, the same password has to beentered which was given during certificate installation.)

Obtaining the Interface Definition

There are two methods to obtain the WSDL document, which is the interface definition:

Method 1 – Obtain from the URL

You can get the WSDL document through the browser. However, getting the document through thebrowser actually generates the WSDL, and the namespace contains the URL used to obtain thedocument. This may not be desirable. For example, the package names of generated Java code thencontain the URL where you obtained the interface definition.

To use this method, obtain the WSDL from:

HTTPS Mode: https://<voyence-server>:8880/Api/services/ApiService?wsdl

Note Note : For better API Performance use the following WSDL URL :

https://<voyence-server>:8880/ncm-webapp/services/ApiService?wsdl

Note <voyence-server> refers to the IP address of the machine where the Network ConfigurationManager server is installed


VMware, Inc. 14

Method 2 – Retrieve the file from the server

The WSDL document resides on the server in the following location. If you have access to the server, youcan obtain the document from:

<VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/samples/WS/conf

Determine which Method to Use

Now that you have the WSDL document, it is up to you how you use it. As a Web Services programmer,you can choose whatever library or toolkit you desire. From there, you can compile it to any supportedlanguage, or you may already have a product that can consume it directly.

Note Check Section “Generating Client-side Stubs using Axis 1.3 or Higher” on page 40 for moreinformation.


VMware, Inc. 15

API Naming 6Network Configuration Manager resources are identified and named through an object identifier. Thisidentifier, referred to as an Object Identifier (OID), uniquely identifies a resource within the NetworkConfiguration Manager system. Using the OID, programmers can directly lookup a Network ConfigurationManager resource.

Network Configuration Manager resources also have human-readable names. Most of these names donot have uniqueness constraints within the Network Configuration Manager system (the notableexception is network names; two networks cannot have the same name within the Network ConfigurationManager system).

For example, a Network Configuration Manager device can have the same name. However, two devicesunder a given network cannot have the same name.

The Network Configuration Manager API provides lookup by OID for all the domain objects. Along withthis, it also provides a mechanism to lookup by name for primary domain objects like Network,Operational Device, Folder, Site, and Job. Network Configuration Manager recommends avoiding lookupsby name for performance reasons. Try to retrieve the object by name once, and cache the OID forsubsequent calls.

Note If a programmer supplies both the resource OID and the resource name, then the OID is used.Otherwise, the name is used.

This chapter includes the following topics:

n Lookup By OID

n Lookup By Name

n Composite Names

n Best Practices

Lookup By OID

The following is an example to lookup a domain object by OID.

// Look up device R1230-5 in network SOUTHWEST-REGION by OID

// R1230-5's OID is c0a857081bf8e93fe3d5e46b00010000

// SOUTHWEST-REGION is c0a857080d6bb23ffbfa048200010000

ResourceIdentityInfo networkId =

new ResourceIdentityInfo(

"c0a857080d6bb23ffbfa048200010000",

VMware, Inc. 16

null,

"network");

ResourceIdentityInfo deviceId =


"c0a857081bf8e93fe3d5e46b00010000",

null, "device");

OperationalDeviceInfo info =

api.getOperationalDeviceInfo(networkId, deviceId, false);

Lookup By Name

The following is an example to lookup a domain object by Name.

ResourceIdentityInfo networkId =


null,

"SOUTHWEST-REGION",

"network");

ResourceIdentityInfo deviceId =


null,

"R1230-5",

"device");

OperationalDeviceInfo info = api.getOperationalDeviceInfo(networkId, deviceId, false);

Composite Names

Most of the Network Configuration Manager resources do not exist in a hierarchical fashion, or have onlya single level of hierarchy. For example, Network Configuration Manager Workspaces exist directly underNetwork Configuration Manager Networks.

The notable exception to the hierarchy rule is Network Configuration Manager Sites and Folders. Sitesand folders can have an arbitrary tree-like structure. To support this hierarchy at the API level, the notionof a composite name is introduced (the remainder of this section uses sites to illustrate composite nameconcepts).

A composite name is an array of ResourceIdentityInfo objects. Each element of the array specifies theparticular Network Configuration Manager resource that comprises a full, hierarchical name. Thisapproach allows for an arbitrary number of levels.

The following is an example of a composite name. following is a graphical representation of a NetworkConfiguration Manager Network, and several sites/sub-sites contained under the network. Note the nameand unique key is shown at each level.

Networks

o Southwest-Region (key: C0A8572F3468993F953401C7FC000000)

|____ o Sites

|_____ o Austin (key: C0A8572F40BFE83FA73801C7FC000000)


VMware, Inc. 17

| |_____ o 100 Congress (key: C0A8572F40EFB981A73801C7FC000000)

|_____ o Santa Fe (key: C0A8572F40BEF38FA73801C7FC000000)

The Santa Fe Site under the Southwest-Region network would be represented as a composite name by atwo-element array of ResourceIdentityInfo objects. The ResourceIdentityInfo object at index 0 of the arraywould have the following values:

ResourceIdentityInfo.resourceKey = "C0A8572F3468993F953401C7FC000000"

ResourceIdentityInfo.resourceType = "network"

ResourceIdentityInfo.resourceName = "Southwest-Region"

The ResourceIdentityInfo object at index 1 of the array would have the following values:

ResourceIdentityInfo.resourceKey = "C0A8572F40BEF38FA73801C7FC000000"

ResourceIdentityInfo.resourceType = "site"

ResourceIdentityInfo.resourceName = "Santa Fe"

The following is a pseudo-code representation of the previous example:

. . .

ResourceIdentityInfo [] compositeName = new ResourceIdentityInfo(2);

compositeName[0] =


"C0A8572F3468993F953401C7FC000000",

"Southwest-Region",

"network");

compositeName[1] =


"C0A8572F40BEF38FA73801C7FC000000",

"Santa Fe",

"site");

To represent the 100 Congress child Site of the top level Austin Site, under the Southwest-Regionnetwork, a three-element array of ResourceIdentityInfo objects would be needed. The following pseudo-code illustrates this:

ResourceIdentityInfo [] compositeName = new ResourceIdentityInfo(3);

compositeName[0] =


"C0A8572F3468993F953401C7FC000000",

"Southwest-Region",

"network");

compositeName[1] =


"C0A8572F40BFE83FA73801C7FC000000",

"Austin",

"site");

compositeName[2] =


"C0A8572F40EFB981A73801C7FC000000",

"100 Congress",

"site");


VMware, Inc. 18

In addition to those methods that deal with Sites and Folders, certain job-related methods require acomposite name as a parameter.

Best Practices

Following are the best practices you should follow for optimal performance.

n Use OIDs wherever possible. Using the LDAP method of lookup using Resource Names affectsperformance.

n On getXXXXInfo() calls, use fullDataSet option only when necessary. Passing a value of true forfullDataSet argument retrieves all the associations, and affects performance.


VMware, Inc. 19

API Usage 7This chapter includes the following topics:

n API Usage in JAVA

n API Usage in Perl

n API Usage in PHP

API Usage in JAVA

This section details the API usage in JAVA.

Using the J2EE Interface

The following are the general steps a typical client would complete after downloading the required jar filesto access the API using the J2EE interface. Samples and examples in this section provide workingillustrations of these concepts.

Prepare the Server Variable, UserName and Password

The following variables needs to be set in config.properties file present at the following location:[ProductDirectory]/ncmcore/webapps/ncm-webapp/samples/J2EE/conf

#Replace the <server-ip> with the actual IP Address of the NCM server.

cc.remoting.servlet.base=http://<server-ip>:8881/ncm-webapp/remoting/

#Replace the username and password values with the actual ones.

user=sysadmin

password=sysadmin

The cc.remoting.servlet.base URL in J2EE samples folder is changed from https (secure) to http bydefault. This is to bring performance improvement for J2EE API calls. To make the J2EE API calls secure,please follow below steps:

1 Open <VOYENCE_HOME>/ncmcore/webapps/ncm-webapp/samples/J2EE/conf/config.properties.

2 Modify the below lines from cc.remoting.sevlet.base=http://<server-ip>:8881/ncm-webapp/remoting/ to cc.remoting.servlet.base=https://<server-ip>8880/ncm-webapp/remoting/.

VMware, Inc. 20

Prepare Spring Security context, and initiate a login

// Establish Spring Security context using the supplied username/password

// The username and password needs to be set in the file

SecurityContextHolder.getContext().setAuthentication(

new UsernamePasswordAuthenticationToken(

Config.getProperty("user"),Config.getProperty("password")

)

);

//Lookup ApiService Bean from the Client Application Context.

try {

applicationContext = new ClassPathXmlApplicationContext("classpath:client-applicationContext.xml");

api = applicationContext.getBean("apiService",ApiService.class);

} catch (Exception e) {

// TODO Auto-generated catch block

e.printStackTrace();

}

Make the API service call

// Get Network information for MSP.

ResourceIdentityInfo rii = new ResourceIdentityInfo(

null, ResourceTypes.NETWORK,

networkName);

NetworkInfo networkInfo = api.getNetworkInfo(rii, true);

ResourceIdentityInfo rii = networkInfo.getResourceIdentityInfo();

System.out.println("Retrieved Network : "

+ rii.getResourceName() + " : "

+ rii.getResourceKey());

Using the Web Services Interface

After completing the steps of obtaining the WSDL document, you will be generating the client-side stubsand compiling them. The following are general steps for using the API.

Get a handle to ApiService using the Service Locator class

ApiServiceSoapBindingStub api;

try {

ApiServiceServiceLocator locator = new ApiServiceServiceLocator();

// Use the line below to change the Service EndPoint address.

// Replace 192.168.24.213 with the IP address of the voyence control

// server you are connecting to.

locator.setApiServiceEndpointAddress(

"https://192.168.24.213:8880/Api/services/ApiService");

api = (ApiServiceSoapBindingStub) locator.getApiService();

}

catch (ServiceException jre) {

if (jre.getLinkedCause() != null) {

jre.getLinkedCause().printStackTrace();

}


VMware, Inc. 21

throw jre;

}

Set the username, password, and the timeout value for the service

// Set the username and password

api.setUsername("myusername");

api.setPassword("mypassword");

// Time out after a minute

api.setTimeout(60000);

Make calls through the apiservice variable

try {

// Get Network information for MSP

ResourceIdentityInfo networkRII = new ResourceIdentityInfo(

null,

"MSP",

"network");

NetworkInfo networkInfo = api.getNetworkInfo(

networkRII,

true)

// Make more calls or process the data you received.

…

…

}

catch (…) {

// Handle exception processing

…

API Usage in Perl

Make sure your system has the SOAP::Lite module installed, and can support SSL web requests. Then,create a new Perl script using the following steps.

Include the SOAP::Lite module

#!perl -w

use SOAP::Lite;

Set the host, user and password values

$soap_host = 'demo.voyence.com';

$soap_user = 'sysadmin';

$soap_pw = 'sysadmin';


VMware, Inc. 22

SOAP: Lite needs to know the web service’s target URL, anddefault namespace

$soap_proxy = 'https://'.$soap_user.':'.$soap_pw.'@'. $soap_host.':8880/Api/services/ApiService';

$soap_uri = 'https://api.common.configmgr.powerup.com'.

Create an instance of the SOAP::Lite object

$soap_client = new SOAP::Lite

uri => $soap_uri,

proxy => $soap_proxy,

autotype => 0;

Make your first SOAP call

$soap_response = $soap_client->getAllNetworks();

if ($soap_response->fault) {

print "\nSOAP fault: ".$soap_response->faultstring."\n";

}

else {

$array_of_riis = $soap_response->result;

# actually a reference to an array of references!

# if this returns duped results with SOAP::Lite v0.65+ it is

# due to a SOAP::Lite bug when talking to Apache Axis

for ($i=0 ; $i < (scalar(@{$array_of_riis})) ; $i++) {

$this_ref = $array_of_riis->[$i];

print "\nObject Type: ".ref($this_ref)."\n";

while (($key, $val) = each(%{$this_ref})) {

print ' '.$key.' = '.$val."\n";

}

}

}

API Usage in PHP

Make sure you are using PHP5 with SOAP and SSL support enabled, and then create a new PHP pageas follows:

Include the Network Configuration Manager API definitions andsupport functions

<?php

require 'VC_API_inc.php';

Set the host, user, and password values


VMware, Inc. 23

$soap_host = 'demo.voyence.com';

$soap_user = 'sysadmin';

$soap_pw = 'sysadmin';

Set the WSDL file location and the SOAP client options

$soap_wsdl = "https://" . $soap_host . ":8880/Api/services/ApiService?wsdl";

// trace = 1 lets us use getLastRequest and getLastResponse

// exceptions = 0 uses SoapFault Objects instead of exceptions

$soap_arry = array("login" => $soap_user,

"password" => $soap_pw,

"trace" => 1,

"exceptions" => 0);

Create an instance of VCSoapClient

$soap_client = new VCSoapClient($soap_wsdl, $soap_arry);

Make your first SOAP call

// get an array of network resource ids

$allnets = $soap_client->getAllNetworks();

// first check to see if we got a SoapFault object from the soap call

if (get_class($allnets) == "SoapFault") {

echo "ERROR: ".$allnets->faultstring.'<br>';

}

elseif (is_array($allnets)) {

foreach ($allnets as $rii) {

echo 'Network '.$rii->resourceName.' resourceKey = '.

$rii->resourceKey.'<br>';

}

}

?>


VMware, Inc. 24

Samples 8All the Java Samples listed in this section use the Web Services interface. Get the J2EE Samples fromNCM Server [ProductDirectory]/ncmcore/webapps/ncm-webapp/samples

There are many samples in the location specified above. These samples are the most effective way to getstarted with programming against the API. Even though you may be programming against the J2EEinterface, the Web Services examples may also help to illustrate usage scenarios, or vice versa. Thesamples in the different directories are not the same, so do not hesitate to look in more than one place forexample usage.

The recommended access to the API is through Web Services, using object-oriented clients that have toolsupport for WSDL. For example, good choices would be Java using Apache axis orOR c#.

Perl users will have to construct the SOAP calls directly. The Perl examples have been left in thisdocument because there is no online sample Perl code at this time, however, the J2EE, Web Services,and PHP examples are now online.

Perl is not the recommended choice for complex integrations, because the SOAP calls must beconstructed manually, and the data structures make this a difficult task. Use higher-level languages forcomplex integrations.

This chapter includes the following topics:

n Sample - Creating a Network Using Perl

n Sample - Assigning a Device Server to a Network Using Perl

n Sample - Creating an Account Credential Using Perl

n Sample - Creating a Community String Credential Using Perl

Sample - Creating a Network Using Perl

# Create a new Network "TestNetwork” using Voyence API.

# Refer to API Usage section for how to

# create an instance of SOAP::Lite

# ie $soap_client = new SOAP::Lite ....

# create a network RII object for new net

$new_net_rii = {

resourceName => 'TestNetwork',

resourceType => 'NETWORK',

resourceKey => undef};

bless $new_net_rii, 'ResourceIdentityInfo';

#create a NetworkInfo object and insert netRII in it

VMware, Inc. 25

$new_net_info = {

resourceIdentityInfo => $new_net_rii,

description => 'created via API/SOAP::Lite'};

bless $new_net_info, 'NetworkInfo';

# build param 0

$net_param = new SOAP::Data

name => 'in0',

attr => {'xsi:type' => ref($new_net_info)},

value => $new_net_info;

$soap_response = $soap_client->createNetwork($net_param);



}

else {

$new_net_rii = $soap_response->result;

print "\nNew resourceKey is: ".$new_net_rii->{'resourceKey'}."\n";

}

Sample - Assigning a Device Server to a Network UsingPerl

# Assigning a Device Server to a Network




# create a network and capture its RII

# see previous example for details

# $soap_response = $soap_client->createNetwork($new_network_info);

# $new_net_rii = $soap_response->result;

# Find the device server you want this network to be associated with.

# psuedocode example:

# $dev_srvr_rii_array = getAllDeviceServers()->result;

# $dev_srvr_rii = $dev_srvr_rii_array->[?];

# build param 0


name => 'in0',

attr => {'xsi:type' => ref($new_net_rii)},

value => $new_net_rii;

# build param 1

$dev_param = new SOAP::Data

name => 'in1',

attr => {'xsi:type' => ref($dev_srvr_rii)},

value => $dev_srvr_rii;

# Assign this device server to that network.

$soap_response =

$soap_client->assignDeviceServerToNetwork($net_param, $dev_param);



}

else {

$dev_srvr_array = $soap_response->result;

print "\nNetwork ".$new_net_rii->{resourceName}.


VMware, Inc. 26

" is assigned to the following DevServers:\n";

for ($i=0 ; $i < scalar(@{$dev_srvr_array}) ; $i++) {

$this_ref = $dev_srvr_array->[$i];

print " ".$this_ref->{resourceName}."\n";

}

}

Sample - Creating an Account Credential Using Perl

# Creating an Account Credential





# see previous example for details



$acct_rii = {

resourceName => 'TestAcctCredName',

resourceType => 'ACCT-CREDENTIAL',


bless $acct_rii, 'ResourceIdentityInfo';

$acct_cred_info = {

id => $acct_rii,

userName => 'TestAcctUserName',

password => 'TestAcctCredPass'};

bless $acct_cred_info, 'AcctCredentialInfo';

# build param 0

$acct_param = new SOAP::Data

name => 'in0',

attr => {'xsi:type' => ref($acct_cred_info)},

value => $acct_cred_info;

# build param 1


name => 'in1',



# Create the account credential.

$soap_response =

$soap_client->createAccountCredential($acct_param, $net_param);



}

else {

$acct_rii = $soap_response->result;

print "\nNew resourceKey is: ".$acct_rii->{'resourceKey'}."\n";

}


VMware, Inc. 27

Sample - Creating a Community String Credential UsingPerl

# Creating a Community String Credential





# see previous example for full example



$comm_rii = {

resourceName => 'TestCSCredName',

resourceType => 'COMMUNITY-CREDENTIAL',


bless $comm_rii, 'ResourceIdentityInfo';

$comm_cred_info = {

id => $comm_rii,

readOnly => 'test-read-only-mod',

readWrite => 'test-read-write-mod'};

bless $comm_cred_info, 'CommunityCredentialInfo';

# build param 0

$comm_param = new SOAP::Data

name => 'in0',

attr => {'xsi:type' => ref($comm_cred_info)},

value => $comm_cred_info;

# build param 1


name => 'in1',



# Create the credential.

$soap_response =

$soap_client->createCommunityStringCredential($comm_param, $net_param);



}

else {

$comm_rii = $soap_response->result;

print "\nNew resourceKey is: ".$comm_rii->{'resourceKey'}."\n";

}


VMware, Inc. 28

VMware Smart Assurance Network Configuration Manager API ...€¦ · programming with the API, the VMware Smart Assurance Network Configuration Manager Application Program Interface

Documents