VMware vCenter vCenter Lab Manager 2.5 User guide

SOAP API Guide

Lab Manager 2.5

VMware, Inc.

3401 Hillview Ave.

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,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, and 7,290,253; 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: 20070709

Item: VLM-ENG-Q207-360

VMware, Inc. 3

Contents

AboutThisBook 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

VMware Lab Manager SOAP API Guide

4 VMware, Inc.

4 Lab ManagerAPIMethodReference 33

ConfigurationCapture 35

Syntax 35

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

VMware, Inc. 5

Contents

GetConfiguration 45

Syntax 45

Response 46

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 53

SampleCode:C# 53

ListMachines 54

Syntax 54

Arguments 54

Response 54

SampleCode:C# 54

VMware Lab Manager SOAP API Guide

6 VMware, Inc.

LiveLink 55

Syntax 55

Arguments 55

Response 56

SampleCode:C# 56

MachinePerformAction 57

Syntax 57

Arguments 57

Response 57

SampleCode:C# 57

Index 59

VMware, Inc. 7

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

 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

VMware Lab Manager SOAP API Guide

8 VMware, Inc.

Conventions

Table 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/communities/content/

 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

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

http://www.vmtn.net

Table 1. Conventions Used in This Manual

Style Elements

Blue(onlineonly) Links,cross‐references,andemailaddresses

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

About This Book

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 M anager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Server.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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. 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/LabManag

er.asmx;

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

ServicePointManager.CertificatePolicy = new

CertificateAccepter();

//**

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

//** username and password

VMware Lab Manager SOAP API Guide

20 VMware, Inc.

//**

binding.AuthenticationHeaderValue = new

LabManagerSoap.AuthenticationHeader();

//

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

{

Page is loading ...

VMware vCenter vCenter Lab Manager 2.5 User guide

VMware vCenter vCenter Lab Manager 2.5 User guide

Related papers

Other documents