Discovery

Sloose has no built-in idea of what a Zoho org contains. Discovery is how it finds out: it reads every module and every field and keeps a snapshot.

Until it has run, there is nothing to curate and nothing to map.

It usually happens without you asking

The first administrator to sign in gets a discovered org. Signing in with Zoho already grants read access to module and field metadata, and Sloose uses that token on the way through — so an org is set up by somebody signing in, not by granting anything further.

The token is used once and discarded. Nothing is stored, and a failure here is not fatal: the setup screen still offers to connect and discover by hand.

Connecting, and what it is actually for

Connecting is a separate, stronger grant: offline access, so the server can read your CRM when nobody is present.

That is what it is for — unattended re-discovery, and the scheduled runs that are coming — and it is deliberately not required to import a file. Asking for standing access to a CRM in order to load one spreadsheet was the wrong bargain.

Only an administrator can connect, and only with the same Zoho user they are signed in as. The refresh token is encrypted at rest and never leaves our server.

Running it again

Org settings → Connectors shows the last run — when, how many modules and fields, how many active users — and offers to run it again.

On a connected org that runs server-side. Otherwise it signs you in again and re-reads on the way back, which needs no further grant. Either way it walks every module the API exposes and reads its fields.

Two kinds of module are skipped, because you could not import into them anyway:

• Modules the Zoho API does not support.
• Linking and web-tab modules, which are structure rather than records.

If a single module’s fields cannot be read, that module is recorded as an error and discovery continues. One inaccessible module does not cost you the other forty.

Reading the diff

After a re-run you get a diff against the previous snapshot: modules and fields added, changed or gone.

This is worth actually reading. A field that changed type, or a picklist that gained options, is the kind of thing that turns a working monthly import into a run full of validation errors — and the diff is where you see it before that happens rather than after.

Removed fields are flagged, not deleted

When the CRM stops returning a field, Sloose marks it as removed and keeps it.

That is deliberate. A project saved six months ago may map that field, and a project referring to something that has silently vanished cannot explain itself. Flagged, it can: the field is still there, marked as gone, and the mapping tells you why nothing is being written.

Removed fields are hidden from mapping by default; ?all=1 on GET /orgs/{org}/config/fields/{module} includes them.

What survives a re-run

Everything you have curated:

• Which modules are enabled, their order, their keys and singular names.
• Match defaults and unique fields.
• Field annotations.
• Excluded fields.

Discovery updates what the CRM says. It does not touch what you have said about it. The two are kept separately for exactly this reason.

How often

There is no schedule; you run it when the CRM changes.

In practice that means: after adding a custom field you intend to import into, after a layout change, and before the first run of a monthly import if somebody has been editing the CRM in the meantime. It is cheap and it is safe to run again.

Active CRM user count is recorded at the same time, which is what plan bands are measured against — see Plans and limits.

When a field you expect is missing

In order of likelihood:

1. Discovery has not run since the field was added. Run it again.
2. The field is excluded for this org, or on this module. See Curating modules.
3. The field is one the import authors itself — record ids and the links Sloose writes between modules are never offered for mapping.
4. The module’s fields failed to read during the last run. The run’s error list says so.