view release on metacpan or  search on metacpan

lib/ASNMTAP/Asnmtap/Plugins/SOAP.pod  view on Meta::CPAN

ASNMTAP::Asnmtap::Plugins::SOAP is a Perl module that provides SOAP functions used by ASNMTAP-based plugins.

=head1 SYNOPSIS

 use ASNMTAP::Asnmtap::Plugins v3.002.003;
 use ASNMTAP::Asnmtap::Plugins qw(:PLUGINS);

 my $objectPlugins = ASNMTAP::Asnmtap::Plugins->new (
   _programName        => 'check_template-SOAP.pl',
   _programDescription => "SOAP::LITE plugin template for testing the '$APPLICATION' with Performance Data",
   _programVersion     => '3.002.003',
   _programGetOptions  => ['proxy:s', 'trendline|T:i'],
   _timeout            => 30,
   _debug              => 0);

 use ASNMTAP::Asnmtap::Plugins::SOAP qw(&get_soap_request);

 use SOAP::Lite;
 my $proxy      = 'http://services.soaplite.com/hibye.cgi';
 my $namespace  = 'http://www.soaplite.com/Demo';
 my $methodName = 'hi';
 my $method     = SOAP::Data->name($methodName)->attr( {xmlns => $namespace} );

 my %soapService_Register_NS = (
   'http://schemas.xmlsoap.org/wsdl/mime/' => 'mime',
   'http://www.w3.org/2001/XMLSchema'      => 's'
 );

 my $xmlContent;
 my $params;

 my ($returnCode, $xml) = get_soap_request ( 
   asnmtapInherited  => \$objectPlugins,
   proxy             => $proxy,
   namespace         => $namespace,
   method            => $method,
   registerNamespace => \%soapService_Register_NS,
   xmlContent        => $xmlContent,
   params            => $params,
   readable          => 1,
   cookies           => 1,
   perfdataLabel     => 'SOAP'
 );

 ($returnCode, $xml) = get_soap_request ( 
   asnmtapInherited  => \$objectPlugins,
   proxy             => 'https://USERNAME:PASSWORD@secure.citap.be/authorization/hibye.cgi',
   namespace         => $namespace,
   method            => $method,
   registerNamespace => \%soapService_Register_NS,
   xmlContent        => $xmlContent,
   params            => $params,
   cookies           => 1,
   perfdataLabel     => 'SOAP with Basic Authentication'
 );

 ($returnCode, $xml) = get_soap_request ( 
   asnmtapInherited  => \$objectPlugins,
   proxy             => 'https://secure.citap.be/authorization/hibye.cgi',
   credentials       => [ 'secure.citap.be:443', "ASNMTAP's Authorization Access", 'USERNAME' => 'PASSWORD' ],
   namespace         => $namespace,
   method            => $method,
   registerNamespace => \%soapService_Register_NS,
   xmlContent        => $xmlContent,
   params            => $params,
   cookies           => 1,
   perfdataLabel     => 'SOAP with Credentials'
 );

 unless ( $returnCode ) {
   if (defined $xml) {
     ...
   } else {
     ...
   }
 }

 $objectPlugins->exit (7);

=head1 Description

=head2 SOAP::Lite based functions.

SOAP::Lite for Perl is a collection of Perl modules which provides a simple and 
lightweight interface to the Simple Object Access Protocol (SOAP, also known as 
Service Oriented Access Protocol) both on client and server side.

=over 4

=item get_soap_request()

SOAP is a simple XML-based protocol to let applications exchange information over HTTP.

More information regarding SOAP can be find at URI: http://www.w3schools.com/soap/

Returns a status for $returnCode (OK..UNKNOWN) and when the status is OK for $xml the extracted XML if exists, otherwise undef.

=over 4

=item asnmtapInherited

A required reference to an ASNMTAP::Asnmtap::Plugins or ASNMTAP::Asnmtap::Plugins::Nagios subclass

Through this way of working we inherited the command line option I<--debug>.

=item custom

optional, is an reference to your own custom defined function

$som: the SOM object provides a simple API for accessing any aspect of
the response's SOAP envelope, a result object from SOAP::Lite.

 sub actionOnSoapResponse {
   my ($asnmtapInherited, $som) = @_;
   return ($returnCode);
 }

and now with customArguments:

 sub actionOnSoapResponse {
   my ($asnmtapInherited, $som, $arguments) = @_;
   return ($returnCode);
 }

=item customArguments

optional, when you need to pass parameters to your own custom defined function, this can be done with customArguments.

 customArguments: SCALAR, ARRAY, HASH,
                  REF SCALAR, REF ARRAY, REF HASH

=item proxy

This lets you specify an endpoint (service address) and also loads the required module at the same time.

 proxy: 'http://services.soaplite.com/hibye.cgi'

When using SOAP with basic authentication you can add username and password to your URL as follows:

 proxy: 'http://USERNAME:PASSWORD@services.soaplite.com/hibye.cgi'

a required scalar.

=item credentials

Set the user name and password to be used for a realm.

 credentials: [ $hostname_port, $realm, $username, $password ]

              [ 'secure.citap.be:443', "ASNMTAP's Authorization Access", 'USERNAME' => 'PASSWORD' ]

a optional array.

=item namespace

Sets the URI that will be used as the namespace for the resulting XML entity.

 namespace: 'http://www.soaplite.com/Demo'

a required scalar.

=item registerNamespace

The register_ns subroutine allows users to register a global namespace with the SOAP Envelope.

 registerNamespace:

 %soapService_Register_NS = (
  'http://schemas.xmlsoap.org/wsdl/mime/' => 'mime',
   'http://www.w3.org/2001/XMLSchema'      => 's'
 );

a required hash.

=item method

The name is what the serializer will use for the tag when generating the XML for this object.

 method: SOAP::Data->name(hi)->attr( {xmlns => 'http://www.soaplite.com/Demo'} );

a required SOAP::Data->name definition

=item soapaction

This lets you specify a handler for on_action event. It is triggered when creating SOAPAction. 
The default handler will set SOAPAction to "uri/method". 
You can change this behavior, for a particular object to "uri/soapaction".
To remove the soapaction you say soapaction => '',

optional scalar, soapaction

=item xmlContent

Parsing XML formatted data.

 xmlContent:
 
 <soapRequest>
   <registrationType>xmlRegistrationType</registrationType>
   <language>xmlLanguage</language>
   <orderBy>xmlOrderBy</orderBy>
 </soapRequest>

optional scalar, xmlContent is one XML

=item params

 params: SOAP::Data->name('req')->type('string')->value(xmlContent);