VMware vCenter vCenter Lab Manager 2.5 User guide

Brand: VMware vCenter

Model: vCenter Lab Manager 2.5

Type: 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

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

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.

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

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

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.

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.

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

VMware vCenter vCenter Lab Manager 2.5 User guide

Related papers

Other documents