view release on metacpan or  search on metacpan

lib/WWW/Salesforce.pm  view on Meta::CPAN

    my $self = shift;

    my $client = $self->_get_client(1);
    my $method =
      SOAP::Data->name("logout")->prefix($SF_PREFIX)->uri($SF_URI);
    my $r = $client->call( $method, $self->_get_session_header() );
    unless ($r) {
        die "could not call method $method";
    }
    if ( $r->fault() ) {
        die( $r->faultstring() );
    }
    return $r;
}

=head2 query

  my $res = $sf->query(query => 'SELECT Id, Name FROM Account');
  $res = $sf->query(query => 'SELECT Id, Name FROM Account', limit => 20);
  # records as an array
  my @records = $res->valueof('//queryResponse/result/records');
  # number of records returned (int)
  my $number = $res->valueof('//queryResponse/result/size');
  # When our query has more results than our limit, we get paged results
  my $done = $res->valueof('//queryResponse/result/done');
  while (!$done) {
    my $locator = $res->valueof('//queryResponse/result/queryLocator');
    # use that locator for the queryMore method
  }

Executes a L<query|https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_query.htm>
against the specified object and returns data that matches the specified
criteria.

The method takes in a hash with two potential keys, C<query> and C<limit>.

The C<query> key is required and should contain an
L<SOQL|https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm>
query string.

The C<limit> key sets the batch size, or size of the result returned.
This is helpful in producing paginated results, or fetching small sets
of data at a time.

=cut

sub query {
    my $self = shift;
    my (%in) = @_;
    if (!defined $in{'query'} || !length $in{'query'}) {
        die("A query is needed for the query() method.");
    }
    if (!defined $in{'limit'} || $in{'limit'} !~ m/^\d+$/) {
        $in{'limit'} = 500;
    }
    if ($in{'limit'} < 1 || $in{'limit'} > 2000) {
        die("A query's limit cannot exceed 2000. 500 is default.");
    }

    my $limit
        = SOAP::Header->name(
        'QueryOptions' => \SOAP::Header->name('batchSize' => $in{'limit'}))
        ->prefix($SF_PREFIX)->uri($SF_URI);
    my $client = $self->_get_client();
    my $r      = $client->query(SOAP::Data->type('string' => $in{'query'}),
        $limit, $self->_get_session_header());

    unless ($r) {
        die "could not query " . $in{'query'};
    }
    if ($r->fault()) {
        die($r->faultstring());
    }
    return $r;
}

=head2 queryAll( HASH )

Executes a query against the specified object and returns data that matches the
specified criteria including archived and deleted objects.

=over

=item query

The query string to use for the query. The query string takes the form of a I<basic> SQL statement. For example, "SELECT Id,Name FROM Account".

=item limit

This sets the batch size, or size of the result returned. This is helpful in producing paginated results, or fetch small sets of data at a time.

=back

=cut

sub queryAll {
    my $self = shift;
    my (%in) = @_;
    if ( !defined $in{'query'} || !length $in{'query'} ) {
        die("A query is needed for the query() method.");
    }
    if ( !defined $in{'limit'} || $in{'limit'} !~ m/^\d+$/ ) {
        $in{'limit'} = 500;
    }
    if ( $in{'limit'} < 1 || $in{'limit'} > 2000 ) {
        die("A query's limit cannot exceed 2000. 500 is default.");
    }

    my $limit = SOAP::Header->name(
        'QueryOptions' => \SOAP::Header->name( 'batchSize' => $in{'limit'} ) )
      ->prefix($SF_PREFIX)->uri($SF_URI);
    my $client = $self->_get_client();
    my $r = $client->queryAll( SOAP::Data->name( 'queryString' => $in{'query'} ),
        $limit, $self->_get_session_header() );

    unless ($r) {
        die "could not query " . $in{'query'};
    }
    if ( $r->fault() ) {
        die( $r->faultstring() );
    }
    return $r;
}


=head2 queryMore( HASH )

Retrieves the next batch of objects from a C<query> or C<queryAll>.

=over

=item queryLocator

The handle or string returned by C<query>. This identifies the result set and cursor for fetching the next set of rows from a result set.

=item limit

This sets the batch size, or size of the result returned. This is helpful in producing paginated results, or fetch small sets of data at a time.

=back

=cut

sub queryMore {
    my $self = shift;
    my (%in) = @_;
    if ( !defined $in{'queryLocator'} || !length $in{'queryLocator'} ) {
        die("A hash expected with key 'queryLocator'");
    }
    $in{'limit'} = 500
      if ( !defined $in{'limit'} || $in{'limit'} !~ m/^\d+$/ );
    if ( $in{'limit'} < 1 || $in{'limit'} > 2000 ) {
        die("A query's limit cannot exceed 2000. 500 is default.");
    }

    my $limit = SOAP::Header->name(
        'QueryOptions' => \SOAP::Header->name( 'batchSize' => $in{'limit'} ) )
      ->prefix($SF_PREFIX)->uri($SF_URI);
    my $client = $self->_get_client();
    my $r      = $client->queryMore(
        SOAP::Data->name( 'queryLocator' => $in{'queryLocator'} ),
        $limit, $self->_get_session_header() );

    unless ($r) {
        die "could not queryMore " . $in{'queryLocator'};
    }

    if ( $r->fault() ) {
        die( $r->faultstring() );
    }
    return $r;
}

=head2 resetPassword( HASH )

Changes a user's password to a server-generated value.

=over

=item userId

A user Id.

=back

=cut

sub resetPassword {
    my $self = shift;
    my (%in) = @_;

    if ( !defined $in{'userId'} || !length $in{'userId'} ) {
        die("A hash expected with key 'userId'");
    }

    my $client = $self->_get_client(1);
    my $method =
      SOAP::Data->name("resetPassword")->prefix($SF_PREFIX)->uri($SF_URI);
    my $r = $client->call(
        $method =>
          SOAP::Data->prefix($SF_PREFIX)->name( 'userId' => $in{'userId'} )
          ->type('xsd:string'),
        $self->_get_session_header()
    );

    unless ($r) {
        die "could not call method $method";
    }
    if ( $r->fault() ) {
        die( $r->faultstring() );
    }
    return $r;
}

=head2 retrieve( HASH )

=over

lib/WWW/Salesforce.pm  view on Meta::CPAN

=head2 get_tables()

Returns a reference to an array of hash references
Each hash gives the properties for each Salesforce object

=cut

sub get_tables {
    my ($self) = @_;

    my $res = $self->describeGlobal();
    unless ($res) {
        die "could not describeGlobal()";
    }
    if ( $res->fault() ) {
        die( $res->faultstring() );
    }

    my @globals = $res->valueof('//describeGlobalResponse/result/sobjects');
    return \@globals;
}

# private methods
sub _get_client {
    my $self = shift;
    my ($readable) = @_;
    $readable = ($readable) ? 1 : 0;

    my $client
        = SOAP::Lite->readable($readable)
        ->deserializer(WWW::Salesforce::Deserializer->new)
        ->serializer(WWW::Salesforce::Serializer->new)
        ->on_action(sub { return '""' })->uri($SF_URI)->multirefinplace(1);

    if ($WEB_PROXY) {
        $client->proxy($self->{'sf_serverurl'},
            proxy => ['https' => $WEB_PROXY]);
    }
    else {
        $client->proxy($self->{'sf_serverurl'});
    }
    return $client;
}

sub _get_client_meta {
    my $self = shift;
    my ($readable) = @_;
    $readable = ($readable) ? 1 : 0;

    my $client
        = SOAP::Lite->readable($readable)
        ->deserializer(WWW::Salesforce::Deserializer->new)
        ->serializer(WWW::Salesforce::Serializer->new)
        ->on_action(sub { return '""' })->uri($SF_URI)->multirefinplace(1)
        ->proxy($self->{'sf_metadataServerUrl'})->soapversion('1.1');
    return $client;
}

sub _get_session_header {
    my ($self) = @_;
    return SOAP::Header->name('SessionHeader' =>
            \SOAP::Header->name('sessionId' => $self->{'sf_sid'}))
        ->uri($SF_URI)->prefix($SF_PREFIX);
}

sub _get_session_header_meta {
    my ($self) = @_;
    return SOAP::Header->name( 'SessionHeader' =>
            \SOAP::Header->name( 'sessionId' => $self->{'sf_sid'} ) )
        ->uri($SF_URIM)->prefix($SF_PREFIX);
}


1;
__END__


=head1 EXAMPLES

=head2 login()

    use WWW::Salesforce;
    my $sf = WWW::Salesforce->login( 'username' => $user,'password' => $pass )
        or die $@;

=head2 search()

    my $query = 'find {4159017000} in phone fields returning contact(id, phone, ';
    $query .= 'firstname, lastname), lead(id, phone, firstname, lastname), ';
    $query .= 'account(id, phone, name)';
    my $result = $sforce->search( 'searchString' => $query );

=head1 SUPPORT

Please visit Salesforce.com's user/developer forums online for assistance with
this module. You are free to contact the author directly if you are unable to
resolve your issue online.

=head1 CAVEATS

The C<describeSObjects> and C<describeTabs> API calls are not yet complete. These will be
completed in future releases.

Not enough test cases built into the install yet.  More to be added.

=head1 SEE ALSO

    L<DBD::Salesforce> by Jun Shimizu
    L<SOAP::Lite> by Byrne Reese

    Examples on Salesforce website:
    L<http://www.sforce.com/us/docs/sforce70/wwhelp/wwhimpl/js/html/wwhelp.htm>

=head1 HISTORY

This Perl module was originally provided and presented as part of
the first Salesforce.com dreamForce conference on Nov. 11, 2003 in
San Francisco.

=head1 AUTHORS

Byrne Reese - <byrne at majordojo dot com>

Chase Whitener <F<capoeirab@cpan.org>>

Fred Moyer <fred at redhotpenguin dot com>

=head1 CONTRIBUTORS