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