ShelfMerch for Zoho People — Administrator Guide
Security, permissions, mapping, and operational guidance for company administrators.
1. Administrator responsibilities
Only connect Zoho People if you have lawful authority to process employee data for your organisation. You are responsible for accurate data, role assignment in ShelfMerch, and complying with applicable employment and privacy laws. See also the Terms of Service and Privacy Policy.
2. Installation
Install ShelfMerch for Zoho People through Zoho Marketplace or your organisation’s approved extension installation process. After installation, open the ShelfMerch Web Tab in Zoho People to sign in and connect.
3. Required permissions
ShelfMerch currently requests these Zoho People OAuth scopes:
- ZOHOPEOPLE.forms.READ — read Zoho People employee form / record data needed for sync
- ZOHOPEOPLE.organization.READ — read organisation information to verify the connection
No additional Zoho scopes are requested by the current integration.
4. OAuth and security
- Zoho OAuth access and refresh tokens are encrypted at rest
- Tokens are stored server-side in your ShelfMerch tenant record
- Tokens are not exposed to browser JavaScript through public status APIs
- OAuth state validation protects the authorization flow
- Access is separated by ShelfMerch tenant / company
- Embedded Zoho sessions are restricted to integration-related actions
5. Connecting an organisation
- Sign in to ShelfMerch as a company administrator.
- Open Connect Zoho People from the Web Tab or integrations experience.
- Complete Zoho OAuth consent for the scopes above.
- Confirm Connected status, organisation name or ID, and that Sync Employees is available.
6. Employee mapping
Current field mapping from Zoho People into ShelfMerch contacts:
| Zoho People (aliases read) | ShelfMerch contact field |
|---|---|
| Zoho record ID (Zoho_ID / recordId / …) | zohoRecordId |
| Employee ID | employeeCode |
| First name / last name / display name | firstName, lastName, name |
| Work email | |
| Department | department |
| Designation / job title | designation |
| Work location | workLocation |
| Date of joining | dateOfJoining |
| Employment status | employmentStatus |
- Missing fields: optional fields may be stored empty; sync continues when required identifiers exist.
- Skipped records: missing Zoho record ID, missing employee ID and email, invalid email, unsupported record shape, duplicates in the Zoho response, or database validation failures.
- Updates: matched primarily by tenant + Zoho record ID; email can help merge when appropriate.
- Phone: not imported from Zoho by the current sync.
7. Running synchronization
Manual sync returns a summary such as:
- totalFetched — employee records retrieved from Zoho
- created — new ShelfMerch contacts created
- updated — existing contacts updated
- skipped — records not imported (see skippedByReason)
- failed — records that failed during save
- skippedByReason — counts grouped by skip reason
8. Tenant isolation
Each ShelfMerch organisation has its own Zoho connection and contacts. One ShelfMerch organisation cannot access another organisation’s Zoho tokens or employee records.
9. Data retention and deletion
- Disconnecting stops future synchronisation and clears Zoho tokens for that tenant.
- Imported records may remain until deleted per your instructions and ShelfMerch retention practices.
- Send deletion or access requests to support@shelfmerch.com.
- Identity and authority may need verification before organisation or employee-data requests are processed.
10. Troubleshooting
- OAuth redirect errors — retry Connect; ensure the Marketplace app / redirect configuration matches the installed ShelfMerch app.
- Reconnect required — complete OAuth again after token refresh failures.
- Missing Zoho People organisation — confirm the Zoho account can read organisation data; reconnect if needed.
- Insufficient permissions — approve both forms and organisation read scopes.
- Employee endpoint errors — temporary Zoho API issues; retry later.
- No employees returned — verify form data and that records include identifiers ShelfMerch can map.
- Popup blocked — allow popups for ShelfMerch.
- Sync timeout — retry; for large directories contact support with timing details.
11. Support checklist
When contacting support@shelfmerch.com, include:
- ShelfMerch organisation name
- Approximate error time
- Screenshot of the safe on-screen error message
- Request ID, when shown