doc/UserGuide/src/300_UserFunctions.adoc

[[navigator]]
== Navigation

=== Overview Data Structure
    
The test and measurement data are stored in a hierarchical structure and visualized in the _Navigator_. The top level element(s) in the tree show the "environments", the data belong to.  In every environment, It starts with the top level element "project" and you can drill down to a "test" element and its "measurement" elements by drilling deeper in the storage hierarchy. 

In this section the different levels of the test data storage and navigation will be described. The standard navigation panel uses and provides the structure of the data as stored in the ASAM ODS data source. Alternatively you can choose different navigation structures by using the  _NodeProvider_. 

image::database.png[float="left"] 
**Environment**

The top level element(s) in the tree show the data source(s), the data belong to. 

image::house.png[float="left"]
**Project**

The top level of the data is the "project" level. It's the highest grouping criteria for test data. 

image::paste_plain.png[float="left"] 
**Pool**

The second level for grouping and characterize test data is the "pool" or "subproject level". It's used to categorized and group the tests in a project.



image::brick_add.png[float="left"]
**Test**

The third level is the highest level with test data. A test belongs to a pool and it includes beside test data the so called teststeps. 

image::brick.png[float="left"]
**Teststep**

The fourth level is the teststep level. Usually a teststep is defined for a limited number of measurements. A teststep belongs to a test and it includes beside teststep data the measurement data. 

image::chart_curve.png[float="left"]
**Measurements**

The lowest level of the test data is the measurement level. It includes imported measurement data for a teststep. A measurement belongs to a teststep.

=== Navigator

The _Navigator_ offers the possibility to browse the openMDM data sets. It a tree, which shows the openMDM data structure. The view of data structure in the _Navigator_ is configurable and determined by the chosen Node Provider configuration. The openMDM Client provides a default configuration for the standard openMDM view. This shows the metadata from the connected ODS database in the following hierarchy:

- Project (e.g PMV 2PV or PMV Model P)
- Pool (e.g Engine Noise Measurements or PBN Measurements)
- Test (e.g PBN_UNECE_R51_20190703160224)
- Teststep (e.g PBN_UNECE_R51_Left_Acc_70)
- Measurement (e.g Channel)

image::hierarchicalLevel.png[title="Hierarchical levels in the Navigator"]

In this screenshot the Node Provider "default" is selected.

With the right mouse button (context menu,) you can invoke a menu that offers you a choice of different functions depending on the current context. 

- Refresh: Newly arrived information for the currently selected data object is shown in the navigation tree and in selected view in the right pane of the openMDM web client	.
- Refresh all: Regardless of the current data object, all the newly arrived information is shown in the tree.
- Copy link: Copy the REST URL for the currently selected data object.
- Add to _Shopping Basket_: Storage of the currently selected data object (multiple selection possible) in the _Shopping Basket_.

image::contextMenu.png[title="Context menu in the Navigator"]
// TODO Alternative screenshot with "Save File" contextMenu_WithSaveFile.png

[[search]]
== Search

In the second tab in the right pane of the openMDM web client is the _MDM Search_. The _MDM Search_ consists of three areas:

- Full Text Search: search for a (sub) string in the metadata. Can be combined with the advanced search.
- Advanced search: Search using multiple attributes. Named search filters can be created and updated for reuse or be deleted .
- Criteria: select search filter, source and result type for a search.

- Results: show search results in a result view.

image::search_simple_init.png[title="MDM Search"]


=== Defining the scope of a search via Criteria selection

With the criteria selection you can define the scope of your search by different options:

**Search filter (for Advanced Search only)**: Select a named search filter. 
A search filter definition contains search attributes and can be reused.
If a filter is selected then its search attributes are available in the Advanced Search area. 

[[Source]]
**Source**: If you have multiple data sources, you can select one or more the search will be executed on.  A multiple selection of environments is possible.

**Result type**: You can select the result type. The following types are available:

* Test
* Teststep
* Measurement

NOTE: When choosing a teststep or measurement as result type you should configure accordingly teststep or measurement specific attributes in your result list.

=== Full Text Search

The full text search (like Google text search) in one text field. You can search for a (sub) string or text in the metadata. The criteria "Source" and "Result type" define the scope of the search. 

You can define a more sophisticated search using the available operators. These operators are described as tool tip text in the search text field. 

image::search_fulltext_operator.png[title="Search with * operator"]

The full text search can be executed stand alone or in combination with the advances search, depending on the check box  _Advanced Search_ inactivated or activated.    

[[advanced_search]]
=== Advanced Search (Attribute Based Search)

For the Advanced Search activate the _Advanced Search_ check box and expand the Advanced Search area. 

IMPORTANT: The button "Search" on the right hand side of the Full Text Search starts all types to searches, even if the text filed is empty.

[[define_attributes]]
==== Define an attribute based search

image::new.png[float="left"] 
Create a new filter and select your attributes by opening the View Editor via this button. +

image::select_attributes.png[title="Select attributes in View Editor"] 

In the Advanced Search you can see the selected attributes:

image::search_advanced_init.png[title="Attributes in the Advanced Search"]

If you select an attribute which is part of all selected environments (see <<Source,Source>>) then the attribute is an so called global search attribute. The search with a global attribute is executed in all environments.

If you select an attribute which isn't part of all selected environments then the attribute is an environment specific attribute and the search is executed in the related environments only.

The Advanced Search area contains the following elements (in each row):

* **Attributes**: These first two columns contain the names of the data object and the object attribute. 

* **Operators**: Operators for the attribute and their search criteria can be set in this column. The operators should be self-explanatory.

* **Value**: Search values are entered here. 

* **Remove Button**: This button remove the selected row form the advanced search. 




==== Use, create, update or delete an existing filter 

* *Create a new filter*: +
<<define_attributes, Define attributes>>.  For reuse you can save and name the search filter using the _Save search filter_ button. You can assign a new name or override an existing filter by choosing the dedicated filter name. 
* *Use an existing filter*: +
Select a Search Filter in the _Search Filter_ drop down box. Activate the Advanced Search check box.
* *Update an existing filter*: +
Select a Search Filter in the _Search Filter_ drop down box. Make your changes by opening the View Editor with the _Edit search filter_ button. You can assign a new name or override an existing filter by choosing the dedicated filter name. Then use the _Save view_ button. You can assign a new name or override an existing filter by choosing the dedicated filter name.
* *Delete an existing filter:* +
Select a Search Filter in the _Search Filter_ drop down box. Use the _Delete search filter_ button.


==== Do the search

For the advanced search you have: 

* to fill the values for the defined attributed
* to define the operator (=, < , > , like)
* optionally: fill the search text field
* to define your data source(s)
* to choose the result type

Use the button "Search" on the right hand side of the Full Text Search.

image::mdmSearch.png[title="MDM Search"]

IMPORTANT: Don't forget to reset the filter criteria, if you want to execute a new (different) search.

[[result_data]]
=== Search Result

Using the buttons in the upper left area of the result area, you can select an existing result-view, create a new view or edit, save and delete existing views with <<view-editor, View Editor>>.

Using the buttons in the upper right result area, you can clear the search results or add selected search results to the _Shopping Basket_.

image::shoppingBasket_init.png[title="Add result to Shopping Basket"]

[[shopping_basket]]
== Shopping Basket 

Store data objects such as projects, pools, tests, teststeps, measurements etc. for further processing.

=== Collect data in the Shopping Basket

The _Shopping Basket_ is located in the lower left area of the openMDM web client. It is a container for data objects. Any data objects can be selected in the _Navigator_ (multiple selection is possible) and placed per context menu in the _Shopping Basket_, to use them as selection for further processing with other openMDM components.

image::shoppingBasket.png[title="Storage of data in the Shopping Basket"]

Using the buttons in the upper left area of the area, you can create new views, edit existing views with <<view-editor, the View Editor>>, save edited views or delete existing views. 
The procedure is similar to that described <<advanced_search, here.>>

[[shopping_basket_data]]
=== Exporting data from the Shopping Basket (ATFX)

Using the buttons in the upper right area of the view, you can clear, download, upload, open or save data of the _Shopping Basket_.

[cols="a,6"]
|===
|Icons |Description 

a|image::downloadSB.png[]
|You can download **content** of the selected objects in the shopping basket using as ATFx file.

a|image::downloadDiffFormats.png[]
|You can download the **data** of the selected objects in the shopping basket using in the selected data format (e.g. ATFx).

|===


[[view-editor]]
== View editor

    Notiz BMW: Diese Funktionalität muss evtl. im Client vereinfacht werden (verständlich für einen Anfänger).

With this editor you can create new search filters, edit existing search filters, create new views for search results or _Shopping Basket_ and edit existing views for search results or _Shopping Basket_.    

image::editView.png[float="left"]
image::new.png[float="left"]

With click on the one of this buttons starts the View Editor dialog.
 
image::templatesEditor.png[title="View Editor"]

You can search for elements via the search field:

image::view_editor_search.png[title="View Editor search"]

The procedure is always similar, see as e.g.  <<advanced_search, here.>>

[[detail_viewer]]
== View data (Detail Viewer)

In the first tab in the right pane of the openMDM web client is the _Details_. It responds to the selection within the _Navigator_. The component _Details_ has 5 tabs.

- General
- Unit Under Test
- Test Sequence
- Test Equipment
- Sensors

    Notiz (BMW): bzgl. Bulletpoints:
    Sollten wir in der GUI evtl. intuitiver gestalten (weil ein Anwender vielleicht nichts von UUT, TS, TE weiß)

image::detailsGeneral.png[title="Metadata in the Details"]

The first tab is called the General. It shows the attributes (= metadata) of the currently selected data object in the _Navigator_. If selected data object in the _Navigator_ isn't a Test or a Teststep or a Measurement then shows only the metadata without any tab.

If selected data object in the _Navigator_ is a Test or a Teststep or a Measurement then all 5 tabs are visible. 

image::detailsSequence.png[title="Test sequence tab in the Details"]

In next 4 tabs you can edit the single attribute values. 

[[visualize_data]]
== Visualize data

[[quick_viewer]]
=== Quick Viewer

The component _Quick Viewer_ is a simpler version of _X/Y Chart Viewer_ with the possibility to switch between graphically or tabular view of channel values.

image::quickViewer.png[title="Quick Viewer"]

[[xychart_viewer]]
=== X/Y Chart Viewer

The _X/Y Chart Viewer_ represents the data of measurements in different views. This includes the graphical and tabular view of channel values. 

You can view one or more ChannelGroups, these are shown in the ChannelGroup selection panel. Each channel of a channel group has an associated axis type. If the axis type of a channel is y-axis, this channel is listed in the Y-Channel selection panel. If the type is x-axis, it is listed in the X-Channel selection panel. If the type is x/y-axis, it is listed in both, the Y-Channel and the X-Channel selection panel.

The following figure shows the general structure of the _X/Y Chart Viewer_ on the basis of example data (= Channel).

image::xyChartViewer.png[title="Structure of the X/Y Chart Viewer"]

==== Component bar

Different push buttons are located here to control the display in the upper right pane of the dialog (e.g. chart, data table, legend, decimal points, etc.)

==== Chart

By the selection of this button starts graphically view of channel values. All another functionalities of Component bar, Selection panel and Option panel are considered for this view.

===== Table

By the selection of this button starts tabular view of channel values. This view has only the page-navigation and the selection for number of lines.

[cols="a,8"]
|===
|Icons |Description 

a|image::hideSelectionPanel.png[]
|For hide the Selection panel. It's possible if the Selection panel is visible.

a|image::showSelectionPanel.png[]
|For show the Selection panel. It's possible if the Selection panel is not visible.

a|image::filterChannelOptions.png[]
|For filter channel options by axis-type.

a|image::provideChannelOptions.png[]
|For provide all channel options.

a|image::hideChartLegend.png[]
|For hide the chart legends of graphical representation of data.

a|image::showChartLegend.png[]
|For show the chart legends of graphical representation of data.

a|image::hideLines.png[]
|For hide the data as graphical representation. 

a|image::showLines.png[]
|For show the data as graphical representation. 

a|image::fillArea.png[]
|For fill the area underneath the graph.

a|image::clearArea.png[]
|For clear the area underneath the graph.

a|image::hideDataPoints.png[]
|For hide the data points in the data lines.

a|image::markDataPoints.png[]
|For mark the data points in the data lines.

a|image::cbSettings.png[]
|Settings for width of data line or data line tension.

|===


==== Selection panel

This panel is used to select the channels to be displayed. It consists of three areas. Channel-filtering with regular expressions is possible for the Channel Group and Y-Channel. 

===== Channel Group

The upper area contains all currently available measurements to the data object selected in the _Navigator_. 

===== Y-Channel

The middle area contains all of the channels that can be used as Y-axis, as well as its display unit. A multiple selection of Y-axes is possible.

===== X-Channel

The area below contains all the available X-axis of the measurement. As X-axis you can only select one channel.

==== Data display

In this dialog area, the selected channels are displayed. This can be done either graphically or in tabular form. A right-click menu provides additional functions.

==== Option panel

Settings for graphic values (size of X-axis, step size etc.).


[[export_files]]
== Export / Import data

=== Attach external files

You can attach external files (such as drawings, descriptions, evaluations, etc.) to the data objects in the hierarchy levels test, test step and measurements. This is done via the tab _Files_ of the openMDM Web Client. The view File attachments appears as an tab in the right pane of the openMDM web client.

image::documents.png[title="File attachments"]

Using the buttons in the upper right area of the view, you can upload new files and/or download, update, preview or delete existing files.

=== Shopping basket

Data results collected in the Shopping Basket can be :downloaded, e.g. as ATFX. These files can be also uploaded.
The data can be saved in the application with a specific named and opened again. Result entries can be cleared.
See <<shopping_basket_data, here>>.