VMware vCenter Lab Manager 3.0 User guide

SOAP API Guide

Lab Manager 3.0

VMware, Inc.

3401 Hillview Ave.

Palo Alto, CA 94304

www.vmware.com

2 VMware, Inc.

Lab Manager SOAP API Guide

You can find the most up-to-date technical documentation on our Web site at:

http://www.vmware.com/support/

The VMware Web site also provides the latest product updates.

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

docfeedback@vmware.com

6,496,847, 6,704,925, 6,711,672, 6,725,289, 6,735,601, 6,785,886, 6,789,156, 6,795,966, 6,880,022,

6,944,699, 6,961,806, 6,961,941, 7,069,413, 7,082,598, 7,089,377, 7,111,086, 7,111,145, 7,117,481,

7,149,843, 7,155,558, 7,222,221, 7,260,815, 7,260,820, 7,269,683, 7,275,136, 7,277,998, 7,277,999,

7,278,030, 7,281,102, 7,290,253, and 7,356,679; patents pending.

VMware, the VMware “boxes” logo and design, Virtual SMP and VMotion are registered trademarks or

trademarks of VMware, Inc. in the United States and/or other jurisdictions. Microsoft is a registered

trademark of Microsoft Corporation in the United States and other countries. All other marks and

names mentioned herein may be trademarks of their respective companies.

Lab Manager is distributed with AxpDataGrid, a third-party product, copyright by Axezz, Oslo,

Norway, http://www.axezz.com/axpdatagrid.

Lab Manager SOAP API Guide

Revision: 20080804

Item: EN-000067-00

VMware, Inc. 3

Contents

AboutThisBook 7

1 IntroducingVMwareLab ManagerSOAPAPI 9

IntegratingLabManagerwithAutomatedTestingTools 10

SupportedOperations 10

LabManagerDataObjects 10

StandardsComplianceandCompatibleDevelopmentPlatforms 11

Security 11

UserAuthentication 11

2 GettingStartedwiththeLab ManagerSOAPAPI 13

Requirements 13

ObtainingandImportingtheWSDL 14

ImportingtheWSDLFileintoYourDevelopmentPlatform 14

InstructionsforUsingMicrosoftVisualStudiowithLabManagerWSDL 14

SimpleandAdvancedCodeSamples 16

SimpleC#ConsoleApplication 17

AdvancedC#Sample:IntegratingLabManagerandQualityCenter 19

3 LabManagerAPIData Types 27

PrimitiveXMLDataTypes 27

LabManagerDataTypes 28

AuthenticationHeader 28

SupportedAPICalls 28

Fields 28

SampleUsage:C# 29

Configuration 29

Machine 30

Lab Manager SOAP API Guide

4 VMware, Inc.

4 LabManagerAPIMethodReference 33

ConfigurationCapture 34

Syntax 34

Arguments 34

Response 35

SampleCode:C# 35

ConfigurationCheckout 36

Syntax 36

Arguments 36

Response 36

SampleCode:C# 36

ConfigurationClone 37

Syntax 37

Arguments 37

Response 38

SampleCode:C# 38

ConfigurationDelete 38

Syntax 38

Arguments 39

Response 39

SampleCode:C# 39

ConfigurationDeploy 40

Syntax 40

Arguments 40

Response 40

SampleCode:C# 40

ConfigurationPerformAction 41

Syntax 42

Arguments 42

Response 42

SampleCode:C# 42

ConfigurationSetPublicPrivate 43

Syntax 43

Arguments 43

Response 43

SampleCode:C# 43

ConfigurationUndeploy 44

Syntax 44

Arguments 44

Response 44

SampleCode:C# 44

VMware, Inc. 5

Contents

GetConfiguration 45

Syntax 45

Response 45

SampleCode:C# 46

GetConfigurationByName 47

Syntax 47

Arguments 47

Response 47

SampleCode:C# 47

GetMachine 48

Syntax 48

Arguments 48

Response 49

SampleCode:C# 49

GetMachineByName 50

Syntax 50

Arguments 50

Response 50

SampleCode:C# 50

GetSingleConfigurationByName 51

Syntax 51

Arguments 51

Response 51

SampleCode:C# 51

ListConfigurations 52

Syntax 52

Arguments 52

Response 52

SampleCode:C# 53

ListMachines 54

Syntax 54

Arguments 54

Response 54

SampleCode:C# 54

LiveLink 55

Syntax 55

Arguments 55

Response 55

SampleCode:C# 56

Lab Manager SOAP API Guide

6 VMware, Inc.

MachinePerformAction 56

Syntax 57

Arguments 57

Response 57

SampleCode:C# 57

Index 59

VMware, Inc. 7

UsetheLab ManagerSOAPAPIGuidetodevelopapplicationsthatuseLab Manager

Webservicedata,automatetasks,orintegrateVMware

®

Lab Managerwithother

softwaretestingtools.

Intended Audience

ThisguideisintendedfordeveloperswhowanttouseLab Managerdatafor

customizedtestingsolutions,orintegrateLab Managerandothersoftwaretestingtools

intheirenvironment.Forexample,usingtheLab ManagerSOAPAPIletsyouintegrate

Lab Managerwithautomatedsoftwaretestingtools.

Thisguideassumesyouhavesomefamiliaritywith:

 Virtualmachinetechnology

 Distributed,multitieredsystemsconcepts

 Developmentandtestingpractices

 WindowsorLinuxoperatingsystems

 WebServices,SOAP,andXML

Document Feedback

VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Ifyouhave

comments,sendyourfeedbackto:

[email protected]

About This Book

Lab Manager SOAP API Guide

8 VMware, Inc.

Technical Support and Education Resources

Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.To

accessthecurrentversionsofthisbookandotherbooks,goto:

http://www.vmware.com/support/pubs

Online and Telephone Support

Useonlinesupporttosubmittechnicalsupportrequests,viewyourproductand

contractinformation,andregisteryourproducts.Goto:

http://www.vmware.com/support

Customerswithappropriatesupportcontractsshouldusetelephonesupportforthe

fastestresponseonpriority1issues.Goto:

http://www.vmware.com/support/phone_support.html

Support Offerings

FindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds.Goto:

http://www.vmware.com/support/services

VMware Professional Services

VMwareEducationServicescoursesofferextensivehands‐onlabs,casestudy

examples,andcoursematerialsdesignedtobeusedason‐the‐jobreferencetools.

Coursesareavailableonsite,intheclassroom,andliveonline.Foronsitepilot

programs andimplementationbestpractices,VMwareConsultingServicesprovides

offeringsto helpyouassess,plan,

build,andmanageyourvirtualenvironment.To

accessinformationabouteducationclasses,certificationprograms,andconsulting

services,goto:

http://www.vmware.com/services/

VMware, Inc. 9

1

TheLab ManagerSOAPapplicationprogramminginterface(API)provides

programmaticaccesstotheLab Managersystem.ByusingthesecureAPI,youcan

connecttoLab ManagerServertoautomateorperformvariousoperations.

TheLab ManagerSOAPAPIusesXML‐basedtechnologies,includingSOAP,asthe

communicationprotocolandWebServicesDescriptionLanguage(WSDL)

asthe

interfacedescriptionlanguage.TheLab ManagerWSDLfiledetailstheavailable

methodsoftheservice(called“operations”inWebServicesvernacular)andparameter

types,aswellastheSOAPendpointfortheservice.

Thischapterincludesthefollowingtopics:

 “IntegratingLabManagerwithAutomatedTestingTools”onpage 10

 “SupportedOperations”onpage 10

 “LabManagerDataObjects”onpage 10

 “StandardsComplianceandCompatibleDevelopmentPlatforms”onpage 11

 “Security”onpage 11

 “UserAuthentication”onpage 11

Introducing VMware

Lab Manager SOAP API

1

Lab Manager SOAP API Guide

10 VMware, Inc.

Integrating Lab Manager with Automated Testing Tools

TheLab ManagerSOAPAPIallowsyoutointeractwithLab Managerdatausingthe

languageandplatformofyourchoice.TheexamplesinthisguideusetheC#

programminglanguageandtheMicrosoft.NETframework,butotherprogramming

languagesanddevelopmentenvironmentsarealsosupported.Ifyouareusinga

languageother

thanC#,seethedocumentationonyourdevelopmentenvironmentfor

comparableinformationaboutdevelopingWebserviceapplications.

InadditiontoextendingorcustomizingLab ManagerbyusingtheSOAPAPI,youcan

alsointegrateLab Managerwithautomatedtestingsystems.Youcanseeanexampleof

thisintegrationin“AdvancedC#Sample:Integrating

LabManagerandQuality

Center”onpage 19.

FormoreinformationaboutLab Managersolutions,developerresources,and

communityresources,gotohttp://www.vmware.com.

Supported Operations

UsingyourpreferredWeb‐enableddevelopmentenvironment,youcanconstructWeb

serviceclientapplicationsusingstandardWebserviceprotocolstoprogrammatically:

 Queryforvirtualmachineandconfigurationinformation.

 Performactionsonmachinesandconfigurations.

 Capture,checkout,clone,delete,anddeployconfigurations.

 CreateaLiveLinkconfigurationURLthatyoucanemailtootherteammembers.

FordetailedinformationaboutsupportedWebserviceoperations,see“LabManager

APIMethodReference”onpage 33.

Lab Manager Data Objects

TheLab ManagerSOAPAPIinteractswiththedatainyourorganizationusingobjects,

whichareprogrammaticrepresentationsoftheLab Managerdata.Objectproperties

representfieldsinthosedataentities.Forexample,aLab Managerconfigurationis

representedbyaConfigurationobject,whichhasfieldsthatrepresenttheconfiguration

name,configurationnumericidentifier,

deploymentstatus,sharedstate,andmore.

Thisdocumentdescribeshowtoperformoperationssuchasquery,clone,capture,and

deployonLab ManagerdatausingtheLab Managerdataobjects.See“LabManager

APIData Types”onpage 27.

VMware, Inc. 11

Chapter 1 Introducing VMware Lab Manager SOAP API

Standards Compliance and Compatible Development

Platforms

TheLab ManagerSOAPAPIcomplieswithSOAP1.1,WSDL1.1,andotherstandards

identifiedintheWS‐IBasicProfileVersion1.1.TheLab ManagerSOAPAPIworkswith

currentSOAPdevelopmentenvironmentsthatadheretotheBasicProfileVersion1.1

standards.TheexamplesinthisdocumentusetheMicrosoftVisualStudio

.NET2003

developmentenvironmentandtheC#programminglanguage.

IfyouareusingVisualStudiofor.NETdevelopment,VMwarerecommendsthatyou

useVisualStudio2003orhigher.

Security

ClientapplicationsthataccesstheLab Managerdatainyourorganizationaresubjectto

thesamesecurityprotectionsthatareusedintheLab ManagerWebconsole.

Lab ManagerexposesallSOAPAPImethodsusingSSL.

WhenaccessingtheSOAPAPIwiththeWebserviceURL,youmightseeanSSL

certificatewarning.Accept

thecertificatetousetheAPIorreplacethecertificatewitha

validsignedcertificate.

User Authentication

Clientapplicationsmustprovidevalidcredentials—aLab Manageruseraccount,

password,andorganizationname—witheachLab ManagerWebservicemethodcall.

TheLab ManagerServerauthenticatesthesecredentials.

N

OTEImplementationdifferencesincertaindevelopmentplatformsmightprevent

accesstosomeorallofthefeaturesintheLab ManagerSOAPAPI.

Lab Manager SOAP API Guide

12 VMware, Inc.

VMware, Inc. 13

2

YoucanreviewintroductoryinformationaboutusingtheLab ManagerSOAPAPIto

developanXMLWebserviceclient.AnXMLWebserviceclientisanycomponentor

applicationthatreferencesandusesanXMLWebservice.Thisdoesnotrequirea

client‐basedapplication.Inmanycases,XMLWebserviceclients

mightbeotherWeb

applications,suchasWebFormsorevenotherXMLWebservices.

Thischaptercoversthesetopics:

 “Requirements”onpage 13

 “ObtainingandImportingtheWSDL”onpage 14

 “SimpleandAdvancedCodeSamples”onpage 16

Requirements

TheinstructionsinthischapterassumethataninstanceofLab Managerisinstalled,

configured,andrunningonyournetwork.Beforeyoucanstartdevelopingan

application,reviewtheserequirements:

 YoumustknowtheaddressoftheLab Managerserverinstance,startingwithits

fullyqualifiedhostnameorIPaddress.Forexample:

https://hostname.company.com/LabManager

 YoumusthaveanaccountonthetargetLab Managerserver.

AssumingyouhaveanappropriateaccountontheLab ManagerServer,youcan

continuewith“ObtainingandImportingtheWSDL”onpage 14.

Getting Started with the

Lab Manager SOAP API

2

Lab Manager SOAP API Guide

14 VMware, Inc.

Obtaining and Importing the WSDL

Aswithanystandards‐basedSOAPAPIimplementation,theLab ManagerAPI

definitionisavailableontheWebserviceasanXML‐formattedWSDLfile.

ToobtaintheWSDL,launchInternetExplorer5.5orhigherandnavigatetothisURL

foryourLab ManagerServer:

https://<hostname>/LabManager/SOAP/LabManager.asmx?WSDL

TheWSDLdefinesalltheLab ManagerAPIcallsandobjects.

FormoreinformationonWSDL,gotohttp://www.w3.org/TR/wsdl.

Importing the WSDL File into Your Development Platform

AfteryouobtaintheWSDL,importitintoyourdevelopmentenvironmentand

generatethenecessaryobjectsforuseinbuildingclientWebserviceapplications.The

processdependsonyourdevelopmentenvironment,programminglanguage,and

associatedtools.Forexample,theMicrosoftVisualStudiodevelopmentenvironment

handlesthetasksautomatically.

Thenextsection

providesanexampleofobtainingtheWSDLandimportingitinthe

MicrosoftVisualStudio2003.Forinstructionsaboutotherdevelopmentplatforms,see

theproductdocumentationforyourplatform.

Instructions for Using Microsoft Visual Studio with Lab Manager

WSDL

MicrosoftVisualStudioprogramminglanguagesaccesstheLab ManagerSOAPAPI

throughobjectsthatserveasproxiesfortheirserver‐sidecounterparts.

WhenaccessingXMLWebservicesinmanagedcode,aproxyclassandthe.NET

Frameworkhandlealloftheinfrastructurecoding.

BeforeyoucanusetheLab ManagerSOAPAPIwith

VisualStudio,youmustfirst

generatetheproxyclassobjectfromtheWSDLfile.

VisualStudioprovidesawizard(“AddaWebReference”)toconnecttoaWebservice

andgeneratethenecessaryartifacts.YoucanaddaWebreferencetoanexisting

applicationorcreateanewapplicationinVisual

Studio.

TheinstructionsbelowarespecifictoMicrosoftVisualStudio2003.

VMware, Inc. 15

Chapter 2 Getting Started with the Lab Manager SOAP API

To add a Web reference

1FromtheWindowsStartmenu,launchMicrosoftVisualStudio.NET2003.

TheVisualStudioenvironmentopens.

2 SelectNewProjecttocreateanewproject,orselectOpentoopenanexisting

project.

3InVisualStudio,chooseAddWebReferencefromtheProjectmenu.

4IntheURLtextbox,typetheURLto

obtaintheservicedescriptionofthe

Lab ManagerWebservice:

https://<hostname>/LabManager/SOAP/LabManager.asmx

5ClickGo.

ThecertificateexchangebetweentheLab Managerserverandthedevelopment

environmentclientbegins.Asecurityalertdisplaysthedetailsofthecertificate

sentfromtheserver.

6ClickYes.

AnalertfromtheVisualStudioenvironmentmightappear.ClickYes.

The

MicrosoftVisualStudioenvironmentconnectstotheWebserviceendpointand

displaystheoperationsdescribedintheLab ManagerWebserviceWSDL.

7 SelectthetextintheWebreferencenametextboxandrenametheWebreference

toLabManagerSoap,thenamespaceusedforthisWebreference.

“LabManagerSoap”isoneword,withoutspaces.

8ClickAddReference.

Acertificatewarningmessagemightappear.ClickYes.

9ClickYesagain.

Seethe“A d d i ng andRemovingWebReferences”topicintheVisualStudio

documentation.

N

OTEThesecurityalertmessagesaregeneratedwhentheLab Managerserver

usesthedefault,self‐signedcertificates.Youcanreplacethesecertificatesonthe

Lab ManagerserverwithcertificatespurchasedfromVerisign,Thawte,andother

certificateauthorities.

Lab Manager SOAP API Guide

16 VMware, Inc.

VisualStudioretrievestheservicedescriptionandgeneratesaproxyclass

(LabManagerSoap)thatservesasaninterfacetotheLab ManagerWebservicefrom

yourapplication.Attheendoftheprocess,theclassisaddedtotheWebReferences

folderoftheproject.(ClickSolutionExplorertoseeLabManagerSoaplistedin

theWeb

Referencesfolder .)

Withthisbasicsetuptaskcompleted,youcanbuildclientapplicationsthatusethe

Lab ManagerSOAPAPI.ThefastestwaytobecomefamiliarwiththeAPIisby

reviewingthecodesamplelistedin“SimpleandAdvancedCodeSamples”onpage 16.

Simple and Advanced Code Samples

Thissectioncontainstwocodesamples—onesimpleandonemorecomplex—written

inC#usingtheMicrosoftVisualStudio2003IDE.

AssumingthatyouhaveaLab Managerinstancerunning,yourprogramming

environmentissetup,andyouhavetheappropriatepermissionsontheLab Manager

server(see“Requirements”onpage 13),youcantest

basicAPIprogramming

connectivitybetweenyourdevelopmentworkstationandyourLab ManagerWeb

servicebyusingthe“SimpleC#ConsoleApplication.”Copythecodelistingdisplayed

inthenextsection,andpasteitintoyourMicrosoftVisualStudio2003environment.

Thecodeperformsseveralsimpletasks.Thefirsttwotasks(bindingto

theWebservice

andprovidingcredentials)aretypicallyrequiredofanyapplicationthatmakescallsto

aLab ManagerWebservice:

 BindstotheLab ManagerSOAPAPI.

 SetsuptheusernameandpasswordformakingaSOAPcall.

 SetsuptheServicePointManagercertificatepolicytoaccepttheSSLcertificate.You

mustsetupthecertificatepolicytoacceptallcertificatestoconnecttotheAPI.

 Makesacalltogetaconfigurationobjectbasedonname.

 Displaysallconfigurationfieldsintheconsole.

N

OTEVMwareassumesyouarefamiliarwithbasicprogrammingconceptsand

alreadyhaveaprogrammingdevelopmentenvironmentsetuponyourcomputer.If

youareusingaprogramminglanguageotherthanC#andaWebservicesdevelopment

environmentotherthanMicrosoftVisualStudio2003,seetheappropriate

documentationformoreinformation.

VMware, Inc. 17

Chapter 2 Getting Started with the Lab Manager SOAP API

Simple C# Console Application

using System;

using System.Net;

namespace LMConsoleApplication1

{

class Class1

{

/// <summary>

/// The main entry point for the application.

/// </summary>

[STAThread]

static void Main(string[] args)

{

try

{

//

//** Bind to the Lab Manager SOAP API

//

LabManagerSoap.VMwareLabManagerSOAPinterface binding =

new LabManagerSoap.VMwareLabManagerSOAPinterface();

//

//** Enter the URL for your system here

//

binding.Url

="https://10.6.1.248/LabManager/SOAP/LabManag

er.asmx;

binding.Timeout = 10 * 60 * 1000; // 10 minutes

ServicePointManager.CertificatePolicy = new

CertificateAccepter();

//**

//** Allocate AuthenticationHeader object to hold caller’s

//** user name and password

//**

binding.AuthenticationHeaderValue = new

LabManagerSoap.AuthenticationHeader();

//

//** Substitute a real user’s user name, password, and

organization name here

//

binding.AuthenticationHeaderValue.username = "jaya";

binding.AuthenticationHeaderValue.password = "Lab Manager";

binding.AuthenticationHeaderValue.organizationname =

"MyOrg";

Lab Manager SOAP API Guide

18 VMware, Inc.

//**

//** Call GetSingleConfigurationByName()

//** Get default configuration that comes with Lab Manager

//** installation and write all property values to console

//**

LabManagerSoap.Configuration defCfg=

binding.GetSingleConfigurationByName("Sample

Configuration");

//

//** Print out all configuration properties to the Console

//

Console.WriteLine("Name = " + defCfg.name);

Console.WriteLine("ID = " + defCfg.id.ToString());

Console.WriteLine("Description = "+ defCfg.description);

Console.WriteLine("isPublic = "+

defCfg.isPublic.ToString());

Console.WriteLine("isDeployed = "+

defCfg.isDeployed.ToString());

Console.WriteLine("fenceMode = "+

defCfg.fenceMode.ToString());

Console.WriteLine("type = " + defCfg.type.ToString());

Console.WriteLine("owner = " + defCfg.owner);

Console.WriteLine("dateCreated = " +

defCfg.dateCreated.ToString());

Console.ReadLine();

}

catch (Exception e)

{

Console.WriteLine("Error: " + e.Message);

Console.ReadLine();

}

} //** end Main

} //** end Class1

/// <summary>

/// This class is needed to automatically accept the SSL certificate

/// the Lab Manager sends on each API call.

/// </summary>

VMware, Inc. 19

Chapter 2 Getting Started with the Lab Manager SOAP API

public class CertificateAccepter : System.Net.ICertificatePolicy

{

public CertificateAccepter() {}

public bool CheckValidationResult(

System.Net.ServicePoint servicePoint,

System.Security.Cryptography.X509Certificates.X509Certificate

cert,

System.Net.WebRequest webRequest, int iProblem)

{

return true;

}

} //** end Namespace}

Advanced C# Sample: Integrating Lab Manager and Quality

Center

TheC#.NETexampleinthissectionisamoreextensive—andmorepractical—example

ofusingtheLab ManagerSOAPAPI.Thissampleshowstheintegrationofthe

Lab ManagerSOAPAPIcallswithMercuryInteractiveCorporationQualityCenter

product.Thesamplecodeperformsthesetasks:

 MakesLab ManagerAPI(Lab ManagerSOAPAPI)callstocheckouta

configurationfromtheLibraryanddeployit.

 RunsaseriesofpredefinedtestsonthedeployedconfigurationusingMercury

QualityCenter.

 MakesLab ManagerSOAPAPIcallstocapturetheconfigurationandundeployit

fromtheWorkspace.

Thesetasksareaccomplishedinthesamplecodeusingthesethreemethods:

 CheckoutDeployConfiguration()method–Obtainstheconfigurationfromthe

LibraryanddeploysittotheLab ManagerWorkspace.

 RunQCTestset()method–RunsaseriesofpredefinedMercuryInteractiveQuality

Centertests.(Formoreinformationaboutthepredefinedtests,seetheMercury

InteractiveQualityCenterdocumentation.)

 CaptureUndeployConfiguration()method–Undeploystheconfigurationand

capturesittotheLibrary.

Inaddition,theGetLMAPI()methodcreatesanewbindingtotheLab ManagerAPI

andsetsupauthenticationparameters.Thismethodconfiguresthecertificatepolicyfor

the.NETservicepointmanagertoacceptanycertificateprogrammatically.

GetLMAPI()returnsaninstance

oftheLab Managerbinding.

Lab Manager SOAP API Guide

20 VMware, Inc.

using System;

using System.Configuration;

using System.Collections.Specialized;

using System.IO;

using System.Net;

using TDAPIOLELib; //** From Mercury Quality Center

namespace MATRun

{

/// <summary>

/// Class1 comprises methods to check out a configuration from the Lab

/// Manager Library and deploy it to the Workspace; execute several

/// tests; and capture a configuration.

/// </summary>

class Class1

{

/// <summary>

/// The main entry point for the application.

/// </summary>

[STAThread]

static void Main(string[] args)

{

NameValueCollection settings=ConfigurationSettings.AppSettings;

string filename = null;

string buildlocation = null;

string buildversion = null;

if ( args.Length > 0 )

{

buildlocation = args[0];

buildversion = args[1];

}

if ( buildlocation == null )

{

buildlocation =

@"\\fs.labmanger.com\public\build\outputdir\1423\artifac

ts";

buildversion = "Lab Manager-2.0.4018";

}

filename =

@"\\fs.labmanager.com\public\build\build-to-test.bat";

StreamWriter f = new StreamWriter(filename);

f.WriteLine(String.Format(@"xcopy {0}\setup.exe c:\ /Y",

buildlocation));

Page is loading ...

VMware vCenter Lab Manager 3.0 User guide

Related papers

Other documents