Metadata-Version: 1.0
Name: Products.salesforcepfgadapter
Version: 1.6b1
Summary: PloneFormGen adapter allowing for creation of arbitrary Salesforce.com         records based on data collected from a web form
Home-page: http://groups.google.com/group/plonesf
Author: Plone/Salesforce Integration Group
Author-email: plonesf@googlegroups.com
License: GPL
Description: Salesforce PFG Adapter (PloneFormGen Add-On)
        ============================================
        Product home is http://plone.org/products/salesforcepfgadapter. A
        `documentation area`_ and `issue tracker`_ are available at the linked
        locations.
        
        .. _documentation area: http://plone.org/documentation/manual/integrating-plone-with-salesforce.com
        .. _issue tracker: http://plone.org/products/salesforcepfgadapter/issues
        
        A Google Group, called `Plone Salesforce Integration`_ exists with the sole
        aim of discussing and developing tools to make Plone integrate well with
        Salesforce.com.  If you have a question, joining this group and posting to the
        mailing list is the likely best way to get support.
        
        .. _Plone Salesforce Integration: http://groups.google.com/group/plonesf
        
        Failing that, please try using the Plone users' mailing list or the #plone irc
        channel for support requests. If you are unable to get your questions answered
        there, or are interested in helping develop the product, see the credits below
        for individuals you might contact.
        
        Overview
        ========
        
        This product builds on top of the foundation for through the web form
        creation provided by `PloneFormGen`_.
        If you are unfamiliar with PloneFormGen's capabilities and the problem
        space it intends to serve, we encourage you to start by downloading that
        and reading the README.txt file in the root of the product. In particular,
        the "Overview" and "Rationale For This Product" sections are recommended.
        
        .. _PloneFormGen: http://plone.org/products/ploneformgen
        
        Once you've setup a suitable PloneFormGen form folder (and correctly
        installed and configured the Salesforce PFG Adapter and its dependencies),
        you'll have the option of adding a new action adapter called a
        "Salesforce Adapter".
        
        Once you've added a Salesforce PFG Adapter to your form, you're presented with
        both "default" and "field mapping" (in addition to the standard "overrides")
        management screens for editing the adapter. The default screen consists of a
        drop-down menu populated with all the sObject types (i.e. Salesforce Objects)
        found in the Salesforce.com instance that corresponds to the credentials
        entered when creating a Salesforce Base Connector in the ZMI. This should
        include both standard and custom sObjects.
        
        Once you've chosen your sObject type, moving through to the "field mapping"
        management screen will display a two-column form for setting which Salesforce
        field will be populated by each field on your form. Each field on your form is
        represented by a single row, with the form field name in the left column, and a
        drop-down selection menu of all available Salesforce fields on the right.
        Select the desired Salesforce field for each form field and click "Save".
        
        NB: While it is not required to map every form field to a Salesforce field,
        you will want to make sure that all the sObject fields defined as required
        fields in your Salesforce configuration *do* have a mapping.  Otherwise, the
        sObject will not be succesfully created on submission of the form.  All required
        fields for your chosen sObject should be marked accordingly and appear at the
        top of the list of options.
        
        Should you go back and switch to a different sObject type after having provided
        a  mapping at any time, you'll want to recreate your desired mapping.  This is
        intended behavior, since the update would fail (or worse, produce very
        confusing results) if the previously selected sObject type's mapping were
        maintained.
        
        If you are using a version of Salesforce PFG Adapter that is >= version 1.5.x
        and you configure a form that contains multiple "Salesforce Adapters", you
        also have the ability to relate the resulting Salesforce.com provided unique
        "Id" for each adapter to a field of your choosing on later executed adapters.
        This is how one can create related Salesforce.com (via a lookup field, which
        is conceptually similar to a foreign key) records from a single form.  Take
        the following scenario as a visual example with to sObjects and their inherent
        schemas::
        
        -----------                -------------
        | Account |                | Contact   |
        -----------                -------------
        | Id      | -------------> | AccountId |
        | Name    |                | LastName  |
        -----------                -------------
        
        In the above scenario, the "Account" adapter will be run before the "Contact"
        adapter regardless of ordering within the PloneFormGen form.  In this sense,
        the "Contact" adapter is *dependent upon* the result from the "Account"
        adapter. Upon creation of the "Account" within Salesforce.com an Id like
        "01r600123009QiJ", will be returned along with the API response.  This will
        then be saved and can be configured to be inserted into the "AccountId" field
        for the "Contact" record that is next created. Care is taken via validation to
        ensure that "circularly dependent" adapters can not be accidentally
        configured.
        
        
        Rationale For This Product
        ==========================
        
        Using the wonderful foundation that is provided by PloneFormGen (and Plone for
        that  matter), the task of creating a form that collects and validates some
        desired information is no longer a task that requires developer intervention,
        but can be done by the content editor with a decent grasp of the Plone user
        interface.  Having this data inside the CMS or emailed is only of limited use
        however.
        
        Salesforce.com provides an extensible, powerful platform from which
        to do Customer Relationship Management (CRM) tasks ranging from sales,
        marketing, nonprofit constituent organizing, and customer service. The
        Salesforce PFG Adapter symbolizes the pragmatic joining of a best of breed CMS
        and CRM so that each can focus on its own strengths in a way that is easy for
        non-developers to use.
        
        Salesforce.com offers functionality called web-to-lead, but aside from
        PloneFormGen's many strengths over the web-to-lead form builder this software
        offers the following additional features:
        
        - Configurable validation of individual form fields
        - Ability to create as many different records as you'd like from the results
        of one form
        - Ability to create custom sObject records with your form
        - Ability to create whichever type of sObject records, whereas web-to-lead
        creates a Lead record, which can only be converted to a Contact, Account, or
        Opportunity record. Want to directly create a Campaign record from a form?
        That's fine.
        - Ability to create multiple records that are related to each other (i.e.
        create an Account record, then create a Contact record with the previously
        created Account's Id filling the Contact's AccountId field.)
        
        
        Dependencies
        ============
        
        Depends upon the beatbox library >= 16.0b1, which is a Python wrapper to the
        Salesforce.com API (version 7.0).  You must have a Salesforce.com account
        that provides API access.
        
        To download and install beatbox, please visit::
        
        http://code.google.com/p/salesforce-beatbox/
        
        Tested with all versions of Plone in the 3.x series and their relevant
        dependencies. For use of SalesforcePFGAdapter with the 2.5.x series of Plone,
        please try SalesforcePFGAdapter version 1.5.
        
        See dependencies for PloneFormGen 1.5.x+.  As a pre-requisite, all of these must be
        met in order to use the Salesforce PFG Adapter.
        
        SalesforceBaseConnector >= 1.2b1. See
        http://plone.org/products/salesforcebaseconnector
        
        DataGridField >= 1.6.x.  Earlier versions didn't properly disable
        DataGridField's add row feature, which is important in our case because the
        user can't add new possible form fields for mapping from within the Salesforce
        Adapter.  Those need to be added to the form itself.
        
        Installation
        ============
        
        Typical for a Zope/Plone product:
        
        * Install and *configure* dependencies (includes beatbox setup and creation of
        Salesforce Base Connector with credentials in the root of the Plone site.)
        
        * Unpack the product package into the Products folder of the Zope/Plone
        instance. Check your ownership and permissions.
        
        * Restart Zope.
        
        * Go to the Site Setup page in the Plone interface and click on the Add/Remove
        Products link. Choose salesforcepfgadapter (check its checkbox) and click the
        Install button. If not done already, this will install PloneFormGen in
        addition to the salesforcepfgadapter.  If PloneFormGen is not available on the
        Add/Remove Products list, it usually means that the product did not load due
        to missing prerequisites.
        
        Permissions
        ===========
        
        See Permissions section of README.txt within PloneFormGen.
        
        Security
        ========
        
        See Security section of README.txt within PloneFormGen.
        
        Known Problems
        ==============
        
        See Known Problems section of README.txt within PloneFormGen. In addition:
        
        - Beatbox, the underlying Python wrapper library to the Salesforce.com API
        does not raise a custom exception in the scenario of the API being
        unavailable due to scheduled maintenance as is evident within the following
        response: SoapFaultError: 'UNKNOWN_EXCEPTION' 'UNKNOWN_EXCEPTION: Server
        unavailable due to scheduled maintenance'
        
        This is left unfixed in all branches <=1.6.x of the Salesforce PFG Adapter,
        due to the modifications that would be required to adequately handle the case
        with technologies lower in the stack, such as Salesforce Base Connector and
        beatbox. This will be addressed in a future release.
        
        Another known problem arises when using versions of DataGridField (DGF), a
        dependency to this product, < 1.6 final. DGF shipped with two versions
        of a css stylesheet called datagridwidget.css (one a .dtml file and the other
        a .css file).  If the incorrect version was active, the PloneFormGen to
        Salesforce "field mapping" user interface appeared as though additional fields
        were addable directly from the Salesforce Adapter editing screen.  In
        addition, the hidden column containing the relative path to the field appeared
        to the user.  This is easily resolved by upgrading to DGF versions >= 1.6.
        
        Credits
        =======
        
        The Plone & Salesforce crew in Seattle and Portland:
        
        - Jon Baldivieso <jonb --AT-- onenw --DOT-- org>
        - Andrew Burkhalter <andrewb --AT-- onenw --DOT-- org>
        - Brian Gershon <briang --AT-- webcollective --DOT-- coop>
        - David Glick <davidglick --AT-- onenw --DOT-- org>
        - Jesse Snyder <jesses --AT-- npowerseattle --DOT-- org>
        
        With special PloneFormGen guest star:
        
        - Steve McMahon <steve@dcn.org>
        
        Jesse Snyder and NPower Seattle for the foundation of code that has become
        Salesforce Base Connector
        
        Simon Fell for providing the beatbox Python wrapper to the Salesforce.com API
        
        Salesforce.com Foundation and Enfold Systems for their gift and work on
        beatbox (see:
        http://gokubi.com/archives/onenorthwest-gets-grant-from-salesforcecom-to-integrate-with-plone)
        
        See the CHANGES.txt file for the growing list of people who helped
        with particular features or bugs.
        
        
        License
        =======
        
        Distributed under the GPL.
        
        See LICENSE.txt and LICENSE.GPL for details.
        
        
        
        1.6b1 (2009-09-08)
        
        - Adjust calls to the salesforcebaseconnector query method to use a single
        full SOQL statement.  beatbox >= 16.0dev is now required.
        [davisagli]
        
        - Use the field id instead of title as the key column for the field mapping,
        so that it's possible to set the mapping programmatically without worrying
        about the titles.
        [davisagli]
        
        - Cut out duplicate setup code and unnecessary API calls throughout testing
        with use of onsetup decorator.
        [andrewb]
        
        - Move substantial portions of package installation to GenericSetup.
        [andrewb]
        
        - No longer supporting Plone 2.5, pull out all the complex workarounds
        associated with support older version.
        [andrewb]
        
        - Added metadata.xml to GenericSetup profile.
        [andrewb]
        
        
        1.5.2 - released August 13, 2009
        
        - Fix broken release.
        [davisagli]
        
        1.5.1 - released August 12, 2009
        
        - Fix for issue #13, whereby hitting the next button while editing a
        Salesforce Adapter with PloneFormGen 1.5b2 redirected off to the Form
        Folder's Quick Edit UI, rather than the field mapping UI as expected.
        [andrewb]
        
        1.5  - released February 18, 2009
        
        - Clean-up of overly long lines (e.g. > 80 chars) in README.txt
        [andrewb]
        
        1.5rc1
        
        - Added information about known issue #30 within dependency DataGridField.
        http://plone.org/products/datagridfield/issues/30
        [andrewb]
        
        - Added read_permission protection to how Salesforce Adapters have been
        configured.  The title is viewable by all, but the SFObjectType, fieldMap,
        and dependencyMap fields are now only visible to those with the
        ModifyPortalContent permission.  Now 'base_view' respects this when
        regurgitating the values on any give adapter object
        [andrewb]
        
        - Stop using trademarked Salesforce.com icon
        [davisagli]
        
        1.5a3
        
        - Better handling of empty FormIntegerField values, which when left blank were
        filled by an empty string that was being passed along within the created
        object.  In the case of a string-like field, this was fine, but integer
        fields (i.e. documented as xsd:double and xsd:int format in the SF WSDL)
        were another story.  This resolves:
        http://plone.org/products/salesforcepfgadapter/issues/8
        Note: If a FormIntegerField was a required field and therefore came through
        as expected in the request, this was handled properly
        [andrewb, thanks greenstork for bug report]
        
        
        1.5a2
        
        - The mutator for our SFObjectType field now takes into account the fact that
        there could exist invalid field mappings and/or dependency mappings for the
        ultimately chosen sObject type, which could lead to an Invalid Field
        exception, should the mappings not be reconfigured.  This is primarily
        useful in the case where the user sets up an adapter to create one field
        type, but later switches to another.  This fixes the following issue:
        http://plone.org/products/salesforcepfgadapter/issues/7
        [andrewb]
        
        - Appropriate cleanup of renamed and/or removed adapters with the Parent
        Adapter mapping interface.  Similar approach to what exists for field
        mapping cleanup.
        [andrewb]
        
        - Better handling of empty FormDateField values, which were plagued by errors
        casting to DateTime format and if successful an invalid xsd:dateTime format.
        This resolves:
        http://plone.org/products/salesforcepfgadapter/issues/6
        http://plone.org/products/salesforcepfgadapter/issues/5
        Note: If a FormDateField was a required field and therefore came through as
        expected in the request, this was handled properly
        [andrewb, thanks greenstork for bug report]
        
        - Adding support for PloneFormGen's FormFileField type to be populated with a
        binary file and uploaded directly to Salesforce.com upon proper base64
        encoding. There may be other use cases, but the Attachment type in
        Salesforce can be associated with any other type, as related by the
        ParentId, field and is where binary data, stored on the Body field, is
        typically associated with a record.
        [andrewb]
        
        - In order to reduce the configuration burden upon the user (i.e. placing
        Salesforce Adapters in the order they will need to operate), we build and
        run adapters from the final adapter within the folder.  This adapter in turn
        manages the needed order and creates the Salesforce records appropriately.
        The 1.5a1 release, however, does not account for disabled adapters.  I.E.
        those that are checked off in the form folder's adapter field. This is now
        fixed. See:
        http://plone.org/products/salesforcepfgadapter/issues/3
        [andrewb]
        
        - In the same category as the following issue:
        http://plone.org/products/salesforcepfgadapter/issues/3, we need to account
        for those adapters with an "execCondition" that fails. This is now fixed.
        See: http://plone.org/products/salesforcepfgadapter/issues/4
        [andrewb]
        
        
        1.5a1
        
        - Adding new DataGridField FixedColumn with visibility set to false for the
        the 'fieldMap' schema field on the Salesforce Adapter, which stores the
        relative path from the parent form to the field in question.  Previously, we
        were 'building' the data structure for the soon to be created Salesforce
        object based on mappings keyed off of each field's title.  Since titles
        aren't necessarily unique, this was fragile and with the introduction of
        support for mapping fieldset-based fields, the code was getting ridiculous.
        *NOTE*: If jumping to this version of salesforcepfgadpater from previous
        versions, you'll need to reinstall the product from the ZMI or the
        Add/Remove Products control panel. This will trigger the migration of all
        existing Salesforce Adapter objects, to include this essential new column
        for the field map.
        [andrewb]
        
        - Reworking overly fragile 'do we need to migrate' infrastructure for versions
        prior to 1.0rc1 which assumed that we'd be listing all known versions to the
        end of time and also that running a profiles steps wouldn't bump the
        installedversion attribute on an installed product, as it now appears to do
        in CMFQIT version 2.1.4. This should allow for a simultaneous Plone 3.1.x
        migration and Salesforce PFG Adapter upgrade.
        [andrewb]
        
        - Added support for form fields within a folderish "fieldset" both from a
        mapping and creation within Salesforce.com objects perspective.
        [andrewb]
        
        - Adding test/code coverage protecting against a maximum recursion depth
        exceeded error via a direct call to getSortedSFAdapters.  This is feasible
        in the case where Salesforce Adapters are configured outside the context
        of the existing Archetype validation code.
        [andrewb]
        
        - Added support for "chained adapters" (that is, forms that create separate,
        but linked SF objects) including: schema extensions for adapters, validation
        against circular chains, and execution of chains in the correct order.
        [jbaldivieso, andrewb]
        
        1.0 - released April 4, 2008
        
        - Added test coverage of onSuccess, the critical piece in ensuring that
        our form values make their way into Salesforce.com as the appropriate
        SFObject type with configured mapping.  I suppose test coverage of
        the main functionality is okay during an rc cycle :)
        [andrewb]
        
        1.0rc2
        
        - Using proper Generic Setup API "runAllImportStepsFromProfile", rather than
        deprecated "setImportContext".  For more information, see the very helpful:
        http://www.nabble.com/Product-install-regression--td14165955.html#a14165955
        [andrewb]
        
        - Cleaning up naughty "import \*" statement within Install.py
        [andrewb]
        
        1.0rc1
        
        - Providing test and migration for legacy adapters that didn't have the
        capability to mark required fields in the UI
        [andrewb, jessesnyder]
        
        - Renaming the Salesforce PFG Adapter's archetype_name to Salesforce
        Adapter, in attempt to increase non-technical accessibility.
        Provided migration for the same
        [andrewb, jessesnyder]
        
        - Add zope security checks to methods in the SalesforcePFGAdapter class
        [jessesnyder]
        
        - Tweaked i18n infrastructure and added German translation.
        [davisagli]
        
        - Don't show extraneous schemata in Plone3
        [jessesnyder]
        
        - Ran Zope's test coverage feature against our code base and extended test
        coverage to key parts of the public aspects of our code base
        [andrewb]
        
        - Implement IMultiPageSchema so that schemata can be processed separately and
        in order, since the field mapping schemata depends on the default schemata
        being submitted first.
        [jessesnyder]
        
        - Re-ordered the adapter's schemata to put 'field mapping' before
        'overrides'. [davisagli]
        
        - Worked around FGDateField issue to format submitted dates properly for
        Salesforce.com input. Used DateTime.HTML4() method on field value
        [ghnatiuk, davisagli]
        
        - Adding labeling to the field mapping ui to show those fields for the
        chosen SFObject, which are non-nillable (i.e required) and don't have a
        computed value (i.e. as in a unique id, which is required but you have no
        control over)
        [jessesnyder, andrewb]
        
        - Sorting of fields that are required first, then those that are optional
        second in the field mapping ui
        [jessesnyder, andrewb]
        
        1.0-alpha2
        
        - Worked around issue where the DataGridField strips proceeding/trailing
        spaces for its FixedRow values, but our generateFormFieldRows method did
        not, thus each save of the adapter produced duplicate mappings in the
        DataGridField UI
        [jessesnyder, andrewb]
        
        - Providing custom mutator for the field map user interface, which now
        auto-cleans up those fields that have been removed or re-titled
        [jessesnyder, andrewb]
        
        1.0-alpha1
        
        - Initial import and creation of standalone product originally created at the
        following branch:
        
        - http://svn.plone.org/svn/collective/PloneFormGen/branches/salesforce_adapter_branch/
        
        
Keywords: Zope CMF Plone Salesforce.com CRM PloneFormGen forms integration
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: Zope2
Classifier: Framework :: Plone
