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