How to Create Custom CRM Modules with Module Builder (CRM)

1. Overview

Module Builder lets a CRM administrator create brand-new modules directly from the Settings UI. Each module behaves like any standard vTiger module: it gets its own menu entry, list view, detail view, edit view, related panels, list filters, sharing rules, workflows, and REST API endpoints.

The entire definition — blocks, fields, relationships, sidebar icon, record numbering — is stored in the database. No PHP files are written for each module, and no developer involvement is required to add or remove a module from a tenant instance.

Key capabilities:

4-step guided wizard for creating a new module.
23 supported field types across Basic, Date/Time, Contact, Picklist, Boolean, Relation, Slider, and File categories.
Custom blocks with drag-to-reorder fields.
Up to 16-column configurable default list view.
Custom 1-to-many, many-to-1, 1-to-1, and many-to-many relationships with other modules.
Auto-included relationships: Activities (Calendar), Documents, Comments, and Emails on every module.
Material-icon picker for the left-sidebar icon.
Auto-numbered record IDs with configurable prefix and starting number.
Soft-delete, restore, force-delete (with table drop), and export as a vTiger package zip.
Full workflow engine support — modules created here can be used as workflow source modules and as related-module conditions.
Modules appear in the global predictive search, the Calendar “Related To” picker, and as targets for Document attachments.

⚠️ Note: Module Builder is available only to administrators. Non-admin users cannot access the Settings → Module Builder screens.

2. Audience and Roles

Role	What They Do
Administrator	Creates, edits, exports, and deletes modules. Configures field-level access through standard Profile settings after creation.
End user (CRM rep, manager, etc.)	Uses the newly created module just like any standard module — list/detail/edit views, related panels, workflows, reports, and search.

Field-level permissions, role visibility, and sharing defaults follow the standard vTiger Profile/Role/Sharing rules. Every existing profile is granted access automatically when a module is created, so it is visible to all users by default. Use Settings → Profiles to restrict access if needed.

3. Where Module Builder Lives

Sign in as an Administrator.
Go to Settings → CRM Settings → Module Management → Module Builder.
Click Module Builder.

The Module Builder list page opens. From here you can:

Click Create New Module (top-right green button) to launch the wizard.
See every custom module that has been created on this instance, with its label, internal name, sidebar icon, status, and per-row action buttons.

4. Creating a New Module — The 4-Step Wizard

Click Create New Module to enter the wizard. A breadcrumb at the top shows the current step. You can navigate forward and backward freely; the wizard only commits to the database when you click Save Module at the end.

4.1 Step 1 — Module Properties This step captures the identity of the module and how its records will be labeled and numbered.

Field	What it does	Required
Module Label	The plural label shown in menus and page titles (e.g. Patient Goals).	Yes
Singular Label	Used in buttons like Create Patient Goal. Auto-filled from the Module Label — change only if the simple “drop the trailing s” guess is wrong.	Yes
Internal Module Name	PascalCase, letters and numbers only, 2–50 characters (e.g. PatientGoals). Used by the database and the REST API. Auto-generated from the label. Cannot be changed after creation.	Yes
Record Identifier Label	Label for the primary “name” field on each record (e.g. Goal Name, Patient Name). This becomes the title of every record, the field shown in related-record dropdowns, and the link text in lists.	Yes
Record Number Prefix	Prefix for the auto-generated record number (e.g. PAT → PAT-00001). Auto-filled from the first 3 letters of the module name. Letters and numbers only; upper-cased automatically.	No
Starting Number	The first sequence number assigned to a new record. Defaults to 1.	No
Sidebar Icon	Pick a Material Icon to represent the module in the left navigation sidebar. The picker shows a scrollable grid of icons; click one to select. The selected icon name and preview is shown below the grid. Defaults to extension.	No

💡 Tip: Pick the Internal Module Name carefully. Once created, the name is used in database table names (vtiger_<name>, vtiger_<name>cf), REST API URLs, workflow definitions, and reports. To change the name later you would have to delete and recreate the module.

Click Next to move to Blocks & Fields.

4.2 Step 2 — Blocks & Fields Records are organised into one or more blocks that appear top-to-bottom on the detail view. The first block (named Module Information by default) automatically contains two system fields:

The Module Number field (e.g. Patient Goals No) — read-only, auto-generated.
The Record Identifier field you defined in Step 1 — the title of the record.

You can add as many additional blocks as you need. Within each block you can add fields, reorder them by drag-and-drop, edit any field’s properties, or remove a user-added field.

Adding a block:

Click + Add Block at the bottom of the page.
Enter a block name (e.g. Address Details, Clinical Notes).
Choose where to insert it from the Insert After dropdown.
Click Add.

Adding a field:

Click + Add Field inside the target block.
Select a Field Type from the list.
Enter the Label the user will see, and the Internal Name (auto-generated from the label, lowercase, underscores).
Configure the type-specific options that appear (see below).
Toggle the field properties as needed:
- Mandatory — record cannot be saved without a value.
- Quick Create — field appears in the Quick Create modal.
- Key Field / Summary — field appears in the Summary view at the top of the detail page.
- Header View — field is pinned to the page header above the blocks.
- Mass Edit — field can be updated for many records at once from the list view.
Click Save Field.

Supported field types:

Category	Types
Basic	Text, Text Area, Integer, Decimal, Percent, Currency
Date / Time	Date, Date-Time, Time
Contact	Email, Phone, URL, Skype
Picklist	Picklist (single-select), Multi-Select Combo Box
Boolean / Toggle	Checkbox, Toggle, Yes/No With Detail
Relation	Reference, Related Module, User/Group List
Slider	Number Slider, Percent Slider
File	File Upload

Type-specific options:

Picklist / Multi-Select Combo Box — enter one value per line in the Picklist Values box. Optionally tick Role-Based to scope visible values per role.
Reference / Related Module — choose one or more modules that the user can pick a record from.
Currency / Percent / Number Slider / Percent Slider — enter min, max, and (for sliders) step values.

Reordering and removing:

Drag any field by its handle to reorder within or between blocks.
Click a field’s delete icon to remove it. The two auto-included fields (Module Number and Record Identifier) cannot be removed.

Click Next to move to Default Filter.

4.3 Step 3 — Default Filter The default filter, named All, defines the columns and column order shown on the module’s list view when a user first opens it.

The left list (Available Columns) shows every field you have defined in Step 2.
The right list (Selected Columns) shows the columns that will appear in the default list view.
Click a field on the left and click Add → to include it. Click ← Remove to drop it.
Use ↑ Up and ↓ Down to change the order.
Maximum 16 columns. The counter at the top right of the right-hand list shows how many are selected.

If you leave the selection empty, the module is created with a sensible default: Module Number, Record Identifier, Assigned To.

⚠️ Note: Users can still create their own list-view filters from the module’s List View page once the module is live. This step only defines the default filter delivered with the module.

Click Next to move to Relationships.

4.4 Step 4 — Relationships Use this step to link the new module to other CRM modules. Every module receives these standard relationships for free, without configuration:

Activities — linked to Calendar (tasks and events can be created against records of the module).
Documents — files can be attached to each record.
Comments — the ModComments thread is enabled.
Emails — outgoing emails can be sent and tracked from the record.

To add a custom relationship, click + Add Relationship and fill in the row:

Column	Meaning
Related Module	Which module to link to. The dropdown lists every active entity module on the instance, sorted alphabetically. Calendar, Comments, and Emails are intentionally hidden — they are always created as default relationships and would conflict if re-added.
Type	The cardinality of the relationship. See below.
Tab Label	The header shown on the related panel (e.g. Patients, Cases). Defaults to the related module name.
Actions	Tick Add to allow inline record creation from the related panel; tick Select to allow picking from existing records.

Choosing a relationship type:

1:N (One-to-many) — one record of the new module owns many records of the related module. A subpanel appears on the new module’s detail view listing the related records. A reference field is added to the related module that points back to the new module. Example: one Patient → many Visits.
N:1 / 1:1 (Many-to-one / One-to-one) — each record of the new module points to one record of the related module. A reference field is added to the new module. The related module gets a subpanel listing back. Example: many Tasks → one Patient.
N:N (Many-to-many) — both sides can link to many of each other. A subpanel appears on both modules and the link is stored in a shared junction table. Example: Goals ↔ Treatment Plans.

You can remove a relationship row before saving by clicking the trash icon on the right of the row. Once the module is saved you can still add and remove relationships from the standard Settings → Module Manager → Edit Module screen.

4.5 Saving the Module Click Save Module on Step 4. A status banner appears at the top of the page while creation runs. If the creation succeeds, the page redirects to the Module Builder list and the new module is also added to the main top navigation menu. Refresh your browser if the menu does not appear immediately — vTiger caches the tab data file per session.

If creation fails, the banner shows the error and the module is left in a partial state, visible in the Module Builder list with an Orphaned badge. You can clean it up with the Delete & Clean Up button (see Section 5.5).

5. Managing Existing Modules

The Module Builder list view shows every custom module created on the instance, with the following per-row actions.

5.1 Edit Layout Opens the standard vTiger Layout Editor for the module. From there you can:

Add or remove fields and blocks after the module has been created.
Reorder fields by drag-and-drop.
Mark fields as mandatory, hidden, quick-create, mass-editable, summary, or header.
Add or change picklist values.
Add related lists.
Set default field values via the new Default Value UI.

Changes are applied immediately to all users; no module rebuild is required.

5.2 Hide (Soft Delete) Soft-deleting a module marks it as hidden across the CRM. The module disappears from menus, list views, related panels, and search, but the data and tables remain in the database. The module name cannot be reused until it is restored or force-deleted. To hide a module:

Click the orange Hide button on the module’s row.
Confirm in the dialog.

The row stays in the Module Builder list with a Hidden status, and the action buttons change to Restore and Delete & Clean Up.

5.3 Restore Available for hidden modules only. Click the green Restore button to make the module visible again. Records, fields, relationships, and filters all return exactly as they were.

5.4 Export Click the Export button to download a vTiger-compatible .zip package of the module. The zip contains:

manifest.xml — the full module definition (blocks, fields, picklists, relationships, table schema).
modules/<Name>/<Name>.php — a minimal stub class.
languages/en_us/<Name>.php — the language strings used by the module.

The exported zip can be installed on another tenant or another environment using the standard Settings → Module Manager → Import Module screen. This is the supported way to clone a module across instances.

💡 Heads up: Exports include the module structure only, not record data. To migrate records use the standard Import / Export Records workflow on the module’s List View.

5.5 Delete & Clean Up (Force Delete) Force-delete permanently and irreversibly removes everything related to the module:

The CRM metadata (blocks, fields, related lists, filters, profile permissions, webservice registration, menu entries).
The physical database tables (vtiger_<name>, vtiger_<name>cf, vtiger_<name>_user_field).
All records that belonged to the module.
The generated language file at languages/en_us/<Name>.php.
The module’s directory under modules/, if one exists.

To force-delete:

Click the red Delete & Clean Up button.
A confirmation modal appears warning that the action cannot be undone.
Type the module’s internal name to confirm and click Delete.

After force-delete, the module’s internal name becomes available again for a future Create.

💡 When to use which delete: Use Hide if you might bring the module back, or if you want to keep historical data for reports. Use Delete & Clean Up only if you are certain the module is no longer needed anywhere.

5.6 Handling Orphaned (Partial) Modules If module creation crashes after the module is registered in vTiger but before the Module Builder registry row is inserted, the module ends up in a partial state. It appears in the list with an Orphaned badge and only the Delete & Clean Up action is offered. Force-deleting the orphan cleans up the vTiger metadata and frees the name for re-creation.

6. What Happens Behind the Scenes

These items are transparent to the admin but help with day-to-day operations.

Record numbering — every record gets an auto-number on creation in the form <PREFIX>-<NUMBER> (e.g. PAT-00001). The starting number and prefix are configured in Step 1 of the wizard.
Assigned To, Created Time, Modified Time, Source, Tags — these standard system fields are added to every module’s More Information block. They behave exactly the same as in built-in modules.
Change history — ModTracker is enabled automatically. Every field change is logged and visible on the record’s Updates tab.
Comments — every record has a Comments thread out of the box.
REST API — the module is registered with the webservice layer, so it is reachable via webservice.php?operation=...&elementType=<ModuleName> using the same authentication as other modules.
Workflow engine — Workflows can target the new module as their source module. Conditions can reference any field on the module, including related-module fields.
Global predictive search — record names from the new module appear in the global top-bar search.
Calendar — Related To — the new module is available as a target in the Quick Create Task and Quick Create Event “Related To” dropdown.

7. Common Tasks — Step by Step

7.1 Create a “Patient Goals” Module Linked to Patients

Settings → Studio → Module Builder → Create New Module.
Step 1:
- Module Label: Patient Goals
- Singular Label: Patient Goal
- Internal Module Name: PatientGoals
- Record Identifier Label: Goal Name
- Record Number Prefix: PG
- Starting Number: 1
- Sidebar Icon: pick flag or trending_up.
Step 2 — keep the auto-added fields, then click + Add Field inside the first block and add:
- Target Date — Date — Mandatory.
- Priority — Picklist with values: High, Medium, Low — Quick Create.
- Progress — Percent — Header View on.
- Notes — Text Area.
Step 3 — add columns in this order: Patient Goals No, Goal Name, Priority, Target Date, Progress, Assigned To.
Step 4 — click + Add Relationship:
- Related Module: Contacts (or Accounts, depending on how your instance models patients)
- Type: N:1
- Tab Label: Patient
- Actions: tick both Add and Select.
Click Save Module.
Refresh the browser. Patient Goals now appears in the main menu, and every Contact’s detail page has a new Patient Goals related panel.

7.2 Add a Field After the Module Is Live

Settings → Studio → Module Builder.
Click Edit Layout on the module row.
In the target block, click + Add Custom Field.
Choose the type, name, label, and properties.
Click Save. The field is immediately available on Edit, Detail, and Quick Create views.

7.3 Move a Module to Another Environment

Settings → Studio → Module Builder.
Click Export on the module row. A .zip file downloads.
Sign in to the target environment as an administrator.
Settings → Studio → Module Manager → Import Module from Zip.
Upload the file and follow the import wizard.
Activate the imported module.

7.4 Recover a Module You Hid by Mistake

Settings → Studio → Module Builder.
Find the row marked Hidden.
Click Restore.
Refresh the browser; the module reappears in the menu with all data intact.

8. Permissions, Roles & Sharing

When a module is created, Module Builder grants every existing profile Save, EditView, CreateView, Delete, Index, and DetailView permissions, with all fields visible and editable. To restrict who can see or change the module:

Settings → Profiles — toggle module access and per-field visibility for each profile.

Settings → Sharing Access — change the default sharing rule (Public Read Only, Public Read/Write, Private, etc.)

Settings → Roles — assign profiles to the roles in your hierarchy.

These tools work the same way for Module Builder modules as they do for built-in vTiger modules.

New users / profiles added later — when you create a new profile after a Module Builder module exists, the new profile inherits access to the module automatically. You only need to explicitly restrict access if you want to deny it.

9. Limitations & Things to Watch For

Internal Module Name is permanent. Plan it before saving.
Module Label can be changed through the Layout Editor → Module Properties, but the underlying database tables are not renamed.
Field types cannot be changed after creation. To switch a field from Text to Picklist, delete the field and add it again under the new type. You will lose existing values for that column.
Picklist values can be edited any time through Settings → Picklist Editor.
Reports and Dashboards — modules created via Module Builder appear in the Reports module immediately. Report folders, custom dashboards, and saved chart definitions need to be created manually as for any module.
Mobile UI — modules are accessible on mobile through the standard responsive layouts. The wizard itself is also responsive and can be used from a tablet, but a desktop browser is recommended.
Soft-deleted modules block name reuse. Until you force-delete or restore them, the module name is taken.
Don’t bulk-delete from the database. Always use the Hide or Delete & Clean Up buttons; they remove dependent rows in the right order. Direct SQL deletes leave orphan rows in vtiger_field, vtiger_profile2field, and similar tables.

10. Troubleshooting

Symptom	Likely Cause	Resolution
The module is created but missing from the top menu	The browser cached the old tab data file.	Hard-refresh the browser (Ctrl+F5) or sign out and back in.
“A module named ‘X’ already exists”	A live or hidden module with the same Internal Name exists.	Pick a different name, or restore/force-delete the existing one.
Save fails with a “duplicate field” error	A previous create attempt for the same name partially completed.	Cancel the wizard, return to the list, click Delete & Clean Up on the orphaned row, then create the module again.
Non-admin users see Access Denied on the module	Profile permissions did not propagate, or the profile was created after the module.	Open Settings → Profiles, edit the profile, and toggle the module’s checkbox on.
Workflows on the module never fire	Webservice entity registration is missing (only happens if creation was interrupted at a specific step).	Force-delete and re-create the module.
Field changes in Layout Editor don’t appear on the detail view	The layout is cached.	Hard-refresh the browser.
Calendar / Tasks “Related To” dropdown does not show the module	Webservice reference type was not registered (rare; same root cause as workflow issue).	Force-delete and re-create the module.

If the symptom is not in this table, capture the error banner text and a screenshot and contact CRM support.

11. Summary Cheat-Sheet

Goal	Where
Open Module Builder	Settings (gear) → Studio → Module Builder
Create a new module	Module Builder list → Create New Module (top-right green)
Edit fields and blocks	Module Builder list → row → Edit Layout
Add or remove relationships after creation	Module Manager → Edit Module
Hide a module without losing data	Module Builder list → row → Hide (orange)
Bring back a hidden module	Module Builder list → row → Restore (green)
Move to another environment	Module Builder list → row → Export (info button), then Module Manager → Import
Permanently remove	Module Builder list → row → Delete & Clean Up (red)
Lock down access	Settings → Profiles, Roles, and Sharing Access.