Field Mappings

When using strongly-typed model objects, the most fundamental issue is how each of the model’s properties is matched to its corresponding field on the Zoho module record. The library uses explicit field-to-property mapping dictionaries to accomplish this objective. This is always the first priority and fastest means of associating Zoho fields with model properties.

To define the field mappings, the library defines an IFieldMappings interface for a field mappings object that maps field names of particular Zoho module fields to property names of the corresponding local models. It defines a DefaultMappings method returning a dictionary representing the default field mappings for a set of models. It is composed of an outer and inner dictionary. The outer dictionary's keys are string values of the model names for which fields are mapped. The outer dictionary's values are another dictionary (the inner dictionary) representing the field mappings. The inner dictionary's keys are string values representing the name of the field in the Zoho module record. The inner dictionary values are string values representing the property names of the local model. The interface also defines a CustomMappings method returning a dictionary representing additional custom field mappings for a set of models. It is composed in the same fashion as the DefaultMappings dictionary. The default versus custom mappings simply allows for easier extension of base implementations that already specify default mappings to default base models. Ordinary customizations then simply call for extending the base model classes with custom fields and extending the base field mappings with corresponding custom mappings.

The library provides a CRMFieldMappingsBase class which is the default implementation of the IFieldMappings interface. It contains a base set of field mappings for all of the default Zoho CRM modules. This class can be extended to specify CustomMappings that relate to customized models built for one or more CRM modules (either field additions to existing modules or custom modules). Depending on the particular CRM implementation / customizations and the strongly-typed model classes being used, this base field mappings class may be extended or it can simply be used as an example for defining a completely custom IFieldMappings implementation.

An IFieldMappings object should be provided to the ZohoCRMClient object in its constructor. If it is not, the default CRMFieldMappingsBase class will be used.

Although the library provides various other options for deserializing Zoho data records (such as automated property matching) and for serializing model objects when posting (inserting or updating) records to the API (see ModelPropertiesSerializationOption, SerializePascalCaseAsSpaced and SerializeRawFields), it's always safest (and likely easiest) to just provide specific field mappings. Depending on the ZohoCRMClient settings, Zoho record fields may get auto-matched to model properties. In this case, the only way that the ZohoSharp library has to serialize these properties for posting back to the Zoho API is by using the RawFields dictionary when the model object implements ISyncableModel. Furthermore, this requires that the model was previously fetched from the API and that the RawFieldsOption were set to StoreUnmapped or StoreAll (or that the model object's RawFields dictionary is updated manually). This is an onerous set of requirements when the safer alternative is to simply specify field mappings for any custom fields.

The provided code samples demonstrate the implementation of custom field mappings and provide the source code for the default field mappings implementation.