The following sections describe the functionality that is supported to interact with the Zoho CRM. This functionality is supplied by the ICRMClientModule objects exposed through instances of the ZohoCRMClient class.
As an alternative to using the model factory directly, these methods simply create a new object representing a module record. They just create new objects locally – they DO NOT communicate with the Zoho API. For the non-generic version, the concrete model types returned are determined by the ZohoCRMClient's model factory. For the generic version, the model types are determined by the generic type parameter T.
There are a set of record retrieval methods that return module records by specifying various fetch criteria (see the method list and parameters below). The concrete model type returned is determined by the ZohoCRMClient object's model factory (see the Model Factory section). Each fetch method has a generic type overload in which a type T can be specified. For these methods, the concrete model type returned is specified by the generic type parameter T. If no records match the fetch criteria, the Zoho API will return an error message and an ApiException will be thrown.
Detailed information related to the logic applied when retrieving records is supplied in the Get Logic section.
GetRecord/GetRecordAsync (single-model gets)GetRecords/GetRecordsAsync (multiple-model gets)GetMyRecords/GetMyRecordsAsync (multiple-model gets)GetCVRecords/GetCVRecordsAsync (multiple-model gets)GetSearchRecords/GetSearchRecordsAsync (multiple-model gets)GetSearchRecordsByPDC/GetSearchRecordsByPDCAsync (multiple-model gets)Certain parameters are marked as required. All other parameters are optional.
GetRecord / GetRecordAsync or GetSearchRecordsByPDC / GetSearchRecordsByPDCAsync.GetRecord / GetRecordAsync or GetSearchRecordsByPDC / GetSearchRecordsByPDCAsync.The following sort options parameters are available to specify the order in which the records matching any other fetch criteria are sorted. The sort order is important in that it works in conjunction with the fromIndex and toIndex. If no sort is defined through one of the parameters listed below, a default sort will be submitted to Zoho. By default records will be sorted by Created Time in a descending order. This is done because it is unclear how records are sorted by Zoho when no sort parameters are submitted. Applicable only to GetRecords / GetRecordsAsync and GetMyRecords / GetMyRecordsAsync.
Model<lead>.Property(m => m.LastName)). Default is null.GetRecords / GetRecordsAsync, GetMyRecords / GetMyRecordsAsync and GetCVRecords / GetCVRecordsAsync.GetCVRecords / GetCVRecordsAsync only.GetSearchRecords / GetSearchRecordsAsync only.GetSearchRecordsByPDC / GetSearchRecordsByPDCAsync only.GetSearchRecordsByPDC / GetSearchRecordsByPDCAsync only.CRMGetRecordOptions object allows for specifying ZohoCRMClient-level options on an individual get call basis. When this options parameter is specified, all of the contained options will override the same options set for the ZohoCRMClient object. See the General Get Options section for more detail.The related record retrieval methods function much the same as the GetRecords methods described previously in the Retrieving Records section, except that records related to a different parent module record are returned. The nomenclature of the method names in the ZohoSharp library depart somewhat from that used in the Zoho CRM API. In the ZohoSharp library, the GetRelatedRecord methods are called on a certain ICRMClientModule object by specifying the child module records to be returned. For instance, the following code will retrieve all the Contact module records related to an Account module record with an Id of 12345678:
List<ContactBase> contacts = client.Accounts.GetRelatedRecords("12345678", CRMModuleBase.Contacts).Cast<ContactBase>().ToList();
Methods representing the converse of the relationship can also be used. The GetRecordsRelatedToParent methods are called on a certain ICRMClientModule to return records of that module type by specifying the parent module. The following code will retrieve the same records as the previous statement:
List<ContactBase> contacts = client.Contacts.GetRecordsRelatedToParent("12345678", CRMModuleBase.Accounts).Cast<ContactBase>().ToList();
Additionally, the library provides specific methods for retrieving child records that are common to most modules – Notes, Attachments and Activities (Events, Calls and Tasks).
Like the standard record retrieval methods, the concrete model type returned is determined by the ZohoCRMClient object's model factory (see the Model Factory section). Each GetRelatedRecords (and the variants described above) method has a generic type overload in which a type T can be specified. For these methods, the concrete model type returned is specified by the generic type parameter T.
If the specified parent module does not define a set of records for the specified child module (or the Zoho API does not allow their retrieval), the Zoho API will return an error message and an ApiException will be thrown. Note also that custom lookup fields are not supported (as they are not supported by the Zoho API).
The library defines model types for a set of “semi-modules” (in the same fashion as all the standard module models). The “semi-modules” are record types that can be returned ONLY through the related record retrieval methods. The Zoho API will not allow these types of records to be retrieved through the standard GetRecords mechanism – they can only be retrieved for a specific parent record. The “semi-module” types are: Notes, Attachments, PotStageHistory (Potential Stage History items) and ContactRoles (Potential Contact Role items).
GetRecordsRelatedToParent/GetRecordsRelatedToParentAsyncGetRelatedRecords/GetRelatedRecordsAsyncGetRelatedNotes/GetRelatedNotesAsyncGetRelatedAttachments/GetRelatedAttachmentsAsyncGetRelatedActivities/GetRelatedActivitiesAsyncCertain parameters are marked as required. All other parameters are optional.
GetRelatedRecords methods). Required.GetRecordsRelatedToParent methods). Required.CRMGetRecordOptions object allows for specifying ZohoCRMClient-level options on an individual get call basis. When this options parameter is specified, all of the contained options will override the same options set for the ZohoCRMClient object. See the General Get Options section for more detail.The Insert Methods insert new record(s) into a CRM module that are defined by strongly-typed model objects. Multiple records cannot be inserted for the Quotes, SalesOrders, Invoices and PurchaseOrders modules - if called for these modules an exception will be thrown. If one of the multiple records submitted is invalid, an exception will be thrown and none of the records will get inserted (and you don't know which record was bad) – this is a result of the Zoho API design, not the ZohoSharp library.
The AddNote(s) methods are special types of record inserts that function in the same fashion as the standard insert record methods except that the Note must be associated with a specific module record as part of the insert.
Detailed information related to the logic applied when inserting records is supplied in the Post Logic section.
InsertRecord/InsertRecordAsync (single-model inserts)InsertRecords/InsertRecordsAsync (multiple-model inserts)AddNote/AddNoteAsync (single-model inserts)AddNotes/AddNotesAsync (multiple-model inserts)Certain parameters are marked as required. All other parameters are optional.
CRMPostRecordOptions object allows for specifying ZohoCRMClient-level options on an individual insert call basis. When this options parameter is specified, all of the contained options will override the same options set for the ZohoCRMClient object. See the General Post Options section for more detail.The Update Methods update CRM module record(s) that are defined by strongly-typed model objects. If a record being updated has an invalid field, the entire record update doesn't necessarily result in an error and in fact is not reported at all in the response (can submit an invalid date or even an invalid Owner and the Zoho system will simply ignore).
Detailed information related to the logic applied when updating records is supplied in the Post Logic section.
UpdateRecord/UpdateRecordAsync (single-model updates)UpdateRecords/UpdateRecordsAsync (multiple-model updates)WebPrimaryKeyAttribute.CRMPostRecordOptions object allows for specifying ZohoCRMClient-level options on an individual update call basis. When this options parameter is specified, all of the contained options will override the same options set for the ZohoCRMClient object. See the General Post Options section for more detail.The Zoho API response to a post request is modeled with the CRMPostResults object. This object provides success/error messages and indicators as to the presence of errors or other concerns with the individual records. The object contains a collection of CRMRecordPostResult objects that relate to each record that was posted (and they are returned in the same order as the posted records). The CRMRecordPostResult object contains the fields that are returned from the Zoho API (the Id, CreatedTime, ModifiedTime, CreatedBy and ModifiedBy), a result code (if applicable), error messages (both originating from Zoho and potential errors arising from the strongly-typed model handling on the ZohoSharp library end) and duplicate insert results (see the Insert Duplicate Handling section). If the ErrorMessage property is not empty or null, then this indicates that an error was returned by the Zoho API. If any items exist in the ModelErrorMessages property, then this indicates that an error occurred when processing the model subsequent to the API post. The RecordsContainErrors property of the CRMPostResults object indicates if any of the records processed have either type of error just described (either Zoho-orginated or originating from subsequent model processing).
Note that due to a Zoho peculiarity, the CreatedBy and ModifiedBy field values returned with the post results (Last Name of User only) are different than the field values returned with a record fetch (First and Last Name of User).
When inserting records, the DuplicateCheckOption allows specification as to how the Zoho API will handle potential duplicate records already on the system. Zoho defines duplicate check field(s) for each module – these are used to determine whether duplicates exist. The CRMRecordPostResult object has a DuplicateInsertResult property that describes the result of an attempt to insert a record. It takes on the values described under each scenario below. The following options for the DuplicateCheckOption are available:
CRMRecordPostResult object corresponding to the inserted record will have a DuplicateInsertResult of None.CRMRecordPostResult object corresponding to the duplicate record will have a DuplicateInsertResult of Identified (and the CRMPostResults object will have its RecordsContainDuplicateInserts property set to true). If a duplicate is not identified, the new record will be inserted and the DuplicateInsertResult will be None.CRMRecordPostResult object corresponding to the updated record will have a DuplicateInsertResult of Updated (and the CRMPostResults object will have its RecordsContainDuplicateInserts property set to true). If multiple duplicates exist on the Zoho system when the Update option is specified, Zoho selects the record created first for updating.There are a couple special circumstances in which fields are defined on the relationship between two different records from two different modules. The Zoho CRM platform defines a member status PickList field for the Lead or Contact records related to a Campaign record. A product list price field is also defined for Product records related to a Price Book record. Additionally, there are limited instances in which many-to-many relationships exist between module records – a Product record can have multiple Lead, Contact, Account or Potential records associated with it and each of the Lead, Contact, Account and Potential records can have multiple Product relationships.
The default Leads and Contacts model objects define a read-only CampaignMemberStatus property for storing the related record’s member status value. When retrieving records directly (e.g., Leads.GetRecords), the API will, understandably, not return a value for this property. Values for this property will only be returned when retrieving related records (e.g., Campaigns.GetRelatedRecords). Realize, however, that this property could be different for the same Lead record in different contexts, depending on which Campaign is being referenced. The CampaignMemberStatus property is also defined on the default Campaigns model object as the member status will also be returned through the inverse of the relationship (e.g., Leads.GetRelatedRecords). Similarly, the default Product and PriceBook model objects define a ListPrice property.
In the same vein that these relationship field values are not returned with the standard record retrieval methods, they may also not be updated with the standard record update methods. In order to update these field values, the Zoho CRM API provides a special updateRelatedRecords method. The ZohoSharp library defines specialized methods on the applicable client module interfaces. For example, to update a Lead record’s member status as related to a particular Campaign record, the following code could be used:
RelatedRecordUpdateResult result = client.Campaigns.UpdateCampaignMemberStatus("CAMPAIGNID", CampaignMemberType.Leads, "LEADID", CampaignMemberStatusPickListBase.Planned);
The ZohoSharp library also allows updating via the inverse of the above relationship as follows:
RelatedRecordUpdateResult result = client.Leads.UpdateCampaignMemberStatus("LEADID", "CAMPAIGNID", CampaignMemberStatusPickListBase.Planned);
The library also defines methods for updating more than one member status / lead record at a time using a dictionary in which the keys represent the Lead Ids and the values represent the member status values. The library provides comparable methods for the product list price relationship with price books. When submitting multiple record updates, only 100 records may be submitted per call (a Zoho API limitation).
Similar methods for updating the Product relationships are defined. The Lead, Contact, Account and Potential client modules define AssociateProduct(s) methods for establishing a Product relationship. The Product client module defines the inverse AssociateRecord(s)ToProduct methods. These methods work in the same fashion as described above, except there is no relationship field defined.
RelatedRecordUpdateResult result1 = client.Leads.AssociateProduct("LEADID", "PRODUCTID"); RelatedRecordUpdateResult result2 = client.Products.AssociateRecordToProduct("PRODUCTID", CRMModuleBase.Leads, "LEADID");
In the case of the single record related field updates, the methods return a RelatedRecordUpdateResult enum value indicating if the update resulted in the addition of a new relationship or if the existing relationship was simply updated (an exception may also be thrown if the Zoho API returns any form of error response). For the multiple record updates, a dictionary is returned that contains keys representing the related record Ids that were submitted for update and values represented by RelatedRecordUpdateResult enum values indicating the update result for each record.
UpdateCampaignMemberStatus/UpdateCampaignMemberStatusAsyncUpdateProductListPrice/UpdateProductListPriceAsyncUpdatePriceBookListPrice/UpdatePriceBookListPriceAsyncAssociateProduct/AssociateProductAsync (single-model updates)AssociateProducts/AssociateProductsAsync (multiple-model updates)AssociateRecordToProduct/AssociateRecordToProductAsync (single-model updates)AssociateRecordsToProduct/AssociateRecordsToProductAsync (multiple-model updates)The only optional parameter in this method set is the cancellationToken.
CampaignMemberType enum representing either Leads or Contacts.PickList value, an Enum or a string.PickList value, an Enum or a string.AssociateProduct(s) methods).AssociateRecord(s)ToProduct methods).The DeleteRecord methods delete CRM module record(s) defined by specifying strongly-typed model objects or a record id. According to the Zoho API design, the delete method will move the record to the recycle bin - you cannot delete the record permanently from your account. The API also does not provide for a multiple record delete – calling the DeleteRecords method(s) will iterate through the provided models, calling the singular API delete method multiple times. If ISyncableModel models are being used, the delete method overload accepting the id parameter should not be used. The overload accepting the model object should be used so that the model(s) state will be updated to Deleted. If a single model is provided and the Zoho API returns an error response, an exception will be thrown. Otherwise, if an error response is received for one of multiple deletes, the CRMRecordDeleteResult record for that model will reflect the error in its ErrorWasReturned and Message properties. This is to ensure that a problem with one of multiple record deletes does not impact the reporting of the delete status for the remaining records.
The delete methods return a CRMDeleteResults object that provides details of the delete results. This object contains a list of CRMRecordDeleteResult objects providing delete results for each record processed. Each CRMRecordDeleteResult object contains the id of the record for which the delete was attempted, a flag indicating if the delete was confirmed, an error flag and message for errors that may have been returned from the Zoho API and a list of error messages (ModelErrorMessages) indicating one or more issues with the local model processing subsequent to Zoho providing the delete results. The RecordsContainErrors property of the CRMDeleteResults object indicates if there were any problems processing any of the record deletes – either one or more items in the Records list have an ErrorWasReturned property value of true or one or more items have ModelErrorMessages.
DeleteRecord/DeleteRecordAsync (single-model updates)DeleteRecords/DeleteRecordsAsync (multiple-model updates)WebPrimaryKeyAttribute on the model class.WebPrimaryKeyAttribute. Default is null.There are a set of methods that handle the manipulation of files or attachments to module records. Files that are 20MB or less may be uploaded to records in all modules.
The UploadFile methods return a CRMPostResults object – see the CRM Post Results section for detail on this type.
The DownloadFile methods and DownloadPhoto methods return a CRMFileDownloadResult object that holds details related to the file being downloaded. This object contains the name of the file that was requested for download, the content length header (if returned from the Zoho API) and the file content stream that represents the requested file. The content stream is the .NET framework object for exposing a sequence of bytes returned from the API. The CRMFileDownloadResult class implements IDisposable in order to dispose of the content stream correctly – calls to the DownloadFile methods should typically be wrapped in a using statement. Code samples are provided that show how to asynchronously process the content stream in client code.
The DeleteFile methods and the photo processing methods (UploadPhoto, DeletePhoto, DeleteFile) return a CRMActionResult object. This object contains standard success information returned from the Zoho CRM for API action calls that do not return records or post results. It simply contains a Zoho success/failure code and a message originating from the Zoho CRM.
The photo processing methods are only applicable to the Leads and Contacts modules and have a file size limit of 2MB.
UploadFile/UploadFileAsyncDownloadFile/DownloadFileAsyncDeleteFile/DeleteFileAsyncUploadPhoto/UploadPhotoAsyncDownloadPhoto/DownloadPhotoAsyncDeletePhoto/DeletePhotoAsyncUploadFile and photo processing methods and the Id of the attachment representing the file to be downloaded or deleted for the DownloadFile and DeleteFile methods.FileStream object will typically be provided.The GetUsers methods return a list of CRMUser objects representing CRM user accounts. These methods are called from the ZohoCRMClient class as opposed to the ICRMClientModule objects as they do not relate to a particular module. The CRMUser object contains the user’s Id, Name, Email, Role, Profile, Status and an indicator as to whether the user is confirmed.
GetUsersTypeOption enum value for specifying which types of users to return. Options are all users, active users, deactive users, admin users and active confirmed admin users. The default is all users.The ConvertLead methods convert a CRM Lead specified by its Id, given a set of conversion options defined by a CRMLeadConversionOptions object. The CRMLeadConversionOptions object contains a set of fields specifying details of the conversion – whether to create a Potential record, the owner to assign to the new records, and whether to notify the old and new record owners. If a Potential record should be created, an additional set of fields relating to the new Potential record should be specified – the name, the closing date, the stage, a contact role (optional), an amount (optional) and a probability (optional). The ConvertLead methods may only be called for the Leads module.
The methods return a CRMLeadConversionResult object containing the Ids of the resulting records when the lead was successfully converted. It contains an AccountId, a ContactId and a PotentialId (which is only populated when the method requests a Potential record to be created).
CRMLeadConversionOptions object specifying details of the conversion.The GetFields methods retrieve a CRMModuleMetadata object containing the fields defined by a CRM module. These methods do NOT return all fields that will be returned when calling the get record methods - the Zoho system fields, like Ids, are not returned.
The CRMModuleMetadata object represents metadata for a Zoho CRM module. It contains the name of the Zoho CRM module, a descriptive label associated with the module that is only applicable to custom modules (and is not automatically populated by the method as this information is not returned from the Zoho API), a flag indicating if the module is a custom module and the data fields that represent the module. The CRMModuleMetadata object contains a Fields property – this is a dictionary representing all the fields contained in the module. The fields are represented by a FieldMetadata object containing details of the field. The CRMModuleMetadata object also contains a Sections property – this is a dictionary of all the field sections contained in the module. Each section is represented by a CRMModuleSection object, which contains a name, label and list of fields. Each field object contained in a section of the Sections property will also be contained in the Fields property.
The CRMModuleMetadata object also contains two dictionary properties for the purpose of comparing the fields returned from the GetFields methods to the default fields defined by the library. This is useful to know what fields are known to be missing from the data returned by the GetFields methods and to know what fields may be missing from the default fields defined by the library as Zoho makes changes to the CRM system. These dictionaries are only populated when the compareToDefaultFieldMappings parameter is set to true. The MissingDefaultFields property is a dictionary of fields returned by the Zoho CRM GetFields methods, but not defined in the default field mappings. The ExtraDefaultFields property is a list of fields defined in the default field mappings, but not returned by the Zoho CRM GetFields methods.
For the Potentials module, the GetFields methods will actually return an object derived from CRMModuleMetadata, CRMPotentialMetadata, which adds a list of CRMPotentialStage objects that are unique to Potentials.
GetFieldsTypeOption enum value for specifying which types of fields to return. Options are all fields, summary view fields and mandatory fields. The default is all fields.© 2022 Jeff Williamson. All rights reserved. Privacy Policy | Terms of Service