Structures

Overview

Structure is an alternative way to retrieve a set of Navigation menu sub-items. Structures serve the same purpose as the enabled in the application's navigation search filters with the main difference that the menu sub-items of a Structure are retrieved dynamically. Structures are more flexible and optimized for any changes, for example, when a new item is added to a specified in the structure data it is automatically retrieved to the application's navigation structure if it matches structure filtering criteria.

Features

Data relevance: once created and configured manually, further the structures are retrieved and maintained automatically by the system. Structures are retrieved dynamically so that any changes in the database or the data source are automatically reflected in structures and result in the latest and up-to-date menu sub-items.
Instant integration: assign the Structure to a Navigation Item for automatic integration in the navigation tree.
Hierarchic arrangement: structure sub-items are arranged and hierarchically organized automatically.
Flexibility: categorize data in the navigation area according to freely definable rules and displayed menu sub-items filtering criteria.

Restrictions

Non-customizable: unlike regular Navigation Items or Search filters, the automatically retrieved sub-items of the menu Structure cannot be manually customized or modified by a regular user and depends entirely on the source of the data for the generated structure and the structure settings defined by the application Administrator.
Single filtering criterion: the structure displays data according to one specific criterion only. This criterion is used to group data into sub-menu items of the structure, for instance, group all services that can be ordered on the portal by service category or group all incidents by all available on the portal incident statuses.

Data source particularities

Structures allow configuring dynamically generated navigation menu structure based on specific data stored locally in the application's database or retrieved from a web service.

Structures are based on a specific data source:

Data Definition: the source of the retrieved data is stored in the Matrix42 platform;
Service operation: processed data is retrieved from a web service which returns a JSON of a strictly defined structure. For details see JSON format section of this page.

The structure is used in the Navigation Item settings and serves as a navigation item's sub-menus in the following way:

Filters: a set of automatically retrieved menu sub-items filtered by specified criteria (do not confuse them with Search filters);
Multi-level sub-menus: automatically retrieved and hierarchically organized menu sub-items.

Structure displaying example: "Locations" Navigation Item with assigned Structure consists of multi-level sub-menus

Configuration steps

Structures are configured in Administration application → User Interface → Navigation Items → Structures → Add structure page by defining:

Data source (mandatory): sub-items can be retrieved to the navigation menu from:
- Data Definition available in the Matrix42 platform;
- Web service that returns data of a specific format and content, that can be processed by the Application.
Data relation (mandatory): specified ASQL expression defines the set of items which are retrieved to the Dataset view of the clicked in the navigation item's structure sub-menu (available for the Data Definition data source only);
Parent (optional): specify an ASQL expression resulting in the source field for the navigation items nesting levels (available for the Data Definition data source only). Displayed data will have a tree structure as a result of the applied composite pattern;
Filter (optional): set ASQL expression is applied to a selected for the Structure Data Definition data source and define which menu sub-items are actually displayed to the end users;
Navigation Item: structure can be assigned to the Navigation Items which are intended for Dataset view displaying.

Creating a Structure

To create a structure in the New Structure form configure the following fields and choose one of the provided data sources for the structure:

Configuration category	Field	Description
General	Name	internally used title of the created structure
General	Description	internally used description of a created structure
Data source	Data Definition	choose from a list of available in the system data definitions. In this case, the source of the data for a structure is stored in the application.
Data source	Service Operation	specify a web service operation name from a list of suggested items. Data is retrieved from a web service, previously saved and configured in the Administration application of the Matrix42 platform. Web service must return a JSON of a strictly defined structure.

Each Structure is based on one specific data source. The follow-up settings differ based on the selected data source.

Data Definition data source

Set up the Item Configuration fields as follows:

Configuration category	Field	Description
Item Configuration	Name	Mandatory: provide an ASQL expression for the selected in the structure settings Data Definition which returns the name of the item. Specified in the name field data is retrieved directly to the navigation menu's structure and shown to the end-users of a corresponding application: The field can contain a simple or a complex ASQL expression: a technical name of an attribute of a specified in the data source Data Definition: FirstName; a combination of attributes from the specified Data Definition class: FirstName + " " + LastName; a complex query which is run for a specified in the structure Data Definition or a Data Definition of the Dataset View used in the Navigation Item.
	Data Relation	A mandatory field which defines the set of items retrieved to the grid of the clicked in the navigation item's structure sub-menu: Specify an ASQL expression which is run against a Data Definition of the Dataset View used in the Navigation Item. The ASQL expression for each data object results in an ID which is compared with the IDs available in a specified for the structure Data Definition. Matched items will be retrieved to the Dataset view as shown on the example.
	Parent	optional field for configuring a hierarchically organized Structure. Specify an ASQL expression that sets up the hierarchical relation between items. The expression is applied to the Data Definition specified as the structure's data source. ASQL expression has to return the ID of the parent item. Such configuration results in the hierarchically organized multi-level sub-menus. Under the hood, the applied ASQL expression initially retrieves a list of all sub-items which do not have a reference to the parent field (is NULL). When a user clicks on the parent sub-item all child items of the subsequent level are retrieved to the navigation structure by a specific parent ID. Structure settings and auto-generated hierarchical structure with specified "Parent" data source Leave the field empty for non-hierarchical data that has no parent-child relation. Structure's sub-menus will be listed on the same level as homogenous menu sub-items: Structure settings and auto-generated structure without specified "Parent" data source Company's organizational structure may serve as an example of a hierarchically organized data. This is a one-to-many parent-child relationship whereby each organizational unit reports to a single organizational unit above them and may have zero or more organizational units below them. This hierarchy can be represented by an appropriate configuration of a "Parent" field and is most suitable when the data to display is stored the way that each record of the data source has a reference to its parent.
	Filter	an optional filter specified as an ASQL expression applied to a selected for the Structure Data Definition data source. Allows retrieving to the navigation menu structure a set of items which match the filtering criteria. Leave empty to list all items of a specified in the structure settings Data Definition in the navigation's structure. For instance, a Navigation Item for Services that can be ordered in the application. Services can be grouped by categories and the configured Structure with empty filter field lists all available service categories as the navigation menu sub-items. Specify an ASQL expression for data filtering. Only items of the Structure's Data Definition which match the logical expression specified here will be shown in the structure. For instance, listing only those service categories, which have assigned services may require an ASQL expression which is run against the specified Data Definition.

Click DONE to save the settings.

Service operation Data source

Service operation settings have only several configurable fields and require a strict format of a returned JSON file.

Configurable fields:

Operation: specify the web operation endpoint from the list of pre-configured in the application web-services.
Data relation: service operation cannot have any common field with the data stored in the application, but this field is mandatory. This field is used as a stub so you can fill out any data to enable the "Save" settings button.
Filter: leave empty to show all sub-items retrieved from the web service or specify filtering criteria for displayed in the structure sub-items. (Unclear format/syntax as it has nothing to do with the database and ASQL filtering).

Service operation settings example

JSON format

Service operation JSON format sample:

"Image": "/SPS/Forms/AttachmentHandler.ashx?FileID=e4037782-8caa-4ddb-ab08-73e179689c92&ObjectID=410d19da-c1b7-4709-ac96-e78210d9eaf0", "Name": "Hardware", "NodeId": "b2916b7b-542a-4a81-88ff-7965a50484e3", "Children": [ { "Parent": "b2916b7b-542a-4a81-88ff-7965a50484e3", "Name": "Computers", "NodeId": "51c247eb-3ba8-46a2-a570-6df869101aea", "Children": [ { "Parent": "51c247eb-3ba8-46a2-a570-6df869101aea", "Name": "Desktops", "NodeId": "5b5ac871-5024-41cd-8b7b-3e8b81f95ae0", "Children": [ ] },

JSON fields and naming

For menu sub-items listed on the same nesting level it is enough to specify:

Name: display name of the menu sub-item in the application's navigation structure;
NodeId: ID of an item to display.

For multi-level menu sub-items specify:

Name: menu sub-item name shown to the application users;
NodeId: ID of a displayed item;
Children: a set of nested sub-menu items;
- Parent: an ID of the parent sub-menu item;
- Name: name to display;
- NodeId: ID of a current item;
- Children: the same set of Parent, Name and NodeId fields for another nesting level in the navigation menu structure.

Assigning a Structure to a Navigation Item

A structure must be assigned to a navigation item in order to be displayed in the application's user interface.

The Structure can be assigned only to a Navigation Item that opens a Dataset View as an action on click and this setting is optional.

To assign a Structure to a Navigation Item:

Open for editing the Navigation Item which opens a Dataset View;
Specify the structure in the Structure field;
SAVE the changes.