Model Details

Id Property Identification

For most post operations, the model property representing the record Id must be identifiable. The only exceptions are post operations for which the PostModelSyncOption is None (as there is no feedback from the post results to the model object that was posted) and for updates, the id parameter must be specified (so that the library can tell the Zoho API which record to update). The Id property will first attempt to be identified by an optional primaryKeyName parameter that specifies the Id property name on the model. If this parameter is null or empty, the library will look for a model property with the WebPrimaryKeyAttribute. The primaryKeyName parameter should not specified for a different property than the property to which the WebPrimaryKeyAttribute is applied.

Ignore Attributes

Strongly-typed models may be decorated with attributes that instruct the library to ignore a property when loading the model object with data from the Zoho API or when serializing data for submission to the API. The library will recognize either the custom attribute WebSyncIgnoreAttribute or a .NET framework attribute XmlIgnoreAttribute. ZohoCRMClient has an option, WebPropertiesIgnoreOption, for controlling which ignore attributes are recognized. If WebSyncIgnoreOnly, then only the WebSyncIgnoreAttribute will be recognized. If XmlIgnoreOnly, then only the XmlIgnoreAttribute will be recognized. Otherwise, if All, then both attributes will be recognized. The default is WebSyncIgnoreOnly.

Read Only Attributes

Strongly-typed models may be decorated with attributes that instruct the library to only populate the property with data fetched through get requests and to never serialize the property data for posting the the Zoho API. The WebSyncReadOnlyAttribute and the WebSyncReadOnlyUpdateAttribute serve this purpose. The WebSyncReadOnlyUpdateAttribute is only applicable to models implementing ISyncableModel and instructs the library to automatically update the property after a post operation in which the PostModelSyncOption is set to FullSync. This should be used for Zoho-calculated field types such as Auto Numbers and Formula fields.

Special Model Properties

There are a set of “special” model properties that require special handling. These properties are identified through a set of attributes – each attribute should be applied to one and only one model property. The special properties and the associated identifying attributes are as follows:

A specific discussion of the owner fields (Owner, OwnerId and OwnerEmail) handling is provided under the Owner Fields Handling section.

Owner Fields Handling

There are special handling mechanisms built into the library for the owner fields. This processing stems from Zoho's handling of a record's owner field (e.g. Lead Owner). When retrieving records, the owner field is populated with the owner's name. However, when inserting or updating a record, using the record owner's name will result in the record being assigned to the default login credential used in the Auth Token. Instead, to update the owner properly, the owner field must contain the email address of the desired record owner. Alternatively, the userId of the desired owner can be specified using the SMOWNERID field.

To handle this situation, the library defines three property attributes to identify the relevant properties of strongly-typed model objects (CRMOwnerAttribute, CRMOwnerIdAttribute and CRMOwnerEmailAttribute). CRMOwnerAttribute and CRMOwnerIdAttribute identify the standard owner and owner id fields described above. CRMOwnerEmailAttribute identifies an additional owner field in which the owner's email can be specified for the purpose of updates and inserts (the ISyncableModel CRM model objects provided with the library define an OwnerEmail property). No field mappings should be specified for this owner email field as it doesn't have a direct counterpart exposed through the Zoho CRM API (and thus will not be populated with record fetches).

When these three owner-related properties are identified on model objects by the attributes described above, the library will attempt to use just one owner identifier when performing inserts or updates. If the owner id is not empty (and has a modified state when model state tracking is not disabled for models implementing ISyncableModel), it will be sent to the Zoho API and the owner property will not be included. Same thing goes for the owner email field, except it will be sent in place of the owner property. Both owner id and owner email may be sent, though this should be avoided by the way in which the model objects are updated by the library client.

The standard owner property will only be sent if neither the owner id nor the owner email properties are sent and it is not empty (and has a modified state when model state tracking is not disabled for models implementing ISyncableModel).

When syncing updates or inserts back to an ISyncableModel model object, a property marked with the CRMOwnerAttribute can only be refreshable and a property marked with the CRMOwnerEmailAttribute will not be synced at all.

Be careful when updating records in the following scenario:

• Custom model objects are being used or state tracking is disabled for ISyncableModel objects, and
• An owner id property is not indentified or not populated, and
• An owner email property is not indentified or not populated, and
• An owner property is populated with a name different from the name associated with the default login credential used in the Auth token

This can result in the owner being updated to the default login credential used in the Auth token.

Lookup Fields Functionality

When a custom Lookup field type is defined in the Zoho CRM, the field returns a string representation of the record that the Lookup value refers to. If there is no Lookup value defined, when fetching data, this field will simply be empty (or null). However, when data is present, an additional field is returned (the Lookup field name with a _ID appended for custom lookup fields) that represents the Id of the referenced record. When a model property is present for this Lookup ID field, it should be decorated with the CRMCustomLookupIDAttribute. The lookup field can be updated with either the lookup name field or the id field.

If the ID field associated with a custom Lookup field (or the custom Lookup field itself) is updated with an invalid ID, the entire request returns an error (even for multi-record updates). If a null/empty value is submitted for a custom Lookup field, it will have no effect and the library will not allow the ID field associated with a custom Lookup field to be submitted with a null/empty value as this would cause a Zoho API error. The result of this is that there is no way to update a custom Lookup field to an empty or undefined state via the API.

The Zoho system handles built-in lookup fields a little differently. The lookup ID field is always returned, even when a lookup value is not specified. At least for the account lookup field on contact records, the following logic applies. If a new account name is specified in the account name lookup field for a contact record and that account doesn’t already exist, it will be created automatically. Updating an existing account name lookup value to null has no effect. However, updating the associated ID field to null will remove the account reference. On an update or insert, if an account name and ID are both specified, the ID value will be used and the name value will be ignored. For this reason, the CRMLookupIDAttribute should be used on properties that represent the id of a built-in lookup field. When this attribute is used, it will allow new records to be inserted by specifying the lookup name value instead of the ID.

Code Snippets

smprop

A syncable model property snippet for creating new model properties for model classes that derive from SyncableModelBase.