Page is loading ...
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:
© 2006 VMware, Inc. All rights reserved. Protected by one or more of U.S. Patent Nos. 6,397,242,
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 IntroducingVMwareLabManagerSOAPAPI 11
IntegratingLabManagerwithAutomatedTestingTools 12
SupportedOperations 12
LabManagerDataObjects 12
StandardsComplianceandCompatibleDevelopmentPlatforms 13
Security 13
UserAuthentication 13
2 GettingStartedwiththeLabManagerSOAPAPI 15
Requirements 16
ObtainingandImportingtheWSDL 16
ImportingtheWSDLFileintoYourDevelopmentPlatform 16
InstructionsforUsingMicrosoftVisualStudiowithLabManagerWSDL 17
SimpleandAdvancedCodeSamples 18
SimpleC#ConsoleApplication 19
AdvancedSample:IntegratingLabManagerandQualityCenter 21
3 LabManagerAPIDataTypes 27
PrimitiveXMLDataTypes 28
LabManagerDataTypes 28
AuthenticationHeader 29
SupportedAPICalls 29
Fields 29
SampleUsage:C# 29
Configuration 30
Machine 30
4 LabManagerAPIMethodReference 33
ConfigurationCapture 35
Syntax 35
VMware® Lab Manager SOAP API Guide
4 VMware, Inc.
Arguments 35
Response 35
SampleCode:C# 35
ConfigurationCheckout 36
Syntax 36
Arguments 36
Response 36
SampleCode:C# 37
ConfigurationClone 38
Syntax 38
Arguments 38
Response 38
SampleCode:C# 38
ConfigurationDelete 39
Syntax 39
Arguments 39
Response 39
SampleCode:C# 39
ConfigurationDeploy 40
Syntax 40
Arguments 40
Response 40
SampleCode:C# 41
ConfigurationPerformAction 41
Syntax 42
Arguments 42
Response 42
SampleCode:C# 42
ConfigurationSetPublicPrivate 43
Syntax 43
Arguments 43
Response 43
SampleCode:C# 43
ConfigurationUndeploy 44
Syntax 44
Arguments 44
Response 44
SampleCode:C# 44
GetConfiguration 45
Syntax 45
VMware, Inc. 5
Contents
Response 45
SampleCode:C# 46
GetConfigurationByName 46
Syntax 46
Arguments 47
Response 47
SampleCode:C# 47
GetMachine 48
Syntax 48
Arguments 48
Response 48
SampleCode:C# 48
GetMachineByName 49
Syntax 49
Arguments 49
Response 49
SampleCode:C# 50
GetSingleConfigurationByName 50
Syntax 50
Arguments 50
Response 51
SampleCode:C# 51
ListConfigurations 52
Syntax 52
Arguments 52
Response 52
SampleCode:C# 52
ListMachines 53
Syntax 53
Arguments 53
Response 54
SampleCode:C# 54
LiveLink 55
Syntax 55
Arguments 55
Response 55
SampleCode:C# 55
MachinePerformAction 56
Syntax 56
Arguments 57
VMware, Inc. 7
ThisprefaceprovidesinformationabouttheVMwareLabManagerSOAPAPIGuideand
linkstoVMware
®
technicalsupportandeducationalresources.
Thisprefacecontainsthefollowingtopics:
“A b o u t ThisBook”
“TechnicalSupportandEducationResources”
About This Book
UsetheVMwareLabManagerSOAPAPIGuidetodevelopapplicationsthatleverageLab
ManagerWebservicedata,automatetasks,orintegrateLabManagerwithother
softwaretestingtools.
Intended Audience
ThisguideisintendedfordeveloperswhowanttoleverageLabManagerdatafor
customizedtestingsolutions,orintegrateLabManagerandothersoftwaretestingtools
intheirenvironment.Forexample,usingtheLabManagerSOAPAPIletsyouintegrate
LabManagerwithautomatedsoftwaretestingtools,suchasMercuryQuality
Center.
Thisguideassumesyouhavesomefamiliaritywith:
Virtualmachinetechnology
Distributed,multitieredsystemsconcepts
Developmentandtestingpractices
Preface
VMware® Lab Manager SOAP API Guide
8 VMware, Inc.
WindowsorLinuxoperatingsystems
WebServices,SOAP,andXML
Document Feedback
Ifyouhavecommentsaboutthisdocumentation,submityourfeedbackto:
Conventions
Table P‐1illustratesthetypographicconventionsusedinthismanual.
Technical Support and Education Resources
Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.
Self-Service Support
UsetheVMwareTechnologyNetwork(VMTN)forself‐helptoolsandtechnical
information:
Productinformation–http://www.vmware.com/products/
Technologyinformation–http://www.vmware.com/vcommunity/technology
Documentation–http://www.vmware.com/support/pubs
VMTNKnowledgeBase–http://www.vmware.com/support/kb
Discussionforums–http://www.vmware.com/community
Usergroups–http://www.vmware.com/vcommunity/usergroups.html
Table P-1. Conventions in this Manual
Style Elements
Blue(onlineonly) Cross‐referencesandemailaddresses
Blueboldface(onlineonly) Links
Blackboldface Userinterfaceelementssuchasbuttonnamesandmenuitems
Monospace Commands,filenames,directories,andpaths
Monospace bold Userinput
Italic Documenttitles,glossary terms,andoccasionalemphasis
<Name> Variableandparameternames
VMware, Inc. 9
Preface
FormoreinformationabouttheVMwareTechnologyNetwork,goto:
http://www.vmtn.net
Online and Telephone Support
Useonlinesupporttosubmittechnicalsupportrequests,viewyourproductand
contractinformation,andregisteryourproducts.Goto:
http://www.vmware.com/support
Customerswithappropriatesupportcontractsshouldusetelephonesupportforthe
fastestresponseonpriority1issues.Goto:
http://www.vmware.com/support/phone_support.html
Support Offerings
FindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds.Goto:
http://www.vmware.com/support/services
VMware Education Services
VMwarecoursesofferextensivehands‐onlabs,casestudyexamples,andcourse
materialsdesignedtobeusedason‐the‐jobreferencetools.Formoreinformationabout
VMwareEducationServices,goto:
http://mylearn1.vmware.com/mgrreg/index.cfm
VMware® Lab Manager SOAP API Guide
10 VMware, Inc.
VMware, Inc. 11
1
TheLabManagerWebserviceSOAPAPIprovidesprogrammaticaccesstotheLab
Managersystem.Byusingthesecureapplicationprogramminginterface(API),youcan
connecttoLabManagerServertoautomateorperformvariousoperations.
TheLabManagerWebserviceSOAPAPIusesXML‐basedtechnologies,including
SimpleObjectAccess
Protocol(SOAP)asthecommunicationprotocolandWeb
ServicesDescriptionLanguage(WSDL)astheinterfacedescriptionlanguage.TheLab
ManagerWSDLfiledetailstheavailablemethodsofthe service(called“operations”in
WebServicesvernacular)andparametertypes,aswellastheSOAPendpointforthe
service.
Thischaptercoversthese
topics:
“IntegratingLabManagerwithAutomatedTestingTools”onpage 12
“SupportedOperations”onpage 12
“LabManagerDataObjects”onpage 12
“StandardsComplianceandCompatibleDevelopmentPlatforms”onpage 13
“Security”onpage 13
Introducing VMware Lab
Manager SOAP API
1
VMware® Lab Manager SOAP API Guide
12 VMware, Inc.
Integrating Lab Manager with Automated Testing Tools
TheLabManagerWebserviceSOAPAPIallowsyoutoleverageLabManagerdata
usingthelanguageandplatformofyourchoice.TheexamplesinthisguideusetheC#
programminglanguageandtheMicrosoft.NETframework,butotherprogramming
languagesanddevelopmentenvironmentsarealsosupported.Ifyouareusing
a
languageotherthanC#,seethedocumentationonyourdevelopmentenvironmentfor
comparableinformationaboutdevelopingWebserviceapplications.
InadditiontoextendingorcustomizingLabManagerbyusingtheSOAPAPI,youcan
alsointegrateLabManagerwithautomatedtestingsystems.Youcanseeanexampleof
thisintegration
in“AdvancedSample:IntegratingLabManagerandQualityCenter”
onpage 21.
FormoreinformationaboutLabManagersolutions,developerresources,and
communityresources,gotohttp://www.vmware.com.
Supported Operations
UsingyourpreferredWeb‐enableddevelopmentenvironment,youcanconstructWeb
serviceclientapplicationsusingstandardWebserviceprotocolstoprogrammatically:
Queryforvirtualmachineandconfigurationinformation.
Performactionsonmachinesandconfigurations.
Capture,checkout,clone,delete,anddeployconfigurations.
CreateaLiveLinkconfigurationURLyoucanemailtootherteammembers.
FordetailedinformationaboutsupportedWebserviceoperations,see“LabManager
APIMethodReference”onpage 33.
Lab Manager Data Objects
TheLabManagerWebserviceSOAPAPIinteractswiththedatainyourorganization
usingobjects,whichareprogrammaticrepresentationsoftheLabManagerdata.Object
propertiesrepresentfieldsinthosedataentities.Forexample,aLabManager
configurationisrepresentedbyaConfigurationobject,whichhasfieldsthatrepresent
the
configurationname,configurationnumericidentifier,deploymentstatus,shared
state,andmore.
Thisdocumentdescribeshowtoperformoperationssuchasquery,clone,capture,and
deployonLabManagerdatausingtheLabManagerdataobjects.Fordetailed
information,see“LabManagerAPIDataTypes”onpage 27.
VMware, Inc. 13
Chapter 1 Introducing VMware Lab Manager SOAP API
Standards Compliance and Compatible Development
Platforms
TheLabManagerWebServiceSOAPAPIcomplieswithSOAP1.1,WSDL1.1,and
otherstandardsidentifiedintheWS‐IBasicProfileVersion1.1.TheLabManagerWeb
ServiceSOAPAPIworkswithcurrentSOAPdevelopmentenvironmentsthatadhere
totheBasicProfileVersion1.1standards.Theexamplesinthis
documentusethe
MicrosoftVisualStudio.NET2003developmentenvironmentandtheC#
programminglanguage.
IfyouareusingVisualStudiofor.NETdevelopment,VMwarerecommendsthatyou
useVisualStudio2003orhigher.
Security
ClientapplicationsthataccesstheLabManagerdatainyourorganizationaresubjectto
thesamesecurityprotectionsthatareusedintheLabManagerWebconsole.Lab
ManagerexposesallSOAPAPImethodsusingSSL.
WhenaccessingtheSOAPAPIwiththeWebserviceURL,youmightseeanSSL
certificatewarning.Acceptthecertificate tousetheAPIorreplacethecertificatewitha
validsignedcertificate.
User Authentication
Clientapplicationsmustprovidevalidcredentials—aLabManageruseraccountand
password—witheachLabManagerWebservicemethodcall.Theuseraccountmust
haveAdministratorprivilegesontheLabManagerServ er.TheLabManagerServer
authenticatesthesecredentials.
N
OTE Implementationdifferencesincertaindevelopmentplatformsmightprevent
accesstosomeorallofthefeaturesintheLabManagerWebserviceSOAPAPI.
VMware® Lab Manager SOAP API Guide
14 VMware, Inc.
VMware, Inc. 15
2
YoucanreviewintroductoryinformationaboutusingtheLabManagerWebservice
SOAPAPItodevelopanXMLWebserviceclient.AnXMLWebserviceclientisany
componentorapplicationthatreferencesandusesanXMLWebservice.Thisdoesnot
needtoinvolveaclient‐basedapplication.Inmany
cases,XMLWebserviceclients
mightbeotherWebapplications,suchasWebFormsorevenotherXMLWebservices.
Thischaptercoversthesetopics:
“Requirements”onpage 16
“ObtainingandImportingtheWSDL”onpage 16
“SimpleandAdvancedCodeSamples”onpage 18
Getting Started with the Lab
Manager SOAP API
2
VMware® Lab Manager SOAP API Guide
16 VMware, Inc.
Requirements
TheinstructionsinthischapterassumethataninstanceofLabManagerisinstalled,
configured,andrunningonyournetwork.Beforeyoucanstartdevelopingan
application,reviewtheserequirements:
YoumustknowtheaddressoftheLabManagerserverinstance,startingwithits
fully‐qualifiedhostnameorIPaddress.
Forexample,https://hostname.company.com/LabManager.
YoumusthaveanaccountwithLabManagerAdministratorprivilegesonthe
targetLabManagerserver.
IfyouarenotanAdministrator,haveyourLabManagerAdministratorsetyouup
withaLabManageraccount.
AssumingyouhaveanappropriateaccountontheLabManagerServer,youcan
continuewith“Obtaining
andImportingtheWSDL.”
Obtaining and Importing the WSDL
Aswithanystandards‐basedSOAPAPIimplementation,theLabManagerAPI
definitionisavailableontheWebserviceasanXML‐formattedWSDLfile.
ToobtaintheWSDL,launchInternetExplorer5.5orhigherandnavigatetothisURL
foryourLabManagerServer:
https://<hostname>/LabManager/SOAP/LabManager.asmx?WSDL
TheWSDLdefinesalltheLabManagerAPIcallsandobjects.
FormoreinformationonWSDL,see:
http://www.w3.org/TR/wsdl
Importing the WSDL File into Your Development Platform
AfteryouobtaintheWSDL,importitintoyourdevelopmentenvironmentand
generatethenecessaryobjectsforuseinbuildingclientWebserviceapplications.The
processdependsonyourdevelopmentenvironment,programminglanguage,and
associatedtools.Forexample,theMicrosoftVisualStudiodevelopmentenvironment
handlesthetasksautomatically.
Thenextsection
providesanexampleofobtainingtheWSDLandimportingitinthe
MicrosoftVisualStudio2003.Forinstructionsaboutotherdevelopmentplatforms,see
theproductdocumentationforyourplatform.
VMware, Inc. 17
Chapter 2 Getting Started with the Lab Manager SOAP API
Instructions for Using Microsoft Visual Studio with Lab Manager
WSDL
MicrosoftVisualStudioprogramminglanguagesaccesstheLabManagerWebservice
APIthroughobjectsthatserveasproxiesfortheirserver‐sidecounterparts.
WhenaccessingXMLWebservicesinmanagedcode,aproxyclassandthe.NET
Frameworkhandlealloftheinfrastructurecoding.
BeforeyoucanusetheLabManager
WebserviceAPIwithVisualStudio,youmustfirst
generatetheproxyclassobjectfromtheWSDLfile.
VisualStudioprovidesawizard(“AddaWebReference”)toconnecttoaWebservice
andgeneratethenecessaryartifacts.YoucanaddaWebreferencetoanexisting
applicationorcreatea
newapplicationinVisualStudio.
TheinstructionsbelowarespecifictoMicrosoftVisualStudio2003.
To add a Web reference
1FromtheWindowsStartmenu,launchMicrosoftVisualStudio.NET2003.
TheVisualStudioenvironmentopens.
2 SelectNewProjecttocreateanewproject,orselectOpentoopenanexisting
project.
3InVisualStudio,choose
AddWebReferencefromtheProjectmenu.
4IntheURLtextbox,typetheURLtoobtaintheservicedescriptionoftheLab
ManagerWebservice:
https://<hostname>/LabManager/SOAP/LabManager.asmx
5ClickGo.
ThecertificateexchangebetweentheLabManagerserverandthedevelopment
environmentclientbegins.Asecurityalertdisplaysthedetailsofthecertificate
sentfromtheserver.
6ClickYestoproceed.
N
OTE ThesecurityalertmessagesaregeneratedwhentheLabManagerserveruses
thedefault,self‐signedcertificates.Youcanreplacethesecertificatesonthe
LabManagerserverwithcertificatespurchasedfromVerisign,Thawte,and
othercertificateauthorities.
VMware® Lab Manager SOAP API Guide
18 VMware, Inc.
AnalertfromtheVisualStudioenvironmentmightappear.ClickYestoproceed.
TheMicrosoftVisualStudioenvironmentconnectstotheWebserviceendpoint
anddisplaystheoperationsdescribedintheLabManagerWebserviceWSDL.
7 SelectthetextintheWebreferencenametextboxandrenametheWebreference
toLabManagerSoap,thenamespaceusedforthisWebreference.
“LabManagerSoap”isoneword,withoutspaces.
8ClickAddReferencetocompletetheprocess.
Acertificatewarningmessagemightappear.ClickYes.
9ClickYesagaintoproceed.
Formoreinformation,seethe“A d d i n g andRemovingWebReferences”topicin
theVisualStudiodocumentation.
VisualStudio
retrievestheservicedescriptionandgeneratesaproxyclass
(LabManagerSoap)thatservesasaninterfacetotheLabManagerWebservicefrom
yourapplication.Attheendoftheprocess,theclassgetsaddedtotheWebReferences
folderoftheproject.(ClickSolutionExplorertoseeLabManagerSoaplistedinthe
Web
Referencesfolder .)
Withthisbasicsetuptaskcompleted,youcanbuildclientapplicationsthatusetheLab
ManagerWebServiceSOAPAPI.ThefastestwaytobecomefamiliarwiththeAPIisby
walkingthroughthecodesamplelistedinthenextsection.
Simple and Advanced Code Samples
Thissectioncontainstwocodesamples—onesimpleandonemorecomplex—written
inC#usingtheMicrosoftVisualStudio2003IDE.
AssumingthatyouhaveaLabManagerinstancerunning,yourprogramming
environmentissetup,andyouhavetheappropriatepermissionsontheLabManager
server(see“Requirements”onpage 16),you
cantestbasicAPIprogramming
connectivitybetweenyourdevelopmentworkstationandyourLabManagerWeb
servicebyusingthe“SimpleC#ConsoleApplication.”Copythecodelistingdisplayed
inthenextsection,andpasteitintoyourMicrosoftVisualStudio2003environment.
N
OTE VMwareassumesyouarefamiliarwithbasicprogrammingconceptsand
alreadyhaveaprogrammingdev elopmentenvironmentsetuponyour
computer.IfyouareusingaprogramminglanguageotherthanC#andaWeb
servicesdevelopmentenvironmentotherthanMicrosoftVisualStudio2003,
seetheappropriatedocumentationformoreinformation.
VMware, Inc. 19
Chapter 2 Getting Started with the Lab Manager SOAP API
Thecodeperformsseveralsimpletasks.Thefirsttwotasks(bindingtotheWebservice
andprovidingcredentials)aretypicallyrequiredofanyapplicationthatmakescallsto
aLabManagerWebservice:
BindstotheLabManagerWebServiceSOAPAPI.
SetsuptheusernameandpasswordformakingaSOAPcall.
SetsuptheServicePointManagercertificatepolicytoaccepttheSSLcertificate.You
mustsetupthecertificatepolicytoacceptallcertificatestoconnecttotheAPI.
Makesacalltogetaconfigurationobjectbasedonname.
Displaysallconfigurationfieldsintheconsole.
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)
/
