Incorrect Model Resolution for Project-Level Overrides on UI

Issue

When a model provided by a module is overridden directly in the project using a project-level override, the Designer interface does not consistently distinguish between the module-owned and project-owned occurrences. Some areas list both occurrences separately, while others resolve only one of them or use an incomplete working model.

Depending on the affected area of the user interface and model, the Designer may:

• use the project-owned model without applying modifications or other contributions from dependent modules, or
• use the original module model instead of the project-owned model, or
• sporadically show only one of the module-owned and project-owned model occurrences below a context in the project tree.

Inconsistent Model Occurrences Below Contexts

In the project tree, data models of type entity and neonView are displayed below their associated context model.

If an entity or neonView exists twice, once as the regular model from a module and once as a project-level override, the context subtree does not reliably distinguish between the two occurrences. It sporadically selects one of them for display. Depending on which occurrence is selected, either the module-owned or the project-owned model appears below the context. The context subtree therefore does not provide a reliable representation of the available data models.

The separate entity node behaves differently. It lists both occurrences of a duplicated entity correctly, and both can be opened independently. A neonView does not have a corresponding separate node because it is available only below its context. As a result, the neonView occurrence that was not selected for the context subtree cannot be opened from the project tree.

Open models with Ctrl+O

Press Ctrl+O to open the model selection dialog. The dialog lists all data models from all included modules, independently of which occurrence is displayed below a context in the project tree. Models that are not accessible from the context subtree can therefore still be selected and opened from this dialog.

This workaround provides access to the affected models but does not change which occurrence is displayed below a context in the project tree.

Original Module Entity Used by Entity Webservices

The second case can occur when an entity with the same name exists both in a module and directly in the project. For example, when an entity webservice is edited, the field selection can be based on the module entity. Fields that exist only in the project-owned entity are then not available and cannot be added to the webservice through the Designer interface.

Missing Contributions from Dependent Modules

With a project-level override, the model stored directly in the project replaces the original model from the module. If applyAllModifications is enabled, applicable modifications from dependent modules are still expected to be applied to this project-owned model.

The transpiler handles this correctly. The Designer interface, however, uses the project-owned model without consistently applying the corresponding modifications. As a result, editors and previews in the Designer may work with an incomplete model, although the generated model in the dist directory and the deployed system are correct.

The following simplified example illustrates the difference.

In this example, the project-level override adds a project-specific valueProcess to the Organisation_entity. A modification from a dependent module additionally adds the ORG_ID entity field.

The transpiler combines both changes and generates the complete effective model. The Designer working model contains the project-level override, but the modification is not applied correctly. The ORG_ID entity field is therefore missing from the Designer interface.

Depending on the affected model and its modifications, this can cause:

• entries to be missing from selection editors in the Property Sheet,
• values changed through modifications to be missing or outdated,
• implementations from extension points to be unavailable,
• services or service implementations to be unavailable for editing,
• views to be missing or displayed incorrectly in neonView previews,
• editors and previews to show a state that differs from the transpiled and deployed system.

Recommended solution

Project-level overrides should generally be avoided for models that are part of the regular module structure.

Go directly to the recommended solution and available workarounds.

Current Status

The issue is known and currently unresolved.

It affects models that meet both of the following conditions:

• the model is provided by a module and overridden directly in the project,
• the affected part of the Designer interface must resolve a model from the duplicate module and project definitions.

The issue is especially visible when dependent modules provide modifications or other contributions for the model, or when an editor resolves the original module model instead of the project-level override. In the latter case, an entity webservice can show only the fields of the module entity even though the project-owned entity should take precedence. It also affects the context tree when an entity or neonView below a context exists both in a module and as a project-level override. The project tree then sporadically selects one of the two occurrences for display, even though areas such as the separate entity node correctly list both entity occurrences.

The transpiled and deployed result is not affected by this Designer limitation. The discrepancy exists between the working representation in the Designer and the effective model generated by the transpiler.

Decision

Project-level overrides were originally intended as a fallback for individual models, for example when the result produced from the module tree or by the transpiler cannot be used as required by a project.

They were not intended as the primary basis for development workflows in which larger parts of a project override module-provided models while continuing to depend on modifications and other contributions from the module tree.

Resolving this limitation would require the existing model-resolution mechanism in the Designer to consistently select project-level overrides as the effective models. All relevant modifications, extension points, services, implementations, and other contributions would then need to be applied to the project-owned target model before it is made available to editors and previews.

This change would affect several areas of the Designer, including model loading, Property Sheet editors, selection editors, service editors, and previews. The context tree would additionally need to distinguish between project-owned and module-owned occurrences and display them consistently below each context.

Due to the scope of the required changes and the current Designer strategy, a comprehensive implementation is not currently planned. The limitation therefore remains documented as a known issue.

Recommended Solution and Workarounds

Return to a Regular Modularization Structure

The recommended solution is to remove the project-level override and return the affected model to the regular module structure.

In a correctly modularized setup, a model has one clearly defined owner within the module tree. The project itself should not contain another model with the same name. Project-specific changes should be added through modifications or other supported contribution mechanisms instead of replacing the complete model.

To migrate an affected model:

1. Identify the module that should own the model.
2. Compare the model stored in the project with the model provided by that module.
3. Extract the project-specific differences from the project-owned model.
4. Implement these differences as modifications or other regular contributions in a project-specific module.
5. Remove the duplicate model from the project.
6. Ensure that the owning module, the project-specific module, and all other contributing modules are included in the module dependency tree.
7. Run the transpile and verify that the resulting model contains all expected contributions.

For example, assume that a module provides Organisation_entity, while the project contains another Organisation_entity that adds a project-specific valueProcess. A dependent module additionally provides a modification that adds the ORG_ID entity field.

Instead of keeping the complete Organisation_entity directly in the project, the desired structure is:

• the original module remains the owner of Organisation_entity,
• a project-specific module provides a modification for the valueProcess,
• the dependent module continues to provide the modification for ORG_ID,
• the project no longer contains its own Organisation_entity.

Both modifications can then be resolved through the regular module tree, and the Designer no longer has to process a project-level override for this model.

The same structure resolves the entity webservice case. Once the project no longer contains a duplicate entity, the webservice editor has a single entity model to resolve. Project-specific fields provided through regular modifications can then be selected through the Designer interface.

It also resolves the context-tree issue. Once each context, entity, and view has one owner in the module tree, the Designer no longer has to distinguish between duplicate project-owned and module-owned occurrences below the contexts.

tip

Because the project no longer overrides Organisation_entity, updates to the original entity can once again be obtained through the regular module dependency. Bug fixes, new properties, and other compatible enhancements become part of the effective model when the owning module is updated and the project is transpiled again, without requiring the project-owned entity to be synchronized manually.

Copy the transpiled Data Models into the Project

As a last resort, the transpiled data models can be copied from the dist directory into the corresponding model directory of the source project.

The models generated during transpilation already contain the applicable modifications from the module tree. After these resolved models have been copied into the project, the Designer can use their complete content directly and no longer needs to apply the same modifications dynamically to the project-level overrides.

This workaround is intended for cases in which contributions are missing from the project-owned working model. It does not reliably address editors that select the original module model instead of the project-level override. For example, the entity webservice field selection can still resolve the module entity while both definitions exist. Use the regular modularization structure described above for that case.

The same restriction applies to entities and neonViews below a context. Copying transpiled data models into a project that also includes the source modules creates duplicate definitions and can trigger the inconsistent display described above. Do not use this workaround to make project-owned and module-owned variants independently accessible in the context tree.

This workaround should be applied to all data models as one consistent model state. Copying only individual affected models can result in a mixture of models from different resolution states and may introduce additional inconsistencies between related models.

Last-resort workaround

This approach is not recommended as a permanent development workflow.

Copying the transpiled models into the project materializes the current resolved state of the module tree. The copied models then become project-owned models and are no longer updated automatically when their original modules or modifications change.

This introduces several risks:

• updates to modules or modifications are not reflected automatically in the copied models,
• the project models can become outdated compared with the current module tree,
• all data models must be regenerated and copied again after relevant module updates,
• copying only some updated models can create an inconsistent model state,
• manual changes to the copied models may be overwritten when the models are refreshed from dist,
• differences between the copied project models and their original module sources can become difficult to identify and maintain,
• the project increasingly relies on project-level overrides and therefore moves further away from the intended modularization structure.

Use this workaround only when the affected workflow cannot be migrated to the regular module structure and no more sustainable solution is currently available.

A possible procedure is:

1. Ensure that the source project and all module dependencies are in the intended revision.
2. Run a complete transpile.
3. Verify that the generated data models in dist contain the expected modifications.
4. Copy all generated data models from dist into the corresponding directory of the source project.
5. Reload the project in the Designer.
6. Verify that the required fields, properties, services, implementations, and views are now available in the affected editors and previews.