# # © Copyright 2009 Hewlett-Packard Development Company, L.P. # EPL license http://www.eclipse.org/legal/epl-v10.html # ## API for talking to HP Onboard Administrator ## NOTE: ## All parameters are passed by name! ## For example: ## hpoa->new(oaAddress => '16.129.49.209'); package xCAT::hpoa; use strict; #use SOAP::Lite; # hpblade.pm requires SOAP::Lite before requiring hpoa.pm, so we can check for SOAP::Lite dynamically use vars qw(@ISA); @ISA = qw(SOAP::Lite); # Constructor # Input: oaAddress, the IP address of the OA # Output: SOAP::SOM object (SOAP response) sub new { my $class = shift; return $class if ref $class; my $self = $class->SUPER::new(); my %args = @_; die "oaAddress is a required parameter" unless defined $args{oaAddress}; # Some info we'll need $self->{HPOA_HOST} = $args{oaAddress}; # OA IP address $self->{HPOA_KEY} = undef; # oaSessionKey returned by userLogIn $self->{HPOA_SECURITY_XML} = undef; # key placed in proper XML $self->{HPOA_SECURITY_HEADER} = undef; # XML translated to SOAP::Header obj bless($self, $class); # We contact the OA via this URL: my $proxy = "https://". $self->{HPOA_HOST} . ":443/hpoa"; # One of the cool things about SOAP::Lite is that almost every # method returns $self. This allows you to string together # as many calls as you need, like this: $self # keep the XML formatted for human readability, in case # we ever have to look at it (unlikely) -> readable(1) # Need to tell SOAP about some namespaces. I don't know if they # are all necessary or not, but I got them from the hpoa.wsdl -> ns("http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd", "wsu") -> ns('http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd', "wsse") -> ns('http://www.w3.org/2001/XMLSchema-instance', 'xsi') -> ns('http://www.w3.org/2003/05/soap-encoding', 'SOAP-ENC') -> ns('http://www.w3.org/2003/05/soap-envelope', 'SOAP-ENV') -> ns('http://www.w3.org/2001/XMLSchema', 'xsd') -> default_ns("hpoa.xsd", "hpoa") # Inform SOAP of the OA URL -> proxy($proxy); return $self; } # Method: call # Input: method and a hash of method's input params (see below) # Output: SOAP::SOM object (SOAP response) # # All methods in the OA API end up getting called by this routine, # even though the user invokes them directly using the method name. # For example, code that looks like this: # $hpoa->userLogIn(username=>$name, password=>$pass) # results in this call: # $hpoa->call('userLogIn', username=>$name, password=>$pass) sub call { my ($self, $method, %args) = @_; # # Each item of %args is of the form: # ($name => $value). # # $value is usually a scalar and SOAP::Lite infers a type. # # If the value needs to be explicitly typed, the $value should be a # reference to an array of the form: # [ $scalar, $type ] # This should work for any parameter that you want to explicitly # type, but for some reason the OA was not having any of it the # last time I tried. # # If the method calls for an array of values, the $value should be # a reference to an array of the form: # [ $itemName, $itemArrayRef, $itemType ] # # If the method calls for more complicated structure, the $value # should be a reference to a hash of the form: # { name1 => value1, name2 => value2 ... } # The values can themselves be scalars, array refs or hash refs, # which will themselves be processed recursively. # # Put the params in a form SOAP likes. my @soapargs = (); while (my ($k, $v) = each %args) { push @soapargs, $self->process_args($k, $v); } # This is required if there are no params, otherwise SOAP::Lite # makes an XML construct that the OA doesn't like. @soapargs = SOAP::Data->type('xml'=> undef) unless @soapargs; # Add the security header if it's not the login method. # I'm hoping that the header will be ignored by the few methods # that don't require security. push (@soapargs, $self->{HPOA_SECURITY_HEADER}) unless ($method eq 'userLogIn') || !defined $self->{HPOA_SECURITY_HEADER}; # Make sure we're using the correct version of SOAP, but # don't mess up packages that use a different version. my $version = xCAT::hpoa->soapversion(); xCAT::hpoa->soapversion('1.2'); # Call the method and put the response in $r my $r = $self->SUPER::call($method, @soapargs); # Reset the SOAP version xCAT::hpoa->soapversion($version); # If this was the login method and it was successful, then extract # the session key and remember it for subsequent calls. if ($method eq 'userLogIn' && !$r->fault) { my $key = $r->result()->{oaSessionKey}; # Got this XML code from the HP Insight Onboard Administrator SOAP # Interface Guide 0.9.7 my $xml = ' <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" SOAP-ENV:mustUnderstand="true"> <hpoa:HpOaSessionKeyToken xmlns:hpoa="hpoa.xsd"> <hpoa:oaSessionKey>' . $key . '</hpoa:oaSessionKey> </hpoa:HpOaSessionKeyToken> </wsse:Security>'; $self->{HPOA_KEY} = $key; $self->{HPOA_SECURITY_XML} = $xml; $self->{HPOA_SECURITY_HEADER} = SOAP::Header->type('xml' => $xml); } # Return the response return $r; } ## Create the correct SOAP::Data structure for the given args ## $n is the argument name ## $v is the value and can be of the following 4 forms: ## $scalar ## - A scalar value. No further processing takes place. ## Produces: <name>value</name> ## [ $scalar, $type ] ## - An array ref containing a scalar value and type. No further ## will take place. ## Produces: <name type=aType>value</name> ## [ $itemName, $aref, $type ] ## - An array ref containing the name for the elements, the elements ## themselves in an array ref, and the type for the elements. The ## elements themselves can be processed. ## Produces: <name> ## <item type=aType>value1</item> ## <item type=aType>value2</item> ## </name> ## { $n1 => $v1, $n2 => $v2 ... } ## - A hash ref containing name value pairs that can themselves ## be processed. ## Produces: <name> ## <n1>v1</n1> ## <n2>v2</n2> ## </name> sub process_args { my ($self, $n, $v, $t) = @_; print "process args: $n => $v\n" if 0; if (!ref $v) { # untyped scalar print "\nUNTYPED SCALAR: $n => $v\n" if 0; return SOAP::Data->new(name => $n, value => $v, type => ''); } if (ref $v eq 'HASH') { # structure my ($nn, $vv, @ar); while (($nn, $vv) = each %$v) { print "\nSTRUCTURE $n: $nn => $vv\n" if 0; unshift @ar, $self->process_args($nn, $vv); } return SOAP::Data->name($n => \SOAP::Data->value(@ar)); } if (ref $v eq 'ARRAY') { if (scalar @$v == 2) { # typed scalar my ($value, $type) = @$v; print "\nTYPED SCALAR: $n => $value ($type)\n" if 0; return SOAP::Data->new(name => $n, value => $value, type => $type); } # Else an array of values my ($itemName, $aref, $type) = @$v; my (@ar, $item); foreach $item (@$aref) { if (ref $item eq 'HASH') { print "\nSUB STRUCTURE $n: $itemName => $item ($type)\n" if 0; unshift @ar, $self->process_args("$itemName", $item); } else { print "\nARRAY $n: $itemName => $item ($type)\n" if 0; unshift @ar, $self->process_args($itemName, [$item, $type]); } } return SOAP::Data->name($n => \SOAP::Data->value(@ar)); } die "Unexpected input parameter value: $n => $v\n"; } ### ### Special fault info for OAs ### # The OA uses it's own fault data structures. The simple # fault methods provided by SOAP::Lite are usually undef. # The OA's fault data looks like this: # { # 'Detail' => { # 'faultInfo' => { # 'operationName' => 'userLogIn', # 'errorText' => 'The user could not be authenticated.', # 'errorCode' => '150', # 'errorType' => 'USER_REQUEST' # } # }, # 'Reason' => { # 'Text' => 'User Request Error' # }, # 'Code' => { # 'Value' => 'SOAP-ENV:Sender' # } #} # # In your code, you should generally check that $response->fault # is defined, then print $response->oaErrorMessage. # If you know the codes, you can act on $response->oaErrorCode # # The OA's fault structure sub SOAP::SOM::oaFaultInfo { my ($self, @args) = @_; return $self->fault->{Detail}->{faultInfo} if (defined $self->fault && defined $self->fault->{Detail} && defined $self->fault->{Detail}->{faultInfo}); return undef; } # The name of the method producing the fault sub SOAP::SOM::oaOperationName { my ($self, @args) = @_; my $oafi = $self->oaFaultInfo; return $oafi->{operationName} if defined $oafi && defined $oafi->{operationName}; return undef; } # Text of the OA fault sub SOAP::SOM::oaErrorText { my ($self, @args) = @_; my $oafi = $self->oaFaultInfo; return $oafi->{errorText} if defined $oafi && defined $oafi->{errorText}; return undef; } # Numeric code of the OA fault sub SOAP::SOM::oaErrorCode { my ($self, @args) = @_; my $oafi = $self->oaFaultInfo; if (defined $oafi) { return $oafi->{errorCode} if defined $oafi->{errorCode}; return $oafi->{internalErrorCode} if defined $oafi->{internalErrorCode}; } return undef; } # Bay Number of the OA fault sub SOAP::SOM::oaOperationBayNumber { my ($self, @args) = @_; my $oafi = $self->oaFaultInfo; return $oafi->{operationBayNumber} if defined $oafi && defined $oafi->{operationBayNumber}; return undef; } # Sometimes there's extra fault information # (Haven't seen any yet!) sub SOAP::SOM::oaExtraFaultData { my ($self, @args) = @_; my $oafi = $self->oaFaultInfo; return $oafi->{extraData} if defined $oafi && defined $oafi->{extraData}; return undef; } # Nicely formatted error message for human consumption. # Tries to use the oaErrorText and oaErrorCode, if defined, # else uses the reason text. sub SOAP::SOM::oaErrorMessage { my ($self, @args) = @_; my $errorText = $self->oaErrorText; # Reason text is either an error message from SOAP (as when # the method or argument doesn't exist), or it's a formatted # form of the faultInfo->errorType enumeration. my $reasonText = $self->fault->{Reason}->{Text}; return $reasonText unless defined $errorText; my $operationName = $self->oaOperationName; my $operationBay = $self->oaOperationBayNumber; my $errorCode = $self->oaErrorCode; my $extraData = $self->oaExtraFaultData; my $operation = "'$operationName' call"; $operation .= " on bay $operationBay" if $operationBay; my $completeText = "$reasonText $errorCode during $operation: $errorText"; $completeText .= "\n\t$extraData" if $extraData; return $completeText; } 1;