Modules are reusable, independent code units encapsulating specific logic, enhancing organization and maintainability. They are used by product designers to outsource and wrap complex logic within or across products, avoiding duplication and easing updates. Modules define inputs, calculations, and outputs but lack views. They can be mocked for testing and integrated into products via Setup → Modules. Two input approaches exist: individual fields or a single JSON input. Modules support validations and advanced workflows like shared dictionaries.
Introduction to Modules
What are modules?
For whom is this relevant?
Product Designers
When and why should you work with modules?
Modules allow you to simply outsource parts of the product logic as a "re-usable building block".
There are two main scenarios where using a module might be the right choice for you:
- You have a relatively complex piece of logic, that you want to perform multiple times within a single product.
- You have a relatively complex piece of logic that you want to re-use across multiple products.
In such cases, outsourcing the logic in a module has a number of advantages, like (but not limited to):
- you avoid having to copy & paste the same logical steps multiple times within the same product (or across multiple products)
- in cases changes are needed, you have to apply them only once within the module
- your product's logic becomes more compact and readable
- you can update a module's logic independently from your product.
Note: there is a third scenario in which modules can be of help, which arises from a technical peculiarity of REALYTIX ZERO: a product build cannot be bigger than 2MB.
This limit is not an issue for the absolute majority of products, but you might encounter it in cases where your product has thousands of fields, or includes (lookup) tables with thousands of rows and/or columns, or performs external calls returning vast amount of data. You will know if this applies to you, as the Product Studio will no longer allow you to save your product, telling you it is too large.
In such cases, splitting your product's logic across one or multiple modules can be used as a workaround, as each module can have an additional 2MB of size.
How to create a new module
On tenant level you can switch between the tabs "Products" and "Modules". To create a new module, simply click on the + Create Module button on the left.
Within your module, you will typically want to define:
- Its input structure,
- Calculation steps to calculate an output based on the input, and
- Its output structure.
The input structure is automatically derived by the fields you define within your module. Just like in an REALYTIX ZERO product, you can declare e.g. number fields, text fields, checkboxes, etc. Similarly, just like in REALYTIX ZERO products, you can declare such fields to be optional or mandatory, disable them based on conditions, etc.
You can then define any logic steps you need to, like e.g. perform calculations, use the Lookup & Table functionality, perform external calls and validations, you can even call a module from within a module.
Once you have calculated the desired result, you can return it via the output structure. You can define this output structure within the $quote.data section of your module, very similarly to how you would do in an REALYTIX ZERO product.
Please note: a module cannot store anything on its own, therefore (unlike a full-fledged REALYTIX ZERO product), a module does not have views, like e.g. an API or Reporting View.
What are module builds?
Module builds are very similar to product releases. Hence, whenever you have something stable you want to give to your product designers using your module, create a new build.
Use Save draft to save work without creating a build. To publish a build, open Save, choose a version increment and select Save and create build.
| Increment | Example |
|---|---|
| Patch | 1.4.2 → 1.4.3 |
| Minor | 1.4.2 → 1.5.0 |
| Major | 1.4.2 → 2.0.0 |
Studio shows the next available version. A published module build or product release cannot be overwritten with the same version number.
One important aspect to be aware of when using modules: in technical terms, they can be thought of like "statically linked software libraries". This means that whenever you create a release of your REALYTIX ZERO product, any module it uses will be copied within the product release. Hence, if you update your module after the product release and want that change effective in your product as well, you will need to release the product again, too.
This also means, than anybody having access to the JSON of a Product Release (i.e. Product Designers), will also be able to see the content of any modules used by the product, regardless of whether they have access to the Module within the Product Studio. In other words, encapsulating logic in a module does not represent a security boundary to preserve intellectual property.
How to use modules from within a product
Video: How to add a module to your product
Note: The video and transcript below show an old version of Module Workflow layout and the Source option. Use Setup → Modules and a published build as described in subsequent sections.
Watch this video to see how a Designer adds a predefined module in Workflow, chooses the module version, and connects product input variables. The example shows how shared services for data enrichment, compliance checks, flood risk checks, or pricing logic can be reused across products instead of being configured repeatedly.
Adding the module to your product
- Open Setup → Modules.
- Select Add module and choose a module.
- Choose a published version or version range.
- Check the resulting tree for errors.
- Save the product draft.
You can use modules owned by your tenant or shared with it. See Managing Product and Module Access.
Indented rows are dependencies of the module above them.
Choosing a constraint
A constraint defines which published builds are allowed.
| Constraint | Permitted builds |
|---|---|
1.2.1 |
Exactly 1.2.1. |
1.2.* |
Any patch in minor version 1.2. |
1.*.* |
Any minor and patch in major version 1. |
Any version — *.*.*
|
Any published build, including a new major version. |
Source is no longer supported. Build the module and select a published version.
Studio resolves the whole dependency tree. All references to the same module must agree on one version. A newer build can be excluded because another branch requires an older version.
Reading the dependency tree
| Indication | Meaning |
|---|---|
| Current version | The build selected for use in this workspace. |
| Proposed version | The build offered in a review. |
| Available | A compatible update is available. |
| Latest | A newer published build exists; it may conflict with a constraint. |
| Unresolved | Studio cannot use a build for this reference. |
| Related conflict | This reference resolves, but another reference to the same module conflicts. |
Expand a row to see its dependencies. You can edit root constraints in the product. To change a nested constraint, edit its parent module and create a new parent build.
Showing IDs and expanding the tree
| Mark | Control | Use |
|---|---|---|
| 1 | Show IDs / Hide IDs | Show or hide the unique ID below each module name. |
| 2 | Expand all / Collapse all | Open or close all dependency branches. |
| 3 | Arrow beside a module | Open or close that branch only. |
| 4 | Copy module ID | Copy the ID shown beside the button. |
The same ID in different branches identifies the same module. Current version identifies its build. These controls do not change constraints or selected versions.
Checking and applying updates
- Select Check updates.
- If offered, select Review updates.
- Compare Current version with Proposed version, including nested modules.
- Select Apply. Now, the changes are effective in the Studio.
- Review and save the product.
Neither checking updates nor reviewing updates change the versions currently in use, until you press Apply.
“No compatible module updates found” can still mean newer builds exist. Check the constraints and any Latest indicators.
Calling a module
A Module Call is available under Structure. For an overview of this node alongside groups, arrays, and Data Providers, see Structures: Groups, Arrays, Modules and External Calls.
- Click on the Plus-Button to add a new field, then choose Structure > Module Call
- Select the desired module. This list only contains modules explicitly added to your product, via Setup → Modules.
- Add the module's input in order to receive its output.
The exact structure and names of the variables expected by your module are automatically derived from the module's input fields. In the example below, the module declared two number fields, named "a" and "b"
- You may use the output of a module for further calculation like every other calculation field.
Mocking a module
The Execution mode feature provides a flexible approach to testing and development by allowing you to choose whether a module executes a real call or returns a mocked (simulated) response instead.
When your product is accessed via the main UI or API, all calls are executed for real. In the studio, however, the Execution Mode allows you to choose per call whether to run it against the real backend or return a mocked response - either by mocking the entire module or just the specific external calls within it.
For structured, repeatable checks that use mocked module or external-call responses, see Testing your Product.
With mocked responses, you are no longer required to build special ‘dryRun’ logic or maintain parallel implementations within each module just for testing purposes. Instead, one or more simulated responses can be set up and swapped in as needed, all within the studio environment. This lets designers try out various scenarios (such as error handling or edge cases) without ever touching real data or relying on external dependencies that may not always be available.
Mocking the entire Module
You can choose to mock an entire module during testing, whether or not it contains external calls. This approach lets you simulate the complete behavior of a module, making it easier to validate different outcomes, isolate specific scenarios, and streamline development. By mocking the whole module, you gain flexibility to test complex logic or simple internal processes without relying on dependencies.
1) Click on the Pen icon.
2) Go to the Mocks section in the menu.
3) Click the + symbol to create a new mock.
4) (Optional) Enter a name for the mock.
5) Define the mocked output in JSON format.
Hint: When you create a new mock, the mocked value will be copied from the current output. This simplifies the process of creating multiple mocks. Simply change the input during the real call execution, and then create a mock to save the current output as a mock.
6) Select the mock
In the output structure, you can now select the defined mock. This means the call will not be executed within the studio; instead, the mocked output will be used for further calculations.
Mocking an external call inside a module
Alternatively, you can mock just the external calls within a module. This option was introduced especially for upcoming Test Case feature, so you can focus your tests on specific interactions or parts of your logic. Mocking external calls is ideal when you want to test modules in a more structured and detailed way, preserving the module’s internal behavior while simulating the responses from external services.
To do this, simply navigate inside the specific module you want to work with—then create the mocks there. Once you have created mocks for the external calls in a module, within a product using that module, you now can select whether to use mock values just for those external calls in a section called Configure mocks within this module.
This option gives you full flexibility to e.g. run the logic in a module with the exception of the actual external calls within it. This can be really useful when you are actively working on the module (and are therefore making changes to its behavior which you want very much to test), but have some external calls in the module which you would not like to send over and over again (e.g. because they are expensive, resource intensive, non-idempotent, etc.)
This approach gives you the flexibility to either simulate the module’s full behavior or focus just on external interactions based on your testing needs.
Validations in modules
If your module defines some validations, and the passed input triggers them, the failed validation will be visible within your product, stopping its logic.
Errors and how to fix them
Example: conflicting versions of a shared module
In this example, the root Shared reference was changed to 1.1.0. The Calculation, Input, Open Questions, Report and ARES modules still require 1.2.1.
| Reference | Required version | Result |
|---|---|---|
| Product → Shared | 1.1.0 |
Resolves, but has a Related conflict. |
| Parent modules → Shared | 1.2.1 |
Constraint mismatch; unresolved. |
Hover over an error to read the explanation. Click it to highlight every reference to that module.
Fix: change the root constraint back to 1.2.1, or change the parent modules so every reference permits a common published version. Publish changed parents, update the product and test again.
After restoring 1.2.1 in this example, Check updates confirms the recovery:
Example: a build does not exist
Searching for 9.9.9 in this module’s picker returns No matching versions. Select an existing build or ask the module owner to publish the required version.
This screenshot shows an empty picker search. A saved dependency with no matching published build can also produce a resolver error.
Example: release blocked by dependency errors
You can keep unfinished work as a draft. Apply with errors, when offered in a review, accepts the unfinished tree. Affected branches cannot execute successfully.
Creating a product release or module build requires resolved dependencies:
Error reference
| Error | Cause | Action |
|---|---|---|
| Version conflict / Constraint mismatch | References require incompatible versions of the same module. | Make all references permit one common published version. |
| No matching version | No published build satisfies the constraint. | Choose another constraint or publish a suitable build. |
| Missing version | A referenced build cannot be found. | Select an existing build and review the selection. |
| Unsupported constraint | A legacy source reference remains. |
Replace it with a published version or wildcard range. |
| Circular dependency | A module appears again in its own dependency chain. | Remove the circular reference and publish corrected parent builds. |
| Access denied | The selected tenant cannot use the module. | Ask the module owner to check usage permissions. |
| Version changed while saving | Another save or build changed the current version. | Reload the latest state, reconcile changes and choose the next available version. |
Best Practices
Input Structure
When defining the input structure of a module, there are two main approaches that are comonly used:
- Approach 1: for each of the expected inputs, you define an appropriate input field of the corresponding type.
- Approach 2: your module defines a single "JSON Data field"
Both approaches are valid, and each have their pro and cons.
Approach 1: Define all input fields individually
| Pro | Con |
|---|---|
|
|
When calling the module from within your product, you would pass the input this way:
Approach 2: Define a single JSON input for all fields
| Pro | Con |
|---|---|
| Easier for advanced users at it contains all data combined together | If you want to validate you need a validation trigger pointing to the corresponding property (see sample below). |
When calling the module from within your product, you would pass the input this way:
Advanced Workflows
Dictionaries and Lookups
You might want to use modules for shared Dictionaries or Lookups among different products at some point. For the underlying table features, see Getting started with Dictionary Tables and Getting started with Lookup Tables.
The following two examples show, that this might make sense for Dictionaries, which are for example used as option values, but when doing the same for Lookups most vital information and functionality will be lost.
As it is done with the input of a module also the output is JSON encoded before being sent to the product, hence object specific Dictionary/Lookup functionality is not anymore available outside of the module.
{
returnDictionary: true
}
{
returnLookup: true
}
Related Articles
- Modules maintained by Realytix
- Structures: Groups, Arrays, Modules and External Calls
- Testing your Product
- Getting started with Lookup Tables
- Getting started with Dictionary Tables