Some Salesforce fields can not be fully used without special attributes. You
can see the most complete form in the output of ``inspectdb``.

-  **sf_read_only** - Some fields require this special attributes to make the
   model writable. Some fields are completely read only (``READ_ONLY``)
   or insertable only but can not be later updated (``NOT_UPDATEABLE``) or
   updateable only but can not be specified on insert (``NOT_CREATEABLE``).
   Examples of such fields are: automatically updated fields "last_modified_by" and
   "last_modified_date" or fields defined by a formula like "name" of contact,
   given by "first_name" and "last_name". Example::

     last_modified_date = models.DateTimeField(sf_read_only=models.READ_ONLY)

-  **Defaulted on create** - Some Salesforce fields have a dynamic default value
   that is not exported by API and assigned by SF only if the field is
   omitted when a new object is inserted. This mechanism is not used by SF
   if the value is ``None``. It is even not accepted for not *nillable* fields
   by Salesforce, while the missing
   value is ok. Django-salesforce supports it by a special default value
   ``model.BooleanField(default=models.DEFAULTED_ON_CREATE)``. That means "let
   it to Salesforce". This is useful for all fields marked by attribute
   *defaultedOnCreate* in Salesforce. For example the current user of
   Salesforce is assigned to ``owner`` field if no concrete user is  assigned,
   but ``None`` would be rejected. All boolean fields have different default values
   according to current ``Checked/Unchecked`` preferences.

-  **Comments fo fields**

   - **``# Reference to tables [...]``**
     Some builtin foreign keys are references to more tables. The class of first
     table is used in the exported ``ForeignKey`` and all tables are listed in
     the comment. Any of them can be used instead.::

       class AccountHistory(SalesforceModel):
           created_by = models.ForeignKey(User) # Reference to tables [SelfServiceUser, User]

   - **``# Master Detail Relationship *``** The asterisk denotes a master-detail
         relationship recognized only by cascade delete attribute as it is usual between bultin
         SF objects. Relations from custom objects are marked explicitely as primary
         or secondary master-detail by ``'0'`` or ``'1'`` instead of ``'*'``.
         All cascade delete is done on the SFDC side, therefore they are exported with
         ``on_delete=models.DO_NOTHING``.

-  **Partial Database Introspection with inspectdb** Tables that are exported into a
   Python model can be restricted by regular expression::

     python manage.py inspectdb --table-filter="Contact$|Account" --database=salesforce

   In this example, inspectdb will only export models for tables with exact
   name ``Contact`` and all tables that are prefixed with ``Account``. This
   filter works with all supported database types.

-  **Verbosity** - This package can set correct column names for Salesforce
   without explicit attribute ``db_column`` for many objects automatically.
   These attributes are not exported if a default verbosity is used. This is
   intended for use only with SFDC. If an alternate non SFDC test database
   is also expected and migrations of any SalesforceModel will be created then
   explicit names in the code are better: ``--verbosity=2``.


-  **ForeignKey(unique=True)** SFDC doesn't allow to create a custom one-to-one
   relationship field. SFDC uses it currently only in three internal objects whose structure
   is not accessible through the SF user interface. A warning that OneToOneField
   would be better for such fields is reported by Django 1.9 if
   a ForeignKey(... unique=True) field is in a model. It is expected that
   most of developers don't need these models or can use a ForeignKey and ignore the warning.
   The OneToOneField will be not not implemented until Salesforce allows to create
   such custom fields.


SOAP API
--------

-  **Accessing the Salesforce SOAP API** - There are some Salesforce actions that cannot or can hardly
   be implemented using the generic relational database abstraction and the REST API.
   For some of these actions there is an available endpoint in the old Salesforce API
   (SOAP) that can be accessed using our utility module. In order to use that module,
   you will need to install an additional dependency ::

     pip install beatbox    # depends on Python 2.7

   Here is an example of usage with ``Lead`` conversion ::

     from salesforce.utils import convert_lead

     lead = Lead.objects.all()[0]
     response = convert_lead(lead)

   All usual
   `additional parameters <https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_convertlead.htm>`__
   are supported in the original mixed letter case. It allows e.g. merging a Lead
   with an existing Account or Contact and to control much more.::

     response = convert_lead(lead, accountId=account_id)

   For the particular case of ``Lead`` conversion, beware that having
   some *custom* and *required* fields in either ``Contact``, ``Account`` or
   ``Opportunity`` can be more complicated. A mapping from custom fields in your
   ``Lead`` to these fields must be defined in the system and these Lead fields
   should not be empty at the time of conversion. Follow the
   `instructions <http://www.python.org/https://help.salesforce.com/apex/HTViewHelpDoc?id=customize_mapleads.htm>`__
   for more details.
