Smarts Network Configuration Manager - Data Storage ... · PDF fileusing the EMC Smarts Network Configuration Manager ... Use this guide to determine how to get those first ... /conf/voyence-ssl.keystore

Abstract

This guide provides details on getting started with programming using the EMC Smarts Network Configuration Manager API and includes samples and usage details.

January 2015

EMC® Smarts® Network Configuration Manager Version 9.4

Application Program Interface (API) Programmer’s Guide

302-001-514 Rev 01

2 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide

Copyright © 2015 EMC Corporation. All Rights Reserved. Published January 2015 EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided “as is.” EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. VMware is a registered trademark of VMware, Inc. in the United States and/or other jurisdictions. All other trademarks used herein are the property of their respective owners.


Table of Contents

Overview .......................................................................................................... 4

Accessing the API Reference Guide (Javadoc) ........................................................ 4

Conventions ..................................................................................................... 5

Installing the API ............................................................................................... 6

Getting Started ................................................................................................. 6

Accessing Network Configuration Manager API ................................................................ 6

NCM Public API Secure Connection ................................................................................. 6

Samples ........................................................................................................................ 7

Using the J2EE Interface ................................................................................................. 8

Accessing the J2EE Interface ....................................................................................... 8

In the Web Service interface ..................................................................................... 10

In the J2EE interface ................................................................................................. 10

Using the Web Services Interface .................................................................................. 10

Obtaining the Interface Definition ............................................................................. 11

Determine which Method to Use ............................................................................... 11

API Naming .................................................................................................... 11

Lookup By OID ............................................................................................................. 12

Lookup By Name .......................................................................................................... 12

Composite Names........................................................................................................ 13

Best Practices .............................................................................................................. 15

API Usage ...................................................................................................... 15

API Usage in JAVA ........................................................................................................ 15

Using the J2EE Interface ........................................................................................... 15

Using the Web Services Interface .............................................................................. 16

API Usage in Perl .......................................................................................................... 18

API Usage in PHP ......................................................................................................... 19

Samples ........................................................................................................ 20

Sample - Creating a Network Using Perl ......................................................................... 21

Sample - Assigning a Device Server to a Network Using Perl ........................................... 22

Sample - Creating an Account Credential Using Perl ....................................................... 23

Sample - Creating a Community String Credential Using Perl .......................................... 24


Overview The EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide is the “what”--and, this EMC Smarts Network Configuration Manager 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 for programming with the API, the EMC Smarts Network Configuration Manager Application Program 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.

The J2EE version requires the client be written in Java.

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

Accessing the API Reference Guide (Javadoc) The EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide and a number of code samples are available online from the Network Configuration Manager server at the following URL. https://SERVER_IP_ADDRESS:8880/Api

Where SERVER_IP_ADDRESS is the IP Address of the machine where the API is installed. https://SERVER_IP_ADDRESS:8880/Api/javadoc

Here is the online EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide in javadoc format.

http://server_ip_address/api/API_VERSION/javadoc/

http://server_ip_address/api/API_VERSION/javadoc/


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

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

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

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

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

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 the background. The EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide is a document generated from the J2EE interface, causing some discrepancies between the document and the code generated from Web Services tools, such as Apache Axis.

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

The WSDL is the interface definition for the web services interface, the javadoc serves to document the functions.

If you are using the Web Services interface, you need to be using the WSDL as the precise definition for each function. The EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide is still a good reference document if you are using Web Services, but there are some differences between what you see in the guide and the actual implementation of the code.

Collections in the guide are Arrays in Web Services implementations.

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

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


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

As a best practice, these lookup-style calls should only be used as an entry point to the API, before any internal Ids (OIDs or keys in the Resource Identity Info objects) have been obtained. Once the programmer 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 volume traffic through the API can simulate many concurrent users of the system.

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

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

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

Installing the API The 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 the duration 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. Additional signatures, if added during the 9.x.y release, remain stable during the lifetime of the 9.x API.

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

Getting Started

Accessing Network Configuration Manager API

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

NCM Public API Secure Connection

For successfully establishing a secure connection with the Network Configuration Manager server and to use the public API, do the following:


1. Access the API using https and port 8880.

2. Export the selfsigned certificate from [ProductDirectory]/conf/voyence-ssl.keystore to a file (for example, Linux server command), run:

$JAVA_HOME/bin/keytool -export -keystore

$VOYENCE_HOME/conf/voyence-ssl.keystore -alias selfsigned –file

<CERTIFICATE>

$JAVA_HOME/bin/keytool -export -keystore

%VOYENCE_HOME%/conf/voyence-ssl.keystore -alias selfsigned-ip –file

<CERTIFICATE2>

3. Click Enter on receiving a prompt for the password.

4. Copy the exported certificate file to the client machine.

5. Import the server certificate into the client running the API client code. For example, while running a java client code, the certificate needs to be imported into the jdk using the following command on a Windows client:

%JAVA_HOME%\bin\keytool.exe -keystore

%JAVA_HOME%\\jre\lib\security\cacerts -import -file <CERTIFICATE> -alias

selfsigned

%JAVA_HOME%\bin\keytool.exe -keystore

%JAVA_HOME%\\jre\lib\security\cacerts -import -file <CERTIFICATE2> -

alias selfsigned-ip

6. Enter the following password after receiving a prompt: changeit

This is the default password, unless otherwise modified.

7. Type Yes on receiving a prompt, “Trust the certificate”.

Samples

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

[ProductDirectory]/ncmcore/webapps/Api/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 all available through this service.

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

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

Accessing the J2EE Interface

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

[ProductDirectory]/ncmcore/webapps/Api/samples/J2EE in the deploy folder of your NCM installation.

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

Filename

Location

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

activemq-all-5.6.0.jar <VOYENCE_HOME>/ncmcore/webapps/Api/WEB-INF/lib

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

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

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

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

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

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

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

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

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

bcprov-jdk14-1.23.0.jar <VOYENCE_HOME>/ncmcore/webapps/Api/WEB-INF/lib

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

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

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


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

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

commons-collections-2.1.jar <VOYENCE_HOME>/ncmcore/webapps/Api/WEB-INF/lib

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

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

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

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

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

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

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

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

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

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

hibernate-core-3.5.0-CR-2.jar <VOYENCE_HOME>/ncmcore/webapps/Api/WEB-INF/lib

hibernate-ehcache-3.5.0-CR-2.jar

<VOYENCE_HOME>/ncmcore/webapps/Api/WEB-INF/lib

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

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

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

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

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

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

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

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

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

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

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

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

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

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

org-netbeans-bootstrap-RELEASE701.jar


org-openide-modules-RELEASE701.jar



org-openide-util-lookup-RELEASE74.jar


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

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

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

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

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

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

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

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

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

spring-aop-4.0.6.RELEASE.jar <VOYENCE_HOME>/ncmcore/webapps/Api/WEB-INF/lib

spring-beans-4.0.6.RELEASE.jar <VOYENCE_HOME>/ncmcore/webapps/Api/WEB-INF/lib

spring-context-4.0.6.RELEASE.jar <VOYENCE_HOME>/ncmcore/webapps/Api/WEB-INF/lib

spring-context-support-4.0.6.RELEASE.jar


spring-core-4.0.6.RELEASE.jar <VOYENCE_HOME>/ncmcore/webapps/Api/WEB-INF/lib

This document has been written from the perspective of using the Web Services Interface. As this section 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 EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide, however, has been generated from the J2EE interface. The functions in the J2EE interface and Web Services Interface are the same.

Occasionally, some parameters have been changed. Usually, it is a collection being expressed as an array. 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.


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 the browser actually generates the WSDL, and the namespace contains the URL used to obtain the document. This may not be desirable. For example, the package names of generated Java code then contain 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

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

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, you can obtain the document from:

<VOYENCE_HOME>/ncmcore/webapps/Api/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 supported language, or you may already have a product that can consume it directly.

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

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

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

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


The Network Configuration Manager API provides lookup by OID for all the domain objects. Along with this, 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 lookups by name for performance reasons. Try to retrieve the object by name once, and cache the OID for subsequent calls.

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

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",

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 only a single level of hierarchy. For example, Network Configuration Manager Workspaces exist directly under Network Configuration Manager Networks.

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

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

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

o Southwest-Region (key: C0A8572F3468993F953401C7FC000000)

|____ o Sites

|_____ o Austin (key: C0A8572F40BFE83FA73801C7FC000000)

| |_____ 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 a two-element array of ResourceIdentityInfo objects. The ResourceIdentityInfo object at index 0 of the array would 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-Region network, 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");

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


Best Practices

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

Use OIDs wherever possible. Using the LDAP method of lookup using Resource Names affects performance.

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

API Usage

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 files to access the API using the J2EE interface. Samples and examples in this section provide working illustrations 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/Api/samples/J2EE/conf

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

cc.remoting.servlet.base=https://<server-ip>:8880/ncm-webapp/remoting/

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

user=sysadmin

password=sysadmin

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 stubs and 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();

}

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';

SOAP: Lite needs to know the web service’s target URL, and default 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 page as follows:

Include the Network Configuration Manager API definitions and support functions <?php

require 'VC_API_inc.php';

Set the host, user, and password values

$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>';

}

}

?>

Samples All the Java Samples listed in this section use the Web Services interface. Download the J2EE Samples from: https://<serverip>:8880/api

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

The recommended access to the API is through Web Services, using object-oriented clients that have tool support 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 this document 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 be constructed manually, and the data structures make this a difficult task. Use higher-level languages for complex integrations.

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

$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 Using Perl # 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}.

" 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";

}

Sample - Creating a Community String Credential Using Perl # 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";

}

Documents

Smarts Network Configuration Manager - Data Storage ... · PDF fileusing the EMC Smarts Network Configuration Manager ... Use this guide to determine how to get those first ... /conf/voyence-ssl.keystore