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. Everything Kompass writes to Zoho is recorded against the user that authorised the connection. With a user such as Kompass Integration, Zoho's history shows clearly which changes came from Kompass, and the connection does not stop working when a member of staff leaves. Give the user 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

Navigate to the Admin site by adding /admin after your Kompass URL (e.g. your-server.kompassbms.com/admin).
Under the Zoho group, select Configurations.
Click Add in the top right to create a new configuration.
Select the Kompass organisation(s) that should use this Zoho connection. One connection can serve several organisations.
Set Notification recipients. These addresses receive an email if synchronisation fails.
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.

On the Configurations list page, select the configuration you just created using the tick-box.
From the Action drop-down menu, select Authorise with Zoho and click Go.
You will be redirected to Zoho. Sign in as the integration user.
Review the access Kompass is requesting and click Accept.
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

On the Configurations list page, select the configuration using the tick-box.
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.

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.
Return the reviewed files to support, who will upload them to create the links.
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

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
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.
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.
Tick the Enable checkbox.
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"
}

If your Zoho accounts or deals keep the category in a field of your own rather than Industry or Type, the same maps apply to that field. See Other Zoho fields below.

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.

Field mappings: who manages each field

Every field that synchronises is listed under Zoho → Field mappings in the Admin site, one row per Zoho field, and each row has a Direction:

Direction	What it means
Kompass to Zoho	Kompass manages the field. It is sent to Zoho when the record is created and whenever it changes in Kompass. If someone changes it in Zoho, Kompass puts its own value back a couple of minutes later.
Zoho to Kompass	Zoho manages the field. Kompass fills it in when it creates the Zoho record, and from then on takes every change made in Zoho. A change made in Kompass is not sent to Zoho, and is overwritten by the next change made in Zoho.
Both ways (latest edit wins)	Either side may change the field, and the change is copied to the other. If the field is changed on both sides between checks, the later change is kept.
Not synced	The field is left alone on both sides.

The direction only decides which values move. Records are always created on both sides as described in What syncs, whatever the directions say.

The standard fields and their starting direction

When you enable a module, Kompass adds a row for each standard field it synchronises. These rows cannot be deleted. Most can be switched to a different direction; the ones marked fixed only work one way, and the reason is shown on the row.

Kompass field	Zoho field	Starting direction
Clients and accounts
Name	Account Name	Zoho to Kompass
Phone, website	Phone, Website	Zoho to Kompass
Address	Billing Street, City, State, Code and Country	Zoho to Kompass
Notes	Description	Zoho to Kompass
Category, type	Industry, Account Type	Zoho to Kompass
Manager	Account Owner	Zoho to Kompass
Parent client	Parent Account	Zoho to Kompass
Contacts
First name, last name, email	First Name, Last Name, Email	Zoho to Kompass
Office phone, mobile	Phone, Mobile	Zoho to Kompass
Position, title	Title, Salutation	Zoho to Kompass
Source	Lead Source	Zoho to Kompass
Address	Mailing Street, City, State, Zip and Country	Zoho to Kompass
Notes	Description	Zoho to Kompass
Client	Account Name	Kompass to Zoho, when the contact is created (fixed)
Projects and deals
Name, details	Deal Name, Description	Zoho to Kompass
Source	Lead Source	Zoho to Kompass
Quote decision date	Closing Date	Zoho to Kompass
Requested by, managed by	Contact Name, Deal Owner	Zoho to Kompass
Category	Type	Kompass to Zoho (can be Both ways, never Zoho to Kompass, as the category drives quoting)
Quoted price	Amount	Kompass to Zoho (fixed: calculated from the quote items)
Phase	Stage	Kompass to Zoho, when the phase changes (fixed)
Probability	Probability	Zoho to Kompass (fixed: Zoho recalculates it whenever the stage changes)
Client	Account Name	Kompass to Zoho, when the deal is created (fixed)
Quotes and products
Every field	Every field	Kompass to Zoho (fixed)

The field that holds the Kompass ID on each module is also listed, and is always Kompass to Zoho. Account Name, Last Name, Deal Name and Stage cannot be set to Not synced, because Zoho will not create a record without them.

Changing a direction

Go to Zoho → Field mappings.
Open a row and change its Direction, or tick several rows and choose Set direction from the Action drop-down to change them together. Rows that cannot take the chosen direction are skipped and listed.
Save.

The new direction applies from the next change on either side. The first time a record is checked after the change, Kompass compares the two values: for a field managed by Zoho, a value in Zoho is taken into Kompass; for a field managed by Kompass, Zoho is set to the Kompass value.

If you switch fields to Kompass to Zoho and want Zoho corrected straight away rather than record by record, tick those rows and run Push Kompass values now. Kompass sends its values for every linked record that differs, in batches of 100. Fields of one module can be pushed together.

Stop people editing a field on the side that does not own it

A field managed by one side can still be edited on the other, and that edit is then undone or never arrives. To avoid the confusion, make each field read-only where it is not managed:

Fields set to Kompass to Zoho: make them read-only in Zoho, using layout rules or the field permissions on your Zoho profiles. Otherwise sales staff see their edits changed back a couple of minutes later.
Fields set to Zoho to Kompass: make them read-only in Kompass. On the Configurations list, tick the Zoho configuration and run Make Zoho-managed fields read-only in Kompass. Kompass adds a rule for each of these fields to the field permissions of every organisation on the connection, so the field can no longer be changed on an existing client, contact or project. New records can still be created with the field filled in.

Run the action again after changing directions: it removes the rules it added for fields that are no longer managed by Zoho, and the configuration page shows a warning while the rules are out of step. It never changes a rule you wrote yourself.

You can also write these rules by hand. They live in the Field settings of the Clients, Contacts or Projects configuration in the Admin site. For example, this rule stops everyone changing a client's phone number:

{
  "rules": [
    {
      "resource": "Client.phone",
      "action": "write",
      "subject_groups": "*",
      "effect": "deny"
    }
  ]
}

See Field permissions for how these rules work.

Other Zoho fields

Fields beyond the standard ones, including fields you created in Zoho, are added with the Import custom fields from Zoho or Import all writable fields from Zoho actions on the configuration. They arrive as Not synced; open the ones you want and choose how each is filled:

Template: a value built from the Kompass record, for example {{ project.reference }} or a gross margin. Templated fields are sent from Kompass to Zoho only, and are never read back.
Kompass field: link the Zoho field to a Kompass field from the list, for example a client's inactive date or a project's category. A linked field can use any direction its Kompass field allows, and Kompass checks on saving that values survive the round trip.

To keep a value such as the client or project category in your own Zoho field instead of Industry or Type, first set the standard row to Not synced, then link your field to the Kompass category. Each Kompass field can be linked to one field per connection.

What syncs, and in which direction

Clients and Zoho accounts. 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, each field follows its direction under Field mappings. With the starting directions Zoho manages client details, so maintain them 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. With the starting directions, the quoted price, category and stage are managed by Kompass and the descriptive fields 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 from your own category field, if you use one), 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:

Go to Zoho → Configurations.
Select the configuration using the tick-box.
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 the field's direction under Zoho → Field mappings. Only fields set to Zoho to Kompass or Both ways are taken from Zoho.
An edit made in Zoho was changed back. The field is set to Kompass to Zoho, so Kompass restores its own value. Change the value in Kompass instead, or change the field's direction. If something in Zoho, such as a workflow, keeps changing the field, Kompass stops restoring it after three times in a day and emails the notification recipients.
An edit made in Kompass was overwritten. The field is set to Zoho to Kompass, so the next change in Zoho replaces it. Make the change in Zoho, or make the field read-only in Kompass as described under Field mappings.
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.