How to...
=========

Set up automatic periodic synchronization
-----------------------------------------

Here is one way to automatically trigger the sync via a cron job. The sync will
run in a separate process from your standard backend instances, so you must be
using ZEO or RelStorage to allow multiple database connections.

1. In the root of your buildout, create a file ``cronviews.py.in``::

    from AccessControl.SecurityManagement import newSecurityManager
    from AccessControl.SecurityManager import setSecurityPolicy
    from Testing.makerequest import makerequest
    from Products.CMFCore.tests.base.security import PermissiveSecurityPolicy, OmnipotentUser
    from zope.app.publication.interfaces import BeforeTraverseEvent
    from zope.event import notify
    import transaction

    # Get our variables from buildout in order.
    site_path = '${site-path}'
    view_names = """${views}"""

    site_path = site_path.strip().strip('/')
    views = [v.strip() for v in view_names.split() if v.strip()]

    # Set up a generic manager user.
    _policy=PermissiveSecurityPolicy()
    _oldpolicy=setSecurityPolicy(_policy)
    newSecurityManager(None, OmnipotentUser().__of__(app.acl_users))

    # Set a request so that traversal succeeds.
    app = makerequest(app)

    # Fire a before traversal event so that browser layers get applied.
    site = app.restrictedTraverse(site_path)
    notify(BeforeTraverseEvent(site, site.REQUEST))

    # Try to open the views.
    for view in views:
        try:
            site.restrictedTraverse(view)()
            transaction.commit()
        except:
            import traceback
            traceback.print_exc()

2. Add sections to buildout.cfg to install this script and run it via cron
   (be sure to replace ``path/to/site``)::

    [buildout]
    parts =
        cronviews
        sfsync

    [cronviews]
    recipe = collective.recipe.template
    input = ${buildout:directory}/cronviews.py.in
    output = ${buildout:directory}/etc/cronviews.py
    site-path = path/to/site
    views =  
        @@sf_sync
    
    [sfsync]
    recipe = z3c.recipe.usercrontab
    times = 00 1 * * *
    command = ${buildout:executable} ${buildout:bin-directory}/instance run ${buildout:directory}/etc/cronviews.py

3. Run the buildout to install the cron job.

Sync a single object on demand
------------------------------

Go to the Salesforce Content control panel in Site Setup.

In the `Salesforce object Id` box, enter the Id of the Salesforce object you
want to sync (you can obtain it from the URL when looking at the object in
Salesforce).  You must also select the content type corresponding to the
Salesforce object type of the item.

Click Synchronize Now to sync the single item.

There is also an API to trigger this sync for a particular object from an
external system (such as a button on an object in Salesforce). To set it up,
go to the Configuration Registry and set a value for the
``collective.salesforce.content.sync_key`` key. Then you can run a sync via,
e.g., http://path/to/plone/sf_sync?token=TOKEN&types:list=OBJTYPE&sf_object_id=ID
where TOKEN is the sync key you configured, OBJTYPE is the Salesforce object type
of the object you want to sync, and ID is its Salesforce Id.


Obtain the Salesforce Id of a Plone item
----------------------------------------

Use the behavior adapter::

  from collective.salesforce.content.interfaces import ISalesforceObject
  sf_object_id = ISalesforceObject(item).sf_object_id
  
This works as long as ``item`` is an item whose type has the ISalesforceObject
behavior enabled.


Retrieve a Plone item by Salesforce Id
--------------------------------------

Query the ``sf_object_id`` catalog index::

  from Products.CMFCore.utils import getToolByName
  catalog = getToolByName(context, 'portal_catalog')
  res = catalog.searchResults(sf_object_id=my_id)
  if res:
      item = res[0].getObject()


Set up vocabularies based on Salesforce picklists
-------------------------------------------------

If you want to set up a Choice field using a vocabulary from Salesforce,
you can use the ``SalesforcePicklist`` field instead::

    <field name="experience" type="collective.salesforce.content.fields.SalesforcePicklist" sf:field="Experience__c">
      <title>Experience</title>
      <required>False</required>
    </field>

The picklist values will be automatically retrieved from Salesforce when
needed, and cached in the ZODB.

For a multi-select choice (Set of Choice) that obtains its vocabulary this way,
use ``SalesforceMultiPicklist``::

    <field name="company_industry" type="collective.salesforce.content.fields.SalesforceMultiPicklist"
      form:widget="z3c.form.browser.checkbox.CheckBoxFieldWidget"
      sf:field="Industry__c">
      <title>Industries</title>
      <required>False</required>
    </field>


Perform custom actions when objects are synced, or no longer synced
-------------------------------------------------------------------

Two events may be raised for an object during sync:

``collective.salesforce.content.events.NotFoundInSalesforceEvent``

  An object event that indicates that this object was not returned by
  Salesforce when its Dexterity type was synchronized.

  There is an included, optional behavior which handles this event:

  ``collective.salesforce.content.interfaces.IPublishUpdated``
    Causes an object to be published after it is updated from Salesforce during a sync.

``collective.salesforce.content.events.UpdatedFromSalesforceEvent``

  An object event that indicates that this object was updated from Salesforce.
  
  There are optional behaviors which handle this event:
   
  ``collective.salesforce.content.interfaces.IDeleteNotFound``
    Causes an item with this behavior to be deleted from Plone if it is not
    found during a Salesforce sync.

  ``collective.salesforce.content.interfaces.IRejectNotFound``
    Causes an item to be rejected (in the workflow sense, i.e. made private) if
    it is not found during a Salesforce sync.

Sync objects in a particular order
----------------------------------

Since the ``criteria`` directive is added to the end of the generated SOQL query,
it can be abused to specify an ORDER BY clause. For example, this schema::

  <schema sf:object="Contact" sf:criteria="ORDER BY Name"></schema>
  
would result in the following SOQL::

  SELECT Id FROM Contact ORDER BY Name

There is not currently any mechanism to control the order in which multiple content
types using the ISalesforceObject behavior are synced, aside from triggering the
sync multiple times specifying different sets of content types.