Detailed Get/Post Logic

Get Logic

1. The get request is generated with the fetch criteria described above
2. The get request is submitted to the Zoho API and the response is processed. If no data is returned or if the Zoho API returns an error message, an APIException will be thrown. If there is a problem parsing the response, a ResponseException or a DeserializationException may be thrown. See the Exception Management section for more details on the exception types.
3. The type of the model objects created is determined by either the generic type parameter submitted with the get method or, if a non-generic get method is used, models are generated of the type(s) defined in ZohoCRMClient’s ModelFactory (implementing ICRMModelFactory) object. See the Model Factory section for more detail.
4. The get response is deserialized into one or more strongly-typed model objects:
   • Record data will not be deserialized into any properties with Ignore attributes (see the Ignore Attributes section).
   • For each record returned, the library will iterate through each Zoho field with the following logic:
     • Attempt to assign the Zoho field value to a model property by using the specified field mappings dictionary (see Field Mappings section). If the data is successfully assigned to a property, the model implements ISyncableModel and RawFieldsOption is StoreAll, the field data will be loaded to the RawFields dictionary (see the Creating Strongly-Typed Models section).
     • Attempt to assign the Zoho field value to a model property by using a special field attribute applied to the model and their default field names. If the data is successfully assigned to a property, the model implements ISyncableModel and RawFieldsOption is StoreAll, the field data will be loaded to the RawFields dictionary (see the Creating Strongly-Typed Models section).
     • Attempt to match the Zoho field name to a model property name by using automatic name matching logic – this involves removing the spaces, underscores, dashes and capitalization when making the comparison. If the data is successfully assigned to a property, the model implements ISyncableModel and RawFieldsOption is StoreeAll or StoreUnmapped, the field data will be loaded to the RawFields dictionary (see the Creating Strongly-Typed Models section).
     • If the data cannot be matched to a property, the model implements ISyncableModel and RawFieldsOption is StoreAll, StoreUnmapped or StoreUnmatched, the field data will be loaded to the RawFields dictionary (see the Creating Strongly-Typed Models section).
   • When each model property is assigned, it must be converted from the string representation returned from Zoho. If this cannot be done successfully and the model implements ISyncableModel, the field data will be loaded to the UnassignableProperties dictionary (see the Creating Strongly-Typed Models section). If the model does not implement ISyncableModel, the property will simply not be assigned. For more detail on the type conversions and mappings, see the Zoho Field Type to .NET Type Mappings section.

Post Logic

1. Identify the post result fields returned by Zoho (those fields returned in the CRMPostResults object). If PostModelSyncOption is not None, the Id property must be identifiable, otherwise an exception is thrown (see the Id Property Identification section).
2. If the model implements ISyncableModel and state tracking is not disabled (an ISyncableModel can disable state tracking upon instantiation or temporarily using the SuspendStateTracking method), the ModelState must be New to execute an insert or Modified to execute an update, otherwise an exception will be thrown.
3. If the model implements IValidatableModel and the ValidateBeforePost option is true, validation will be attempted prior to posting (see the Model Validation section). If validation fails, an exception will be thrown.
4. The model object(s) are serialized to xml for submission to the Zoho API:
   • Any properties with Ignore attributes will not be serialized (see the Ignore Attributes section)
5. An attempt is made to identify an Id property (see the Id Property Identification section)
6. For updates, if the model implements ISyncableModel and state tracking is not disabled, only those properties with a property state (accessed via ISyncableModel’s GetPropertyState method) of Modified will be serialized
   • Attempts are made to identify all special model properties (see the Special Model Properties section). If the property has a field mapping, the mapped Zoho field will be used for the special properties. If the special property is not mapped and the WebSyncSeparatePascalCaseAttribute is applied to the property, then spaced format field name derived from the property name will be used. Otherwise, the default Zoho field name will be used.
   • The owner-related special fields are serialized such that only the Owner Id and/or the Owner Email properties are submitted if they’re available (the Owner Email property is submitted as the Owner field). If neither is available, then the Owner property may be submitted (see the Owner Fields Handling section).
   • Only the CreatedById and ModifiedById special fields can be serialized for posting and they will only be serialized if they have a value (nulls are not allowed). The CreatedBy and ModifiedBy properties cannot be posted.
   • The CreatedTime, ModifiedTime and LastActivityTime special fields cannot be posted either.
   • Properties decorated with the WebSyncReadOnlyAttribute or the WebSyncReadOnlyUpdateAttribute will not be serialized (see the Read Only Attributes section)
   • Properties identified as lookup id fields via the CRMLookupIdAttribute will not be serialized if they do not have a value (passing a null value to Zoho will cause an error)
   • Properties with specified field mappings will be serialized using the mapped Zoho field name (see the Field Mappings section)
   • If ModelPropertiesSerializationOption is not SerializeMappedOnly, an attempt will be made to serialize unmapped properties using the logic described under SerializeAllMatched of the ModelPropertiesSerializationOption option.
   • If ModelPropertiesSerializationOption is SerializeAll, any remaining properties will be serialized. If the property is decorated with the WebsyncSeparatePascalCaseAttribute, the Zoho field name will be converted to a spaced format, otherwise the Zoho field name will be identical to the property name.
   • If the model implements ISyncableModel and the SerializeRawFields option is true, any RawField entries that have not already been serialized via a model property, will be serialized.
   • When each model property is serialized, it must be converted to a string representation – if this cannot be done successfully, an exception will be thrown, cancelling the entire post operation before submittal to the Zoho API (see the Zoho Field Type to .NET Type Mappings section).
7. When populating field data with “null”, Zoho will consider this empty (same as if an empty string was populated).
8. When a non-existent field name is submitted (for an update or insert), it is simply ignored by Zoho
9. The post request is submitted to the Zoho API and the response is used to construct a CRMPostResults object (see the CRM Post Results section).
10. If the PostModelSyncOption is not None, the model objects are updated with the field values returned in each CRMRecordPostResult record of the CRMPostResults.Records property. Each model object is only updated if there were no errors associated with posting that model object record. If the post was an insert and a duplicate for a posted model object was identified but not updated (DuplicateInsertResult.Identified), then no model properties will be updated. Otherwise, for inserts, the Id property will be assigned the value returned with the post results. If the special fields CreatedTime, ModifiedTime, CreatedBy and ModifiedBy are identified on the model objects, the field values returned with the post result will be applied to the corresponding model object. If errors occur in assigning the above field values to the model properties, error strings are added to the CRMPostResults object record's ModelErrorMessages property. This is done to avoid throwing an exception after the Zoho API may already have been updated and to allow all model objects unaffected by the error to get updated appropriately.
11. For each posted model object implementing ISyncableModel, the model state is set to Unsynced and the model property dictionaries (UnassignableProperties, UnsyncableProperties and RefreshableProperties) are cleared. These updates will occur only for those models associated with post result records that do not have an error message. Updates will also not occur for inserts in which a duplicate was identified and not updated. Model states are only updated for models in which state tracking is not disabled, but the model property dictionaries will be cleared for all ISyncableModels. If errors occur in assigning the model state, error strings are added to the CRMPostResults object record's ModelErrorMessages property. This is done to avoid throwing an exception after the Zoho API may already have been updated and to allow all model objects unaffected by the error to get updated appropriately.
12. If the PostModelSyncOption is FullSync, for each posted model object implementing ISyncableModel, a full sync will be performed by issuing a secondary get requests for the model record and comparing each property value, determining if the posted values were recorded in the Zoho system as expected and determining if any other values have changed in the Zoho system that are not reflected in the local model object. The model state of each posted model will also be updated to Synced (or Unsyncable or Refreshable) and the model property dictionaries (UnassignableProperties, UnsyncableProperties and RefreshableProperties) will be cleared. These updates will occur only for those models associated with post result records that do not have an error message. Updates will also not occur for inserts in which a duplicate was identified and not updated. Model states are only updated for models in which state tracking is not disabled, but the model property dictionaries will be cleared for all ISyncableModels. If errors occur in assigning the model state, error strings are added to the CRMPostResults object record's ModelErrorMessages property. This is done to avoid throwing an exception after the Zoho API may already have been updated and to allow all model objects unaffected by the error to get updated appropriately.
13. The full sync operation will:
    • not process any properties marked with ignore attributes (see the Ignore Attributes section).
    • assign the fetched values from the secondary get request(s) to the original object model for the following special properties (if they are identifiable): CreatedBy, CreatedById, ModifiedBy, ModifiedById and LastActivityTime.
    • assign the fetched values from the secondary get request(s) to the original model for the Owner and OwnerId special properties if the original model property is null or empty.
    • assign the fetched values from the secondary get request(s) to the original model for any other model properties decorated with the WebSyncReadOnlyUpdateAttribute.
14. All other model properties (except those already updated with the post results) will be compared. If a posted property value is different from the secondary get request fetched value, the property state will be set to Unsyncable and the fetched value will be added to the UnsyncableProperties dictionary. If a non-posted property value is different from the secondary get request fetched value, the property state will be set to Refreshable and the fetched value will be added to the RefreshableProperties dictionary.
    • The Owner special property can only be refreshable and the OwnerEmail property will not be synced at all.