One of the biggest advantages of an open-source CRM like vTiger is that you can make it fit your business exactly. You can add fields, build new modules, automate processes and connect other systems. But there is a catch: customisations done the wrong way make every future upgrade painful, and sometimes impossible.
We regularly take over vTiger installations where years of changes were made directly in the core files. Upgrading them means finding and rewriting every change by hand. This guide explains how to customise vTiger so your changes survive upgrades — and which tool to reach for first.
The golden rule: don’t edit core files
Almost every upgrade problem comes from editing vTiger’s own files: changing a template here, adding a few lines to a module’s PHP code there. It works today, but the next upgrade overwrites those files, and the changes are silently lost — or worse, half lost.
Instead, use the layers vTiger provides for customisation, roughly in this order:
- Configuration through the settings screens
- Workflows for automation
- Custom modules and extensions built with vtlib
- Event handlers and the web services API for code that must react to data
Only when none of these can do the job should core code be touched — and then the change must be documented, kept as a patch in version control and re-applied deliberately on every upgrade.
Level 1: Configure before you code
A surprising amount of customisation needs no code at all. From vTiger’s settings you can:
- Add custom fields to any module, including picklists, dates, currencies and checkboxes.
- Rearrange the layout with the layout editor, grouping fields into blocks and hiding the ones you don’t use.
- Edit picklist values such as lead sources, sales stages and industries.
- Set up roles, profiles and sharing rules so each team sees only what it should.
- Design templates for emails, quotes and invoices.
All of this is stored in the database, not in the code, so it is carried through upgrades automatically. Always check whether a requirement can be met here first.
Level 2: Automate with workflows
vTiger’s workflows can react when a record is created or changed, or run on a schedule. They can update fields, send emails, create tasks and events, and more. Typical examples:
- When a lead’s status changes to “Qualified”, create a follow-up task for its owner.
- When an opportunity is marked “Closed Won”, email the operations team.
- Every morning, flag support tickets that have been open for more than three days.
Scheduled workflows rely on the CRM’s scheduler, which needs a server cron job. If scheduled automations never seem to run, the cron job is the first thing to check.
Level 3: Custom modules with vtlib
When you need a completely new kind of record — say, “Property”, “Vehicle” or “Training Batch” — build it as a custom module using vtlib, vTiger’s library for creating and packaging modules.
A properly built module:
- Lives in its own folder, separate from vTiger’s core modules.
- Registers its fields, blocks, related lists and permissions through vtlib.
- Can be packaged, installed on a test system first, and updated as a unit.
- Works with vTiger’s standard features — lists, filters, workflows, reports and the API — without extra effort.
This is the right home for most business-specific logic. It keeps your changes together, testable and upgrade-safe.
Level 4: Event handlers and the API
Sometimes code must run when data changes — to calculate a value, validate a record, or send it to another system. vTiger’s event handlers let you hook into actions such as saving a record, without editing the module that saves it. Register the handler from your own custom module, and the logic stays outside the core code.
For integrations with other systems — your website, accounting software or a mobile app — use vTiger’s web services API rather than writing directly to the database. The API respects permissions, required fields and workflows, so data entered through an integration behaves exactly like data entered by a user.
Keeping customisations under control
- Use version control. Keep your custom modules, templates and any unavoidable patches in Git, so you always know what has changed.
- Keep a change log. A simple document listing each customisation, why it exists and where it lives saves hours during upgrades and handovers.
- Test on a copy first. Build and test changes on a staging copy with realistic data, never directly on the live CRM.
- Review before you add. Every customisation is something to maintain. Check that a field or module will really be used before building it.
Planning an upgrade
When customisations follow these rules, upgrades become routine:
- Take a full backup of files and database.
- Restore it to a staging server.
- Run the upgrade on staging and test every custom module, workflow and integration.
- Re-apply any documented core patches if they are still needed — often the new version makes them unnecessary.
- Schedule a short maintenance window and repeat on the live system.
If your vTiger installation has years of undocumented changes in its core files, an upgrade is still possible. It starts with an audit that finds every modification and moves it into the right layer. We do this regularly for clients, and we build new custom modules and integrations the upgrade-safe way from the start.
