For users testing modularity v2 in Ninox 3.17 beta on Private Cloud

1. Introduction

Modularity lets you build a self-contained Ninox database (a module) that plugs into other workspaces through a module interface. The pay-off is isolation, reuse, and safe updates—bugs and schema tweaks stay inside their own module, and you can release new versions without affecting consumers.

This article is for partners who are testing modularity in its beta phase. We walk you from first contact through daily use and troubleshooting. If you need full definitions, keep the glossary open in a second tab.

Heads-up while you test the beta

• Some stages are under active development, so expect UI changes and occasional rough edges.
• Only data fields can be exposed in this beta; relationship, formula, image, and dynamic (multiple) choice fields aren't supported yet.
• The HR module can't be connected yet. As mentioned in the webinar demo, our current focus is making modules independent, interoperable, and interchangeable. Once that's working, we'll tackle distribution and easier updates.
• We'll update this article and the other documentation (glossary, concepts) as each new stage ships.
• For questions or issues while testing, post in the forum. For documentation-specific questions, please comment directly under the article.

For existing production databases you want to convert into modules

Existing links to connected databases and external API integrations should continue to work. The main caveat is exposing a field that originates from an inter-database connection created with modularity v1; that may not be supported. Please test this during the beta and share feedback if it doesn't work.

2. Key roles and terms

• Module author: Builds the provider database, exposes tables/fields, versions the interface, and will later publish the module.
• Module consumer: Adds the module to a workspace, connects to its interface, chooses read or write access, and may later be able to extend it inside their own Ninox app.
• End user: Works in the finished solution, usually unaware that modules power it behind the scenes.

3. Understanding modules and interfaces

What is a module?

A module is a self-contained Ninox database that shares only the data and logic you choose. You can reuse it in many workspaces and update it safely without exposing your internal setup. In the future, we may add ways to package or monetize modules, but those capabilities aren't available in this beta.

What is an interface?

An interface is the public contract between your provider database and any consumer databases that connect to it. It defines every table and field you expose, using:

• The interface ID (a unique label that identifies the API)
• Each table ID with its public name
• Each field ID with its public name
• The access rights for each field (Read or Write)

Visual guide—module anatomy

This diagram shows how the 3 parts of a module work together today:

• Provider database: Where your tables, fields, and scripts live. Anything you expose here goes out through the interface. You always retain write access.
• Module interface: The list of tables and fields you've exposed, with their internal names, the names your module consumers see, and each item's access level.
• Consumer database: What your end-users install. Ninox creates external tables here that mirror your exposed data and stay in sync while connected. You decide whether end-users can write back to those tables.

4. Module lifecycle

The diagram shows the ideal end-to-end journey for a module: Design → Expose → Test → Publish → Consume/Provide → Update/Discontinue.

Below is a walkthrough of each stage, with a note on what you can do today in the beta and what's currently not available.

1. Design – available today

   Build your schema, scripts, and business logic in a normal Ninox database. Treat this as the blueprint for your future module.

2. Expose – available today (with limits)

   Open Module settings > Configure public fields and pick which tables and data fields become public. Only data fields can be exposed in the current beta; relationship, formula, image, and dynamic (multiple) choice fields aren't available in this beta.

3. Test – not available

   Automated integration tests that validate your exposed interface before publishing aren't in the beta yet. For now, create a throw-away consumer database and test manually.

4. Publish – not available

   Later versions may let you package the module (including its interface) and release it to a channel so any workspace can discover and add it. During the beta, sharing is limited to private workspaces or imports (direct copies).

5. Consume and Provide – available today
   • Consume: Add the module to another workspace; Ninox creates external tables that stay in sync.
   • Provide: Once a consumer connects, your provider database supplies live data (and accepts writes if you granted that permission) through the exposed interface.
6. Update (available today – with limits) and Discontinue (not available)

Renaming the interface ID as well as updating, moving, or deleting exposed tables and fields creates a new interface, letting consumers update when they're ready. To discontinue a module, mark old versions as obsolete and guide consumers to update.

• Update: Modularity v2 doesn't yet support updates to your own modules. In the meantime, use the update manager or share an updated database for import.
• Discontinue: There's no formal deprecation flow yet. You can't mark versions as obsolete or prompt consumers to update inside Ninox. For now, communicate directly with consumers and provide manual guidance for moving to newer versions.

5. Names and IDs—what you can safely rename

Interface ID: Unique, human-readable label that identifies the API. Renaming creates a new interface and breaks existing connections on the consumer side until the consumer updates to the new version.

Table/field name: Only visible to authors, safe to rename any time.

Public table/field name: Consumer-facing name associated with a hidden system ID. Safe to rename because the hidden ID never changes.

6. Creating, editing, and deleting an interface (authors)

To create a module interface

1. From workspace home, click the card of the provider database.
2. Toggle on Edit mode.
3. In the left navigation panel, on the right side of the database name, click the ellipsis button.
4. From the menu, select Module settings.
5. In the Configure public fields dialog: in the top-left corner, select a table from the menu.
6. Select the fields you want to expose.
7. Optional, for each field: give consumers permission to overwrite your source data by toggling on Write.
8. Optional, for each table: set record permissions by checking Create and/or Delete.
9. When you're done, click the Save button.
10. Reconfirm by clicking the Save button in the dialog.
11. On the Module settings page, click the Configure public fields button.
12. Back on the Module settings page, enter an interface ID and click the Save interface button.

Warning: Your interface ID is an API-level identifier, which means changing the the ID later bumps the interface version automatically, breaking connections, and asking consumers to update to the new version. Since interface IDs also used to identify available interfaces in authors' databases, make sure to choose a human-readable name that describes the module's purpose.

Tip: Expose only what consumers really need—fewer sync points mean fewer surprises. Grant Write access sparingly; once enabled, consumers can overwrite your source data.

To edit a module interface

1. Navigate to the Module settings page and click the Edit interface button.
2. Now you can:
   1. Add new fields to be exposed or remove exposed fields. Access the Configure public fields dialog and follow the same steps as for creating an interface.
   2. Update the interface ID by clicking the Edit interface button.

To delete a module interface

1. Navigate to the Module settings page and click the Delete button.
2. Reconfirm by clicking the Delete interface button in the dialog.

Note: Unselecting all previously exposed fields in the Configure public fields dialog and saving your changes automatically deletes your module interface.

7. Data sharing and synchronization

Supported today: Tables and simple data fields such as text, number, date + time, yes / no, choice, and multiple choice.

Planned, not yet supported: Relationship fields, formula fields, image fields, dynamic (multiple) choice fields.

For testing purposes: Ensure that your data is transferred in a supported format (i.e. as data fields).

8. Connecting a module (consumers)

To connect a module:

1. From workspace home, click the card of the provider database.
2. Toggle on Edit mode.
3. Click the Connect module card.
4. Select a module in the Connect module dialog.
5. Click the Next button.
6. In the top-left corner, select a table from the menu to get a preview of all fields available for connection, and your access rights for each field.
7. Click the Connect button.
8. The dialog disappears and, if the connection is successful, the message Module interface saved is briefly displayed in the upper right corner of your screen.

9. Resolving data conflicts and reconnecting a module (consumers)

If a provider or consumer database is deleted or moved, the data stays put but syncing stops.

To reconnect a module:

1. From workspace home, click the card of the provider database.
2. Toggle on Edit mode.
3. Click the Connect module card.
4. Select a module in the Connect module dialog.
5. Click the Next button.
6. As when you first connected, you'll see a preview of all fields available for connection and your access rights for each field.
7. Click the Connect button.
8. All detected data conflicts are displayed. New records are highlighted in green, updated records in blue, and deleted records in red.
9. You have two options:
   1. Overwrite conflicting consumer data with provider data. To do this, click the Connect button again. The dialog disappears and, if the connection is successful, the message Module interface saved is briefly displayed in the upper right corner of your screen.
   2. Resolve data conflicts manually. To do this, open the table named in the dialog and correct the conflicting consumer data. When you are finished, click Cancel. Then restart the process to connect the module.

10. Removing fields (authors)

To remove exposed fields from an interface:

1. From workspace home, click the card of the provider database.
2. Toggle on Edit mode.
3. In the left navigation panel, on the right side of the database name, click the ellipsis button.
4. From the menu, select Module settings.
5. On the Module settings page, under the table name, click the trash icon for each field you no longer want to expose.
6. Repeat this process for all tables that contain fields you want to remove.
7. Click the Save interface button.
8. Reconfirm by clicking the Save button in the dialog.

11. Where to go next

• For a deeper, more abstract understanding of Ninox modularity, visit the modularity concepts.
• For precise definitions of roles, fields, names, and permissions, refer to the glossary.