doc/GettingStartedGuide/src/070_installApplication.adoc

== Install, deploy and configure application

For deployment, you need the build artefact: +
org.eclipse.mdm.nucleus-<version>.war

This file is an element of the file: openMDM_application-<version>.zip

Get this file from:

. the Project Download Page: https://projects.eclipse.org/projects/technology.mdmbl/downloads
. or from your build:
/org.eclipse.mdm/build/distributions/

The ZIP archive contains:

* the backend org.eclipse.mdm.nucleus-VERSION.war
* the configurations in /configuration
* sql scripts for the User Preference Service in /schema.


=== Configuration Files

Copy the content of the extracted /configuration folder to: +
`$GLASSFISH_ROOT/glassfish/domains/domain1/config`

**Configuration file - global.properties:** + 
`org.eclipse.mdm/nucleus/property/src/main/configuration/global.properties` +

To enable globally the freetext search set the parameter: +
`freetext.active=true`, 
if enabled, make sure: 

* that ElasticSearch is started and that the port in the property elasticsearch.url is set correct (check it in the ElasticSearch log and  via your browser with the url and port, the result should be a json response) 
* the freetext parameters are set in the service.xml
* freetext search is active for at least one service

**Configuration file - service.xml:** + 
`org.eclipse.mdm/nucleus/connector/src/main/configuration/service.xml` 

* configure the data sources, for ODS Servers look into your ODS Server log file to determine the corba URL
* To use the freetext search configure for each datasource separately:
** specific parameters for the NotificationService and the freetext search
** set the freetext.active parameter to true (Example2)
** disable the freetext search for a datasource:
** set the freetext.active parameter to false (Example3) +
**or**
** leave away the freetext.* parameters, as they are optional (Example1)


 <services>
 <!-- Example1: ODS Server without freetext.* parameters -> freetext search is not active -->
 <service entityManagerFactoryClass="org.eclipse.mdm.api.odsadapter.ODSContextFactory">
	    <param name="nameservice">corbaloc::1.2@YOUR_HOST1:2809/NameService</param>
	    <param name="servicename">YOUR_SERVICE1.ASAM-ODS</param>
 </service>
 <!-- Example2: Peak ODS-Sever with active freetext search -->
 <service entityManagerFactoryClass="org.eclipse.mdm.api.odsadapter.ODSContextFactory">
    	<param name="nameservice">corbaloc::1.2@YOUR_HOST2:2809/NameService</param>
	    <param name="servicename">YOUR_SERVICE2.ASAM-ODS</param>
	    <!--The indexing requires a user to get the DataItems from the ODS Server. Those are the credentials for the user -->
	    <param name="freetext.active">true</param> <!--to configure the Avalon, set to false (*) -->
	    <param name="freetext.user">sa</param>
	    <param name="freetext.password">sa</param>
	    <param name="freetext.notificationType">peak</param>
	    <param name="freetext.notificationUrl">http://YOUR_HOST2:8089/api</param>
 </service>

 <!-- Example3:  Avalon ODS-Sever -> freetext search is not active-->
 <service entityManagerFactoryClass="org.eclipse.mdm.api.odsadapter.ODSContextFactory">
	    <param name="nameservice">corbaloc::1.2@YOUR_HOST3:2809/NameService</param>
	    <param name="servicename">YOUR_SERVICE3.ASAM-ODS</param>
	    <!--The indexing requires a user to get the DataItems from the ODS Server. Those are the credentials for the user -->
	    <param name="freetext.active">false</param> <!--to configure the Avalon, set to true (*) -->
	    <param name="freetext.user">sa</param>
	    <param name="freetext.password">sa</param>
	    <param name="freetext.notificationType">avalon</param>
	    <param name="freetext.pollingInterval">5000</param>
 </service>
 </services>


Restart the application server.

Note: An explanation about the the corbaloc and corbaname URLs, find here:
http://www.ciaranmchale.com/corba-explained-simply/the-corbaloc-and-corbaname-urls.html

=== Configure Login Module (Realm Configuration)

The realm is configured in a standardized way. Configure your LDAP, AD or other systems according to the glassfish security documentation:  https://javaee.github.io/glassfish/doc/5.0/security-guide.pdf[Glassfish 5] or https://javaee.github.io/glassfish/doc/4.0/security-guide.pdf[Glassfish 4].

For local installations you can setup and configure a file realm, described in the readme.md: +
http://git.eclipse.org/c/mdmbl/org.eclipse.mdm.git/tree/README.md

Note: The component "org.eclipse.mdm.realms" is not used any longer, since 5.0.0M4. And it is no longer supported.

=== Property lookups for parameters values in service.xml

The service.xml contains all information necessary for the Connector-Service to connect to the available data sources/adapter instances. Since this information includes secret information like passwords, it is possible to provide lookups, which gives you the possibility to specify tokens as references to properties defined elsewhere.

There are different lookups available:

* sys: Looks up variables defined as system properties
* env: Looks up variables defined as environment variables

Example:

 <param name="password">${env:odsPassword}</param>


=== Configure system properties

* use system property "org.eclipse.mdm.api.odsadapter.filetransfer.interfaceName" to set a specific network interface name to be used
* use system property “org.eclipse.mdm.configPath” to redefine the location of the Glassfish config folder, e.g. “GLASSFISH_ROOT/glassfish/domains/domain1/config” 

=== Deployment of org.eclipse.mdm.nucleus
Deploy the backend ( org.eclipse.mdm.nucleus-VERSION.war) on your Glassfish server.
Execute the following command (replacing PATH-TO-WAR and VERSION)

 <glassfish_root>$ ./bin/asadmin 
 asadmin> deploy --force=true --name org.eclipse.mdm.nucleus   <PATH-TO-WAR>/org.eclipse.mdm.nucleus-<VERSION>.war

Afterwards, goto  http://localhost:8080/org.eclipse.mdm.nucleus and Login with sa/sa

NOTE: Deployment in GlassFish 5 Server Administration Console is not working.

[[headless_deployment]]
=== Headless Deployment

The default configuration for the authentication method is set to  “FORM” . If you want to do a headless deployment change it to “BASIC”.
 
Change this file:
org.eclipse.mdm/nucleus/application/src/main/webconfig/web.xml
 
from 

	<auth-method>FORM</auth-method> 
	to 
	<auth-method>BASIC</auth-method> 

[[nodeprovider_config]]
=== Node Provider

The navigation structure of the client application can be adapted to the needs with one or more configurations of the Node Provider.
The Node Provider consists of a JSON based configuration to define the navigation structure.

The configuration of a Node Provider must be created as preference with the prefix `nodeprovider.`.

A Node Provider can be configured in three different ways.

1. Web Client (see <<nodeprovider-web, Nodeprovider Configuration>>)
2. REST Interface (Preferences Endpoint) +
Take a look at `http://{SERVER}:{PORT}/{APPLICATIONROOT}/swagger.html`
3. Database access (not recommended)

==== Node Provider JSON structure

The structure of the JSON document must be as follows:

* Root node
* Nodes for structure configuration

First the root entry of the JSON document must contain an `id`, a `name` and a context mapping.

.Example Node provider root
----
{
	"id" : "generic_measured",
	"name" : "Generic Measured",
	"contexts" : {
	    "*" : {}
    }
}
----

The context mapping can either contain a wildcard `*` or the name of one application context available in the used openMDM configuration. For example “NVHDEMO”. The wildcard configuration will be applied to each application context available.

Each context mapping consists of nested nodes which in sum describe the navigation structure configuration.

Each of that nested nodes consist of the following attributes:

* `type` (String) +
As the type of the node from the openMDM model. For example “Environment”, “Project” or a node for the given Context where the names depend on the given model definition.

* `filterAttributes` (Array of Strings) +
The attributes of a node which should be used for filtering. For example “Id”, “Name”.

*  `labelAttributes` (Array of Strings) +
The attributes of a node which should be used for displaying.

* `labelExpression` +
An EL Syntax based expression to format the display name. The attributes used as “labelAttributes” can be used here. For example “${Id)” to display the Id of a node.

* `valuePrecision` (String) +
One of: `YEAR`, `MONTH`, `DAY`, `HOUR` or `MINUTE` +
Which allows to group selected DATE attributes.

* `contextState` (String) +
One of: `MEASURED`, `ORDERED` +
Allows to set the context for Context related nodes to get either the measured or the ordered value.

* `virtual` (Boolean) +
Defines a new Node which is not part of the default navigation structure.

* `child` (Object with next structure) +
Defines the next level of the navigation structure

===== Example Node

NOTE: This example only shows 3 levels of nested nodes. The full configuration should at least contain configuration down to a Measurement entity.

----
"type" : "Environment",
"filterAttributes" : ["Id"],
"labelAttributes" : ["Name"],
"virtual" : false,
"child" : {
    "type" : "Project",
    "filterAttributes" : ["Id"],
    "labelAttributes" : ["Name", "Id"],
    "virtual" : false,
    "child" : {
        "type" : "vehicle",
        "filterAttributes" : ["model"],
        "labelAttributes" : ["model"],
        "labelExpression" : "Model: ${model}",
        "virtual" : true,
        "contextState": "MEASURED",
    }
}
----