Migrated to MD

This document contains information about the new Filter process introduced in NAE 5.4.0 and the API provided by the application engine for interacting with the instances of this Filter process.

Filter data field

This filter stores a generated elastic query string query as it’s value.

It has two additional properties that store the metadata necessary for the reconstruction of a filter.

• allowedNets - similar to case ref data variable type, a list of identifiers of “allowed nets“ is stored in the filter field. The stored nets represent the nets that can be used to construct search queries with the advanced search component.

• filterMetadata - data necessary for reconstructing the state of the advanced search component. The backend currently does not provide any utility methods for construction of the metadata object. An interface for this object can be found in the documentation.

Note that while a filter field does not throw an error when displayed in editable mode and changes can be made to its frontend representation, these changes are not propagated to backend and do not cause a set data event to fire. Because of this we recommend only using filter fields in visible mode, to display their values set by the frontend filter API.

Neither title nor any other meta attribute of the filter field (such as description) is displayed.

Open

An editable filter field

Open

A visible filter field

Open

Immediate filter field as displayed on a case panel
The full human readable query text is displayed on hover

Filter process

The engine filter process can be located under resources/petriNets/engine-processes/filter.xml

Open

Model of the filter process (until 5.6.0)

Open

Model of the filter process (5.6.0 - 5.6.2)

Open

Model of the filter process (since 5.6.3)

Open

Model of the filter process (since 5.7.0)

The process is relatively simple as it only stores the data necessary for the persistence of filters created by users of the application engine.

The process can be overridden by the developers, by placing a net with the same file name and identifier into the location specified above. The process defines a “process interface” that must remain unchanged when overriding the process for the frontend API that connects to the process to work correctly. Attributes of the process that are part of the “process interface“ and must remain unchanged will be highlighted in red.

Data variables

Filter

an immediate data variable of type filter with id filter.

This field contains the saved filter.

Filter type

an immediate data variable of type enumeration_map with id filter_type.

The available options should have the keys Case and Task. With any associated values.

This data variable stores the type of the filter stored in the filter field of the filter process. The keys are used for filtering of the filter processes.

Filter visibility

an immediate data variable of type enumeration_map with id visibility.

The available options have keys public and private.

This data variable can be used for filtering of the filter processes based on some internal rules. The frontend filter API does not utilize this field for filtering by default.

Origin ViewId

an immediate data variable of type text with id origin_view_id.

The viewId of the view where the filter was created is stored in this data variable.

Filter name

data variable of type text with id new_title.

This data variable is used to change the title of the newly created filter case according to the wishes of the user.

I18n filter name

(since 5.6.0)

an immediate data variable of type enumeration with id i18n_filter_name.

Contains the name of the filter with translations. Is used to generate default configurable group navigation entry titles

Filter case id

TODO: @Jakub Kovář

And me

TODO: @Jakub Kovář

And view

TODO: @Jakub Kovář

TaskRef and parent

TODO: @Jakub Kovář

Trimmed origin view id

TODO: @Jakub Kovář

Is imported

(since 5.7.0)

data variable of type number with id is_imported

This is the reference value for variable arc to decide, if the filter is imported from import filter process or is automatically created from backend.

Is not imported

(since 5.7.0)

data variable of type number with id is_not_imported

This is the reference value for variable arc to decide, if the filter is not imported from import filter process or is automatically created from backend.

Missing allowed nets

(since 5.7.0)

data variable of type text (htmltextarea) with id missing_allowed_nets

The purpose of this textarea is to show list of missing allowed nets for current filter. It is displayed in import_filters transition while importing new filter from xml.

Missing nets translations

(since 5.7.0)

data variable of type enumeration_map with id missing_nets_translation

The purpose of this map filed is to translate message in htmltextarea missing_allowed_nets, because message in textarea is dynamically generated depending on selected locale.

Transitions

The net consists of seven transitions. Set filter metadata and create new filter are used when creating filter from frontend filter API. Automated new is used, when creating filter from backend automatically. Import filter transition is used when importing filters in import_filters process. Last three transitions Details, View filter and View as ancestor are used in displaying filter preview.

Set filter metadata

This transition is executed automatically by the frontend filter API in order to set the necessary filter data into the process instance, when a new filter is created (saved).

(since 5.6.0) It must have the transition ID frontend_create. In previous versions there was no ID constraint.

It must contain 3 data fields that are set via an API request:

• filter

• filter_type

• origin_view_id

As of version NAE 5.5.0 custom set data requests can be sent via the frontend filter API. These requests target this task. Therefore if you want to set additional properties to your newly created filter instances you can do so by adding the necessary data variables to this task and the using the frontend API to set their values.

Create new filter

This transition is displayed to the user in the side menu when a new filter case instance is created (a filter is saved) through the frontend filter API.

It must have the transition ID newFilter.

It can reference any filter data variables. The default implementation references, the filter and its type in visible mode (they were set in the previous step), an editable visibility choice and an editable text field for setting the new filter case title (via a finish action).

Automated new filter

(since 5.6.0)

This transition is executed by the DefaultFiltersRunner, in order to set the data present in the previous two transitions with a single setData operation.

It must have the transition ID auto_create.

It must contain 4 data fields that are set via a setData API call.

• filter

• filter_type

• origin_view_id

• visibility

Details

This transition makes the filter metadata accessible to the users of the application.

View filter

(since 5.6.0)

This transition displays only the filter field and can be taskrefed to show a referenced filter somewhere (such as in the configurable group navigation entries and filter previews).

(since 5.6.3) In addition to the filter field the ancestor filters are displayed here as well. Each of them is prefixed with an AND text to indicate that they are are combined with the original filter with the and operator.

If the root of the filter chain is a filter process (indicate by its origin_view_id field being set to an empty string) this filters content will be the last entry displayed. If the root is a frontend filter the last entry will contain a text indicating the view from which the filter originates. The ID excludes any tab suffixes.

It must have the transition ID view_filter.

It must contain 1 data field:

• filter

View as ancestor

(since 5.6.3)

Contains the same information as the View filter task, but every row is prefixed with an AND text (including the first row).

This task is referenced when resolving ancestor filters from the immediate children of this filter.

Import filter

(since 5.7.0)

This transition is used in import_filters process to allow edit of filter name and filter visibility when importing new filter.

It must have the transition ID import_filter

It should contains at least these data fields to show user which filter is he importing and allow him to change some fundamental filter properties:

• new_title (editable)

• filter_type (visible)

• visibilty (editable)

• filter (visible)

• missing_allowed_nets (visible)

Backend filter API

Since filteres are now implemented as Petriflow processes, they share the same API with any other process. The old filter related services, controllers and other classes have been deprecated in the 5.4.0 release and should no longer be used.

There are a few things to keep in mind however.

Using filter fields for filtering of cases and tasks

You can use the value and other attributes of a filter field to create database queries.

When doing so make sure to check if the filter has the appropriate type (that is only use Case filters to filter cases and Task filters to filter tasks).

The value attribute of a filter field is an elastic query string query (as mentioned above) and cannot be used to filter entries from the Mongo database. It can however be turned into a CaseSearchRequest class instance, by populating the query attribute with the filter field value. This object can then be passed to the ElasticCaseService to find the matching cases. If you want to search for task instances then analogous classes and services exist.

Actions API

Filter fields have only a limited support in the actions API.

Only their value can be changed with the change action and this change is NOT propagated to the other filter field attributes (allowedNets and filterMetadata). Since these two attributes are the important part when restoring an advanced search component state on the frontend it can easily lead to “desynchronisation“ of these values.

Set data method

The set data method of the TaskDataService can be used to modify all the attributes of a filter field. All of them must be set at the same time, any missing attributes will have its value set to null.

DefaultFiltersRunner

(since 5.6.0)

Contains utility methods that can be used to create default system filter process instances. Author of these filters is the system user.

Frontend filter API

Since saved filters are cases you should use the existing API for interacting with cases. Utility methods exist for some operations. You should keep in mind however that, the frontend library does not provide a full filter persistence and management implementation, only the building blocks for creating one, therefore you must implement it on your own according to your wishes. An overview of these building blocks can be found in the following sections.

Filter constants

The enum UserFilterConstants contains identifiers and IDs of all parts of the filter process referenced by the frontend filters API.

UserFiltersService

The UserFiltersService contains the API for saving, loading and deleting filter process instances.

The search component contains buttons that trigger the save and load methods, so you do not have to use this service directly, but if you wish to create your own user interface you can re-use the implementation provided by this service.

Injection tokens are available for the configuration of the side menu components used to save and load filters (NAE_SAVE_FILTER_COMPONENT and NAE_LOAD_FILTER_COMPONENT). An injection token is also available for configuring the filter that filters the filter process instances displayed when loading a filter (NAE_FILTERS_FILTER).

SearchComponent

The SearchComponent is a wrapper for the two search mode components (fulltext and advanced) these components can be used independently of each other and the search component combines them into one and adds various control elements to them.

The search component has two outputs - filterLoaded and filterSaved. These emit data related to either the saved filter, or the selected filter in the load pop-up. The developers must process these outputs in order to implement fully functional filter management.

As of NAE 5.5.0 an additional input is available - additionalFilterData. This input can be used to modify the content of the set data request that is sent by the UserFiltersService, when a new filter is created. This way a less invasive option is available when overriding the default filter process and adding additional metadata necessary for your implementation of filter management.

An injection token is available for the configuration of the search component - NAE_SEARCH_COMPONENT_CONFIGURATION. It provides a SearchComponentConfiguration object that can be used to hide many elements of the search component (buttons mostly). This way you can remove the save and/or load filter buttons and therefore not allow the users to persist filters in the specific view.

SearchService

The SearchService provides two new complementary methods - createPredicateMetadata and loadFromMetadata. These can be used to populate the search service with a predicate stored inside of a filter field (filterMetadata attribute). If an advanced search component is connected to the search service, then it will automatically display the loaded predicate.