more docs

CHANGES.txt

@@ -1,8 +1,8 @@
 Changelog
 =========
 
-0.1 (unreleased)
-----------------
+1.0b1 (unreleased)
+------------------
 
 * Install a Salesforce base connector when the package is installed.
   [davisagli - 2011-09-20]

README.rst

@@ -3,33 +3,34 @@ Introduction
 
 ``collective.salesforce.content`` provides a Dexterity behavior for setting up
 Plone Dexterity content types that are connected to objects in a Salesforce.com
-database. These features are currently implemented:
+database. Arbitrary schema fields can be mapped and updated periodically based on
+automatic queries to Salesforce.
 
-* Metadata can be added to fields in a content type's schema to indicate how
-  the Dexterity object maps to a Salesforce object.
+This is currently an integrator-level package with minimal UI. As consultants,
+we have used this functionality as a foundation for solving use cases like:
 
-* A Salesforce Object behavior that can be added to a Dexterity type. The
-  behavior gives the type a Salesforce ID field and provides an indexer 
-  for that field. It also acts as an adapter to the ISalesforeObject
-  interface, which provides methods for syncing the object with Salesforce.
+* Expose a member directory on a public Plone website based on Account or Contact
+  records pulled from Salesforce.com each night.
 
-* A synchronization view that queries Salesforce and creates/updates the
-  appropriate objects in Plone. It looks for Dexterity FTIs with the 
-  aforementioned behavior, reads the Salesforce mappings from their schemas,
-  and executes the appropriate queries.
+* Provide browseable and searchable tables of arbitrary data whose
+  canonical storage is in Salesforce.com.
 
-* A simple converter system that uses adapters to convert values returned by
-  Salesforce into the appropriate schema values and vice-versa. These
-  converters can be registered globally for a particular field type, or they
-  can be specified by name for a field instance.
-
-These features remain to be completed:
+* In conjunction with ``dexterity.membrane``, allow users represented in
+  Salesforce.com to log in to a Plone site, with appropriate roles based on their
+  status in Salesforce.com.
 
-* Recording changes from the Dexterity object back to Salesforce.
+* Pull pricing records from Salesforce as a basis for charging the correct amount
+  in online transactions on the Plone website.
 
-* Querying Salesforce for and updating a single Plone object.
+Documentation
+=============
 
-* Converters for more complex field types.
+`Read the documentation <http://readthedocs.org/docs/collectivesalesforcecontent/en/latest/>`_.
+
+Issue Tracker
+=============
+
+`Submit issues <https://github.com/Groundwire/collective.salesforce.content/issues>`_.
 
 Credits
 =======

docs/howto.rst

@@ -4,7 +4,70 @@ 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
 ------------------------------