Zoho CRM

Overview

This article explains how to connect your Kompass account to Zoho CRM. Once connected, clients, contacts and projects are kept in step between the two systems, and quote items are published to Zoho as quotes. Only admin users can set up and manage the Zoho connection.

Prerequisites

  • A Zoho CRM account with administrator access to the organisation you wish to connect
  • A dedicated Zoho CRM user for the integration (see the note below)
  • One free field on each of the Accounts, Contacts and Deals modules in Zoho for Kompass to record its own IDs in (see the next section)
  • Admin access to your Kompass account
  • The Zoho permission group on your user. If you do not see a Zoho group in the Admin site, contact Kompass support to have Zoho permissions added to your account.

Create a dedicated Zoho user first. Kompass records which Zoho user made each change and deliberately ignores changes made by the user that authorised the connection, so that its own writes are not read straight back. If you authorise as yourself, your own edits in Zoho will not reach Kompass. Create a user such as Kompass Integration in Zoho, give it access to the records you want synchronised, and authorise as that user.

Before you start: where Kompass records its IDs

Kompass recognises its own records in Zoho by writing the Kompass record ID into a field on the Zoho record. You do not have to create anything for this: by default it uses a standard Zoho field that most businesses leave empty.

  • Accounts: SIC Code
  • Contacts: Skype ID
  • Deals: Next Step

Check those three fields are empty before you connect. Kompass overwrites whatever is in them, and it reads an existing value as one of its own record IDs, which can attach a Zoho record to the wrong Kompass record. If your team uses any of the three, say so before the sync is enabled and a different field will be used instead.

Support confirms this for you during the record linking in Step 4: the comparison it sends back reports how many of your records already hold a value in the field.

If you can create fields in Zoho, that is the tidier option. Create a single line text field (kompass_id, for example) on Accounts, Contacts or Deals, and ask support to point the connection at it. Any records already recorded in the standard field keep working, and move over to the new field on their own.

Whichever field is used, Kompass fills it in and keeps it up to date. Leave it alone: changing or clearing the value breaks the link to the Kompass record, and the two records are then treated as unrelated.

Step 1: Create a Zoho configuration

  1. Navigate to the Admin site by adding /admin after your Kompass URL (e.g. your-server.kompassbms.com/admin).
  2. Under the Zoho group, select Configurations.
  3. Click Add in the top right to create a new configuration.
  4. Select the Kompass organisation(s) that should use this Zoho connection. One connection can serve several organisations.
  5. Set Notification recipients. These addresses receive an email if synchronisation fails.
  6. Click Save. Leave the Enable checkbox unticked for now; you will enable the sync in Step 5 once existing records have been linked.

Step 2: Authorise with Zoho

Sign out of Zoho first, or use a private browser window, so that you sign in as the dedicated integration user and not as yourself.

  1. On the Configurations list page, select the configuration you just created using the tick-box.
  2. From the Action drop-down menu, select Authorise with Zoho and click Go.
  3. You will be redirected to Zoho. Sign in as the integration user.
  4. Review the access Kompass is requesting and click Accept.
  5. You will be redirected back to the Kompass Admin with a success message.

Kompass works out which Zoho data centre your account lives in (zoho.com, zoho.eu, zoho.in and so on) during this step, so there is nothing regional to configure.

Step 3: Test the connection

  1. On the Configurations list page, select the configuration using the tick-box.
  2. From the Action drop-down, select Test connection and click Go.

Kompass reports the name of the Zoho organisation it reached. If the test fails, repeat Step 2.

Step 4: Link your existing records

Stop here if your Zoho CRM already contains accounts or contacts. Enabling the sync at this point will pull every unlinked Zoho account in as a new Kompass client, and push every Kompass client into Zoho as a new account, leaving duplicates on both sides. Link the records that already exist in both systems first.

Contact Kompass support to run the comparison. For each of accounts, contacts and deals, support produces a spreadsheet listing the Zoho record, the Kompass record it most likely matches, and a confidence score.

  1. Review each spreadsheet and confirm the suggested matches. Correct a wrong match by changing the Kompass ID, and clear the Kompass ID to leave a row unmatched.
  2. Return the reviewed files to support, who will upload them to create the links.
  3. Ask for the comparison to be re-run to confirm that only records which genuinely need creating are still unmatched.

Deals carry the same risk: an unlinked deal whose account is linked creates a new project in Kompass. Link the deals for projects you already track in both systems before enabling the sync.

Step 5: Configure the sync and enable it

  1. Open the configuration and select the modules to synchronise under Sync modules:
    • Clients: Kompass clients and Zoho accounts
    • Contacts: Kompass contacts and Zoho contacts
    • Projects: Kompass projects and Zoho deals
    • Quote items: publishes Kompass quote items to Zoho as quotes
  2. If you enable Contacts, enable Clients as well. A Zoho contact can only be brought across once its parent account exists in Kompass. The same applies to Projects: a deal needs both its account and a contact on the resulting client before it can create a project.
  3. Set the Default project category. A project needs a category, so this is used when a deal arrives whose type matches none of yours. Without it, deals that match no category are left in Zoho.
  4. Tick the Enable checkbox.
  5. Click Save.

Synchronisation starts within a couple of minutes.

Step 6: Map your values

Kompass and Zoho rarely use identical wording for categories, statuses and similar fields, so the configuration holds a set of maps. Each map is a list of pairs: the Kompass name on the left, the matching Zoho value on the right.

The maps are entered as JSON, so an entry looks like this:

{
  "Commercial": "Construction",
  "Residential": "Real Estate"
}

An empty map is written as {}.

You only need entries where the two systems disagree. A value with no entry in the map is sent to Zoho exactly as it is named in Kompass. If your Kompass client type is already called Customer and so is the Zoho picklist entry, leave it out of the map.

Finding your Zoho picklist values

Picklists are customisable, so yours may differ from the Zoho defaults. To see the exact entries for a field, in Zoho go to Setup → Customisation → Modules and Fields, open the module (Accounts, Deals), and click the field. Copy the values from there rather than typing them from memory.

The maps

Client category map takes your Kompass client category to the Industry field on the Zoho account.

{
  "Commercial": "Construction",
  "Residential": "Real Estate"
}

Project category map takes your Kompass project category to the Type field on the Zoho deal. This is a separate map from the client one, so the same name can translate differently on each side, and it is also the map that decides the category of a project created from a Zoho deal. A deal whose type matches no entry falls back to the Default project category you set in Step 5.

{
  "Topographic Survey": "Survey",
  "Measured Building Survey": "Building"
}

Type map takes your Kompass client type to Account Type on the Zoho account. The Zoho defaults include Customer, Prospect, Partner, Reseller, Supplier, Vendor, Competitor and Other.

{
  "Client": "Customer",
  "Subcontractor": "Vendor"
}

Source map takes your Kompass project source to Lead Source on the Zoho deal. The Zoho defaults include Advertisement, Cold Call, Employee Referral, External Referral, Partner, Public Relations, Trade Show, Web Download and Web Research.

{
  "Word of mouth": "External Referral",
  "Website enquiry": "Web Research"
}

Stage map takes the Kompass project phase to Stage on the Zoho deal. Unlike the others, the Kompass side of this map is a fixed list you cannot change, and the names are all lower case: created, quoted, accepted, surveyed, processed, checked, delivered, invoiced, received, suspended and abandoned. Because none of these match a Zoho stage, a new configuration arrives with this map already filled in, using the stock Zoho stages shown below. Check it against your own stages and correct any that you have renamed.

{
  "created": "Qualification",
  "quoted": "Proposal/Price Quote",
  "accepted": "Closed Won",
  "surveyed": "Closed Won",
  "processed": "Closed Won",
  "checked": "Closed Won",
  "delivered": "Closed Won",
  "invoiced": "Closed Won",
  "received": "Closed Won",
  "suspended": "Negotiation/Review",
  "abandoned": "Closed Lost"
}

The supplied mapping treats a project as won once it is accepted, which suits most workflows: everything after acceptance is delivery work, and Zoho has no stages for it. Change it to whichever of your own stages match how your sales team reports.

Tax map takes your Kompass VAT rate name to the tax name in Zoho.

{
  "Standard": "VAT 20%",
  "Zero": "VAT 0%"
}

Country map is only needed where Zoho expects a country name that differs from the standard one Kompass sends. The left side is the two-letter country code, not the name.

{
  "GB": "United Kingdom"
}

The Zoho value must match the picklist entry exactly, including capitalisation. A value that does not match is rejected by Zoho or leaves the field blank, and the record is then reconciled again on every check.

The left side of each map is the Kompass name as it is spelt today. If you later rename a category, type, source or VAT rate in Kompass, update the map at the same time, otherwise that value stops being translated and is sent to Zoho under its new name.

What syncs, and in which direction

  • Clients and Zoho accounts. Creation works both ways: a new Kompass client creates the account in Zoho with its current details, and an account created in Zoho creates the client in Kompass. After that Zoho is the master copy: changes made in Zoho update the Kompass client, and later changes in Kompass are not pushed. Maintain client details in Zoho.
  • Contacts and Zoho contacts. The same rule applies, with one condition: a contact created in Zoho only reaches Kompass once its account has been linked. Until then it waits, and comes across on the next check after the account arrives. If the linked client already has a contact with the same email address, Kompass uses that contact rather than creating a duplicate.
  • Projects and Zoho deals. A new Kompass project creates the deal. The project value, category and status stay owned by Kompass and are pushed whenever they change; the descriptive fields on the deal are owned by Zoho, including the closing date, which is held in Kompass as the quote decision date. A deal created in Zoho creates the project in Kompass, provided the deal has an account and that account is linked. A deal with no account is ignored.
  • Quote items and Zoho quotes. One-way, from Kompass to Zoho. Services used on the quote are created in Zoho as products the first time they are needed.

A deal holds less than a Kompass project needs, so the missing details are filled in when the project is created. The client comes from the deal's account, and the address from that client. The category comes from the deal type, or the default category if the type matches none of yours. The quote deadline and requested date are set to the day the project is created, and the requested-by contact is the deal's contact, or the client's first contact if the deal has none. The organisation is the client's own where it belongs to only one, otherwise the connection's where it covers only one, otherwise the deal owner's main organisation.

A deal is left in Zoho, rather than creating a project, if it has no account, if its account is not linked yet, if its type matches no category and no default is set, or if its client has no contacts. Once the missing piece is in place the deal comes across on a later check, or the next time it is edited in Zoho.

Kompass checks Zoho for changes roughly every two minutes, and checks for deletions every fifteen minutes. When your Zoho API credits for the day start to run low it automatically slows down to about five minutes, then returns to the normal rate once credits recover.

Deleting a record in Zoho removes the link only. The Kompass client, contact or project is left in place, and stops synchronising.

Deleting a record in Kompass works the same way round: the link is removed and the Zoho account, contact or deal is left in place.

An account or contact in Zoho that still refers to a Kompass record which no longer exists, because it was deleted or merged into another, is skipped rather than created again. This is deliberate, so that a deletion or merge in Kompass is not undone.

Disconnecting from Zoho

To pause synchronisation without breaking the connection, untick Enable on the configuration and save.

To disconnect completely:

  1. Go to Zoho → Configurations.
  2. Select the configuration using the tick-box.
  3. From the Action drop-down, select Disconnect from Zoho and click Go.

The sync stops immediately and the stored authorisation is revoked. Existing links are kept, so you can re-authorise later by repeating Step 2 without having to match records again.

Troubleshooting

  • Nothing synchronises at all, or the error email mentions a missing or invalid field. This usually means the connection is pointed at a field that does not exist in your Zoho account. Contact support with the error email.
  • A Zoho record has been matched to the wrong Kompass record. Check whether the field Kompass uses for its IDs (SIC Code, Skype ID or Next Step) already held a number before the sync was enabled. Contact support, who can move the connection to a different field.
  • Authorisation fails or times out. The authorisation request is valid for ten minutes. Start again from Step 2 and complete the Zoho sign-in without pausing.
  • You receive a "Zoho CRM" error email. These go to the addresses in Notification recipients. If the message says the connection needs re-authorising, the Zoho token has been revoked or has expired: repeat Step 2.
  • An edit made in Zoho did not reach Kompass. Check who made it. Changes made by the user that authorised the connection are ignored on purpose, which is why the integration should have its own Zoho user.
  • A record keeps updating on its own. This usually means a mapped value does not match the Zoho picklist. Review the maps in Step 6.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us