34 posts tagged with "migration-guide"

Migration guide​

@imports anchor​

Some expanders have been migrated to the new import system, see changelog for the list. This means that feature anchor for imports are no longer necessary and hence they have been removed. To add imports in these files you can add uses statements to the feature expander.

Name changes​

Some services have changed name to better comply to the guidelines or to better describe the functionality. This reflects in custom imports and need to be checked.

• dataConnector.service -> DataConnector-data-access.service
• dataConnector.datasource -> DataConnector-data-source.service
• dataConnector.filtersource -> DataConnector-filter-source.service
• dataConnector-infinite.datasource -> DataConnector-infinite-data-source.service
• .data models have been changed to .document.

Moved service injection location​

Instead of injection services in the constructor they are now injected as variables. This is also done using the new import system, which makes it easier to maintain. See changelog for the list of affected files. It also changed some of the injected names used:

• dataSource -> dataConnectorDataSource
• filterSource -> dataConnectorFilterSource
• route -> activatedRoute
• translate -> translateService

Mapping location change​

DataConnector models are not mapped in the DataConnector-data-access.service anymore, but have there dedicated mapping services now. If any customizations were added to these mappings, then the corresponding harvest code needs to be moved to the new mapping services.

Removed shared components​

The DropdownComponent and MultiSelectDropdownComponent have been removed and the use has been replaced with the select component from ngx-ns-core.

Default translation file​

The default translation file has changed from en.json5 to gen.json5. This one is used by default, but can be replaced with a custom one by using option angular.defaultLanguage on AngularApp. You should change the name of the harvest file to keep custom translations.

Functional key -> id​

In this version a refactoring has been done to not rely on functional key of the DataElement as a variable anymore, but use a generic id name. This impacts routes and method arguments.

Routes​

In places where you retrieve the id from the route, the name of the variable should be changed.

const id = this.activatedRoute.snapshot
    .paramMap.get('externalId');'

const id = this.activatedRoute.snapshot
    .paramMap.get('id');

Method arguments​

The method interface has been altered in places where the id of an element is needed to use id instead of functional key. This has been done to better comply to the id and displayLabel field added to all element models. This can be used with duck typing as well now.

getSingle({ uuid }: { uuid: string }): Observable<DemoElementModel>

getSingle({ id }: { id: string }): Observable<DemoElementModel>

Changes and improvements​

QueryValueType​

The QueryValueType enumeration is used to indicate the type of an object passed to a query constraint. Usually a developer will not interact with this, as every constraint factory method that takes it as a parameter, also comes with a variant that does not. In the latter case, the type will be inferred from the object that is passed to the constraint. This can only be inferred for known types, which is mostly primitives and java.util.Date.

As a default, when not recognized, the type would automatically be set to String, resulting into a conversion of the object to String in supporting constraints. With this update the type QueryValueType.OBJECT was added which handles the supplied object as a raw value that is passed directly into JPA, as this is sometimes desired.

Since converting to String is typically not intended behavior for objects that are not of that type, the default when a type cannot be determined is now QueryValueType.OBJECT. This is a breaking change, but should have very little impact, as currently, cases where unknown object types are passed to a constraint are likely to be unintended. In cases where this is intended, the migration guide will explain how to resolve this in the new implementation.

In the past six months we've seen adoption of the process-automation component. Feedback has been great and people seem to be happy with the changes we made. We felt the current feature set came to a point where it warrants a first stable release. This of course does not mean development will stop here, as there are many features we still plan to add.

Resources​

Feature set summary​

The list below should give you a good idea of the features we currently support through process-automation:

• Fully supports the workflow model.
  • Integrates all defined transitions, including branching transitions.
  • Respects configuration on TaskElements, such as transactionType and TaskOutcomes.
  • Supports configuring WorkflowImplementation through defining QueuedProcessors.
• Multi-node or multi-instance configurations are supported.
  • Internal state-machine to perform leader-election in the presence of multiple nodes.
  • Ensures smooth execution of transitions, with no conflicting state.
  • Improved scalability by providing extensible queue configurations.
• Event-based execution model, backed by a queue.
  • CRUD triggers: transition an element on create or modify.
  • Transition trigger: immediately queue the next transition after another completes.
  • DataCommand trigger: transition an element when a command is performed.
  • Schedule trigger: Cron-like configuration for time-based transitions.
  • FlowEngine trigger: behaves similar to the classic Flow implementation.
• Modular design, ships with standard configurations and can be extended easily.
  • Provided queue implementations: ApplicationPersistence (DB) and InMemory.
  • Provided processing implementations: Asynchronous and ExecutorService.

Migration guide available in full post... (Read more)

Migration guide​

Branding​

Using the option angular.hasCustomBranding we can toggle the default nsx branding off and have custom anchors instead.

Customization​

Option angular.hasCustomHeaderContent can be used to turn off the default expanded behaviour of the top bar. With the option angular.hasCustomTableRowActions on a DataView you can have custom anchors instead of the default actions in a table.

Ngx-ns-core update​

The size of the runtime library was getting to big for the application's initial load. For this reason the library has been split up in smaller sub-entries, which improves load times and tree-shaking. However, this changed the imports for these runtime components and services.

import { AlertService } from '@nsx/ngx-ns-core'

import { AlertService } from '@nsx/ngx-ns-core/alert'

Changes and improvements​

This update contains a lot of improvements for wiring capabilities, making it easier to reuse expanded elements in custom pages.

List page refactored​

The expanded list page has been updated to use the new table with multi sort capabilities. The table is extracted from the page component and resides in its separate DataViewTable component. It now uses the upgraded filter component, that is generated based on the QuerySearch setup. Filtering state between the ngx-ns-core component and the generated dropdown form is managed by the new DataConnectorFilterSource service. Instead of managing the pagination, filtering and sorting manually in the list component, a DataConnectorDataSource service has been introduced to make this easier.

Table refactored​

Breaking change: Existing components nsx-table, nsx-table-column and directive [nsxTableCell] have been replaced with counterparts from the ngx-ns-core library.

The table now has multi sort capabilities, supports sticky headers and columns, and accepts a NscDataSource as well as data arrays.

Paginator refactored​

Breaking change: Existing component nsx-paginator has been replaced with counterpart from the ngx-ns-core library.

Filter refactored​

Breaking change: Existing component nsx-table-search has been replaced with counterpart from the ngx-ns-core library. The filtering capabilities have been upgraded.

Changes and improvements​

Upgrade to Angular 17 and Angular Material 17​

In the previous release (4.1.x) we upgraded to from Angular 14 to 16, but used legacy Angular Material 14 components. Now we have upgraded completely to the latest 17 version.

Breadcrumbs refactored​

Breaking change: in routing change name and isBreadcrumb data entries to breadcrumb. The former is replaced by breadcrumb and the latter has become obsolete.

Styling setup refactored​

Breaking change: _theme-to-material-component-exposer.scss has been replaced with _theme-to-component-exposer.scss. Material expose mixin _theme-to-css-classes-exposer.scss has been deleted. Behaviour can be re-added custom if wanted.

Switch to Material symbols​

We switched to Material symbols instead of Material icons as default icon font set.

Added use of Angular library​

Created the ngx-ns-core library containing runtime components, services and directives. Some of the expanded components and services have already been migrated, e.g. sidebar, top-bar, breadcrumbs, etc.

Changes and improvements​

Migrating to QuerySearch metamodel​

Since version 3.x of rest-expanders, which was released just over a year ago, rest-expanders has integrated with querysearch-expanders by using the QuerySearch metamodel. This was introduced in such a way that it was 100% backwards compatible and also added to the model when expanding implicitly, so no change could really be observed from the perspective of an application developer.

Today the QuerySearch metamodel has matured to the point that what currently exists of the model is stable and will no longer have any big structural changes that are not additive. So with this version of rest-expanders, the implicitly added model will be removed. This means that it has to be defined in the model by the developer and coupled to the rest-expanders using the relevant jaxrs.querySearch option that has been implicitly used for quite some time.

The transmuters to add default REST APIs to the model have been modified to do this automatically, so in that sense, there will be no change to the way of interacting with rest-expanders in the majority of cases.

DataCommand options​

In rest-expanders version 3.8.0, options were introduced to mark the DataCommands that are to be used for the CRUD operations in the REST API. Starting with this version, the validation to check if this has been migrated has been removed, as well as them being implicitly added to the model. We assume that every project has been migrated by now, but this will be the last version where the Upgrade transmutation for rest-expanders does this migration automatically.

This version of the expanders updates the groupId of all Maven modules in the expanded application project, to be more consistent and configurable.

Resources​

The expansion resources below provide Expanders 5.35.1.

Changes and improvements​

Maven groupIds​

In the past, all modules in the application project had the groupId org.normalizedsystems, except for the ear file module, which was org.normalized. To finally bring some consistency into this and differentiate them from those in other applications (to avoid collisions between base-component artifacts), this has now been changed.

The new groupId is now uniform across the entire project and is specifically org.normalizedsystems with the application shortname added after it in lowercase. So for shortname testApp it is org.normalizedsystems.testapp.

These new groupIds are merely the default settings though, it can now be configured with the application option maven.groupId, for which the value will be used as the groupId instead.

PascalCase for expander templating​

We've now added PascalCase as a format for all engines in the expander framework, the same way it is available for other formats.

We have been hard at work on the process automation component, which supersedes the workflow component.

Resources​

Workflow model​

The first step is moving away from database config into the model. The workflow model allows you to define all workflows statically. It also provides bindings for the workflow component such that it automatically updates the database configuration when changes are made to the model. Having the information in the model also gives the MicroRadiant the ability to visualize your workflows.

We also provide a tool for importing existing database configuration into the model.

Process automation component​

A preview release is now available for the new process automation component!

The component is a new approach to workflows, designed with more flexibility in mind. The key distinction is queue based processing, where the previous component could only handle timed polling. This means we can now start supporting a wide range of triggers, such as CRUD events, transitions, cron schedules and even the flow engines you're already familiar with.

Migration​

Migration can be quite involved depending on the current state of your application. To ease the difficulty, we provide a migration guide with smaller steps so applications can incrementally adopt the new component.

It is recommended for all applications to at least perform Step 1 (workflow model) and Step 2 (task outcome model). This will already give some advantages like model-based configuration and makes it easier to adopt process automation on a stable release.

This version of the expanders introduces improved support for imports in Expanders.

Resources​

The expansion resources below provide Expanders 5.33.2.

Changes and improvements​

Better support of Imports in mapping files​

The mapping file syntax has been extended with 2 new keywords: artifact and uses.

Mapping files often had a separate list statement to resolve imports:

<mapping xmlns="https://schemas.normalizedsystems.org/xsd/expanders/2023/0/0/mapping">
  <list name="valueTypes"
        eval="finder.fieldOperatorPairs.{ field }.{? valueField neq null }.{ javaType }"
        param="javaType" unique="javaType">
    <filter name="requiresImport" eval="javaType.requiresImport()"/>
    <value name="qualifiedType" eval="javaType.qualifiedTypeName"/>
  </list>
  <list name="fields" eval="finder.fieldOperatorPairs"
          param="fieldOperatorPair" filter="fieldOperatorPair.field neq null">
    <let name="field" eval="fieldOperatorPair.field"/>
    <value name="name" eval="field.name"/>
    <!-- ... -->
  </list>
  <!-- ... -->
</mapping>

This can be replaced by adding uses statements for the imported classes. The artifact definition describes which import resolver to use.

<mapping xmlns="https://schemas.normalizedsystems.org/xsd/expanders/2023/1/0/mapping">
  <artifact this="classBuilder.from(finder).qualifiedName + 'Details'" importStrategy="java"/>
  <list name="fields" eval="finder.fieldOperatorPairs"
          param="fieldOperatorPair" filter="fieldOperatorPair.field neq null">
    <let name="field" eval="fieldOperatorPair.field"/>
    <value name="name" eval="field.name"/>
    <uses eval="field.javaType"/>
    <!-- ... -->
  </list>
  <!-- ... -->
</mapping>

The imports can then be inserted into the template with @imports:

base() ::= <<
package <dataElement.type.packageName>;

// <expanderComment>

// anchor:imports:start
@imports
// anchor:imports:end
@anchor:imports
...
>>

Check out the article to learn more.