view release on metacpan or  search on metacpan

lib/ServiceNow/SOAP.pm  view on Meta::CPAN

it is possible to significantly improve the performance of large queries.

You may pass this method either a list of column names,
or a string containing a comma delimited list of names.
It will override any prior calls to L</exclude> or L</include>.
It returns a reference to the modified Query object.

For some reason the Direct Web Services API allows you to specify a 
list of columns to be excluded from the query result,
but there is no similar out-of-box capability 
to specify only the columns to be included.
This function implements the more obviously needed behavior 
by inverting the list.
It uses the WSDL to generate a list of columns returned by L</getRecords>,
and subtracts the specified names to create an C<"__exclude_columns">
extended query parameter.

See also: L</except>, L</exclude>

B<Syntax>

    $query->include(@list_of_columns);
    $query->include($comma_delimited_list_of_columns);
    
B<Example>

This example returns a list of all records in the C<cmdb_ci_computer> table,
but only 5 columns are returned.

    my $tbl = $sn->table("cmdb_ci_computer");
    my $qry = $tbl->query()->include(
        qw(sys_id name sys_class_name operational_status sys_updated_on));
    my @recs = $qry->fetchAll();    

=cut

sub include {
    my $self = shift;
    my $table = $self->{table};
    my $excl = $table->except(split /,/, join(',', @_));
    $self->exclude($excl);
    return $self;
}

sub setIndex {
    my $self = shift;
    $self->{index} = shift;
    return $self;
}

1;

=head1 PROXY

You may have trouble using the SOAP API if you are running Perl behind
a proxy server.  
The easiest solution is to configure the proxy with environment variables
as in this example.

    use ServiceNow::SOAP;
    $ENV{HTTP_PROXY} = "http://my.proxy.server";
    $ENV{HTTPS_PROXY} = $ENV{HTTP_PROXY};
    $ENV{PERL_LWP_ENV_PROXY} = 1;
    my $sn = ServiceNow($instance, $username, $password);

This works because ServiceNow::SOAP is built on top of SOAP::Lite
which is built on top of LWP.
For more information refer to:
L<http://search.cpan.org/dist/libwww-perl/lib/LWP.pm#ENVIRONMENT>

=head1 DIAGNOSTICS

Sometimes, when you are developing a new script,
it seems to hang at a certain point, 
and you just want to know what it is doing.
You can enable tracing of Web Service calls
by setting the C<trace> option
in the L</ServiceNow> function as follows.

    my $sn = ServiceNow($instance, $username, $password, trace => 1);

Set trace to 1 to print a single line for each Web Services call.
Set trace to 2 to print the complete XML result for each call.

If you want even more, then add the following to your code.
This will cause L<SOAP::Lite> to dump the HTTP headers
and content for all messages, both sent and received.

    SOAP::Lite->import(+trace => 'debug');

=head1 AUTHOR

Giles Lewis <gflewis@cpan.org>

=head1 ACKNOWLEDGEMENTS

Greg George, author of L<ServiceNow::Simple>,
from which a number of ideas were sourced. 

=head1 LICENSE

This program is free software; you can redistribute it and/or modify it
under the terms of the the Artistic License (2.0). You may obtain a
copy of the full license at:

L<http://www.perlfoundation.org/artistic_license_2_0>

Any use, modification, and distribution of the Standard or Modified
Versions is governed by this Artistic License. By using, modifying or
distributing the Package, you accept this license. Do not use, modify,
or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made
by someone other than you, you are nevertheless required to ensure that
your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service
mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge
patent license to make, have made, use, offer to sell, sell, import and
otherwise transfer the Package with respect to any patent claims