Salesforce PFG Adapter

Mapping Form Fields

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.

Preset Values

Sometimes you want every object created by a particular form to have the same value for a particular field. For instance, you might want to set the "Lead Source" field of a Lead to "Web". This can be accomplished using the "Preset Field Values" setting.

In the left column, enter the value you want to store in the field. (e.g. "Web")

In the right column, select the field in which the value should be stored. (e.g. Lead Source)

If you need a more complicated expression in order to determine the value, you could instead create a hidden form field, edit its default value override expression, and map it using the form field mapping setting.

Chained Adapters

Salesforce-PloneFormGen adapters can be used to create multiple related objects from a single form. e.g. creating a Contact linked to an Account:

-----------                -------------
| Account |                | Contact   |
-----------                -------------
| Id      | -------------> | AccountId |
| Name    |                | LastName  |
-----------                -------------

To create this link, the 'AccountId' external key of the Contact object needs to be set to the Id of the Account it should be associated with. This can be accomplished with Salesforce-PloneFormGen by creating one Salesforce Adapter for the Account and one Salesforce adapter for the Contact, and then setting the "Configure Parent Adapters" setting of the contact adapter so that it maps the Id from the account adapter to the AccountId field of the Contact.

In this setup, 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 used by the Contact record which is created subsequently. Care is taken via validation that "circularly dependent" adapters can not be accidentally configured.

Updating Existing Objects

By default a Salesforce Adapter will always create new objects in Salesforce. It is also possible to use them in an "update" mode in which the form will find an object in Salesforce matching a given expression, load the form with values from that object, and then save changes to the object when the form is submitted.

This can be set up using the following settings on the "create vs. update" section of the Salesforce Adapter configuration:

Creation Mode

Set to 'create' to always create a new object (default). Set to 'update' to try to find and update an existing object.

Expression to match existing object for update

Enter a TALES expression which evaluates to a SOQL WHERE clause that returns the Salesforce.com object you want to update. If you interpolate input from the request into single quotes in the SOQL statement, be sure to escape it using the sanitize_soql method. For example, the following could be used to match objects whose Username__c field equals a value passed in the 'username' parameter of the request:

python:"Username__c='" + sanitize_soql(request.form.get('username', '')) + "'"

Behavior if no existing object found

Determines the desired behavior in case no object was found matching the given expression. If set to 'Fail with an error message.', an error will be displayed (default). If set to 'create', a new object will be created instead.

NB: The adapters accomplish prepopulation of form fields by modifying the default value override for all mapped fields. Default value overrides that have already been customized will be left intact.

NB: Salesforce is queried using the match expression only when the form is first loaded; at which point the Salesforce Id of the object that was found is stored in a Zope session. This ensures that changes are always saved to the same object that was loaded, even if other changes happened to the database in the meantime. However, it does mean that if the user's session is destroyed (such as during a Zope restart), then submitting the form will fail.

When using chained adapters, some adapters could be used in update mode while others are used in create mode. For example, this could be used to add a new Opportunity associated with an existing Account. Currently this requires setting up at least one form field mapping for each adapter to work properly. In addition, the behavior if a single field is mapped by multiple adapters is not yet defined.