Modules - An Introduction | Zoho Vertical Studio Help

Modules - Business Data Containers

Modules are the core building blocks used to model business data in a Vertical Studio application. Developers use modules to define what data is stored and how users work with that data in subscriber organizations.
Each module represents a business entity and supports end-to-end application behavior around that data, including layouts, permissions, views, automation, and process controls. The sections below explain module structure, configuration, and packaging behavior in detail.
For example, in a real-estate application, developers can use modules such as Properties, Site Visits, and Rental Agreements to manage the full journey from inquiry to lease completion.
Similarly, in a healthcare application, developers can use modules such as Patients, Appointments, and Prescriptions to track clinical interactions and follow-up care. These are illustrative examples. Modules can be designed for many other business models and workflows.

Core module concepts

Module, field, and record

A module represents one business entity in your application. If you are familiar with databases, you can think of a module as similar to a table. A field represents one attribute of that entity, similar to a table column, and a record represents one saved entry, similar to a table row.
For example, in a Rentals application, you can create a module called Properties. Fields in that module can include Property Name, Location, Rent Amount, and Availability Status. Each property you add, such as Palm Residency - Unit 302, is stored as one record in the Properties module.

Application capabilities supported by a module

A module in Vertical Studio does more than store data. It also includes application capabilities that define how users capture, access, and process that data.
Using the Properties module in a real-estate application as one example:
  1. Layouts and sections: Can organize data-entry screens for different use cases, such as one layout for residential properties and another for commercial properties.
  2. Permissions and profile access: Can control who can view, create, edit, or delete property records, for example allowing sales users to update listings while restricting delete access to admins.
  3. Views and related lists: Can help users work with records faster by showing filtered lists such as Available Properties and related information such as linked Site Visits.
  4. Automation rules: Can trigger automatic actions, such as assigning a follow-up task when a property status changes to Negotiation.
  5. Validation rules: Can enforce data quality by blocking invalid updates, for example preventing a record from being saved if Monthly Rent is missing.
  6. Blueprints and business processes: Can guide records through controlled stages such as Listed, Site Visit Scheduled, Negotiation, and Agreement Signed.

How modules appear in subscriber organizations

When users in a subscriber organization open the application, modules appear as tabs. Records are commonly accessed in two interfaces: list view and detail view.
  1. List view: Shows multiple records in a table-like list so users can scan, sort, filter, paginate, and perform bulk actions.
  2. Detail view: Opens one specific record and shows all of its field values so users can review and update that record.

Relationship patterns

Use lookup-based relationships for one-to-many scenarios and linking modules for many-to-many scenarios where association-level data must also be stored.
  1. One-to-many relationship: One record in Module A can link to one record in Module B, while Module B can contain many linked records from Module A.
  2. Many-to-many relationship: Records in both modules can connect to multiple records in the other module.
  3. Linking module: Use a linking module to store relationship-level data such as enrollment date, completion status, or score.
This pattern is useful when the relationship itself contains business data that does not belong to either parent module.

Module types and terminologies

In Vertical Studio, some modules are available as pre-built modules that are created by the platform. For example, modules such as Leads, Contacts, or Deals are available as pre-built starting points depending on the application context.
Developers can also create their own modules in the Developer Console based on business requirements and publish them to subscribers. For example, a real-estate developer can build modules such as Properties, Site Visits, and Rental Agreements, then publish these modules so they are available in subscriber organizations.
In subscriber organizations, these modules are available as standard modules in the application experience, and any modules created directly in the subscriber org are treated as user-created modules.

Layouts and sections

What is a layout?

A layout defines how fields are organized in the module create and edit forms. You can create multiple layouts when different teams or processes need different forms for the same module.
Example: In an insurance application, the Claims module can have one layout for motor claims and another layout for health claims.
Use multiple layouts when the same module needs different data-capture flows. For example, a property management application can use one layout for residential properties and another for commercial properties, with different mandatory fields and section order in each layout.

What is a section?

A section is a grouped block inside a layout used to organize related fields. Sections improve form readability and reduce data-entry errors.
Use sections to make long forms easier to complete and review. A clear section structure also helps subscribers understand what information is required at each stage of their workflow.
For example, in a Properties module you can define sections such as:
  1. Property Details
  2. Pricing and Availability
  3. Owner and Contact Information
  4. Legal and Agreement Details
In each section, keep related fields together and avoid mixing unrelated information.

Where to access and configure modules in the developer console

  1. Log in to your Developer Console.
  2. Go to Build > Modules.
  3. Click Create New Module. Or select a module you want to make changes to.
  4. Enter module details and configure layout, sections, fields, and permissions.
  5. Click Save.
  6. Publish a new application version.

Packaged modules

A packaged module is a module created in the Developer Console and included when you publish your application.
Info
For subscriber availability, publishing a module alone is not sufficient. The module must also be added to the selected pricing plan. If a module is published but not added to the pricing plan, it will not be available to subscribers, even after they upgrade.
After adding a module to the pricing plan, publish again so the change is reflected for subscribers. Module configuration is available across all plan tiers.

To learn more about package behavior, refer to Components and Packaging in Zoho Vertical Studio.

Packaging behavior

Property

Upgrade Type

Subscriber Modify Access

Module display label

Upgradable

No

Module API name (packaged and pre-built modules)

Non-Upgradable

No

Fields

Upgradable

No

Layout section order (packaged sections)

Upgradable

No

Layout field order (system-defined fields)

Upgradable

No

Permissions and profile access settings

Non-Upgradable

Yes

Field Mandatory property

Upgradable

No

Field Unique property

Upgradable

No

Field Tooltip property

Upgradable

No

Subforms

Upgradable

No

Subform fields

Upgradable

No

Module tab order

Non-Upgradable

Yes

Module visibility state

Upgradable 

No
*The subscriber can update the visibility status from the Organize modules section

Info
Note:
  1. A module cannot be deleted if it is part of a published version of your application.
  2. Packaged fields, sections and subforms cannot be deleted in the developer console. Developers can only move these to the unused items list. 

Subscriber layout customization rules

Hiding or showing modules

  1. If a module is hidden in the Developer Console, it is hidden in subscriber organizations after the next upgrade.
  2. Records in that module are also hidden until the module is made visible again.

Working with packaged sections

  1. Subscribers cannot delete packaged sections.
  2. Subscribers cannot change the order of packaged sections.
  3. If a packaged section is deleted in the Developer Console, it is removed from subscriber organizations after upgrade. Fields in that section are moved to the unused list.
  4. If a packaged section has the same name as an existing subscriber-created section, the packaged section is added with a 0 suffix. Both sections remain available independently.

Adding and reordering sections

  1. Subscribers can add their own sections.
  2. Subscriber-added sections are always placed after packaged sections.
  3. Subscribers can reorder only the sections they add.

Working with fields

  1. System-defined fields, including pre-defined and packaged custom fields, remain in the order defined by the developer.
  2. Subscribers can reorder only the fields they add.
  3. Subscriber-added fields are always placed after system-defined fields.
  4. If a packaged field is moved to the unused state, it appears in the unused list for layouts where it is not already used. If the field is already present in a layout, it remains available in that layout.

Working with subforms

  1. Packaged subforms are upgradable.
  2. Subscribers cannot delete packaged subforms.
  3. Subscribers cannot add or remove fields in packaged subforms.
  4. Packaged subform fields cannot be edited or deleted by the subscribers.

Subscriber outcomes

How module upgrades behave

Scenario 1: You rename a packaged module
After publishing a package for the first time, you rename a module.
What happens:
  1. You can continue to change the module display name after publishing.
  2. The module API name becomes non-editable in the developer console after first publish.
  3. When subscribers upgrade, the updated display name is reflected in their org.
  4. New subscribers who sign up to the latest version also see the updated display name.
  5. Subscribers cannot edit the display name or API name of packaged modules.
Scenario 2: A subscriber customizes a packaged module
A subscriber wants to make changes in a module from your package.
What subscribers can do:
  1. Add their own fields and sections.
  2. Reorder only the sections they added.
  3. Reorder only the fields they added.
What subscribers cannot do:
  1. Edit the display name or API name of packaged modules.
  2. Change properties of packaged fields such as Mandatory, Unique, and Tooltip.
  3. Remove packaged sections or fields.
  4. Reorder packaged sections or fields.
Scenario 3: You update packaged fields
You publish a new version after adding fields or changing field properties.
What happens after subscribers upgrade:
  1. Newly added packaged fields are available.
  2. Changes to Mandatory, Unique, and Tooltip are applied.
  3. Subscribers cannot edit these properties for packaged fields.
  4. New subscribers who sign up to the latest version also get the latest packaged fields and field properties.
Info
Note: Packaged fields cannot be deleted in the developer console. They can only be moved to the unused list. If a subscriber has already added that field to a custom layout created in the subscriber org, it remains available in that layout. For other layouts, it will be moved to the Unused fields section. 
Scenario 4: You update packaged layouts
You modify layouts by adding or rearranging sections.
What happens after subscribers upgrade:
  1. Packaged section order follows the latest package version.
  2. Subscribers keep sections they added.
  3. Subscriber-added sections remain after packaged sections.
  4. Subscribers can reorder only the sections they added.
  5. System-defined fields stay in developer-defined order.
  6. Subscriber-added fields remain after system-defined fields.
  7. Subscribers can reorder only subscriber-added fields, and only among themselves.
  8. New subscribers who sign up to the latest version get the latest packaged layout structure.
  9. If a section with the same name already exists in a subscriber org, the packaged section is added with a 0 suffix. Both sections remain available independently.
Scenario 5: You change module permissions
You update module permissions in the Developer Console and publish a new version.
What happens:
  1. Permission settings are not packaged.
  2. Subscriber orgs do not receive these permission changes through upgrade or during sign-up.
Scenario 6: You hide a module
You hide a module and publish a new version.
What happens after subscribers upgrade:
  1. The module is hidden in subscriber orgs. The data in that module is not lost. When the module is made visible again from the developer console, the module and its data will be available in subscriber orgs.
  2. New subscribers who sign up to the latest version also do not see that module. 
Scenario 8: You want a new module to be available to subscribers
You create a module and want subscribers to see it.
Required steps:
  1. Add the module to a pricing plan.
  2. Publish the package version.
If either step is missing, the module will not be available in subscriber orgs. New subscribers can see the module only when both steps are completed in the version they sign up to.

Troubleshooting module availability and access errors

Use these checks when a module appears disabled, does not load in a subscriber org, or returns permission errors after publish or upgrade.

Module is missing or disabled in a subscriber org

If a module does not appear in list view, tab navigation, or the relevant record flow, confirm the following before troubleshooting deeper:
  1. The module is included in the published application version.
  2. The module is assigned to the relevant pricing plan for that subscriber org.
  3. The module is not hidden by a visibility rule or by subscriber-side Organize modules configuration.
  4. The module was republished after the last change and the subscriber org completed a version upgrade.
  5. For repeated issues, verify whether the module name is blocked by a visibility conflict or whether the module is intentionally hidden for the target profile or location.

Module access or permissions save fails

If a user cannot save a permission change, update the owner, or assign a module to a profile, confirm the following:
  1. The assigned owner or profile user is active and still has valid access to the related org.
  2. The module is not locked by an app, pricing-plan, or package state that prevents the change.
  3. The user performing the change has the required admin or developer rights for the target configuration.
  4. The module is not being modified while another package or upgrade flow is still pending.
  5. This pattern is common when a change depends on ownership or profile state rather than on a package defect.

Territory or assignment logic does not create expected records

If a module or record assignment rule does not work as expected, verify that the rule owner or trigger user meets the required role and profile conditions.
  1. The assignment or routing logic may depend on an admin-level owner instead of a standard user.
  2. Territory rules often fail when the record owner is not configured for the expected admin or assignment profile.
  3. Validate the rule in a staging org before publishing a dependency-heavy change.

Custom button or record-triggered action returns a null record ID

If a button, action, or custom function receives an empty or null record ID, confirm the following:
  1. The record context exists before the action runs.
  2. The target record was opened from a valid list or detail page, not from an empty or stale selection.
  3. The action is not trying to resolve a record that was deleted or moved during the same flow.
  4. The button is associated with the correct module and the expected record context is still active.
This is usually a context or event-order issue rather than a module-definition problem.

Integration or sync is blocked by a disabled module state

If a third-party integration, sync, or document workflow is inactive even though the setup appears correct, check for the following:
  1. The connected module is still enabled and visible in the application.
  2. The relevant profiles still have access to that module.
  3. The module is not hidden in the subscriber org or disabled by the package state.
  4. The integration is not depending on a module that has been moved or removed from the current application version.
In these cases, the underlying cause is usually a module state or permission mismatch rather than a connection failure.

Webhook or trigger event setup does not fire for a module

If a webhook, automation trigger, or record event does not fire even though the module and workflow appear configured, confirm the following:
  1. The trigger is attached to the correct module and the expected record event.
  2. The event is enabled in the current application version and has not been disabled during an upgrade.
  3. The target record actually exists and is created or updated in the expected module context.
  4. The integration is using the correct record type, not a stale or mismatched module reference.
  5. The module is not hidden, disabled, or unavailable for the profile that should initiate the trigger.
This issue is usually caused by a mismatch between the configured module event and the event that actually runs in the current org state, not by a broken webhook endpoint alone.
If a document, signature flow, or related record is not appearing in the expected module after a user action, check the following:
  1. The target module is active, visible, and available to the users completing the flow.
  2. The record is being created or updated in the correct module, not in a duplicate or hidden module view.
  3. The related field mappings are still valid after any module, profile, or layout changes.
  4. The workflow or integration does not depend on a module that has been moved, hidden, or removed from the current application version.
When signatures or document actions fail to sync, verify the module state and mapping before investigating the external document or signature service.

A module action or button is missing from a module

If users do not see a module action, call action, or related button in a module experience, confirm the following:
  1. The module is enabled and available in the application and pricing plan.
  2. The user profile has access to the required module and action configuration.
  3. The action is not hidden by module visibility settings, profile rules, layout restrictions, or custom role-based conditions.
  4. The expected related record context is still valid when the action is triggered.
This pattern can appear in the Calls module or any other module with custom actions, and it is usually a module availability or visibility issue rather than a problem with the action logic itself.

Module data or navigation output does not match the expected records

If a navigation flow, lookup, or data extraction returns the wrong record set or an unexpected module value, review the following:
  1. The flow is pointing to the correct module and not to a hidden, removed, or renamed module.
  2. The field or module mapping still matches the current application version and the version running in the subscriber org.
  3. The record context has not changed because of a layout, section, or visibility update.
  4. The target record and module are still available in the current pricing plan and package state.
This pattern usually occurs when an action or mapping still references an older module configuration after a publish or upgrade. Check the current module state and the active app version before investigating the downstream logic.