VMware vCenter vCenter Lab Manager 2.4 User guide

VMware® Lab Manager

SOAP API Guide

VMware Lab Manager 2.4

VMware, Inc.

3145 Porter Drive

Palo Alto, CA 94304

www.vmware.com

2 VMware, Inc.

VMware® 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:

[email protected]

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,961,941, 6,961,806 and 6,944,699; 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. All other marks and names

mentioned herein may be trademarks of their respective companies.

VMware Lab Manager SOAP API Guide

Revision: 20061220

Item: VL-ENG-Q406-301

VMware, Inc. 3

Contents

Preface 7

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

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

SupportedOperations 12

LabManagerDataObjects 12

StandardsComplianceandCompatibleDevelopmentPlatforms 13

Security 13

UserAuthentication 13

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

Requirements 16

ObtainingandImportingtheWSDL 16

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

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

SimpleandAdvancedCodeSamples 18

SimpleC#ConsoleApplication 19

AdvancedSample:IntegratingLabManagerandQualityCenter 21

3 LabManagerAPIDataTypes 27

PrimitiveXMLDataTypes 28

LabManagerDataTypes 28

AuthenticationHeader 29

SupportedAPICalls 29

Fields 29

SampleUsage:C# 29

Configuration 30

Machine 30

4 LabManagerAPIMethodReference 33

ConfigurationCapture 35

Syntax 35

VMware® Lab Manager SOAP API Guide

4 VMware, Inc.

Arguments 35

Response 35

SampleCode:C# 35

ConfigurationCheckout 36

Syntax 36

Arguments 36

Response 36

SampleCode:C# 37

ConfigurationClone 38

Syntax 38

Arguments 38

Response 38

SampleCode:C# 38

ConfigurationDelete 39

Syntax 39

Arguments 39

Response 39

SampleCode:C# 39

ConfigurationDeploy 40

Syntax 40

Arguments 40

Response 40

SampleCode:C# 41

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

GetConfiguration 45

Syntax 45

VMware, Inc. 5

Contents

Response 45

SampleCode:C# 46

GetConfigurationByName 46

Syntax 46

Arguments 47

Response 47

SampleCode:C# 47

GetMachine 48

Syntax 48

Arguments 48

Response 48

SampleCode:C# 48

GetMachineByName 49

Syntax 49

Arguments 49

Response 49

SampleCode:C# 50

GetSingleConfigurationByName 50

Syntax 50

Arguments 50

Response 51

SampleCode:C# 51

ListConfigurations 52

Syntax 52

Arguments 52

Response 52

SampleCode:C# 52

ListMachines 53

Syntax 53

Arguments 53

Response 54

SampleCode:C# 54

LiveLink 55

Syntax 55

Arguments 55

Response 55

SampleCode:C# 55

MachinePerformAction 56

Syntax 56

Arguments 57

VMware® Lab Manager SOAP API Guide

6 VMware, Inc.

Response 57

SampleCode:C# 57

Index 59

VMware, Inc. 7

ThisprefaceprovidesinformationabouttheVMwareLabManagerSOAPAPIGuideand

linkstoVMware

®

technicalsupportandeducationalresources.

Thisprefacecontainsthefollowingtopics:

 “A b o u t ThisBook”

 “TechnicalSupportandEducationResources”

About This Book

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

ManagerWebservicedata,automatetasks,orintegrateLabManagerwithother

softwaretestingtools.

Intended Audience

Thisguideisintendedfordeveloperswhowanttoleverage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,suchasMercuryQuality

Center.

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

 Virtualmachinetechnology

 Distributed,multitieredsystemsconcepts

 Developmentandtestingpractices

Preface

VMware® Lab Manager SOAP API Guide

8 VMware, Inc.

 WindowsorLinuxoperatingsystems

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

Document Feedback

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

[email protected]

Conventions

Table P‐1illustratesthetypographicconventionsusedinthismanual.

Technical Support and Education Resources

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

Self-Service Support

UsetheVMwareTechnologyNetwork(VMTN)forself‐helptoolsandtechnical

information:

 Productinformation–http://www.vmware.com/products/

 Technologyinformation–http://www.vmware.com/vcommunity/technology

 Documentation–http://www.vmware.com/support/pubs

 VMTNKnowledgeBase–http://www.vmware.com/support/kb

 Discussionforums–http://www.vmware.com/community

 Usergroups–http://www.vmware.com/vcommunity/usergroups.html

Table P-1. Conventions in this Manual

Style Elements

Blue(onlineonly) Cross‐referencesandemailaddresses

Blueboldface(onlineonly) Links

Blackboldface Userinterfaceelementssuchasbuttonnamesandmenuitems

Monospace Commands,filenames,directories,andpaths

Monospace bold Userinput

Italic Documenttitles,glossary terms,andoccasionalemphasis

<Name> Variableandparameternames

VMware, Inc. 9

Preface

FormoreinformationabouttheVMwareTechnologyNetwork,goto:

http://www.vmtn.net

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 Education Services

VMwarecoursesofferextensivehands‐onlabs,casestudyexamples,andcourse

materialsdesignedtobeusedason‐the‐jobreferencetools.Formoreinformationabout

VMwareEducationServices,goto:

http://mylearn1.vmware.com/mgrreg/index.cfm

VMware® Lab Manager SOAP API Guide

10 VMware, Inc.

VMware, Inc. 11

1

TheLabManagerWebserviceSOAPAPIprovidesprogrammaticaccesstotheLab

Managersystem.Byusingthesecureapplicationprogramminginterface(API),youcan

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

TheLabManagerWebserviceSOAPAPIusesXML‐basedtechnologies,including

SimpleObjectAccess

Protocol(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coversthese

topics:

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

 “SupportedOperations”onpage 12

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

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

 “Security”onpage 13

Introducing VMware Lab

Manager SOAP API

1

VMware® Lab Manager SOAP API Guide

12 VMware, Inc.

Integrating Lab Manager with Automated Testing Tools

TheLabManagerWebserviceSOAPAPIallowsyoutoleverage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Sample:IntegratingLabManagerandQualityCenter”

onpage 21.

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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Webservice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.Fordetailed

information,see“LabManagerAPIDataTypes”onpage 27.

VMware, Inc. 13

Chapter 1 Introducing VMware Lab Manager SOAP API

Standards Compliance and Compatible Development

Platforms

TheLabManagerWebService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Web

Service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and

password—witheachLabManagerWebservicemethodcall.Theuseraccountmust

haveAdministratorprivilegesontheLabManagerServ er.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WebserviceSOAPAPI.

VMware® Lab Manager SOAP API Guide

14 VMware, Inc.

VMware, Inc. 15

2

YoucanreviewintroductoryinformationaboutusingtheLabManagerWebservice

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

needtoinvolve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 16

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

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

Getting Started with the Lab

Manager SOAP API

2

VMware® Lab Manager SOAP API Guide

16 VMware, Inc.

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withLabManagerAdministratorprivilegesonthe

targetLabManagerserver.

IfyouarenotanAdministrator,haveyourLabManagerAdministratorsetyouup

withaLabManageraccount.

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

continuewith“Obtaining

andImportingtheWSDL.”

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,see:

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.

VMware, Inc. 17

Chapter 2 Getting Started with the Lab Manager SOAP API

Instructions for Using Microsoft Visual Studio with Lab Manager

WSDL

MicrosoftVisualStudioprogramminglanguagesaccesstheLabManagerWebservice

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

Webservice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.

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toproceed.

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.

VMware® Lab Manager SOAP API Guide

18 VMware, Inc.

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

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tocompletetheprocess.

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

9ClickYesagaintoproceed.

Formoreinformation,seethe“A d d i n g andRemovingWebReferences”topicin

theVisualStudiodocumentation.

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gets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WebServiceSOAPAPI.ThefastestwaytobecomefamiliarwiththeAPIisby

walkingthroughthecodesamplelistedinthenextsection.

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 16),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.

N

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

alreadyhaveaprogrammingdev elopment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. 19

Chapter 2 Getting Started with the Lab Manager SOAP API

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WebService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.

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 Web Service

//

LabManagerSoap.VMwareLabManagerSOAPinterface binding =

new LabManagerSoap.VMwareLabManagerSOAPinterface();

//

//** Enter the URL for your system here

//

binding.Url ="https://10.6.1.248/LabManager/SOAP/LabManager.asmx;

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

ServicePointManager.CertificatePolicy = new CertificateAccepter();

//**

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

//** username and password

//**

binding.AuthenticationHeaderValue = new

LabManagerSoap.AuthenticationHeader();

VMware® Lab Manager SOAP API Guide

20 VMware, Inc.

//

//** Substitute a real user’s username and password here

//

binding.AuthenticationHeaderValue.username = "jaya";

binding.AuthenticationHeaderValue.password = "Lab Manager";

//**

//** Call GetSingleConfigurationByName()

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

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

//**

LabManagerSoap.Configuration defCfg=

binding.GetSingleConfigurationByName("Sample 1");

//

//** 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>

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)

Page is loading ...

VMware vCenter vCenter Lab Manager 2.4 User guide

VMware vCenter vCenter Lab Manager 2.4 User guide

Related papers

Other documents