README.txt in Salesforce Suite 6.2

SALESFORCE MODULE
-----------------
  Contents of this README:
    ABOUT
    REQIREMENTS
    INSTALLATION
    UPDATING / REINSTALLING / ENABLING / DISABLING
    QUICKSTART
    PREMATCHING
    EXPORT QUEUE
    WORKING WITH WSDL FILES
    NOTIFICATIONS
    EXTENDING
    TROUBLESHOOTING
    REPORTING BUGS


ABOUT
-----
  This module suite implements a mapping functionality between Salesforce
  Objects and Drupal entities. In other words, for each of your supported Drupal
  entities (e.g. node, user, or entities supported by extensions), you can 
  assign Salesforce objects that will be created / updated when the entity is
  saved. For each such assignment, you choose which Drupal and Salesforce fields
  should be mapped to one another.

  This suite also includes an API architecture which allows for additional
  modules to be easily plugged in (e.g. for webforms, contact form submits,
  etc).
  
  For a more detailed description of each component module, see MODULES.txt


REQUIREMENTS
------------
  1) You need a salesforce account. Developers can register here:
  
  http://www.developerforce.com/events/regular/registration.php
  
  You will need to know your login data and your security token.

  2) PHP needs the SOAP web services kit installed, as per:
  
  http://php.net/soap

  3) Required modules
     Chaos Tool Suite - http://drupal.org/project/ctools

  4) Recommended modules
     Libraries API - http://drupal.org/project/libraries


RECOMMENDED
-----------

  1) Download and install your organization's generated Enterprise WSDL file.
     (see WORKING WITH WSDL FILES)

  2) AES encryption
     http://drupal.org/project/aes
     (see SOME NOTES ABOUT SECURITY)


INSTALLATION
------------
  1) Download, uncompress and situate the module as per usual.

  2) Download the Salesforce PHP Toolkit

     The official Force.com PHP toolkit is available from github.
     The recommended method of installing is using git.
     $ git clone git://github.com/developerforce/Force.com-Toolkit-for-PHP.git

     You can also use drush make:
     $ drush make salesforce.make.example
     
     Project homepage:
     https://github.com/developerforce/Force.com-Toolkit-for-PHP

     If "libraries" module is installed, place the "soapclient" directory in
     "salesforce/soapclient" in your libraries path.
     You should end up with:

     sites/all/libraries/salesforce/soapclient

     Otherwise, if "libraries" modules is not installed, place the "soapclient"
     directory within the "toolkit" directory in "salesforce_api".
     You should end up with:

     sites/all/modules/salesforce/salesforce_api/toolkit/soapclient

  3) Enable the module on admin/build/modules along with at least one of the
     object modules (sf_node, sf_user, sf_contrib). sf_node is the usual place
     to start.

  4) Assign a WSDL directory and upload your organization's WSDL file
     (admin/settings/salesforce and admin/settings/salesforce/wsdl).


UPDATING / REINSTALLING / ENABLING / DISABLING
----------------------------------------------
  If you have previously installed this module on your Drupal site and are 
  upgrading, you need to do the following to update the module.

  0) ALWAYS backup your site's code and your database.

  1) Download the latest version of Salesforce Suite and then run update.php,
     or use the following drush command: "drush up salesforce"

  ### Older versions

  If you are using an older version of the Salesforce 2.x module (2009 or 
  earlier), follow these directions:
  
  0) Backup your site's code and database. Download your WSDL, which would be
     in sites/all/modules/salesforce_api/wsdl/enterprise.wsdl

  1) Download the latest version of Salesforce Suite and then run update.php,
     or use the following drush command: "drush up salesforce"
  
  2) You will have to update your WSDL directory. It is recommended that your 
     WSDL file be stored outside your webroot. After enabling the new version 
     of Salesforce, visit admin/settings/salesforce and set the WSDL directory 
     and click "Save configuration". You will then be prompted to upload a new 
     WSDL file (admin/settings/salesforce/wsdl).
     
  Note that your fieldmaps may need adjustment after upgrading.

QUICKSTART
----------
  0) Minimal: enable salesforce_api and sf_node or sf_user.
     Kitchen sink: enable salesforce_api, sf_node, sf_user, sf_prematch, and 
     sf_queue
  
  1) Visit admin/settings/salesforce and enter your login information in the
     "Salesforce API Settings" fieldset and "WSDL directory".
     Save that configuration.

  2) Upload your organization's generated WSDL file.

  3) Click on the "Fieldmaps" local task, and create a fieldmap between Drupal
     and Salesforce objects.

  3) If you left the "automatic" box checked, the next time a Drupal object is
     created, it will create a corresponding object in Salesforce.
     Alternatively, you can click the "salesforce" tab on any node which you've
     established a mapping for and manually create a Salesforce object for it.


PREMATCHING
-----------
  The module sf_prematch provides administrators the ability to set up duplicate
  prevention criteria on each fieldmap. When sf_permatch is enabled, 
  administrators will be directed to set up matching criteria after creating a 
  fieldmap. Each time a Salesforce export is triggered, this criteria will be 
  used to identify any pre-existing records. If any matching record is found, 
  the matched record will be updated instead of a new record being created. The 
  impetus for this is to reduce the database management workload for 
  Salesforce.com administrators.


EXPORT QUEUE
------------
  The module sf_queue implements a queueing system for exports. Since Salesforce 
  API's create and update functions can modify up to 200 records at a time, this 
  module offers significant efficiencies for users trying to minimize their API 
  usage. Further, if an account's API limit is exceeded, the queue provides a 
  failsafe so that data is not lost. Failed API transactions will be queued for 
  future reprocessing. In addition, sf_queue is highly configurable to allow 
  administrators maximum flexibility in setting up the queue.


SOME NOTES ABOUT SECURITY
--------------------------
  By default all SalesForce credentials are stored in the variables table,
  unencrypted. If this is a problem for you, this module supports encryption via
  aes module http://drupal.org/project/aes. You will need to create a directory
  outside your webroot (you can use the same one you used for your WSDL) wherein
  your encryption key will be stored. Your credentials will thus forth be
  encrypted as securely as AES allows. PLEASE NOTE: your data is still only as
  secure as your network. It may be possible for a savvy attacker to access your
  data at any of various points between your Drupal site and SalesForce.com. As
  this always, you should educate yourself about the risks involved before storing
  and transferring sensitive data across the internet.


WORKING WITH WSDL FILES
-----------------------
  If you do not upload a WSDL file, Salesforce module will use a default .wsdl
  file (soapclient/enterprise.wsdl.xml), which may not be compatible with your
  organization's Salesforce installation or the current Salesforce API. It is
  highly recommended that you supply your own enterprise wsdl file via WSDL
  administration at admin/settings/salesforce/wsdl.

  Every time your Salesforce schema changes, you will need to regenreate your
  WSDL and upload it to your Drupal site if the changes affect mapped Salesforce
  objects. Changing Salesforce schema may result in breaking your fieldmaps, so
  please do so with extreme caution.

  When switching between wsdl files, keep in mind that PHP's SoapClient is
  caching wsdl information. Though PHP's SOAP WSDL cache should be cleaned when
  you upload a new WSDL file, you can permenantly disable caching of wsdl
  information by adding this line to your settings.php:

  ini_set('soap.wsdl_cache_enabled',  '0');

  You can control the life time of your cache by adding this line to your
  settings.php:

  ini_set('soap.wsdl_cache_ttl',      '0');

  For more information on SoapClient refer to
  http://php.net/manual/en/book.soap.php


NOTIFICATIONS
-------------
  Salesforce Outbound Messages (referred to as Notifications) are XML messages
  from Salesforce that can be sent based on Salesforce Workflow actions to any
  web endpoint. The included module sf_notifications handles processing of any
  such Notifications.

  To allow Drupal to respond to Notifications, enable the sf_notifications
  module as you would any other module, and point your Outbound Message(s) to
  the notification endpoint:

    http://example.com/sf_notifications/endpoint
    
  Configuring Salesforce Outbound Messages and Workflow is outside the scope of
  this documentation.
  
  SF_notifications will expose your existing fieldmaps to function as
  handlers for notifications. You can configure which of your fieldmaps should
  be active, and set conditions upon which the Notifications will be used to
  create Drupal objects. One application of Notifications is to implement full
  two-way synchronization between Salesforce and Drupal.  


EXTENDING
----------
  Support for mapping fields from commonly used modules like location and cck is 
  provided by sf_contrib module. If you use node_location, user_location, 
  cck_location, or any cck other fields and you'd like them to be available for 
  export, you need to enable this module.
  
  In addition to out of the box support for various cck fields, an extensible 
  framework is available for developers to build or alter support for contrib 
  modules. See sf_contrib for examples and best practices, as well as hooks.php 
  for documentation of the available integration points.


TROUBLESHOOTING
---------------
  Troubleshooting connection errors:
    * Are you using the right WSDL? Generate a new one.
    * Disable SOAP WSDL cache.
    * If you’re switching from sandbox to enterprise make sure that you switched
      accounts when generating the wsdl
    * Can you connect to the sandbox?
    * Are you logging everything? Have you checked watchdog?
    * Re-enter the token, user name and pass
    * Try another user

  In Salesforce:
    * Regnerate the WSDL
    * If you’re switching from sandbox to enterprise, make sure you're in the
      right account
    * Make sure the ip of server is not blocked
    * Go to: setup > users. Check login attempts of the user you are trying to
      connect with
    * Reset the credentials associated with the user

  In the Salesforce API module:
    * Replace WSDL file with the one you want to use
      (admin/settings/salesforce/wsdl)

  Install Devel:
    * excecute php:
      $somevariable = salesforce_api_connect();
      dpm($somevariable);

  In the file salesforce.module:
    * In salesforce_api_login(), find the line
      $sf->client->createConnection($wsdl)
    * Before that line put dpm($wsdl);
    * Make sure that your WSDL file is named "enterprise.wsdl.xml"

  PHPinfo():
    * Check that SOAP is enabled
    * Check that soap.wsdl_cache_enabled is FALSE
    * Check that openssl is enabled.

  If you have shell access:
    * curl https://login.salesforce.com to make sure your machine can connect.


REPORTING BUGS
--------------
  Bug reports should adhere to Drupal standards.

  Before creating a new issue, please:
    * Review existing issues at http://drupal.org/project/issues/salesforce
    * Use latest code from CVS on a *new* Drupal install
    * Include the PHP error message
    * Turn on "log all salesforce activity" and include any relevant watchdog
      errors
    * Install a generated WSDL file and Clear your WSDL cache
      (see WORKING WITH WSDL FILES)
    * Confirm php's SOAP support
    * Confirm whether you were able to successfully:
      - Connect to Salesforce
      - Save credentials
      - Login to https://login.salesforce.com/ with those credentials
      - Load the test/demo page
      - Create a fieldmap
    * Go through the Troubleshooting steps above and include any relevant info
    * Include all the information from the list above, and system information,
      including operating system, php version, apache version