File Coverage

blib/lib/VMware/LabManager.pm

Criterion	Covered	Total	%
statement	23	72	31.9
branch	1	14	7.1
condition	1	3	33.3
subroutine	6	11	54.5
pod	6	6	100.0
total	37	106	34.9

package VMware::LabManager;

use warnings;
use strict;

use Time::HiRes qw(time);    #used to generate unique confignames.

=head1 NAME

VMware::LabManager - Perl module to provide basic VMware Lab Manager operations.

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.01';

=head1 SYNOPSIS

This module provides an encapsulation of VMware Lab Manager SOAP API in
convenient API format. Basic functionality like deploying & deleting a library
config to & from the workspace are provided.

A little code snippet to get you started:

    use VMware::LabManager;
    use Data::Dumper;

    #instantiate the LM object
    my $lm = VMware::LabManager->new('username','passwd','labManager hostname', 'org');

    #or if you want the XML messages dumped (i.e. verbose), pass the debug option:
    my $lm = VMware::LabManager->new('username','passwd','labManager hostname', 'org', 'debug');

    #deploy_config returns the config ID of the config that is deployed
    my $configID = $lm->deploy_config('my_library_config_name');
    print $configID;

    #get all the machines in the deployed config
    my $machineArray = $lm->get_machines($configID);
    print Dumper($machineArray);

    #delete the config once you are done.
    $action = $lm->delete_config($configID);
    print $action

=head1 DESCRIPTION

This module does not provide a one-to-one mapping of the Lab Manager SOAP API,
but rather it provides an API wrapper, which combines certain SOAP calls as a
meaningful single operation. Thus this module is heavily tailored for automation
purposes. But, it should also cater to the broader audience as it still does
provide overall functionality that might be required.

Using this module, you can checkout a config & deploy it in one single method call,
similarly undeploy & delete in a single method call. This module also provides a
method to get the list of all machines (and their details) that a deployed
configuration has. Apart from that the SOAP object & auth header methods are
exposed; So if need be, they can be used to access other SOAP calls available
through Lab Manager SOAP service.

=head1 SUBROUTINES/METHODS

=head2 new

This function instantiates the LM object. The arguments in the B are:

=over 4

=item * Username - Your username for Lab Manager login.

=item * Password - Your password for Lab Manager login.

=item * Hostname - FQDN of the Lab Manager you are trying to log in.

=item * Organization - Organization to which you belong to in Lab Manager.

=back

This does not authenticate with the Lab Manager server yet. That happens when you
use one of the other methods.

=cut

sub new
{
 my $class = shift;
 my $uname = shift; # username for LM
 my $pass  = shift; # password for LM
 my $host  = shift; # LM hostname
 my $org   = shift; # LM organization name
 my $debug = shift; # enable debug, off by default

 # Set the debug option if passed to the constructor.
 if ( defined $debug && ( $debug eq 'debug' ) )
 {
  eval("use SOAP::Lite +trace => 'debug'");
 } else
 {
  eval("use SOAP::Lite");
 }

 my $self = {
              Username     => $uname,
              Password     => $pass,
              Hostname     => $host,
              Organization => $org
 };

 bless( $self, $class );
 return $self;
}

=head2 get_soap

This method is primary used internally, but there are situations where it could
be used for other SOAP methods that have not been exposed by this module. This
method returns SOAP::Lite object & sets the readable option on. You can use this
in conjunction with Authentication header, which you can get from get_auth_header()
method.

NOTE: Usage of this method outside the scope of this API is not recommended.

=cut

sub get_soap
{
 my $self = shift;
 my $soap = SOAP::Lite->on_action(
  sub {
   return "http://vmware.com/labmanager/" . $_[1];
  }
   )->default_ns('http://vmware.com/labmanager')
   ->proxy(
          'https://' . $self->{Hostname} . '/LabManager/SOAP/LabManager.asmx' );
 $soap->readable(1);
 return $soap;
}

=head2 get_auth_header

This method returns an authentication header wrapper that is needed for each
SOAP call that you make to Lab Manager. It uses the options you provided in the
new() method to build this header.

=cut

sub get_auth_header
{
 my $self = shift;
 my $auth_header = SOAP::Header->new(
                            name => 'AuthenticationHeader',
                            attr => { xmlns => "http://vmware.com/labmanager" },
                            value => {
                                       username         => $self->{Username},
                                       password         => $self->{Password},
                                       organizationname => $self->{Organization},
                            },
 );

 return $auth_header;
}

=head2 deploy_config

This method is tailored for automation. During automation, one primarily cares about
deploying a library image. A single method call to encapsulate the whole set of
operations is more deirable.

This method requires a config name (make sure it is unique in the system), which
it uses to:

=over 4

=item * Checkout the config to your default workspace with a random name.

=item * Deploy the confignation in fenced mode.

=item * Return the unique numeric Config ID of the deployed config.

=back

You have to use this config ID to undeploy & delete it at at later stage.

=cut

sub deploy_config
{
 my $self        = shift;
 my $config_name = shift; # library config name
 my $soap        = $self->get_soap();
 my $auth_header = $self->get_auth_header();
 my $res;

 # Get Configuration by Name
 $res = $soap->GetConfigurationByName(
                                       $auth_header,
                                       SOAP::Data->name(
                                                         'name' => $config_name
                                         )->type('s:string')
 );

#check for error ... there's more in the faultdetail hash, could use Dumper to examine it
 if ( $res->fault )
 {
  return
    join( ': ',
          'LabManager SOAP error', $res->faultcode,
          $res->faultstring,       $res->faultdetail );
 }

 # Get the id of the configuration
 my $configID = undef;

# LM API does not provide any direct way of getting the version it is running & the data structure
# returned for this method changed in v4.0. I am just lazy, change the statement below if you use older version.
# For previous versions of LM: $configID = $res->result->{'Configuration'}->{'id'};

 $configID = $res->result->{'Configuration'}[0]->{'id'};

 # Check out Configuration to workspace
 my $new_config_name = $config_name . time;
 $res = $soap->ConfigurationCheckout(
                                      $auth_header,
                                      SOAP::Data->name(
                                                  'configurationId' => $configID
                                        )->type('s:int'),
                                      SOAP::Data->name(
                                             'workspaceName' => $new_config_name
                                        )->type('s:string')
 );

 #check for error...
 if ( $res->fault )
 {
  return
    join( ': ',
          'LabManager SOAP error', $res->faultcode,
          $res->faultstring,       $res->faultdetail );
 }

 # Get the configID of the checked out config
 my $checked_out_config_ID = $res->result;

 # Deploy that config...
 $res = $soap->ConfigurationDeploy(
                             $auth_header,
                             SOAP::Data->name(
                                     'configurationId' => $checked_out_config_ID
                               )->type('s:int'),
                             SOAP::Data->name( 'isCached' => 'false' )
                               ->type('s:boolean'),
                             SOAP::Data->name( 'fenceMode' => 4 )->type('s:int')
 );

 #check for error...
 if ( $res->fault )
 {
  return
    join( ': ',
          'LabManager SOAP error', $res->faultcode,
          $res->faultstring,       $res->faultdetail )
    . "\n";
 }

 return $checked_out_config_ID;
}

=head2 get_machines

This method returns an array of all the Machines in the deployed config. For each
machine it includes mac address, name, internal IP, external IP, name & its id.

=cut

sub get_machines
{
 my $self        = shift;
 my $config_ID   = shift; # config ID that we got when we deployed
 my $soap        = $self->get_soap();
 my $auth_header = $self->get_auth_header();
 my $res;

 #Get the list of machines in a given config
 $res = $soap->ListMachines(
  $auth_header,
  SOAP::Data->name(
                    'configurationId' => $config_ID
    )->type('s:int')
 );

 #check for error...
 if ( $res->fault )
 {
  return
    join( ': ',
          'LabManager SOAP error', $res->faultcode,
          $res->faultstring,       $res->faultdetail );
 }

 #return an array of all machines information.
 return $res->paramsall;
}

=head2 delete_config

This method performs two actions - 1)undeploy the configuation (if it is not undeployed)
and 2) delete the configuation. This method takes the config ID of the configuration
you deployed earlier using the deploy_config() method.

=cut

sub delete_config
{
 my $self        = shift;
 my $config_ID   = shift; # config ID that we got when we deployed
 my $soap        = $self->get_soap();
 my $auth_header = $self->get_auth_header();
 my $res;

 # Undeploy the configuration
 $res = $soap->ConfigurationUndeploy(
                                      $auth_header,
                                      SOAP::Data->name(
                                                 'configurationId' => $config_ID
                                        )->type('s:int')
 );

 #check for error...
 if ( $res->fault )
 {
  return
    join( ': ',
          'LabManager SOAP error', $res->faultcode,
          $res->faultstring,       $res->faultdetail );
 }

 # Delete the configuration
 $res = $soap->ConfigurationDelete(
                                    $auth_header,
                                    SOAP::Data->name(
                                                 'configurationId' => $config_ID
                                      )->type('s:int')
 );

 #check for error...
 if ( $res->fault )
 {
  return
    join( ': ',
          'LabManager SOAP error', $res->faultcode,
          $res->faultstring,       $res->faultdetail );
 }

 return 'Deleted';
}

=head1 AUTHOR

"Aditya Ivaturi", C<< <"ivaturi at gmail.com"> >>

=head1 BUGS

Please report any bugs or feature requests to C, or through
the web interface at L.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc VMware::LabManager


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * Search CPAN

L

=back


=head1 LICENSE AND COPYRIGHT

Copyright 2010 "Aditya Ivaturi".

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.


=cut

1;    # End of VMware::LabManager