NAME

WWW::Salesforce - this class provides a simple abstraction layer between SOAP::Lite and Salesforce.com.

DESCRIPTION

Because SOAP::Lite does not support complexTypes, and document/literal encoding is limited, this module works around those limitations and provides a more intuitive interface a developer can interact with.

SYNOPSIS

 use WWW::Salesforce;
 my $sforce = WWW::Salesforce->new(
    #all parameters below are optional.  The values given are the defaults
    serverurl => 'https://www.salesforce.com/services/Soap/u/16.0',
    uri => 'urn:partner.soap.sforce.com',
    object_uri => 'urn:sobject.partner.soap.sforce.com',
    prefix => 'sforce'
 ); #This will confess its errors and die if it fails!
 
 $sforce->login(
    username => 'foo', #required
    password => 'bar', #required
    token => 'nzAx8oThkUopg184FAfOq9Df9'
 ) or die $sforce->errstr;

METHODS

new( HASH )

The new method creates the WWW::Salesforce object. No calls can be made with the object that's returned until you use the login method. If the creation of the object fails, WWW::Salesforce will confess its errors and die.

The following are the accepted input parameters (all are optional):

serverurl

The default is 'https://www.salesforce.com/services/Soap/u/16.0'. Change this value if you want to use your sandbox account, etc.

uri

The default is 'urn:partner.soap.sforce.com'. Change this for the enterprise account, etc. This is SOAP XML stuff.

object_uri

The default is 'urn:sobject.partner.soap.sforce.com'. Change this for the enterprise account, etc. This is SOAP XML stuff.

prefix

The default is 'sforce'. You should probably leave this one be. This is SOAP XML stuff.

errstr()

The errstr method returns the last error encountered with this object. Upon the failure of a method call, that method call will return 0 (false) and set the error string which you can obtain with this method.

CORE METHODS

login( HASH )

The login method returns an object of type WWW::Salesforce if the login attempt was successful. Upon a successful login, the sessionId is saved so that developers need not worry about setting these values manually.

The following are the accepted input parameters:

username (REQUIRED)

A Salesforce.com username.

password (REQUIRED)

The password for the user indicated by username.

token

Salesforce.com checks the IP address from which the client application is logging in, and blocks logins from unknown IP addresses. For a blocked login via the API, Salesforce.com returns a login fault. Then, the user must add their security token to the end of their password in order to log in. A security token is an automatically-generated key from Salesforce.com. For example, if a user's password is mypassword, and their security token is XXXXXXXXXX, then the user must enter mypasswordXXXXXXXXXX to log in. Users can obtain their security token by changing their password or resetting their security token via the Salesforce.com user interface. When a user changes their password or resets their security token, Salesforce.com sends a new security token to the email address on the user's Salesforce.com record. The security token is valid until a user resets their security token, changes their password, or has their password reset. When the security token is invalid, the user must repeat the login process to log in. To avoid this, the administrator can make sure the client's IP address is added to the organization's list of trusted IP addresses. For more information, see http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_concepts_security.htm#topic-title_login_token.

logout()

The logout method logs the current user out and readies your object for another login.

UTILITY METHODS

getServerTimestamp()

Returns a string. Gets the current system timestamp (GMT) from the sforce Web service.

 my $tstamp = $sforce->getServerTimestamp() or die $sforce->errstr;
 print $tstamp;

getUserInfo()

Returns a hash reference. Use getUserInfo() to obtain personal information about the currently logged-in.

 my $h_ref = $sforce->getUserInfo() or die $sforce->errstr;
 print $h_ref->{'userId'};

resetPassword( "userId" )

Returns 1 or a string on success. Changes the desired user's password to a server-generated value.

 #supply the user id of the person you want to reset
 my $passwd = $sforce->resetPassword( '00510000000tFa7AAE' );
 if ( $passwd ) {
         print "Yay!  Your new password is $password";
 }
 else {
         print "boo! ", $sforce->errstr;
 }

setPassword( HASH )

Returns 1 or a string on success. Sets the specified user's password to the specified value.

 my $res = $sforce->setPassword(
        'userId' => '00510000000tFa7AAE',
        'password' => 'foobar'
 );
 if ( $res ) {
         print "yay!";
 }
 else {
         print "boo! ", $sforce->errstr;
 }

The following are the accepted input parameters:

userId (REQUIRED)

A user Id.

password (REQUIRED)

The new password to assign to the user identified by userId.

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.

SEE ALSO

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

    Examples on Salesforce website:
    L<http://www.salesforce.com/us/developer/docs/api/index.htm>

AUTHORS

Chase Whitener <cwhitener at gmail dot com>

Thanks to:

Michael Blanco - Finding and fixing some bugs.

Garth Webb - Finding and fixing bugs. Adding some additional features and more constant types.

Ron Hess - Finding and fixing bugs. Adding some additional features. Adding more tests to the build. Providing a lot of other help.

Tony Stubblebine - Finding a bug and providing a fix.

Jun Shimizu - Providing more to the WWW::Salesforce::Constants module and submitting fixes for various other bugs.

Byrne Reese - <byrne at majordojo dot com> - Byrne Reese wrote the original Salesforce module.

COPYRIGHT

Copyright 2003-2004 Byrne Reese, Chase Whitener. All rights reserved.

cpanm WWW::Salesforce

perl -MCPAN -e shell
install WWW::Salesforce