CRM Functionality Details

The following documentation provides details around the use of the library for specific CRM modules and functions. This is not intended to be exhaustive documentation on all of the Zoho API functionality, but rather provide some clarity around common use cases, issues with the Zoho API and their impact on library functionality.

Common Properties

• The following properties are common to many/most modules and are readonly: CreatedBy, ModifiedBy (though the CreatedById and ModifiedById properties are NOT readonly), CreatedTime, ModifiedTime and LastActivityTime
• The CreatedById and ModifiedById properties can be set independently at any time (insert or update) - if not set, they will default to the user associated with the current api authorization key
• To update a record's owner, either the OwnerId property or the OwnerEmail property should be used - if not set, the owner will default to the user associated with the current api authorization key

Related Record Foreign Keys

• Most one-to-many relationships effectively have a foreign key on the module records on the many side of the relationship (e.g., a Contact has an AccountId property)
• These records usually also have a name property associated with the Id property (e.g., a Contact has an AccountName property)
• This dual referencing of the related record has a number of implications on the way the ZohoSharp library works:
  • If both fields are included on the post request to the Zoho API, the Id field will take precedent (so it won't matter what the name field contains, even if the Id field is empty)
  • This means that if it is desired to specify the relationship using the name field, the Id field should NOT be included on the post request
  • When inserting records, there are 2 factors involved in the ZohoSharp library that should allow the name property to be safely specified on its own
    • First, by default, the library does not post null or empty properties on inserts (PostNullFieldsOnInsert is false)
    • Second, even if PostNullFieldsOnInsert were set to true, as long as the Id properties are marked with the CRMLookupIDAttribute (which the base models take care of), null or empty values will not be posted for inserts
  • When updating records, the automatic exclusion of null or empty fields on the post request is not so simple - what if it is desired to update an existing value to null/empty? The following mechanisms address this issue:
    • To handle this scenario, the library defines a mechanism to specify only those properties that should be included in the post request or properties that should be excluded (properties of CRMPostRecordOptions)
    • The CRMPostRecordOptions also defines a PostNullFields property that allows no null/empty fields to be posted on a single request
    • Finally, if using the Syncable models (and state tracking is not disabled), this issue is automatically solved by the fact that the model tracks which properties have been modified and will only post field values related to the modified properties

Core Modules (Leads, Accounts, Contacts)

• When an Account record is deleted, any Contact records or Potential records related to that Account will be deleted as well
• When an Account record is deleted that has member Accounts associated with it, the member Accounts will NOT be deleted (and in fact, the relationship to the deted parent Account is not removed, referencing a deleted Account)
• When a Contact record is deleted, any Potential records related to that Contact will NOT be deleted - the Potential's Contact will simply be set to null
• A Contact may be related to an Account by specifying either the AccountName property or the AccountId property - however, see the discussion of Related Rerd Foreign Keys for implications when using the ZohoSharp library
• An Account may be assigned as a member Account to a parent Account by specifying either the ParentAccount property or the ParentAccountId property - hover, see the discussion of Related Record Foreign Keys for implications when using the ZohoSharp library
• An Account's member Accounts may not be retrieved using the GetRecordsRelatedToParent or GetRelatedRecords methods (Zoho will return a result, but not the relt you would expect – Zoho will just return the parent Account itself)
• To retrieve an Account's member Accounts, a GetSearchRecords request must be performed, searching on the Parent Account field

Lead Conversion

• Upon Lead conversion, an account with the name of the Lead's Company will get created (existing Accounts with the same name will NOT be recognized - duicate accounts will get created)
• When a Lead is converted, the Contact created will automatically be associated with the Account created (via the Contact's AccountName/AccountId properties)
• When the Lead conversion is instructed to create a Potential, the Potential record created will automatically be associated with both the Contact created the Account created (via the Potential's AccountName/AccountId and ContactName/ContactId properties)
• When a Lead is converted and a Potential created, the Potential will automatically receive a single Contact Role record - if the CRMLeadConversionOptions.actRole property is specified, the Contact Role record will receive this role, otherwise the role name will be blank
• When a Lead is converted and a Potential created (by specifying the CRMLeadConversionOptions.CreatePotential = true), the CRMLeadConversionOptions' PotentialName, ClosingDate and Stage properties must be specified

Potentials

• If a new Potential record is inserted directly, when a Contact is associated with the Potential (via the ContactName or ContactId properties), either at the im of the initial insert or on a subsequent update, a Contact Role record will be created, but there is NO way to set the role name
• The Potential contact role records can be retrieved, but they can NOT be added, modified or deleted via the API
• When a Potential record is created, the first stage history item is automatically created
• When a Potential record is updated and any one or more of the following properties are modified, a new stage history item will be automatically created: Stae, robability, ClosingDate or Amount
• The Potential stage history records can be retrieved, but not directly manipulated
• When a new Potential is inserted directly, the record may be created without specifying an Account, but this is not recommended as the UI will enforce an ccunt relationship upon editing
• When a new Potential is inserted directly, the PotentialName, the Account (through either AccountName or AccountId), the ClosingDate and the Stage should be peified
• A Potential may be related to an Account by specifying either the AccountName property or the AccountId property and may be related to a Contact by specifying either the ContactName property or ContactId property - however, see the discussion of Related Record Foreign Keys for implications when using the ZohoSharp library

Campaigns

• Setting the Campaign Source (by setting the CampaignSourceId) for a Lead or Contact does not do anything
• Leads and Contacts can have multiple Campaigns associated with them (and existing Campaign associations can have their status updated)
• The API will NOT allow Campaigns to be disassociated with Leads or Contacts
• When a Lead is converted, one or more Campaigns are automatically associated with the new Contact
• The Potential's Campaign Source will NOT be populated upon Lead conversion even if the Lead has a single Campaign associated with it
• A Potential's Campaign Source field may be updated directly by setting the CampaignSource or CampaignSourceId field - however, see the discussion of Related Rerd Foreign Keys for implications when using the ZohoSharp library
• When a Campaign is deleted, no related records (Leads or Contacts) are deleted; when related Leads or Contacts are deleted, the Campaign(s) will not be deleted either

Notes

• Notes can be attached to any module record by calling the AddNote(s) methods
• Notes can be updated by calling the regular UpdateRecord(s) methods
• Notes can be deleted by calling the regular DeleteRecord(s) methods
• Only the Title and Content fields can be populated on insert or update (others, except those noted below, can be populated, but won't stick)
• The Owner, CreatedBy and ModifiedBy fields for Notes can be set on insert or update, though it's only the ModifiedBy field that shows in the Zoho UI - these fields can only be set by using the user Id and setting the OwnerId, CreatedById anModifiedById fields (using the user name or email will not do anything)
• Metadata / GetFields cannot be called for Notes records
• When Leads with Notes are converted, the Notes will automatically be transferred to the new Contact records
• Note records can be retrieved by calling the GetRecord methods and specifying the Note's Id or by using the search methods
• However, when a note is retrieved (by Id or a search), there does NOT appear to be any way to get the module record to which the note is attached

Activities (Tasks, Calls, Events)

• When inserting an Activity (Task, Call or Event), only the ContactId property should be used to relate the Activity to a Contact; for relating the Activity to all other modules (solely or in addition to a Contact), the RelateToId and RelatedToModule properties should be used
• An Activity should not be related to both a Contact and a Lead
• When relating an Activity to a Contact, the Activity may also be related to another module record (typically one with a Contact relationship)
  • If another module record relationship is not specified (via the RelateToId and RelatedToModule properties) and the specified Contact is related to an Account, then the Activity will show under both the Contact record and the Contact's Account record; however, under the Activity detail, the Account relationship will not be listed
  • If the specified Contact is not related to an Account, but is related to another module record (like Product or Vendor), the Activity will not automatically show within the related module record (like it does with Accounts) - the relationship must be specified explicitly
  • If the specified Contact is related to an Account and it's not desired to have the Activity related to another module record, it's best to explicitly relate the Activity to the Account
• Activities should not be reassigned through an update (Zoho seems to handle this inconsistently) - better to delete the Activity and establish a new one
• The ContactName and RelatedToName properties of Activity models are read-only and should not be used to establish a relationship
• The ContactId, RelatedToId and RelatedToModule properties of Activity models should never be submitted to Zoho with null values - the library explicitly protects against this
• When a Lead with related Activities is converted, the Activity records are automatically associated with the new Contact and Account
• When a Contact with related Activities is deleted, ALL of the related Activities are deleted as well - even if an Activity is also related to another module record that has not been deleted
• When any module record with related Activities is deleted, ALL of the related Activities are deleted as well - even if an Activity is also related to a Contact record that has not been deleted

Products

• One or more existing Product records can be associated with existing Lead, Contact, Account or Potential records (and vice versa) - however, the Zoho API does NOT expose a mechanism to remove these associations like the UI does
• When converting a Lead with associated Products, if a Potential is not created during the conversion, the Products will automatically be associated with the new Contact; if a new Potential is created, the Products will automatically be asciated with the new Potential and NOT the new Contact
• Products will not be deleted as a result of deleting any records with product relationships

Vendors

• The VendorName (along with the VendorId) property of a Contact or Product may be used to associate the Contact/Product with a Vendor - however, see the discussion of Related Record Foreign Keys for implications when using the ZohoSharp liary
• Deleting a Vendor will not cause any related Products or Contacts to be deleted

Cases and Solutions

• A Case may be related to an Account, Contact, Potential and Product - none of these relationships are required and none of them have to be related to each other; adding any single relationship will not automatically add any other relationship
• Any of the above relationships can be added by specifying either the name property or the id property - however, see the discussion of Related Record Foreign Keys for implications when using the ZohoSharp library
• Comments effectively CANNOT be added to a Case record via the API:
  • specifying a value for the AddComments property will successfully populate the Add Comment field - however, it will not populate the Comments list like the CRM UI does
  • adding a comment to the Comments property is ignored by the API, thus this property is marked as read-only
• When an Account, Potential or Product record that is related to a Case is deleted, the Case will be deleted as well (however, deleting a related Contact will not trigger the Case delete)
• A Solution may be related to a Product (though not required) - the relationship can be added by specifying either the ProductName property or the ProductId property - however, see the discussion of Related Record Foreign Keys for implications when using the ZohoSharp library
• Comments effectively CANNOT be added to a Solution record via the API (for the same reasons as described for Case records)
• WARNING: There appears to be a Zoho bug that does not populate the comments list for Solution records
• When a Product record that is related to a Solution is deleted, the Solution will be deleted as well

Price Books

• Price Book records can be manipulated through the API, BUT the pricing details cannot be returned or defined through the API
• A Price Book can be related to multiple Products and a Product can have multiple Price Book associations - this relationship defines a list price field
• The API will allow new Price Book Product relationships to be defined and the Product list price can be updated for existing relationships
• The API will NOT allow Price Books to be disassociated from Products
• Deleting a Product that is associated with a Price Book will not delete the Price Book record

Accounting Modules (Quotes, Sales Orders, Invoices, Purchase Orders)

• Quotes, Sales Orders, Invoices or Purchase Orders should be created with the Subject property populated, an Account (or Vendor for Purchase Orders) relationship established and product detail line items specified through the ProductDetails property (the Account relationship can be added by specifying either the AccountName property or the AccountId property - however, see the discussion of Related Record Foreign Keys for implications when using the ZohoSharp library)
• A Quote or Sales Order may be related to a Potential and/or a Contact (though not required) - these relationships can be added by specifying either the name properties or the id properties - however, see the discussion of Related Record Foreign Keys for implications when using the ZohoSharp library
• An Invoice or Purchase Order may be related to a Contact (though not required) - these relationships can be added by specifying either the name properties or the id properties - however, see the discussion of Related Record Foreign Keys for implications when using the ZohoSharp library
• The ProductDetails property is a list of CRMProductLineItem objects - this class calculates the calculated properties by default as the Zoho API will NOT calculate these values on the server side
• When submitting CRMProductLineItem objects for a Quote/Sales Order/Invoice/Purchase Order's ProductDetails property, the ProductId must be present (the ProductName, QuantityInStock and UnitPrice properties are read-only and will never be sent to the Zoho API on inserts or updates)
• Once added to Zoho, the product detail line items CANNOT be removed via the API (submitting a null/empty value for the Product Details field will not accomplish anything)
• This is important to recognize when manipulating the local list of CRMProductLineItem objects - specifying different items and updating to Zoho will only get the local object out of sync with the Zoho records
• This also implies that using multiple line items referring to the same Product is dangerous - Zoho will allow an insert, but updating the product detail line items will be impossible
• The Zoho API also does not calculate the Quote/Sales Order/Invoice/Purchase Order Sub Total and Grand Total fields - so these properties must be calculated before inserting or updating to Zoho (the Quote/Sales Order/Invoice/Purchase Order classes provide a Calculate method, but IT MUST BE CALLED MANUALLY - the class will not automatically update the calculated property values when precedent property values are changed)
• When using ISyncableModel versions (QuoteSyncableBase, SalesOrderSyncableBase, InvoiceSyncableBase or PurchaseOrderSyncableBase), the model state will NOT be automatically updated when the ProductDetails List of CRMProductLineItems is manipulated (list items added, removed or updated)
• The CRM API cannot be used to convert a Quote into a Sales Order or an Invoice, or a Sales Order into an Invoice like can be done through the UI (in which the new record automatically establishes a relationship to the record from which it was converted) - however, no functionality is lost by establishing the new record and its fields manually
• A Sales Order may be related to a single Quote record (through QuoteId or QuoteName) and an Invoice may be related to a single Sales Order record (through SalesOrderId or SalesOrderName) - however, see the discussion of Related Record Foreign Keys for implications when using the ZohoSharp library
• A Product record cannot be deleted when it is associated with a Quote, Sales Order, Invoice or Purchase Order in the product details section
• Deleting an Account that is related to one or more Quotes, Sales Orders or Invoices will delete the Quote/Sales Order/Invoice record(s) as well
• Deleting a Vendor that is related to one or more Purchase Orders will NOT delete the Purchase Order record(s)
• Deleting a Contact or Potential record that is related to a Quote, Sales Order, Invoice or Purchase Order, will not delete the Quote/Sales Order/Invoice/Purchase Order - the reference will simply be removed