32 posts tagged with "migration-guide"

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.

In this release of Expanders, we've cleaned up some long-deprecated code that still uses UserContext as the main context transport object. There's also been several improvements in the infrastructure to improve ease of use for functional keys.

Resources​

The expansion resources below provide Expanders 5.32.0.

Changes and improvements​

Functional key infrastructure​

FinderResolver​

A new class FinderResolver has been introduced, which is called from the Bean.find() method in the logic layer. This class will automatically resolve the DataRefs for any field operator pairs that target link fields. Resolving means that it will resolve the DataRef against the database in case there's no database identifier present in it. While much of the methods in the stack already did this, the finders still did not, which often caused some confusion. The finder would not work as intended if the database identifier was not present in the DataRefs. This resolution will only occur if there is no database identifier in the DataRef, so the impact on performance should be negligible in existing code.

Agent.getDetails()​

The Agent.getDetails(DataRef) method did not behave quite the same as LocalAgent.getDetails(DataRef). Even though the same code was called down the line, the way it worked on the remote agent would lose all information in the DataRef except for the database identifier. This meant that it had to be resolved prior to use. This issue has now been resolved as well, by having it call getProjection() instead, just like its LocalAgent counterpart.

Context transport​

In a distant past, there was no Context class, rather the only context was UserContext ans it was used to pass all context information. This has been replaced for years in favor of the Context class and the UserContext has since only been used for actual information about the user. Therefore, we've started removing a lot of this deprecated infrastructure that still relied on UserContext where Context should be used instead. Some of these methods include Agent.getAgent(UserContext) and LocalAgent.getLocalAgent().

Deprecating old methods​

We intend to remove a lot of clutter that has been created in the stack over the years, with methods for backwards compatibility that should no longer be used. We've started marking many of these methods as deprecated for removal, so it is already clear to developers that these should not be used in new code and should be refactored if they are still in use in older code. A prime example of these are methods in the stack that still use a database identifier as a Long parameter, rather than a DataRef. We'll be marking more of these as deprecated in future releases.

Typed finders​

The typed finders system is now the default for all applications. The option finders.enableTypedFinders is now no longer required. Typed finders means that generics are used through the stack for finders, to ensure that the compiler will verify that they are not used with infrastructure of the wrong DataElement. It also changes the FinderBean to use mapped method references for the finder implementations, rather than reflection. This means that it is no longer possible to defined custom finders that are not present in the model.

Changes and improvements​

2 new ValueTypes have been added: VarText and EmailAddresses.

• VarText is text of variable length. It is similar to Text, but adds nativeTypes for the SQL-expanders, so that the columns are correctly initialized.
• EmailAddresses extends VarText. It expects a comma-separated list of e-mail addresses.