WWW::Salesforce(3)

📦

version 0.304 · 2 versions

0.304 · fedora 43 (latest)
0.304 · fedora 44

💖 WWW::Salesforce — the perl man page but make it cute 💖

okay bestie, welcome to WWW::Salesforce(3), straight outta User Contributed Perl Documentation. grab a strawberry 🍓 and let's get into it.

✨ NAME ✨

WWW::Salesforce — this class provides a simple SOAP client for Salesforce.com. that's the whole vibe. it's giving "let me talk to Salesforce so you don't have to". 💅

🦋 SYNOPSIS 🦋

here's the whole thing in action, no cap:

use Try::Tiny;
use WWW::Salesforce ();
try {
    my $sforce = WWW::Salesforce->login(
        username => 'foo',
        password => 'password' . 'pass_token',
        serverurl => 'https://test.salesforce.com',
        version => '52.0' # must be a string
    );
    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 {
    # log or whatever. we'll just die for example
    die "Could not perform an action: $_";
}

like, we log in, we query, we count the records, we print the first one. iconic behavior honestly. 👑

🌸 DESCRIPTION 🌸

so this class provides a simple abstraction layer between SOAP::Lite and Salesforce (<https://www.salesforce.com>). and yeah, the reason it exists at all? SOAP::Lite does not support "complexTypes", and document/literal encoding is limited. so this module works around those limitations and hands you a way more intuitive interface a developer can actually interact with. it's the glow-up arc fr fr. ✨

🎀 CONSTRUCTOR ARGUMENTS 🎀

okay so WWW::Salesforce doesn't have attributes in the traditional sense. so instead of attributes, you pass these arguments into the constructor. yes it's a lil quirky, we love her anyway. 💖

🍓 password

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

the password is a combination of your Salesforce password and your user's Security Token — that's <https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_concepts_security.htm>. so like, password plus token, smooshed together. don't forget the token bestie, it will NOT work without it. 😭

🧚 serverurl

my $sforce = WWW::Salesforce->new(serverurl => 'https://login.salesforce.com');
# or maybe one of your developer instances
$sforce = WWW::Salesforce->new(serverurl => 'https://test.salesforce.com');

when you login to Salesforce, it's sometimes useful to login to one of your sandbox or other instances. all you need is the base URL right here. that's it. that's the whole thing. 🫶

🌈 username

my $sforce = WWW::Salesforce->new(username => 'foo@bar.com');

when you login to Salesforce, your username is necessary. literally required. can't skip this one. 🙈

⭐ version

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

Salesforce makes changes to their API and luckily for us, they version those changes. so you get to choose which API version you want to use by passing this argument. however — it must be a string. like, actually a string. no numbers. i'm so serious. 💀

👑 CONSTRUCTORS 👑

WWW::Salesforce constructs its instance and immediately logs you into the Salesforce API — docs are over here: <https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_login.htm>. so that there's less confusion, we have the traditional constructor as well as a second constructor named login. two doors, same room, pick your fave. ✨

💜 new

my $sforce = WWW::Salesforce->new(
  username => 'foo@bar.com',
  password => 'password' . 'security_token',
  serverurl => 'https://login.salesforce.com',
  version => '52.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. and after construction? these items are not mutable. so decide before you build her, bestie. 💅

my $sforce = WWW::Salesforce->login(
  username => 'foo@bar.com',
  password => 'password' . 'security_token',
  serverurl => 'https://login.salesforce.com',
  version => '52.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. same rules, different door. 🚪✨

lowkey the same warning twice but bestie we're just being thorough, ok?? 😌

✨ METHODS ✨

💅 `convertLead( HASH )`

okay so the convertLead method is literally the glow-up button for a Lead. It 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". bye bye bestie 👋

🌸 `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 at https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_describeglobal.htm.

💜 `describeLayout( HASH )`

Describes metadata about a given page layout, including layouts for edit and display-only views and record type mappings. it's giving layout lore ✨

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. slay, batch edition 💅

🫶 `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. clock check ⏰✨

🌸 `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: http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_logout.htm

🔥 `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('//QueryResult/result/records');
      # number of records returned (int)
      my $number = $res->valueof('//QueryResult/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 at https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_query.htm 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. SOQL docs live at https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm.

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. it sees everything, bestie 👀

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. it's giving flexible ✨

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`

no extra description in the original, just vibes and method name 🫶

🎀 `checkAsyncStatus( $pid )`

no extra description in the original, just vibes and method name 🫶

⭐ `checkRetrieveStatus( $pid )`

no extra description in the original, just vibes and method name 🫶

🫶 `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 🌈

DBD::Salesforce by Jun Shimizu
SOAP::Lite by Byrne Reese
Examples on Salesforce website: 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 <capoeirab@cpan.org>
Fred Moyer <fred at redhotpenguin dot com>

🎀 CONTRIBUTORS 🎀

Michael Blanco
Garth Webb
Jun Shimizu
Ron Hess
Tony Stubblebine

⭐ COPYRIGHT & LICENSE ⭐

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

and that's the whole page, bestie! 💖✨ This iconic little manual is WWW::Salesforce(3), from perl v5.42.0, dated 2025-07-25. periodt. 👑🦋

📦 where this page comes from

fedora 43: perl-WWW-Salesforce 0.304-11.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

WWW::Salesforce(3)

💖 WWW::Salesforce — the perl man page but make it cute 💖

✨ NAME ✨

🦋 SYNOPSIS 🦋

🌸 DESCRIPTION 🌸

🎀 CONSTRUCTOR ARGUMENTS 🎀

🍓 password

🧚 serverurl

🌈 username

⭐ version

👑 CONSTRUCTORS 👑

💜 new

🦋 login

✨ METHODS ✨

💅 convertLead( HASH )

✨ create( HASH )

🦋 delete( ARRAY )

🌸 describeGlobal()

💜 describeLayout( HASH )

🎀 describeSObject( HASH )

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

🫶 describeTabs()

💖 get_session_id()

💖 get_user_id()

💖 get_username()

🦋 getDeleted( HASH )

🌈 getServerTimestamp()

🌸 getUpdated( HASH )

💅 getUserInfo( HASH )

✨ logout()

🔥 query

💜 queryAll( HASH )

🎀 queryMore( HASH )

⭐ resetPassword( HASH )

🫶 retrieve( HASH )

💖 search( HASH )

🦋 setPassword( HASH )

🌈 sf_date

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

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

🔥 describeMetadata()

💜 retrieveMetadata

🎀 checkAsyncStatus( $pid )

⭐ checkRetrieveStatus( $pid )

🫶 getErrorDetails( RESULT )

💖 bye()

🦋 do_query( $query, [$limit] )

🌈 do_queryAll( $query, [$limit] )

🌸 get_field_list( $table_name )

💅 get_tables()

✨ EXAMPLES ✨

💖 login()

💖 search()

🫶 SUPPORT 🫶

💀 CAVEATS 💀

🌈 SEE ALSO 🌈

👑 HISTORY 👑

💖 AUTHORS 💖

🎀 CONTRIBUTORS 🎀

⭐ COPYRIGHT & LICENSE ⭐

💅 `convertLead( HASH )`

✨ `create( HASH )`

🦋 `delete( ARRAY )`

🌸 `describeGlobal()`

💜 `describeLayout( HASH )`

🎀 `describeSObject( HASH )`

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

🫶 `describeTabs()`

💖 `get_session_id()`

💖 `get_user_id()`

💖 `get_username()`

🦋 `getDeleted( HASH )`

🌈 `getServerTimestamp()`

🌸 `getUpdated( HASH )`

💅 `getUserInfo( HASH )`

✨ `logout()`

🔥 `query`

💜 `queryAll( HASH )`

🎀 `queryMore( HASH )`

⭐ `resetPassword( HASH )`

🫶 `retrieve( HASH )`

💖 `search( HASH )`

🦋 `setPassword( HASH )`

🌈 `sf_date`

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

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

🔥 `describeMetadata()`

💜 `retrieveMetadata`

🎀 `checkAsyncStatus( $pid )`

⭐ `checkRetrieveStatus( $pid )`

🫶 `getErrorDetails( RESULT )`

💖 `bye()`

🦋 `do_query( $query, [$limit] )`

🌈 `do_queryAll( $query, [$limit] )`

🌸 `get_field_list( $table_name )`

💅 `get_tables()`

💖 `login()`

💖 `search()`