Skip to content

p5-salesforce/WWW-Salesforce

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

120 Commits
.github/workflows
.github/workflows
 
 
lib/WWW
lib/WWW
 
 
t
t
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
.mailmap
.mailmap
 
 
.perltidyrc
.perltidyrc
 
 
.travis.yml
.travis.yml
 
 
Build.PL
Build.PL
 
 
Changes
Changes
 
 
LICENSE
LICENSE
 
 
META.json
META.json
 
 
README.md
README.md
 
 
cpanfile
cpanfile
 
 
dist.ini
dist.ini
 
 

Repository files navigation

NAME

WWW::Salesforce - This class provides a simple SOAP client for Salesforce.com.

WARNING

NOTE: As of version 65.0 of the Salesforce APIs, the SOAP login method will no longer exist. Also, the login method for SOAP will be removed after the Summer ’27 release. Read about this change here: https://help.salesforce.com/s/articleView?id=005132110&type=1.

SYNOPSIS

use v5.26;
use Syntax::Keyword::Try;
use WWW::Salesforce ();

try {
    my $sforce = WWW::Salesforce->login(
        serverurl => 'https://test.my.salesforce.com',
        version => '64.0', # must be a string
        type => 'soap',
        username => 'foo',
        password => 'password' . 'pass_token'
    );
    my $res = $sforce->query(query => 'select Id, Name from Account');
    say "Found this many: ", $res->valueof('//queryResponse/result/size');
    my @records = $res->valueof('//queryResponse/result/records');
    say $records[0];
}
catch ($e) {
    # log or whatever. we'll just die for example
    die "Could not perform an action: $e";
}

try {
    my $sforce = WWW::Salesforce->login(
        serverurl => 'https://test.my.salesforce.com',
        version => '64.0', # must be a string
        type => 'oauth2-usernamepassword',
        client_id => 'abc2134asdgkljag',
        client_secret => 'axyalaskjag234qdf',
        username => 'foo',
        password => 'password' . 'pass_token'
    );
    my $res = $sforce->query(query => 'select Id, Name from Account');
    say "Found this many: ", $res->valueof('//queryResponse/result/size');
    my @records = $res->valueof('//queryResponse/result/records');
    say $records[0];
}
catch ($e) {
    # log or whatever. we'll just die for example
    die "Could not perform an action: $e";
}

DESCRIPTION

This class provides a simple abstraction layer between SOAP::Lite and Salesforce. 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.

CONSTRUCTOR ARGUMENTS

Given that WWW::Salesforce doesn't have attributes in the traditional sense, the following arguments, rather than attributes, can be passed into the constructor.

client_id

my $sforce = WWW::Salesforce->new(client_id => 'abc123xyz12398', ...);
my $sforce = WWW::Salesforce->new(clientid => 'abc123xyz12398', ...);
my $sforce = WWW::Salesforce->new(clientId => 'abc123xyz12398', ...);

The client_id or clientid or clientId is the consumer key of the connected app. To access the consumer key, from the App Manager, find the connected app and select View from the dropdown. Then click Manage Consumer Details. You're sometimes prompted to verify your identity before you can view the consumer key.

client_secret

my $sforce = WWW::Salesforce->new(client_secret => 'abc123xyz12398', ...);
my $sforce = WWW::Salesforce->new(clientsecret => 'abc123xyz12398', ...);
my $sforce = WWW::Salesforce->new(clientSecret => 'abc123xyz12398', ...);

The client_secret or clientsecret or clientSecret is the consumer secret of the connected app. To access the consumer secret, from the App Manager, find the connected app and select View from the dropdown. Then click Manage Consumer Details. You're sometimes prompted to verify your identity before you can view the consumer secret.

password

my $sforce = WWW::Salesforce->new(password => 'foobar1232131', ...);
my $sforce = WWW::Salesforce->new(pass => 'foobar1232131', ...);

The password or pass is a combination of your Salesforce password and your user's Security Token.

serverurl

my $sforce = WWW::Salesforce->new(serverurl => 'https://login.salesforce.com', ...);
# or maybe one of your specific instance URLs
my $sforce = WWW::Salesforce->new(serverUrl => 'https://test.my.salesforce.com', ...);
my $sforce = WWW::Salesforce->new(instanceurl => 'https://test.my.salesforce.com', ...);
my $sforce = WWW::Salesforce->new(instanceUrl => 'https://test.my.salesforce.com', ...);

The serverurl (or serverUrl, instanceurl, instanceUrl) is used as your host to login to Salesforce. The default value here is https://login.salesforce.com. All you need is the base URL here.

type

my $sforce = WWW::Salesforce->new(type => 'soap', ...);
my $sforce = WWW::Salesforce->new(
  type => 'oauth2-usernamepassword',
  client_id => 'abc2134asdgkljag',
  client_secret => 'axyalaskjag234qdf',
  ...
);

NOTE: As of version 65.0 of the Salesforce APIs, the SOAP login method will no longer exist. Also, the login method for SOAP will be removed after the Summer ’27 release. Read about this change here: https://help.salesforce.com/s/articleView?id=005132110&type=1.

Given that our tried and true method of logging in with the SOAP login method is going away, we are now providing you with an option of how to login.

The default login type will still be soap for now. However, you can get ahead of things by setting your login type to oauth2-suernamepassword. The OAuth 2.0 Username-Password Flow will work largely the same way as the old SOAP login, but you'll need to provide a client from your Salesforce instance's App Manager. Login to the Salesforce front-end and go to Setup -> App Manager.

username

my $sforce = WWW::Salesforce->new(username => '[email protected]', ...);
my $sforce = WWW::Salesforce->new(user => '[email protected]', ...);

When you login to Salesforce, your username or user is necessary.

version

my $sforce = WWW::Salesforce->new(version => '64.0');

Salesforce makes changes to their API and luckily for us, they version those changes. You can choose which API version you want to use by passing this argument. However, it must be a string.

CONSTRUCTORS

WWW::Salesforce constructs its instance and immediately logs you into the Salesforce API. So that there's less confusion, we have the traditional constructor as well as a second constructor named login.

new

my $sforce = WWW::Salesforce->new(
  username => '[email protected]',
  password => 'password' . 'security_token',
  serverurl => 'https://login.salesforce.com',
  version => '64.0'
);

When you create a new instance, the "username" in WWW::Salesforce and "password" in WWW::Salesforce arguments are required. The others are not required. After construction, these items are not mutable.

login

my $sforce = WWW::Salesforce->login(
  username => '[email protected]',
  password => 'password' . 'security_token',
  serverurl => 'https://login.salesforce.com',
  version => '64.0'
);

When you create a new instance, the "username" in WWW::Salesforce and "password" in WWW::Salesforce arguments are required. The others are not required. After construction, these items are not mutable.

METHODS

convertLead( HASH )

The convertLead method returns an object of type SOAP::SOM if the login attempt was successful, and 0 otherwise.

Converts a Lead into an Account, Contact, or (optionally) an Opportunity

The following are the accepted input parameters:

  • %hash_of_array_references

    leadId => [ 2345, 5678, ],
contactId => [ 9876, ],

create( HASH )

Adds one new individual objects to your organization's data. This takes as input a HASH containing the fields (the keys of the hash) and the values of the record you wish to add to your organization. The hash must contain the 'type' key in order to identify the type of the record to add.

Returns a SOAP::Lite object. Success of this operation can be gleaned from the envelope result.

$r->envelope->{Body}->{createResponse}->{result}->{success};

delete( ARRAY )

Deletes one or more individual objects from your organization's data. This subroutine takes as input an array of SCALAR values, where each SCALAR is an sObjectId.

describeGlobal()

Retrieves a list of available objects for your organization's data. You can then iterate through this list and use describeSObject() to obtain metadata about individual objects. This method calls the Salesforce describeGlobal method.

describeLayout( HASH )

Describes metadata about a given page layout, including layouts for edit and display-only views and record type mappings.

  • type

    The type of the object you wish to have described.

describeSObject( HASH )

Describes metadata (field list and object properties) for the specified object.

  • type

    The type of the object you wish to have described.

describeSObjects( type => ['Account','Contact','CustomObject__c'] )

An array based version of describeSObject; describes metadata (field list and object properties) for the specified object or array of objects.

describeTabs()

Use the describeTabs call to obtain information about the standard and custom apps to which the logged-in user has access. The describeTabs call returns the minimum required metadata that can be used to render apps in another user interface. Typically this call is used by partner applications to render Salesforce data in another user interface.

get_session_id()

Gets the Salesforce SID

get_user_id()

Gets the Salesforce UID

get_username()

Gets the Salesforce Username

getDeleted( HASH )

Retrieves the list of individual objects that have been deleted within the given time span for the specified object.

  • type

    Identifies the type of the object you wish to find deletions for.

  • start

    A string identifying the start date/time for the query

  • end

    A string identifying the end date/time for the query

getServerTimestamp()

Retrieves the current system timestamp (GMT) from the Salesforce web service.

getUpdated( HASH )

Retrieves the list of individual objects that have been updated (added or changed) within the given time span for the specified object.

  • type

    Identifies the type of the object you wish to find updates for.

  • start

    A string identifying the start date/time for the query

  • end

    A string identifying the end date/time for the query

getUserInfo( HASH )

Retrieves personal information for the user associated with the current session.

  • user

    A user ID

logout()

Ends the session for the logged-in user issuing the call. No arguments are needed. Useful to avoid hitting the limit of ten open sessions per login. Logout API Call

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 query against the specified object and returns data that matches the specified criteria.

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

The query key is required and should contain an SOQL query string.

The 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.

queryAll( HASH )

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

  • query

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

  • 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.

queryMore( HASH )

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

  • queryLocator

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

  • 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.

resetPassword( HASH )

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

  • userId

    A user Id.

retrieve( HASH )

  • fields

    A comma delimited list of field name you want retrieved.

  • type

    The type of the object being queried.

  • ids

    The ids (LIST) of the object you want returned.

search( HASH )

  • searchString

    The search string to be used in the query. For example, find {4159017000} in phone fields returning contact(id, phone, firstname, lastname), lead(id, phone, firstname, lastname), account(id, phone, name)

setPassword( HASH )

Sets the specified user's password to the specified value.

  • userId

    A user Id.

  • password

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

sf_date

Converts a time in Epoch seconds to the date format that Salesforce likes

update(type => $type, HASHREF [, HASHREF ...])

Updates one or more existing objects in your organization's data. This subroutine takes as input a type value which names the type of object to update (e.g. Account, User) and one or more perl HASH references containing the fields (the keys of the hash) and the values of the record that will be updated.

The hash must contain the 'Id' key in order to identify the record to update.

upsert(type => $type, key => $key, HASHREF [, HASHREF ...])

Updates or inserts one or more objects in your organization's data. If the data doesn't exist on Salesforce, it will be inserted. If it already exists it will be updated.

This subroutine takes as input a type value which names the type of object to update (e.g. Account, User). It also takes a key value which specifies the unique key Salesforce should use to determine if it needs to update or insert. If key is not given it will default to 'Id' which is Salesforce's own internal unique ID. This key can be any of Salesforce's default fields or an custom field marked as an external key.

Finally, this method takes one or more perl HASH references containing the fields (the keys of the hash) and the values of the record that will be updated.

describeMetadata()

Get some metadata info about your instance.

retrieveMetadata

checkAsyncStatus( $pid )

checkRetrieveStatus( $pid )

getErrorDetails( RESULT )

Returns a hash with information about errors from API calls - only useful if ($res->valueof('//success') ne 'true')

{
    'statusCode' => 'INVALID_FIELD_FOR_INSERT_UPDATE',
    'message' => 'Account: bad field names on insert/update call: type'
    ...
}

bye()

Synonym for logout.

Ends the session for the logged-in user issuing the call. No arguments are needed. Returns a reference to an array of hash refs

do_query( $query, [$limit] )

Returns a reference to an array of hash refs

do_queryAll( $query, [$limit] )

Returns a reference to an array of hash refs

get_field_list( $table_name )

Returns a ref to an array of hash refs for each field name Field name keyed as 'name'

get_tables()

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

EXAMPLES

login()

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

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 );

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.

CAVEATS

The describeSObjects and 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.

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>

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.

AUTHORS

Byrne Reese - <byrne at majordojo dot com>

Chase Whitener <[email protected]>

Fred Moyer <fred at redhotpenguin dot com>

CONTRIBUTORS

Michael Blanco

Garth Webb

Jun Shimizu

Ron Hess

Tony Stubblebine

COPYRIGHT & LICENSE

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

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

About

Interface to the Salesforce.com API

search.cpan.org/dist/WWW-Salesforce

Resources

Readme

License

View license
Activity
Custom properties

Stars

7 stars

Watchers

2 watching

Forks

12 forks
Report repository

Releases 2

0.400 Latest
Sep 18, 2025
+ 1 release

Packages

No packages published

Contributors 8

Languages