The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-SFDC-0.36-TRIAL
River stage one • 1 direct dependent • 1 total dependent
++
/ WWW::SFDC

NAME

WWW::SFDC - Wrappers around the Salesforce.com APIs.

VERSION

version 0.36

SYNOPSIS

    use WWW::SFDC;

    # Create session object. This will cache your credentials for use in
    # all subsequent API calls.
    my $session = WWW::SFDC->new(
      username => $username,
      password => $password,
      url => url,
      apiVersion => apiversion
    );

    # Access API calls by specifying which API you're calling and the
    # method you want to use, for instance:
    $session->Apex->executeAnonymous('system.debug(1);');
    $session->Partner->query('SELECT Id FROM Account LIMIT 10');

OVERVIEW

WWW::SFDC provides a set of packages which you can use to build useful interactions with Salesforce.com's many APIs. Initially it was intended for the construction of powerful and flexible deployment tools.

The idea is to provide a 'do what I mean' interface which allows the full power of all of the SOAP APIs whilst abstracting away the details of status checking and extracting results.

Contents

WWW::SFDC

Provides the lowest-level interaction with SOAP::Lite. Handles the SessionID and renews it when necessary.

You should not need to interact with WWW::SFDC itself beyond constructing and calling API modules - the methods in this class are in general plumbing.

WWW::SFDC::Constants

Retrieves and caches the metadata objects as returned by DescribeMetadata for use when trying to interact with the filesystem etc.

WWW::SFDC::Manifest

Stores and manipulates lists of metadata for retrieving and deploying to and from Salesforce.com.

WWW::SFDC::Metadata

Wraps the Metadata API.

WWW::SFDC::Partner

Wraps the Partner API.

WWW::SFDC::Tooling

Wraps the Tooling API.

WWW::SFDC::Zip

Provides utilities for creating and extracting base-64 encoded zip files for Salesforce.com retrievals and deployments.

ATTRIBUTES

apiVersion

The API version with which to call Salesforce.com. Must be over 30, since the metadata API interface changed quite a lot in 31. Defaults to 33.

loginResult

The result of the login call. API modules use this to populate the correct endpoint URL.

password

Used to authenticate with Salesforce.com. Unless you have a whitelisted IP address, this needs to include your security token.

pollInterval

How long (in seconds) WWW::SFDC should wait between retries, and how often it should poll for updates on asynchronous jobs. Defaults to 15 seconds.

attempts

How many times WWW::SFDC should retry when encountering connection issues. Defaults to 3. It's a good idea to have this value above 0, since SFDC occasionally returns 500 errors when under heavy load.

url

The URL to use when logging into Salesforce. Defaults to https://test.salesforce.com - set this to https://login.salesforce.com or to a specific instance as appropriate.

username

Used for authentication against SFDC.

METHODS

call($URL, $NameSpace, $method, @parameters)

Executes a Salesforce.com API call. This will retry $self-attempts> times in the event of a connection error, and if the session is invalid it will refresh the session ID by issuing a new login request.

Returns a WWW::SFDC::CallResult and throws a WWW::SFDC::CallException.

isSandbox

Returns 1 if the org associated with the given credentials are a sandbox. Use to decide whether to sanitise metadata or similar.

EXPERIMENTAL

This module is quite unstable, as it's early in its development cycle. I'm trying to avoid breaking too much, but until it hits 1.0, there is a risk of breakage.

There are also lots of unimplemented API calls in some of the libraries. This is because I don't currently have a use-case for them so it's not clear what the return types or testing mechanisms should be. Pull requests are welcome!

METADATA API EXAMPLES

Retrieval of metadata

The following provides a starting point for a simple retrieval tool. Notice that after the initial setup of WWW::SFDC the login credentials are cached. In this example, you'd use _retrieveTimeMetadataChanges to remove files you didn't want to track, change sandbox outbound message endpoints to production, or similar.

Notice that I've tried to keep the manifest interface as fluent as possible - every method which doesn't have an obvious return value returns $self.

    package ExampleRetrieval;

    use WWW::SFDC;
    use WWW::SFDC::Manifest;
    use WWW::SFDC::Zip qw'unzip';

    my ($password, $username, $url, $apiVersion, $package);

    sub _retrieveTimeMetadataChanges {
      my ($path, $content) = @_;
      return $content;
    }

    my $client = WWW::SFDC->new(
      password  => $password,
      username  => $username,
      url       => $url
    );

    my $manifest = WWW::SFDC::Manifest->new(
            constants => $client->Constants,
            apiVersion => $apiVersion
      )
      ->readFromFile($package)
      ->add(
        $session->Metadata->listMetadata(
            {type => 'Document', folder => 'Apps'},
            {type => 'Document', folder => 'Developer_Documents'},
            {type => 'EmailTemplate', folder => 'Asset'},
            {type => 'ApexClass'}
          )
      );

    unzip
      'src/',
      $session->Metadata->retrieveMetadata($manifest->manifest()),
      \&_retrieveTimeMetadataChanges;

Deployment

Here's a similar example for deployments. You'll want to construct @filesToDeploy and $deployOptions context-sensitively!

    package ExampleDeployment;

    use WWW::SFDC;
    use WWW::SFDC::Manifest;
    use WWW::SFDC::Zip qw'makezip';


    my $client = WWW::SFDC->new(
      password  => $password,
      username  => $username,
      url       => $url
    );

    my $manifest = WWW::SFDC::Manifest
      ->new(constants => $client->Constants)
      ->addList(@filesToDeploy)
      ->writeToFile('src/package.xml');

    my $zip = makezip
      'src',
      $manifest->getFileList(),
      'package.xml';

    my $deployOptions = {
       singlePackage => 'true',
       rollbackOnError => 'true',
       checkOnly => 'true'
    };

    $client->Metadata->deployMetadata($zip, $deployOptions);

PARTNER API EXAMPLE

To unsanitise some users' email address and change their profiles on a new sandbox, you might do something like this:

    package ExampleUserSanitisation;

    use WWW::SFDC;
    use List::Util qw'first';

    my $client = WWW::SFDC->new(
      username => $username,
      password => $password,
      url => $url
    );

    my @users = (
      {
        User => 'alexander.brett',
        Email => 'alex@example.com',
        Profile => $profileId
      }, {
        User => 'another.user',
        Email => 'a.n.other@example.com',
        Profile => $profileId
      },
    );

    $client->Partner->update(
      map {
        my $row = $_;
        my $original = first {$row->{Username} =~ /$$_{User}/} @users;
        +{
           Id => $row->{Id},
           ProfileId => $original->{Profile},
           Email => $original->{Email},
        }
      } $client->Partner->query(
          "SELECT Id, Username FROM User WHERE "
          . (
            join " OR ",
              map {"Username LIKE '%$_%'"} map {$_->{User}} @inputUsers
          )
        )
    );

SEE ALSO

App::SFDC

App::SFDC uses WWW::SFDC to provide a command-line application for interacting with Salesforce.com

ALTERNATIVES

Both of these modules offer more straightforward, comprehensive and mature wrappers around the Partner API than this module does at the moment. If all of your requirements can be fulfilled by that, you may be better off using them.

This module is designed for use in deployment applications, or when you want to juggle multiple APIs to provide complicated functionality.

WWW::Salesforce
Salesforce

BUGS

Please report any bugs or feature requests at https://github.com/sophos/WWW-SFDC/issues.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WWW::SFDC
    perldoc WWW::SFDC::Metadata
    ...

You can also look for information at https://github.com/sophos/WWW-SFDC

AUTHOR

Alexander Brett <alexander.brett@sophos.com> http://alexander-brett.co.uk

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by Sophos Limited https://www.sophos.com/.

This is free software, licensed under:

  The MIT (X11) License

The full text of the license can be found in the LICENSE file included with this distribution.