SOAP API Guide Lab Manager 2.
VMware Lab Manager SOAP API Guide VMware Lab Manager SOAP API Guide Revision: 20070709 Item: VLM-ENG-Q207-360 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 © 2007 VMware, Inc. All rights reserved. Protected by one or more of U.S. Patent Nos.
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 Si
VMware Lab Manager SOAP API Guide 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
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
VMware Lab Manager SOAP API Guide 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 6 VMware, Inc.
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.
VMware Lab Manager SOAP API Guide Conventions Table 1 illustrates the typographic conventions used in this manual. Table 1.
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.
VMware Lab Manager SOAP API Guide 10 VMware, Inc.
1 Introducing VMware Lab Manager SOAP API 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.
VMware Lab Manager SOAP API Guide 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.
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 .
VMware Lab Manager SOAP API Guide 14 VMware, Inc.
2 Getting Started with the Lab Manager SOAP API 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.
VMware Lab Manager SOAP API Guide 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.
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.
VMware Lab Manager SOAP API Guide 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. 8 Click Add Reference to complete the process.
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.
VMware Lab Manager SOAP API Guide //** 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.
Chapter 2 Getting Started with the Lab Manager SOAP API 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 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.
VMware Lab Manager SOAP API Guide using System.IO; using System.Net; using TDAPIOLELib; //** From Mercury Quality Center namespace MATRun { /// /// Class1 comprises methods to check out configurations from the Lab /// Manager library and deploy to the workspace; execute several tests; /// and capture a configuration. /// class Class1 { /// /// The main entry point for the application.
Chapter 2 Getting Started with the Lab Manager SOAP API RunQCTestset(); CaptureUndeployConfiguration(config); } //** End Main() method // //** Initialize parameters // static string library_config = "ProofOfBuild-R2"; static string storage_server ="LM Server"; static string perform_capture =”Yes”; static string soap_server = "LM Server"; /// /// The RunQCTestset()method executes a series of pre-defined /// tests using Mercury Interactive’s Quality Center product.
VMware Lab Manager SOAP API Guide { System.Threading.Thread.Sleep(30); status.RefreshExecStatusInfo(null, true); } // results TDAPIOLELib.TSTestFactory tsf; tsf = (TSTestFactory) testSet.TSTestFactory; TDAPIOLELib.List testlist; testlist = tsf.NewList(""); foreach ( TSTest test in testlist) { TDAPIOLELib.Run r= (Run) test.LastRun; if (r != null) { Console.WriteLine(test.Name + " " + r.Name + " " + r.Status.
Chapter 2 Getting Started with the Lab Manager SOAP API //** Get configuration information -- Configuration object // LabManagerSoap.Configuration config = binding.GetSingleConfigurationByName(srcconfig); Console.WriteLine("Checkout configuratioin "+ srcconfig); // //** Check configuration out of Configuration Library and //** name it(configname) // int newCheckoutID = binding.ConfigurationCheckout(config.id, configname); Console.
VMware Lab Manager SOAP API Guide ///and sets up authentication and other basic parameters. This method ///returns a CertificateAcceptor object. /// static LabManagerSoap.VMwareLabManagerSOAPinterface GetLMAPI() { // //** Bind to SOAP interface // LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); // //**Allocate caller login object // binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.Url = binding.Url.
3 Lab Manager API Data Types 3 This chapter covers these topics about Lab Manager API data types: “Primitive XML Data Types” on page 28 “Lab Manager Data Types” on page 28 “AuthenticationHeader” on page 29 “Configuration” on page 30 “Machine” on page 30 VMware, Inc.
VMware Lab Manager SOAP API Guide Primitive XML Data Types Lab Manager SOAP API data types are based on the primitive XML data types shown in Table 3‐1. Table 3-1. Primitive XML Data Types in the Lab Manager SOAP API Value Description xsd:Boolean A logical value, including true, false, 0, and 1. xsd:date Date values. xsd:dateTime Date/time values (timestamps). xsd:double Numeric value that corresponds to the IEEE double‐precision 64‐bit floating point type defined in the standard IEEE 754‐1985.
Chapter 3 Lab Manager API Data Types AuthenticationHeader This data structure passes the user name and password of the caller in all Lab Manager Web service SOAP API methods. Supported API Calls All Fields Table 3-3. AuthenticationHeader Fields Field Data Type Description username string Lab Manager account user name. password string Lab Manager account password.
VMware Lab Manager SOAP API Guide Configuration This data structure exists for each configuration in the Lab Manager configuration library or Workspace. A configuration is a group of virtual machines (and its operating systems, applications, and data) which Lab Manager controls as a single unit. An integer ID field uniquely identifies a configuration. Configuration names are not guaranteed to be unique. Table 3-4. Configuration Fields Field Data Type Description id int Configuration identifier.
Chapter 3 Lab Manager API Data Types Table 3-5. Machine Fields (Continued) Field Data Type Description status int 1=Off, 2 =On, 3=Suspended, 4=Stuck, 128=Invalid. isDeployed boolean True if deployed VMware, Inc.
VMware Lab Manager SOAP API Guide 32 VMware, Inc.
4 Lab Manager API Method Reference 4 This section contains information about Lab Manager Web service methods and how to call them using C# .NET code samples. Table 4-1. Lab Manager Web Service SOAP API Methods Method Description “ConfigurationCapture” on page 35 Captures a Workspace configuration and saves it to a specified Lab Manager storage server. “ConfigurationCheckout” on page 36 Checks out a configuration from the configuration library and moves it to the Workspace.
VMware Lab Manager SOAP API Guide Table 4-1. Lab Manager Web Service SOAP API Methods (Continued) 34 Method Description “GetConfigurationByName” on page 47 Returns Configuration objects matching a configuration name. (Configuration names are not guaranteed to be unique.) “GetMachine” on page 48 Returns a Machine object matching a machine identifier. “GetMachineByName” on page 50 Returns a Machine object matching a machine name.
Chapter 4 Lab Manager API Method Reference ConfigurationCapture This method captures a Workspace configuration and saves it to a specified Lab Manager storage server with a name. Syntax int newConfigId = ConfigurationCapture(10, “Config10Capture”); Arguments Table 4-2. Arguments Field Data Type Description configurationID int Configuration identifier. newLibraryName string Capture name. Response Table 4-3.
VMware Lab Manager SOAP API Guide //** Get configuration identifier and deployed status from object int configurationId = Config.id; bool deployed = Config.isDeployed; //** Capture configuration if it’s deployed if (deployed) { //** Save capture with date and time stamp string captureName=Config.name + DateTime.Now.ToString(); string LMStorageServer = "LM Server"; binding.ConfigurationCapture(configurationId, captureName); } } catch (Exception e) { Console.WriteLine("Error: " + e.Message); Console.
Chapter 4 Lab Manager API Method Reference Sample Code: C# try { // //** LMSoap is the name of the Web reference in Visual Studio. // LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); // //** Create login // binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.username = "jaya"; binding.AuthenticationHeaderValue.password = "Lab Manager"; binding.Url = "https://demo18.LabManager.
VMware Lab Manager SOAP API Guide ConfigurationClone This method clones a Workspace configuration, saves it in a storage server, and makes it visible in the Workspace under the new name. Syntax int result = ConfigurationClone(6, “Config6Clone”); Arguments Table 4-6. Arguments Field Data Type Description configurationId int Numeric identifier of the configuration in the configuration library. newWorkspaceName string Workspace name of the clone. Response Table 4-7.
Chapter 4 Lab Manager API Method Reference catch (Exception e) { Console.WriteLine("Error: " + e.Message); Console.ReadLine(); } ConfigurationDelete This method deletes a configuration from the Workspace. You cannot delete a deployed configuration. Syntax ConfigurationDelete(6); Arguments Table 4-8. Arguments Field Data Type Description configurationID int Numeric identifier of the Workspace configuration. Response none Sample Code: C# try { LabManagerSoap.
VMware Lab Manager SOAP API Guide //** Delete configuration if it isn’t deployed if (!deployed) { binding.ConfigurationDelete(configurationId); } else { //** //** Must undeploy configuration before deleting it //** binding.ConfigurationUndeploy(configurationId); binding.ConfigurationDelete(configurationId); } } catch (Exception e) { Console.WriteLine("Error: " + e.Message); Console.
Chapter 4 Lab Manager API Method Reference Sample Code: C# try { LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); //** Create login binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.username = "jaya"; binding.AuthenticationHeaderValue.password = "Lab Manager"; ServicePointManager.CertificatePolicy = new CertificateAccepter(); //** Get Configuration object LabManagerSoap.
VMware Lab Manager SOAP API Guide 6—Snapshot. Saves a configuration state at a specific point in time. 7—Revert. Returns the configuration to a snapshot state. 8—Shutdown. Shuts down a configuration before turning it off. Syntax ConfigurationPerformAction(int configurationID, int action); Arguments Table 4-10. Arguments Field Data Type Description configurationID int Configuration identifier. action int Action to take on the configuration.
Chapter 4 Lab Manager API Method Reference binding.ConfigurationPerformAction(configurations[j].id,4/*Resum e*/); } } catch (Exception e) { Console.WriteLine("Error: " + e.Message); Console.ReadLine(); } ConfigurationSetPublicPrivate Use this call to set the state of a configuration to “public” or “private.” If the configuration state is public, others are able to access this configuration. If the configuration is private, only its owner can view it.
VMware Lab Manager SOAP API Guide binding.AuthenticationHeaderValue.password = "Lab Manager"; ServicePointManager.CertificatePolicy = new CertificateAccepter(); //** Get Configuration object LabManagerSoap.Configuration Config = binding.GetSingleConfigurationByName("Config24"); //** Get configuration identifier and shared status from object bool shared = Config.isPublic; //** Make configuration public if it isn’t already. if (!shared) { binding.ConfigurationSetPublicPrivate(Config.
Chapter 4 Lab Manager API Method Reference binding.Url = "https://demo18.LabManager.com/LabManager/SOAP/LabManager.asmx"; binding.Timeout = 10 * 60 * 1000; // 10 minutes ServicePointManager.CertificatePolicy = new CertificateAccepter(); binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.username = "jaya"; binding.AuthenticationHeaderValue.
VMware Lab Manager SOAP API Guide Response Table 4-14. Response Field Data Type Description configuration Configuration Configuration object matching configuration id passed. Sample Code: C# try { //** LabManagerSoap is the name of the web reference in Visual Studio LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); //** Create login binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.
Chapter 4 Lab Manager API Method Reference GetConfigurationByName This call takes the name of a configuration and returns an array of configurations matching that name. Configuration names are not unique. More than one configuration with a given name can exist. If configurations with that name do not exist, an empty array is returned. Syntax Configuration [] config = GetConfigurationByName(“Config9”); Arguments Table 4-15. Arguments Field Data Type Description name string Configuration name.
VMware Lab Manager SOAP API Guide // //** Write to the console all configurations and their properties. // for (int i=0; i < Configs.Length; i++) { Console.WriteLine("Config name = " + Configs[i].name); Console.WriteLine("id = " + Configs[i].id.ToString()); Console.WriteLine("description = " + Configs[i].description); Console.WriteLine("isPublic = " + Configs[i].isPublic.ToString()); Console.WriteLine("isDeployed = " + Configs[i].isDeployed.ToString()); Console.WriteLine("fenceMode = " + Configs[i].
Chapter 4 Lab Manager API Method Reference Response Table 4-18. Response Field Data Type Description machine Machine Machine object matching the machine identifier. Sample Code: C# try { LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.username = "jaya"; binding.AuthenticationHeaderValue.
VMware Lab Manager SOAP API Guide GetMachineByName This call takes a configuration identifier and a machine name and returns the matching Machine object. Syntax Machine mach = GetMachineByName(10, “Config9VM1”); Arguments Table 4-19. Arguments Field Data Type Description configurationId int Configuration identifier. name string Machine name. Response Table 4-20. Response Field Data Type Description machine Machine Machine Object. Sample Code: C# try { LabManagerSoap.
Chapter 4 Lab Manager API Method Reference Console.WriteLine("isDeployed = " + machine.isDeployed.ToString()); Console.ReadLine(); } catch (Exception e) { Console.WriteLine("Error: " + e.Message); Console.ReadLine(); } GetSingleConfigurationByName This call takes a configuration name, searches for it in both the configuration library and Workspace and returns its corresponding Configuration object. An error is returned if more than one configuration exists with that name.
VMware Lab Manager SOAP API Guide ServicePointManager.CertificatePolicy = new CertificateAccepter(); //** Get Configuration object LabManagerSoap.Configuration Config = binding.GetSingleConfigurationByName("Config24Capture"); //** Write to the console all configuration properties. Console.WriteLine("Config name = " + Config.name); Console.WriteLine("Config id = " + Config.id.ToString()); Console.WriteLine("Config description = " + Config.description); Console.WriteLine("Config isPublic = " + Config.
Chapter 4 Lab Manager API Method Reference Response Table 4-24. Response Field Data Type Description configurations[] Configuration Array Array of Configuration objects. Sample Code: C# try { //** //** LabManagerSoap is the name of the Web reference in Visual Studio. //** LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); //** Create login binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.
VMware Lab Manager SOAP API Guide Console.ReadLine(); } catch (Exception e) { Console.WriteLine("Error: " + e.Message); Console.ReadLine(); } ListMachines This method returns an array of type Machine. The method returns one Machine object for each virtual machine in a configuration. Syntax Machine [] machines = ListMachines(1); Arguments Table 4-25. Arguments Field Data Type Description configurationID int Configuration numeric identifier. Response Table 4-26.
Chapter 4 Lab Manager API Method Reference int configurationType = 1; //** Get workspace configuration LabManagerSoap.Configuration [] configurations = binding.ListConfigurations(configurationType); for (int j=0; j < configurations.Length; j++) { Console.WriteLine("Configuration = " + configurations[j].name.ToString()); LabManagerSoap.Machine [] machines = binding.ListMachines(configurations[j].id); //** Write to the console all machines in configuration for (int i=0; i < machines.Length; i++) { Console.
VMware Lab Manager SOAP API Guide Response Table 4-28. Response Field Data Type Description URL string A string containing the configuration URL in the library. The URL can be sent in an email to recreate the configuration when clicked. Sample Code: C# try { LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); //** Create login binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.
Chapter 4 Lab Manager API Method Reference MachinePerformAction This method performs one of the following machine actions as indicated by the action identifier: 1—Power On. Turns on a machine. 2—Power Off. Turns off a machine. Nothing is saved. 3—Suspend. Freezes a machine CPU and state. 4—Resume. Resumes a suspended machine. 5—Reset. Reboots a machine. 6—Snapshot. Save a machine state at a specific point in time. 7—Revert. Returns a machine to a snapshot state. 8—Shutdown.
VMware Lab Manager SOAP API Guide int configurationType = 1; //** Get workspace configuration //** //** Get array of all configurations //** LabManagerSoap.Configuration [] configurations = binding.ListConfigurations(configurationType); //** //** Loop through all configurations. //** for (int j=0; j < configurations.Length; j++) { //** //** Get array of all machines in configurations //** LabManagerSoap.Machine [] machines = binding.ListMachines(configurations[j].
Index C O CaptureUndeployConfiguration 25 CertificateAccepter() 26 CheckoutDeployConfiguration 24 Code simple and advanced samples 18 operations supported 12 D S data types AuthenticationHeader 29 Configuration 30 for Lab Manager 28 Machine 30 primitive XML 28 development environment supported 12 security using SSL 13 SOAP API obtaining the WSDL 16 SOAP API methods ConfigurationCapture 35 ConfigurationCheckout 36 ConfigurationClone 38 ConfigurationDelete 39 ConfigurationDeploy 40 ConfigurationPerfor
VMware Lab Manager SOAP API Guide T technical support resources 8 U user groups accessing 8 users authenticating 13 V VMware community forums accessing 8 60 VMware, Inc.
