SOAP API Guide Lab Manager 3.
Lab Manager SOAP API Guide Lab Manager SOAP API Guide Revision: 20080804 Item: EN-000067-00 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 © 2006–2008 VMware, Inc. All rights reserved. Protected by one or more U.S. Patent Nos.
Contents About This Book 7 1 Introducing VMware Lab Manager SOAP API 9 Integrating Lab Manager with Automated Testing Tools 10 Supported Operations 10 Lab Manager Data Objects 10 Standards Compliance and Compatible Development Platforms 11 Security 11 User Authentication 11 2 Getting Started with the Lab Manager SOAP API 13 Requirements 13 Obtaining and Importing the WSDL 14 Importing the WSDL File into Your Development Platform 14 Instructions for Using Microsoft Visual Studio with Lab Manager WSDL Sim
Lab Manager SOAP API Guide 4 Lab Manager API Method Reference 33 ConfigurationCapture 34 Syntax 34 Arguments 34 Response 35 Sample Code: C# 35 ConfigurationCheckout 36 Syntax 36 Arguments 36 Response 36 Sample Code: C# 36 ConfigurationClone 37 Syntax 37 Arguments 37 Response 38 Sample Code: C# 38 ConfigurationDelete 38 Syntax 38 Arguments 39 Response 39 Sample Code: C# 39 ConfigurationDeploy 40 Syntax 40 Arguments 40 Response 40 Sample Code: C# 40 ConfigurationPerformAction 41 Syntax 42 Arguments 42 Respon
Contents GetConfiguration 45 Syntax 45 Response 45 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 52 Sample Code: C# 53 ListMachines 54 Syntax 54 Arguments 54 Response 54 Sample
Lab Manager SOAP API Guide MachinePerformAction 56 Syntax 57 Arguments 57 Response 57 Sample Code: C# 57 Index 59 6 VMware, Inc.
About This Book Use the Lab Manager SOAP API Guide to develop applications that use Lab Manager Web service data, automate tasks, or integrate VMware® Lab Manager with other software testing tools. Intended Audience This guide is intended for developers who want to use Lab Manager data for customized testing solutions, or integrate Lab Manager and other software testing tools in their environment.
Lab Manager SOAP API Guide Technical Support and Education Resources The following sections describe the technical support resources available to you. To access the current versions of this book and other books, go to: http://www.vmware.com/support/pubs 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.
1 Introducing VMware Lab Manager SOAP API 1 The Lab Manager SOAP application programming interface (API) provides programmatic access to the Lab Manager system. By using the secure API, you can connect to Lab Manager Server to automate or perform various operations. The Lab Manager SOAP API uses XML‐based technologies, including SOAP, as the communication protocol and Web Services Description Language (WSDL) as the interface description language.
Lab Manager SOAP API Guide Integrating Lab Manager with Automated Testing Tools The Lab Manager SOAP API allows you to interact with 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 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 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.
Lab Manager SOAP API Guide 12 VMware, Inc.
2 Getting Started with the Lab Manager SOAP API 2 You can review introductory information about using the Lab Manager 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 require 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.
Lab Manager SOAP API Guide 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:///LabManager/SOAP/LabManager.asmx?WSDL The WSDL defines all the Lab Manager API calls and objects. For more information on WSDL, go to http://www.w3.org/TR/wsdl.
Chapter 2 Getting Started with the Lab Manager SOAP API To add a Web reference 1 From 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. 3 In Visual Studio, choose Add Web Reference from the Project menu. 4 In the URL text box, type the URL to obtain the service description of the Lab Manager Web service: https:///LabManager/SOAP/LabManager.
Lab Manager SOAP API Guide 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 is 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 SOAP API.
Chapter 2 Getting Started with the Lab Manager SOAP API Simple C# Console Application using System; using System.Net; namespace LMConsoleApplication1 { class Class1 { /// /// The main entry point for the application. /// [STAThread] static void Main(string[] args) { try { // //** Bind to the Lab Manager SOAP API // LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); // //** Enter the URL for your system here // binding.
Lab Manager SOAP API Guide //** //** Call GetSingleConfigurationByName() //** Get default configuration that comes with Lab Manager //** installation and write all property values to console //** LabManagerSoap.Configuration defCfg= binding.GetSingleConfigurationByName("Sample Configuration"); // //** Print out all configuration properties to the Console // Console.WriteLine("Name = " + defCfg.name); Console.WriteLine("ID = " + defCfg.id.ToString()); Console.WriteLine("Description = "+ defCfg.
Chapter 2 Getting Started with the Lab Manager SOAP API 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) { return true; } } } //** end Namespace} Advanced C# Sample: Integrating Lab Manager and Quality Center The C# .
Lab Manager SOAP API Guide using using using using using using System; System.Configuration; System.Collections.Specialized; System.IO; System.Net; TDAPIOLELib; //** From Mercury Quality Center namespace MATRun { /// /// Class1 comprises methods to check out a configuration from the Lab /// Manager Library and deploy it 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 f.Close(); Console.WriteLine(String.
Lab Manager SOAP API Guide { if ( testSet.Name.ToUpper() == chosenTestSet.ToUpper()) { Console.WriteLine("Scheduling "+ testSet.Name); TSScheduler sched = (TSScheduler) testSet.StartExecution(host); sched.RunAllLocally = false; sched.Run(null); ExecutionStatus status = (ExecutionStatus) sched.ExecutionStatus; while ( status.Finished == false ) { System.Threading.Thread.Sleep(30); status.RefreshExecStatusInfo(null, true); } // results TDAPIOLELib.TSTestFactory tsf; tsf = (TSTestFactory) testSet.
Chapter 2 Getting Started with the Lab Manager SOAP API static string CheckoutDeployConfiguration( string version) { // //** Check out a configuration and deploy it to the Workspace string srcconfig = "ProofOfBuild-R2"; //** Configuration name System.DateTime time = System.DateTime.Now; string configname = version+"-"+ time.ToString().Replace(" ", "_").Replace("/","-"); // //** Bind to Lab Manager SOAP Web service // LabManagerSoap.
Lab Manager SOAP API Guide static void CaptureUndeployConfiguration(string configname) { // //** Bind to Lab Manager SOAP Web Service // LabManagerSoap.VMwareLabManagerSOAPinterface binding = GetLMAPI(); LabManagerSoap.Configuration config = binding.GetSingleConfigurationByName(configname); if ( perform_capture.Equals("Yes") ) { Console.WriteLine("Capture configuration "+ configname); int newConfigCaptureID = binding.ConfigurationCapture(config.id, configname); } Console.
Chapter 2 Getting Started with the Lab Manager SOAP API /// /// /// /// /// The CertificateAccepter class automatically accepts the SSL certificate sent by Lab Manager with each API call from a client application. public class CertificateAccepter : System.Net.ICertificatePolicy { public CertificateAccepter() {} public bool CheckValidationResult( System.Net.ServicePoint servicePoint, System.Security.Cryptography.X509Certificates.X509Certificate cert, System.Net.
Lab Manager SOAP API Guide 26 VMware, Inc.
3 Lab Manager API Data Types 3 This chapter covers these topics about Lab Manager API data types: “Primitive XML Data Types” on page 27 “Lab Manager Data Types” on page 28 “AuthenticationHeader” on page 28 “Configuration” on page 29 “Machine” on page 30 Primitive XML Data Types Lab Manager SOAP API data types are based on the primitive XML data types shown in Table 3‐1. These primitive types are the building blocks for the Lab Manager data types used in making Lab Manager API calls.
Lab Manager SOAP API Guide Lab Manager Data Types When writing your client application, follow the data typing rules defined for your programming language and development environment.Your development tool handles the mapping of typed data in your programming language with these SOAP data types. The Lab Manager data types are defined in the Lab Manager WSDL file. For each type, this chapter lists its properties and description. Table 3-2.
Chapter 3 Lab Manager API Data Types Sample Usage: C# /** ** Visual Studio Console application in C# ** LMsoap = Web reference name for LM Web service ** Set up login code for all LM Web service method calls ** **/ try { LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); binding.AuthenticationHeaderValue =new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.username = "hedley"; binding.AuthenticationHeaderValue.
Lab Manager SOAP API Guide Table 3-4. Configuration Fields (Continued) Field Data Type Description isDeployed boolean True if deployed; false if not deployed. isPublic boolean True if others can view and access; false if not. name string Configuration name. owner string Owner user name. type int Configuration type: 1 =Workspace configurations, 2 = Library configurations. Machine This data structure exists for each virtual machine in the configuration library or Workspace of Lab Manager.
Chapter 3 Lab Manager API Data Types Table 3-5. Machine Fields (Continued) Field Data Type Description ownerFullName string Full name of the virtual machine owner. status int 1=Off 2 =On 3=Suspended 4=Stuck 128=Invalid. VMware, Inc.
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 SOAP API Methods Method Description “ConfigurationCapture” on page 34 Captures a Workspace configuration and saves it to a specified Lab Manager datastore. “ConfigurationCheckout” on page 36 Checks out a configuration from the configuration library and moves it to the Workspace.
Lab Manager SOAP API Guide Table 4-1. Lab Manager SOAP API Methods (Continued) 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 Response Field Data Type Description configurationID int Configuration identifier of the new capture. 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.
Lab Manager SOAP API Guide ConfigurationCheckout This method checks out a configuration from the configuration library and moves it to the Workspace under a different name. Syntax int result = ConfigurationCheckout(7, “Config7May10”); Arguments Field Data Type Description configurationID int Numeric identifier of the configuration in the configuration library. workspaceName string Workspace name of the checked‐out configuration.
Chapter 4 Lab Manager API Method Reference // //** Get Configuration object // LabManagerSoap.Configuration Config = binding.GetSingleConfigurationByName("Win2K3Exchange"); int configurationId = Config.id; // //** Timestamp library configuration name as new Workspace name // string checkoutName=Config.name + DateTime.Now.ToString(); // //** Check out and move to Workspace // int newConfigID = binding.ConfigurationCheckout(Config.id, checkoutName); Console.WriteLine("New Config ID=" + newConfigID.
Lab Manager SOAP API Guide Response Field Data Type Description workspaceId int Numeric identifier of the new Workspace configuration. 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.username = "jaya"; binding.
Chapter 4 Lab Manager API Method Reference Arguments Field Data Type Description configurationID int Numeric identifier of the Workspace configuration. Response No response. Sample Code: C# try { LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); //** Create login binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.username = "jaya"; binding.AuthenticationHeaderValue.
Lab Manager SOAP API Guide catch (Exception e) { Console.WriteLine("Error: " + e.Message); Console.ReadLine(); } ConfigurationDeploy This method allows you to deploy an undeployed configuration which resides in the Workspace. Syntax ConfigurationDeploy(6, false, 1); Arguments Field Data Type Description configurationID int Numeric identifier of the configuration in the Workspace. isCached boolean Always set a false value. isFenced int 1 = Not fenced. 2 = Fenced – Block traffic in and out.
Chapter 4 Lab Manager API Method Reference binding.AuthenticationHeaderValue.organizationname = "MyOrg"; ServicePointManager.CertificatePolicy = new CertificateAccepter(); //** Get Configuration object LabManagerSoap.Configuration Config = binding.GetSingleConfigurationByName("Config24"); //** Get configuration identifier and deployed status from object int configurationId = Config.id; bool deployed = Config.isDeployed; //** Deploy configuration if it isn’t already.
Lab Manager SOAP API Guide Syntax ConfigurationPerformAction(int configurationID, int action); Arguments Field Data Type Description action int Action to take on the configuration. configurationID int Configuration identifier. Response No response. Sample Code: C# try { LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.VMwareLabManagerSOAPinterface(); binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.
Chapter 4 Lab Manager API Method Reference 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, all Lab Manager users in all organizations can access this configuration (read only). If the configuration is private, only its owner and administrators can view it.
Lab Manager SOAP API Guide //** 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.id, true); } } catch (Exception e) { Console.WriteLine("Error: " + e.Message); Console.
Chapter 4 Lab Manager API Method Reference binding.AuthenticationHeaderValue = new LabManagerSoap.AuthenticationHeader(); binding.AuthenticationHeaderValue.username = "jaya"; binding.AuthenticationHeaderValue.password = "Lab Manager"; binding.AuthenticationHeaderValue.organizationname = "MyOrg"; // //* Get configurations in Workspace, not Library // int configurationType= 1; LabManagerSoap.Configuration[] configurations = binding.
Lab Manager SOAP API Guide 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.username = "jaya"; binding.AuthenticationHeaderValue.password = "Lab Manager"; 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 Field Data Type Description name string Configuration name.
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].fenceMode.
Chapter 4 Lab Manager API Method Reference 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.password = "Lab Manager"; binding.AuthenticationHeaderValue.
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 Field Data Type Description configurationId int Configuration identifier. name string Machine name. Response Field Data Type Description machine Machine Machine Object. Sample Code: C# try { LabManagerSoap.VMwareLabManagerSOAPinterface binding = new 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.
Lab Manager SOAP API Guide //** 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.isPublic.ToString()); Console.WriteLine("Config isDeployed = " + Config.
Chapter 4 Lab Manager API Method Reference 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.username = "jaya"; binding.AuthenticationHeaderValue.password = "Lab Manager"; binding.AuthenticationHeaderValue.
Lab Manager SOAP API Guide 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 Field Data Type Description configurationID int Configuration numeric identifier. Response Field Data Type Description machine[] Machine array Array of Machine objects. Sample Code: C# try { LabManagerSoap.VMwareLabManagerSOAPinterface binding = new LabManagerSoap.
Chapter 4 Lab Manager API Method Reference 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.WriteLine("Machine = " + machines[i].name); Console.WriteLine("id = " + machines[i].id.ToString()); Console.WriteLine("description = " + machines[i].description); Console.WriteLine("internalIP = " + machines[i].internalIP); Console.WriteLine("externalIP = " + machines[i].
Lab Manager SOAP API Guide 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"; binding.AuthenticationHeaderValue.organizationname = "MyOrg"; binding.Url = "https://demo18.LabManager.com/LabManager/SOAP/LabManager.
Chapter 4 Lab Manager API Method Reference 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. Shuts down a machine before turning off. Syntax MachinePerformAction(3); Arguments Field Data Type Description action int Action to take on the machine. machineID int Machine identifier. Response No response. Sample Code: C# try { LabManagerSoap.
Lab Manager SOAP API Guide { //** //** Get array of all machines in configurations //** LabManagerSoap.Machine [] machines = binding.ListMachines(configurations[j].id); //** //** Loop through all machines //** for (int i=0; i < machines.Length; i++) { //** //** Check status—if machine is suspended, then resume it //** if (machines[i].status == 3) { binding.MachinePerformAction(machines[i].id, 4); } } } } catch (Exception e) { Console.WriteLine("Error: " + e.Message); Console.ReadLine(); } 58 VMware, Inc.
Index C S CaptureUndeployConfiguration 24 CertificateAccepter() 25 CheckoutDeployConfiguration 23 Code simple and advanced samples 16 security, using SSL 11 SOAP API methods ConfigurationCapture 34 ConfigurationCheckout 36 ConfigurationClone 37 ConfigurationDelete 38 ConfigurationDeploy 40 ConfigurationPerformAction 41 ConfigurationSetPublicPrivate 43 ConfigurationUndeploy 44 GetConfiguration 45 GetConfigurationByName 47 GetMachine 48 GetMachineByName 50 GetSingleConfigurationByName 51 ListConfiguration
Lab Manager SOAP API Guide 60 VMware, Inc.
