1WWW::Salesforce(3) User Contributed Perl Documentation WWW::Salesforce(3)
2
6 WWW::Salesforce - This class provides a simple SOAP client for
7 Salesforce.com.
8
10 use Try::Tiny;
11 use WWW::Salesforce ();
12 try {
13 my $sforce = WWW::Salesforce->login(
14 username => 'foo',
15 password => 'password' . 'pass_token',
16 serverurl => 'https://test.salesforce.com',
17 version => '52.0' # must be a string
18 );
19 my $res = $sforce->query(query => 'select Id, Name from Account');
20 say "Found this many: ", $res->valueof('//queryResponse/result/size');
21 my @records = $res->valueof('//queryResponse/result/records');
22 say $records[0];
23 }
24 catch {
25 # log or whatever. we'll just die for example
26 die "Could not perform an action: $_";
27 }
28
30 This class provides a simple abstraction layer between SOAP::Lite and
31 Salesforce <https://www.salesforce.com>. Because SOAP::Lite does not
32 support "complexTypes", and document/literal encoding is limited, this
33 module works around those limitations and provides a more intuitive
34 interface a developer can interact with.
35
37 Given that WWW::Salesforce doesn't have attributes in the traditional
38 sense, the following arguments, rather than attributes, can be passed
39 into the constructor.
40 password
42 my $sforce = WWW::Salesforce->new(password => 'foobar1232131');
43 The password is a combination of your Salesforce password and your
45 user's Security Token <https://developer.salesforce.com/docs/atlas.en-
46 us.api.meta/api/sforce_api_concepts_security.htm>.
47 serverurl
49 my $sforce = WWW::Salesforce->new(serverurl => 'https://login.salesforce.com');
50 # or maybe one of your developer instances
51 $sforce = WWW::Salesforce->new(serverurl => 'https://test.salesforce.com');
52 When you login to Salesforce, it's sometimes useful to login to one of
54 your sandbox or other instances. All you need is the base URL here.
55 username
57 my $sforce = WWW::Salesforce->new(username => 'foo@bar.com');
58 When you login to Salesforce, your username is necessary.
60 version
62 my $sforce = WWW::Salesforce->new(version => '52.0');
63 Salesforce makes changes to their API and luckily for us, they version
65 those changes. You can choose which API version you want to use by
66 passing this argument. However, it must be a string.
67
69 WWW::Salesforce constructs its instance and immediately logs you into
70 the Salesforce <https://developer.salesforce.com/docs/atlas.en-
71 us.api.meta/api/sforce_api_calls_login.htm> API. So that there's less
72 confusion, we have the traditional constructor as well as a second
73 constructor named login.
74 new
76 my $sforce = WWW::Salesforce->new(
77 username => 'foo@bar.com',
78 password => 'password' . 'security_token',
79 serverurl => 'https://login.salesforce.com',
80 version => '52.0'
81 );
82 When you create a new instance, the "username" in WWW::Salesforce and
84 "password" in WWW::Salesforce arguments are required. The others are
85 not required. After construction, these items are not mutable.
86 login
88 my $sforce = WWW::Salesforce->login(
89 username => 'foo@bar.com',
90 password => 'password' . 'security_token',
91 serverurl => 'https://login.salesforce.com',
92 version => '52.0'
93 );
94 When you create a new instance, the "username" in WWW::Salesforce and
96 "password" in WWW::Salesforce arguments are required. The others are
97 not required. After construction, these items are not mutable.
98
100 convertLead( HASH )
101 The "convertLead" method returns an object of type SOAP::SOM if the
102 login attempt was successful, and 0 otherwise.
103 Converts a Lead into an Account, Contact, or (optionally) an
105 Opportunity
106 The following are the accepted input parameters:
108 %hash_of_array_references
110 leadId => [ 2345, 5678, ],
111 contactId => [ 9876, ],
112 create( HASH )
114 Adds one new individual objects to your organization's data. This takes
115 as input a HASH containing the fields (the keys of the hash) and the
116 values of the record you wish to add to your organization. The hash
117 must contain the 'type' key in order to identify the type of the record
118 to add.
119 Returns a SOAP::Lite object. Success of this operation can be gleaned
121 from the envelope result.
122 $r->envelope->{Body}->{createResponse}->{result}->{success};
124 delete( ARRAY )
126 Deletes one or more individual objects from your organization's data.
127 This subroutine takes as input an array of SCALAR values, where each
128 SCALAR is an "sObjectId".
129 describeGlobal()
131 Retrieves a list of available objects for your organization's data.
132 You can then iterate through this list and use describeSObject() to
133 obtain metadata about individual objects. This method calls the
134 Salesforce describeGlobal method
135 <https://developer.salesforce.com/docs/atlas.en-
136 us.api.meta/api/sforce_api_calls_describeglobal.htm>.
137 describeLayout( HASH )
139 Describes metadata about a given page layout, including layouts for
140 edit and display-only views and record type mappings.
141 type
143 The type of the object you wish to have described.
144 describeSObject( HASH )
146 Describes metadata (field list and object properties) for the specified
147 object.
148 type
150 The type of the object you wish to have described.
151 describeSObjects( type => ['Account','Contact','CustomObject__c'] )
153 An array based version of describeSObject; describes metadata (field
154 list and object properties) for the specified object or array of
155 objects.
156 describeTabs()
158 Use the "describeTabs" call to obtain information about the standard
159 and custom apps to which the logged-in user has access. The
160 "describeTabs" call returns the minimum required metadata that can be
161 used to render apps in another user interface. Typically this call is
162 used by partner applications to render Salesforce data in another user
163 interface.
164 get_session_id()
166 Gets the Salesforce SID
167 get_user_id()
169 Gets the Salesforce UID
170 get_username()
172 Gets the Salesforce Username
173 getDeleted( HASH )
175 Retrieves the list of individual objects that have been deleted within
176 the given time span for the specified object.
177 type
179 Identifies the type of the object you wish to find deletions for.
180 start
182 A string identifying the start date/time for the query
183 end A string identifying the end date/time for the query
185 getServerTimestamp()
187 Retrieves the current system timestamp (GMT) from the Salesforce web
188 service.
189 getUpdated( HASH )
191 Retrieves the list of individual objects that have been updated (added
192 or changed) within the given time span for the specified object.
193 type
195 Identifies the type of the object you wish to find updates for.
196 start
198 A string identifying the start date/time for the query
199 end A string identifying the end date/time for the query
201 getUserInfo( HASH )
203 Retrieves personal information for the user associated with the current
204 session.
205 user
207 A user ID
208 logout()
210 Ends the session for the logged-in user issuing the call. No arguments
211 are needed. Useful to avoid hitting the limit of ten open sessions per
212 login. Logout API Call
213 <http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_logout.htm>
214 query
216 my $res = $sf->query(query => 'SELECT Id, Name FROM Account');
217 $res = $sf->query(query => 'SELECT Id, Name FROM Account', limit => 20);
218 # records as an array
219 my @records = $res->valueof('//QueryResult/result/records');
220 # number of records returned (int)
221 my $number = $res->valueof('//QueryResult/result/size');
222 # When our query has more results than our limit, we get paged results
223 my $done = $res->valueof('//queryResponse/result/done');
224 while (!$done) {
225 my $locator = $res->valueof('//queryResponse/result/queryLocator');
226 # use that locator for the queryMore method
227 }
228 Executes a query <https://developer.salesforce.com/docs/atlas.en-
230 us.api.meta/api/sforce_api_calls_query.htm> against the specified
231 object and returns data that matches the specified criteria.
232 The method takes in a hash with two potential keys, "query" and
234 "limit".
235 The "query" key is required and should contain an SOQL
237 <https://developer.salesforce.com/docs/atlas.en-
238 us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm> query string.
239 The "limit" key sets the batch size, or size of the result returned.
241 This is helpful in producing paginated results, or fetching small sets
242 of data at a time.
243 queryAll( HASH )
245 Executes a query against the specified object and returns data that
246 matches the specified criteria including archived and deleted objects.
247 query
249 The query string to use for the query. The query string takes the
250 form of a basic SQL statement. For example, "SELECT Id,Name FROM
251 Account".
252 limit
254 This sets the batch size, or size of the result returned. This is
255 helpful in producing paginated results, or fetch small sets of data
256 at a time.
257 queryMore( HASH )
259 Retrieves the next batch of objects from a "query" or "queryAll".
260 queryLocator
262 The handle or string returned by "query". This identifies the
263 result set and cursor for fetching the next set of rows from a
264 result set.
265 limit
267 This sets the batch size, or size of the result returned. This is
268 helpful in producing paginated results, or fetch small sets of data
269 at a time.
270 resetPassword( HASH )
272 Changes a user's password to a server-generated value.
273 userId
275 A user Id.
276 retrieve( HASH )
278 fields
279 A comma delimited list of field name you want retrieved.
280 type
282 The type of the object being queried.
283 ids The ids (LIST) of the object you want returned.
285 search( HASH )
287 searchString
288 The search string to be used in the query. For example, "find
289 {4159017000} in phone fields returning contact(id, phone,
290 firstname, lastname), lead(id, phone, firstname, lastname),
291 account(id, phone, name)"
292 setPassword( HASH )
294 Sets the specified user's password to the specified value.
295 userId
297 A user Id.
298 password
300 The new password to assign to the user identified by "userId".
301 sf_date
303 Converts a time in Epoch seconds to the date format that Salesforce
304 likes
305 update(type => $type, HASHREF [, HASHREF ...])
307 Updates one or more existing objects in your organization's data. This
308 subroutine takes as input a type value which names the type of object
309 to update (e.g. Account, User) and one or more perl HASH references
310 containing the fields (the keys of the hash) and the values of the
311 record that will be updated.
312 The hash must contain the 'Id' key in order to identify the record to
314 update.
315 upsert(type => $type, key => $key, HASHREF [, HASHREF ...])
317 Updates or inserts one or more objects in your organization's data. If
318 the data doesn't exist on Salesforce, it will be inserted. If it
319 already exists it will be updated.
320 This subroutine takes as input a type value which names the type of
322 object to update (e.g. Account, User). It also takes a key value which
323 specifies the unique key Salesforce should use to determine if it needs
324 to update or insert. If key is not given it will default to 'Id' which
325 is Salesforce's own internal unique ID. This key can be any of
326 Salesforce's default fields or an custom field marked as an external
327 key.
328 Finally, this method takes one or more perl HASH references containing
330 the fields (the keys of the hash) and the values of the record that
331 will be updated.
332 describeMetadata()
334 Get some metadata info about your instance.
335 retrieveMetadata
337 checkAsyncStatus( $pid )
338 checkRetrieveStatus( $pid )
339 getErrorDetails( RESULT )
340 Returns a hash with information about errors from API calls - only
341 useful if ($res->valueof('//success') ne 'true')
342 {
344 'statusCode' => 'INVALID_FIELD_FOR_INSERT_UPDATE',
345 'message' => 'Account: bad field names on insert/update call: type'
346 ...
347 }
348 bye()
350 Synonym for "logout".
351 Ends the session for the logged-in user issuing the call. No arguments
353 are needed. Returns a reference to an array of hash refs
354 do_query( $query, [$limit] )
356 Returns a reference to an array of hash refs
357 do_queryAll( $query, [$limit] )
359 Returns a reference to an array of hash refs
360 get_field_list( $table_name )
362 Returns a ref to an array of hash refs for each field name Field name
363 keyed as 'name'
364 get_tables()
366 Returns a reference to an array of hash references Each hash gives the
367 properties for each Salesforce object
368
370 login()
371 use WWW::Salesforce;
372 my $sf = WWW::Salesforce->login( 'username' => $user,'password' => $pass )
373 or die $@;
374 search()
376 my $query = 'find {4159017000} in phone fields returning contact(id, phone, ';
377 $query .= 'firstname, lastname), lead(id, phone, firstname, lastname), ';
378 $query .= 'account(id, phone, name)';
379 my $result = $sforce->search( 'searchString' => $query );
380
382 Please visit Salesforce.com's user/developer forums online for
383 assistance with this module. You are free to contact the author
384 directly if you are unable to resolve your issue online.
385
387 The "describeSObjects" and "describeTabs" API calls are not yet
388 complete. These will be completed in future releases.
389 Not enough test cases built into the install yet. More to be added.
391
393 L<DBD::Salesforce> by Jun Shimizu
394 L<SOAP::Lite> by Byrne Reese
395 Examples on Salesforce website:
397 L<http://www.sforce.com/us/docs/sforce70/wwhelp/wwhimpl/js/html/wwhelp.htm>
398
400 This Perl module was originally provided and presented as part of the
401 first Salesforce.com dreamForce conference on Nov. 11, 2003 in San
402 Francisco.
403
405 Byrne Reese - <byrne at majordojo dot com>
406 Chase Whitener <capoeirab@cpan.org>
408 Fred Moyer <fred at redhotpenguin dot com>
410
412 Michael Blanco
413 Garth Webb
415 Jun Shimizu
417 Ron Hess
419 Tony Stubblebine
421
423 Copyright 2003-2004 Byrne Reese, Chase Whitener, Fred Moyer. All rights
424 reserved.
425 This program is free software; you can redistribute it and/or modify it
427 under the same terms as Perl itself.
428perl v5.38.0 2023-07-21 WWW::Salesforce(3)