Migrated to MD

This guide is aimed at developers that wish to know the implementation detail so the configurable group navigation, so that they may interact with or override its functionality. If you are a user and wish to know how to use the options available to you read the User guide instead.

Overview

The configurable group navigation consists of 3 engine processes that interact with each other in order to create the necessary configuration.

• Group process - contains the task that configures the menu

• Filter process - stores the saved filters

• Preference filter item - creates an M:N mapping between filters and groups and holds the information about the individual navigation entries

A new runner - DefaultFiltersRunner - has been introduced in order to create the instances of the default filters. Whenever a new group instance is created, its navigation is configured in such a way that it contains the default filters, with their case icons set as the entry icons and their names set as the entry names.

Processes

Group process

The frontend gets its data regarding the group navigation from a task in the group process. This task must always be available, otherwise the frontend won’t be able to get the necessary data and the navigation entries will not be generated. The ID of this task must be navigationMenuConfig as this is the ID search for by the frontend. An enum - GroupNavigationConstants - exists in the application-engine frontend library, that contains the identifiers of all group navigation fields referenced by the frontend application.

This task must contain a task ref with all the preference filter item process instances in order for the frountend to parse the value correctly.

Filter process

Consult the Filter processes guide for information regarding the filter process.

The filter process contains an enumeration field with ID i18n_filter_name. This field can contain translations as its value and its value is used to set the initial value of the navigation entry name. This way default translations of the default configurable group navigation entries can be set.

Preference filter item process

Each instance of this process represents a navigation menu item in one group. This way if a referenced filter process instance changes its filter all the menu items referencing it will automatically update themselves to reference the new filter value. Furthermore the same filter can be displayed in multiple groups under different names and with different icons independent of each other.

Most of the data variables in this net must maintain their IDs, otherwise the frontend won’t be able to parse the data contained within.

The navigation entry contains two fields that hold the title:

• an enumeration field entry_name - this field contains the I18n value with all the translations and is used to generate the text displayed in the navigation menu entry

• a text field entry_default_name - this field is displayed to the user and allows the editing of the entry name. Its set action changes the entry_name value to a new I18nString with the value of this field set as the default translation.

Currently it is impossible for users of the application to set I18n navigation entry names. This feature will be available in a future release, but in the meantime it can be accomplished either by overriding the preference_filter_item process, or by setting the value with custom actions in some way.

Role authorizations, fields and formats

This process holds information about process roles which can or cannot view current menu entry. They are saved in a MultichoiceMap fields allowed_roles and banned_roles.

Each of their entries has following format:

• String key “ROLE_IMPORT_ID:NET_IMPORT_ID“ (Example: “loan_officer:mortgage”)

• I18nString value “ROLE_NAME (NET_TITLE)" (Example: “Loan Officer (Mortgage )“

Role authorization functionality is provided by ConfigurableMenuService.java class.

When user wants to add new roles to either list, he should select a process from EnumerationMap field processes_available.

• This fields options are created during its GET event. Only those processes (and their versions) whose author is equal to currently logged user are added.

• Each entry has format:

  • String key “NET_IMPORT_ID:MAJORVERSION-MINORVERSION-PATCH“ (Example: “mortgage:1-0-0”)

    • Version string needs to be part of key in order to have unique keys for different versions of the same process

    • Dots in version string are replaced by hyphens “-“ because Mongo doesn’t allow dots in Map keys)

  • I18nString value “NET_TITLE:VERSIONSTRING“ (Example: “Mortgage :1.0.0“)

After the process is selected, MultichoiceMap field roles_availablegets its options updated. Each entry represents a role from selected process which has not been already added to allowed_roles or banned_roles (regardless of its process version) and its format is following:

• String key “ROLE_IMPORT_ID:NET_IMPORT_ID“ (Example: “loan_officer:mortgage”)

• I18nString value “ROLE_NAME" (Example: “Loan Officer“)

Default filters

The DefaultFiltersRunner creates instances of the default filter processes. These are set as navigation menu entries of newly created groups.

The runner class contains utility methods that can be used to create default filter process instances in a slightly friendlier way. The default filters must have different case titles, as these are used to determine if the filters were already created - a filter with the same name as an existing filter (created by the system user) will not be created.

Frontend

Routing configuration

The configurable group navigation can work both with dynamic routing generated by the Netgrif library, as well as with static routing declared by the developer. The configuration necessary to make it work differs slightly in these scenarios. The aim of this section is to provide instructions for using both setups.

Auto-generated dynamic routing

A special view - groupNavigation - should be declared in nae.json that tells the application where in the navigation tree should the configurable navigation entries be inserted. It can be located anywhere in the tree but must declare a route for the entry. This route fragment will be used to generate the full path just as with any regular view.

Since this entry itself serves only as a marker for the dynamic navigation generation it should not have a navigation entry on its own.

Custom routing

If the custom routing is used with the auto-generated dynamic navigation, then a groupNavigation view must be declared in nae.json, same as in the previous section. This view will only be used to generate the navigation entry and the routing link this entry redirects to - no routing will be configured.

Routing must then be configured with the following entry:

the filterCaseId path attribute is shown only for clarity. We recommend using its constant - GroupNavigationConstants.GROUP_NAVIGATION_ROUTER_PARAM instead.

The mapped component can differ if the developer wishes to override the component resolution behavior. If overriding the component resolution is the goal more information can be found in the following section.

The AuthenticationGuardService should be used to restrict access to the view, since it uses backend requests to get the necessary navigation information and therefore requires the user to be authenticated.

Using non-dynamic views

If your application contains views that are not generated by the dynamic navigation and you want to allow users to save and re-use filters created in these views you must ensure certain properties of these views.

Dynamic views created from saved filters can load their entire filter history in order to restore a complete reproduction of the saved filter. If the filter originates from a default filter process this restoration does not need any help from the developer. If however the filter originates from a view with a filter that is only declared on the frontend some help is required.

The FilterRepository service must contain the filters of each view that can serve as a filter origin. The ID of these filters must match the viewId of these views, excluding the suffix that is automatically added by the tabbed view. If this requirement is not met an error will be logged and an empty filter will be loaded instead, which may result in incorrect results being displayed to the application users.

Overriding group navigation view components

The configurable group navigation can contain task or case filters as its entries.

By default if a task filter entry is selected a simple task view with the selected filter will be displayed.

If a case filter entry is selected a tabbed case view with the selected filter will be displayed and clicking on case panels will open new tabs with tabbed task views.

This behavior mimics the behavior of case and task views generated by our schematics.

The components used to display these views are taken from the components library, but can be overridden in your application.

All navigation entries are mapped to a single component - the GroupNavigationComponentResolverComponent, this component then resolves the appropriate view based on the navigation entry data.

The NAE_GROUP_NAVIGATION_COMPONENT_RESOLVER_COMPONENT injection token can be used to provide a different component to serve as the resolver. Alternatively you can extend the AbstractGroupNavigationComponentResolverComponent and re-use its functionality and only provide a different implementation of the GroupNavigationComponentResolverService.

The components used to display the navigation entry filters must be able to set their search categories, their allowed nets and their filter from the entry task data.

Provider factory methods for this extraction are available in our libraries.

Category and Allowed nets inheritance

Filter data variables contain metadata that include both the allowed nets and the available search categories. These data must be provided in order for the component to display the filter correctly.

When a filter is set as a menu item it transfers its allowed nets and enabled search categories to the view it defines.

Whether this behavior is active, or not depends on the metadata properties:

• defaultSearchCategories - if true the filter will merge its categories with the default search categories of the appropriate type. The default search categories are injected using the NAE_DEFAULT_CASE_SEARCH_CATEGORIES and NAE_DEFAULT_TASK_SEARCH_CATEGORIES injection tokens.

• inheritAllowedNets - if true the allowed nets set in the filter metadata will be merged with the allowed nets provided by the BaseAllowedNetsService.

Allowed nets and enabled search categories can therefore be determined for each of the default filters in the runner, or for any other filter with actions. Alternatively inheritance can be used to provide the same behavior in all of the views without the need to duplicate the information in multiple filters.

The default engine implementation saves filters with both of these metadata options set to true. This behavior can be overridden by changing the settings in the NAE_SEARCH_COMPONENT_CONFIGURATION injection token.