Getting Started

Setup

The ZohoSharp library is implemented as a Portable Class Library, enabling a single binary that runs on several (.NET) platforms. There are two versions of the ZohoSharp binary – one targeting .NET 4.0 (ZohoSharpNET40.dll) and another targeting .NET 4.5 (ZohoSharp.dll). There are some instances in which the core library should call platform-specific .NET framework APIs. ZohoSharp provides platform-specific, Enlightenment assemblies for this purpose. Simply reference the ZohoSharp core assembly and whichever Enlightenment assembly is applicable to your project. There are also a number of library dependencies that must also be referenced by client projects – the following NuGet packages should be installed:

• Microsoft.Bcl (v1.1.3+)
• Microsoft.Bcl.Build (v1.1.10+)
• Microsoft.Bcl.Async (v1.0.16)
• Microsoft.Net.Http (v2.2.15+)
• Newtonsoft.Json (v5.0.8+)

ZohoSharp NuGet packages will be available soon that will simplify the project setup.

Data Model Preferences

If you will be using strongly-typed objects to interact with the ZohoSharp library, you have three main options: use POCO models, use the syncable model implementation provided by the ZohoSharp library or use your own custom models. If using POCO models or the syncable models and you do not need to incorporate any customizations made to your Zoho CRM, then no model setup work is required – you can use the base classes provided by the library (e.g., AccountBase or AccountSyncableBase). To handle customizations made to the Zoho CRM, the appropriate base classes can simply be extended to incorporate your additions. See the Creating Strongly-Typed Models section for details on this subject.

SAMPLE CODE: POCO MODEL CUSTOMIZATION

[DataContract(IsReference = true)]
public class Lead : LeadBase
{
    public Lead() : base()
    {
        this.CustomPickListProperty = PickList.None;
    }
 
    [DataMember]
    public virtual int CustomIntProperty { get; set; }
    [DataMember]
    public virtual PickList CustomPickListProperty { get; set; }
 
}

Establish Field Mappings

If you are using just the base models provided by the library, no work here is required. If you have extended any of these classes or are using your own model classes, field mappings must be established. See the Field Mappings section for further detail.

SAMPLE CODE: CUSTOM FIELD MAPPINGS

public class CRMFieldMappings : CRMFieldMappingsBase
{
    public CRMFieldMappings()
        : base()
    {
        _customFieldMappings = new Dictionary<string, Dictionary<string, string>>();
        _customFieldMappings.Add(CRMModuleBase.Leads, GenerateLeadFieldMappings());
    }
 
    private Dictionary<string, Dictionary<string, string>> _customFieldMappings;
    public override Dictionary<string, Dictionary<string, string>> CustomMappings()
    {
        return _customFieldMappings;
    }
 
    private Dictionary<string, string> GenerateLeadFieldMappings()
    {
        //Add("<Zoho Field Name>", "<Lead Object Property Name>")
        Dictionary<string, string> fieldMappings = new Dictionary<string, string>()
        {
            { "Custom Int Property", "CustomIntProperty" },
            { "Custom PickList Property", "CustomPickListProperty" }
        };
        return fieldMappings;
    }
}

Establish a Model Factory

The library uses the syncable models by default – so if this is your choice, no work here is required either. Otherwise, a model factory class should be created that extends CRMModelFactoryBase and overrides the CreateModel method. This will simply tell the library what type of objects to create when returning model data from the Zoho CRM API. See the Model Factory section for further detail.

SAMPLE CODE: CUSTOM MODEL FACTORY

public class CRMModelFactory : CRMModelFactoryBase
{
    public override object CreateModel(string moduleName)
    {
        switch (moduleName)
        {
            case CRMModuleBase.Leads:
                return new Lead();
            default:
                return base.CreateModel(moduleName);
        }
    }
}

Establish a ZohoCRMClient Instance

All of the interaction with the Zoho CRM API via the ZohoSharp library takes place through an instance of the ZohoCRMClient class. Simply create an instance using the appropriate constructor overload if custom field mappings and/or a custom model factory were established. The ZohoCRMClient must be provided the Zoho CRM API authorization token and can optionally be setup with a number of other options. See the detailed implementation guide for a discussion of these options.

SAMPLE CODE: CLIENT SETUP

ZohoCRMClient client = new ZohoCRMClient("YOURAUTHTOKEN", new CRMModelFactory(), new CRMFieldMappings());
client.DefaultModelTypesToGenerate = ModelType.POCO;

Start Interacting

Now you are free to focus on your business logic that involves interaction with the Zoho CRM without much concern for the API implementation details. All of the API methods available are accessible via built-in module properties or through the Module method. For example, to return a list of the top 50 Lead objects, you would simply use:

SAMPLE CODE: LOAD LEAD RECORDS

List<Lead> leads = client.Leads.GetRecords(1, 50).Cast<Lead>().ToList();

The same list could be retrieved using the generic Module method as follows:

SAMPLE CODE: LOAD LEAD RECORDS

List<Lead> leads = client.Module(CRMModuleBase.Leads).GetRecords(1, 50).Cast<Lead>().ToList();

However, the Modules method allows you to specify any custom modules that you may have setup in your CRM implementation.

All of the methods available for interacting with the CRM API are documented in the Interacting with the Zoho CRM section. There are standard and asynchronous (with Async appended to the method name) methods defined for each action.