Merge "Bug 571879 - Usability improvements in search component" into dev
diff --git a/doc/IconConfiguration_mdmbl .pdf b/doc/IconConfiguration_mdmbl .pdf
new file mode 100644
index 0000000..4146739
--- /dev/null
+++ b/doc/IconConfiguration_mdmbl .pdf
Binary files differ
diff --git a/doc/src/010_documentHistory.adoc b/doc/src/010_documentHistory.adoc
new file mode 100644
index 0000000..c564d65
--- /dev/null
+++ b/doc/src/010_documentHistory.adoc
@@ -0,0 +1 @@
+**Document history:**
\ No newline at end of file
diff --git a/doc/src/releases.adoc b/doc/src/020_releases.adoc
similarity index 84%
rename from doc/src/releases.adoc
rename to doc/src/020_releases.adoc
index f449e80..a200dad 100644
--- a/doc/src/releases.adoc
+++ b/doc/src/020_releases.adoc
@@ -1,5 +1,10 @@
== Milestones & Releases: New and Noteworthy
+=== Milestone 5.2.0M3
+Support for importing/exporting ATFx external component files directly was added. Therefore some API methods in **org.eclipse.mdm.api.base** were changed. See release_notes.md for a detailed list of changes.
+The quickviewer and x-y-charviewer in the web client was extended to show multiple channels in its data table.
+
+
=== Milestone 5.2.0M2
The old repositories are not used any more, they will be archived soon. Do not use!
diff --git a/doc/src/introduction.adoc b/doc/src/030_introduction.adoc
similarity index 92%
rename from doc/src/introduction.adoc
rename to doc/src/030_introduction.adoc
index 937a425..df7dede 100644
--- a/doc/src/introduction.adoc
+++ b/doc/src/030_introduction.adoc
@@ -12,6 +12,8 @@
**Mailinglists**:
+
+
* For development communication we use the mdmbl mailing list: +
https://dev.eclipse.org/mailman/listinfo/mdmbl-dev
* The openMDM Working group mailing list: +
@@ -99,17 +101,12 @@
https://ci.eclipse.org/mdmbl/
There a nightly builds for the dev and the master branches of org.eclipse.mdm +
-There are also builds for Gerrit and Sonar.
+There are also builds for Gerrit.
==== Sonar
-Note: 5.2.0M2 - not working, build scripts under construction +
-The Eclipse SonarQube server is available via
-https://sonar.eclipse.org​[https://sonar.eclipse.org/]. +
-Rules: Qualitygate - sonar way with findbugs
+Note: since 5.2.0M2 - not working, build scripts under construction.
-Static code analysis is configured for the dev branch of org.eclipse.mdm +
-Generated and test sources are excluded.
=== ODS Server used for Developer Tests
diff --git a/doc/src/040_prerequisites.adoc b/doc/src/040_prerequisites.adoc
new file mode 100644
index 0000000..ebbce37
--- /dev/null
+++ b/doc/src/040_prerequisites.adoc
@@ -0,0 +1,83 @@
+== Prerequisites
+
+Already installed on your machine or install it:
+
+* Java 8:
+** Oracle Java SE 8u201 and higher +
+http://www.oracle.com/technetwork/java/javase/downloads/
+** AdoptJDK: openJDK 8 with HotSpot
+https://adoptopenjdk.net/
+* Git: https://git-scm.com
+
+Test, if programs are available from a console:
+
+* `>java -version`
+* `>git --version`
+
+If not, add the programs to your PATH variable or set corresponding ** *_HOME variables**.
+
+=== Gradle
+
+See https://gradle.org/install/ for installation on you system.
+Version: 4.10.2 (updated 21.2.2020)
+This is optional, as the projects are using the Gradle Wrapper which is delivered with the source code.
+
+=== Eclipse IDE
+Get the current “Eclipse IDE for Enterprise Java Developers” Distribution from https://www.eclipse.org/downloads
+It is recommended to use the Eclipse Installer.
+
+Install Plugins:
+
+* SonarLint via Eclipse Marketplace
+* EclEmma Code Coverage Tool (optional)
+
+Create a new workspace for the mdmbl project and configure it:
+
+* set encoding to UTF-8
+* set Java Code Style formatting rules to the Eclipse default rules [built in]
+
+**Formatter:**
+
+We highly recommend to use the Eclipse 2019/03 or higher IDE. Set the formatting rules to the Eclipse default rules [built in].
+If you use a former version, then import the formatting rules from:
+org.eclipse.mdm/tools/eclipse_formatter.xml
+
+This is **important** as the default rules in Eclipse have changed with the releases.
+
+==== Install Eclipse Copyright Tool
+
+For proper maintenance of the copyright header install this tool and run it before pushing to Gerrit.
+
+Help > Install New Software…
+
+Choose the appropriate Update Site for your Eclipse version -> Choose Releng Tools
+
+image::images/CopyrightTool1.png[]
+
+**Configuration of Eclipse copyright tool:**
+
+The Copyright Tool is configured using the preferences.
+
+image::images/CopyrightTool2.png[]
+
+**Template text:**
+
+****
+
+Copyright (c) ${date} Contributors to the Eclipse Foundation
+
+See the NOTICE file(s) distributed with this work for additional
+information regarding copyright ownership.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License v. 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0.
+
+SPDX-License-Identifier: EPL-2.0
+
+****
+
+==== Use Eclipse copyright tool
+Once installed and configured, the Copyright tool can accessed via context menu on a project +
+-> Fix copyright
+
diff --git a/doc/src/050_getAndBuildCode.adoc b/doc/src/050_getAndBuildCode.adoc
new file mode 100644
index 0000000..18bc78e
--- /dev/null
+++ b/doc/src/050_getAndBuildCode.adoc
@@ -0,0 +1,162 @@
+== Get and build the code
+
+=== Source Code Repositories
+The application is split into several modules, each one dedicated to a certain scope of functions. All source code has been made available in git repositories hosted by the Eclipse Foundation +
+https://eclipse.org/org/foundation/ +
+The version control system used to track all changes is Git: https://git-scm.com/
+
+
+==== Manually checkout
+
+Change to the workspace directory
+Run the following command to checkout the source code:
+
+ git clone <repository URL>
+
+Checkout the following repositories for the openMDM Application:
+
+ git clone http://git.eclipse.org/gitroot/mdmbl/org.eclipse.mdm
+
+There are additional openMDM tools:
+
+ git clone http://git.eclipse.org/gitroot/mdmbl/org.eclipse.mdm.openatfx.mdf.git
+ git clone http://git.eclipse.org/gitroot/mdmbl/org.eclipse.mdm.mdfsorter.git
+
+
+==== Checkout in Eclipse IDE
+
+Alternatively configure eGit in your Eclipse IDE and checkout there.
+
+* Open the Git Perspective
+* Open “Clone a Git Repository ….”
+* Checkout with Username / Password: +
+`https://<eclipse_username>@git.eclipse.org/r/a/mdmbl/<my_repo>``
+
+The password is the Gerrit Password, look there: +
+https://git.eclipse.org/r/#/settings/http-password
+
+e.g. `https://<eclipse_login>@git.eclipse.org/r/a/mdmbl/org.eclipse.mdm`
+
+Or anonymous with the URIs above.
+
+**After cloning the repositories, your Git perspective:**
+
+NOTE: If these "green symbols" are not present, it means that Gerrit has not yet been configured correctly. Follow the instructions in this chapter. [TODO: Link to Git & Gerrit Config]
+
+image::images/GitPerspective.png[]
+
+=== Importing projects to the Eclipse IDE
+Import the project to your Eclipse IDE via File -> Import -> Import as existing gradle project.
+
+=== Building the projects
+Run `./gradlew clean build` in the root directory of org.eclipse.mdm.
+Execute `./gradlew clean build install` also generates the jars, and the war file.
+
+
+Or you build the projects in the Eclipse IDE via a Run Configuration:
+
+image::images/RunConfig.png[]
+
+The following projects are build:
+
+. apicopy
+. application
+. businessobjects
+. connector
+. filerelease
+. freetextindexer
+. preferences
+. property
+. webclient
+
+If you do not see these projects after the build in your Eclipse IDE, just import the org.eclipse.mdm project again as “existing gradle project”.
+
+==== Building the projects without the webclient
+
+To build the application without the webclient, pass the argument headless to the gradle script of the `org.eclipse.mdm` project. The webclient is not included to the war file.
+
+ ./gradlew clean build -Pheadless
+
+In your console you get the message:
+
+****
+`Configure project :nucleus
+Headless build! Webclient will not be included into web archive. To build and include the webclient remove the property headless or set -Pheadless=false. +
+…. +
+Task :nucleus:webclient:install SKIPPED`
+****
+
+
+image::images/RunConfig2.png[]
+
+If there are still java errors after importing and building, right click on the project +
+-> Gradle -> Refresh Gradle Project +
+For other build problems. see the section Known setup bugs.
+[ TODO: add link to chapter]
+If your problem is not listed there, create a Bugzilla Bug for it:
+
+https://bugs.eclipse.org/bugs/enter_bug.cgi?product=MDMBL
+
+
+=== Configure Git and Gerrit
+
+For checking in code to a repository you need to configure Gerrit in the Git perspective.
+
+Additional informations:
+
+* Gerrit can be found at https://git.eclipse.org/r/
+* There is a tutorial, it also explains how to use Gerrit with Eclipse: http://www.vogella.com/tutorials/Gerrit/article.html
+* See documentation from Eclipse: https://wiki.eclipse.org/Gerrit
+
+Prerequisites:
+
+* Get your Gerrit Password via: https://git.eclipse.org/r/#/settings/http-password
+* Configure your Gerrit settings:
+https://git.eclipse.org/r/#/settings/ +
+-> Watched Projects -> Add the mdmbl projects.
+
+==== Configure repositories
+
+Go to your Eclipse IDE -> Git Perspective:
+
+* Expand the project
+* Remotes -> origin -> Select “Configure Push” from context menu -> OK
+* URI -> click change button
+* Configure URI window:
+** URI: https://<eclipse_username>@git.eclipse.org/r/a/mdmbl/<projectname> +
+e.g. https://<eclipse_username>@git.eclipse.org/r/a/mdmbl/org.eclipse.mdm
+** Protocol: choose HTTPS
+** Fill in username and password (the Gerrit one from the settings above)
+** Check the option “Store in secure store”
+* Back to the “Configure Push” Window, section “Ref mapping” -> add
+** Local Branch: HEAD
+** Choose remote branch:
+*** for the dev branch e.g. refs/for/dev
+*** for the master branch: refs/heads/master
+* Try the “Dry-Run” Button to test your configuration
+* Save
+* “Gerrit Configuration” (right click on the remote)
+** URI: same as above
+** Username: same as above
+** Destination branch: dev (or another)
+* Finish
+
+
+==== Configure Push
+
+To push code to Gerrit you can:
+
+. As a committer:
+.. The recommenden way: +
+Push code to Gerrit for reviewing (in Git repositories view: Push to Gerrit)
+.. Push code directly to Gerrit without any review
+(in Git repositories view: Push to upstream)
+
+. As a non-committer: +
+Push code to Gerrit for reviewing (in Git repositories view: Push to Gerrit)
+
+==== Commits to Gerrit
+
+* Add Signed-Off-By when you commit to sign off the commit
+* In the Eclipse IDE: +
+open the git staging perspective, open the window "Commit message" and next to the label "Commit Message" there are 3 buttons. the middle button is the "Add signed-off-by" button. Click it.
diff --git a/doc/src/060_preInstallations.adoc b/doc/src/060_preInstallations.adoc
new file mode 100644
index 0000000..3b867e1
--- /dev/null
+++ b/doc/src/060_preInstallations.adoc
@@ -0,0 +1,187 @@
+== Preconditions and required installations
+
+=== Glassfish
+
+**Supported versions:**
+
+**Glassfish, Version 4.1.2**
+
+* Download Full Platform: +
+https://javaee.github.io/glassfish/download
+* Administration-Guide: +
+ https://javaee.github.io/glassfish/doc/4.0/administration-guide.pdf
+* Security-Guide: +
+https://javaee.github.io/glassfish/doc/4.0/security-guide.pdf
+* Some patches are necessary. Refer to this chapter for patching glassfish. [ TODO link to chapter]
+
+**Glassfish, Version5.1.0**
+
+* Full Platform from https://projects.eclipse.org/projects/ee4j.glassfish/downloads
+* Deployment with Glassfish Administration Console is not possible, because of a Glassfish Bug: 545170 - "Archive Path is NULL" when deploying from GUI +
+(https://bugs.eclipse.org/bugs/show_bug.cgi?id=545170)
+* Administration-Guide: +
+https://javaee.github.io/glassfish/doc/5.0/administration-guide.pdf
++ Security-Guide: +
+https://javaee.github.io/glassfish/doc/5.0/security-guide.pdf
+
+**Installation:**
+
+* Unzip the file into a directory without spaces (recommended).
+* Test it:
+** change to the glassfish-root directory
+** invoke `./glassfish/bin/asadmin start-domain`
+** change to your browser
+** URL localhost:8080 should show you a welcome page
+** URL localhost:4848 should show you the admin page
+** Note: if you need to change the default ports 8080 or 4848 please see the glassfish documentation
+
+
+=== Database for the User Preference Service
+The Preference service stores its data to a relational database. The database connection is looked up by JNDI and the JNDI name and other database relevant parameters are specified in +src/main/resources/META-INF/persistence.xml+. The default JNDI name for the JDBC resource is set to jdbc/openMDM.
+
+For the User Preference Service you need a database with a schema “openMDM”.
+
+Note: “OPENMDM” is the default schema name, it can be changed in the file:
+`/org.eclipse.mdm.nucleus/org.eclipse.mdm.preferences/src/main/resources/META-INF/persistence.xml`
+
+For activating the change, the artefacts have to be rebuilt.
+
+==== Apache Derby Database
+The Glassfish Application Server has included the Derby libraries.
+
+**Create database and tables:**
+
+* Change to your <glassfish_root> directory. +
+* Start the database:
+
+ <glassfish_root>$ ./glassfish/bin/asadmin start-database
+
+ * Start the ij Tool (http://db.apache.org/derby/papers/DerbyTut/ij_intro.html):
+
+ <glassfish_root>$ java -jar ./javadb/lib/derbyrun.jar ij
+
+* Create database with default name “openMDM”
+
+ ij> CONNECT 'jdbc:derby://localhost:1527/openMDM;create=true';
+
+* Create the table “preference”
+
+ ij> CREATE TABLE OPENMDM.PREFERENCE (ID BIGINT GENERATED BY DEFAULT AS IDENTITY NOT NULL, keyCol VARCHAR(255), SOURCE VARCHAR(255), username VARCHAR(255), valueCol CLOB(2147483647) NOT NULL, PRIMARY KEY (ID));
+
+* Add constraints
+
+ ij> ALTER TABLE OPENMDM.PREFERENCE ADD CONSTRAINT UNQ_PREFERENCE_0 UNIQUE (source, username, keyCol);
+
+* Check table:
+
+ ij> SELECT * FROM OPENMDM.PREFERENCE;
+
+* Create the table “system_process” (since 5.2.0M1):
+
+ ij> CREATE TABLE OPENMDM.SYSTEM_PROCESS (ID BIGINT GENERATED BY DEFAULT AS IDENTITY NOT NULL, process_id VARCHAR(255), process_key VARCHAR(255), last_locked BIGINT, PRIMARY KEY (ID));
+
+* close ij
+
+ ij> exit;
+
+* Stop database.
+
+ <glassfish_root>$ ./bin/asadmin stop-database
+
+
+==== Other Database Products
+
+There is also the possibility to use other database products. For Postgres DB you will find the according sql scripts after the nucleus build in the following directory: +
+`$workspace/org.eclipse.mdm.nucleus/build/distributions/schema/org.eclipse.mdm.preferences`.Other database products supported by EclipseLink may also work, but are neither tested nor supported by the mdmbl project.
+
+
+==== Configure JDBC for the User Preference Service DB
+
+For the User Preference Sevice DB configure JDBC resource and its dependent JDBC Connection Pool. It has to be created and configured through asadmin command line tool.
+(the glassfish web administration console is not recommended, as it is pretty buggy).
+
+**Description for the Derby Database with defaultname “openMDM”:**
+
+. Start domain, database and admin-tool:
+
+ <glassfish_root>$ ./bin/asadmin start-domain
+ <glassfish_root>$ ./bin/asadmin start-database
+ <glassfish_root>$ ./bin/asadmin
+
+
+. Create JDBC Connection Pool “openMDM” with
+User, Password and DatabaseName “openMDM”:
+
+ asadmin> create-jdbc-connection-pool --datasourceclassname org.apache.derby.jdbc.ClientDataSource --restype javax.sql.DataSource --property password=openMDM:user=openMDM:serverName=localhost:databaseName=openMDM:connectionAttributes=\;create\\=true openMDM
+
+
+. Check JDBC Connection Pool:
+
+ asadmin>ping-connection-pool
+ asadmin>list-jdbc-connection-pools”
+
+. Create JDBC Resource:
+
+ asadmin> create-jdbc-resource --connectionpoolid openMDM jdbc/openMDM
+
+
+. Check JDBC Resource:
+
+ asadmin>list-jdbc-resources
+
+. Stop domain, database:
+
+ <glassfish_root>$ ./bin/asadmin stop-domain domain1
+ <glassfish_root>$ ./bin/asadmin stop-database
+
+=== ElasticSearch
+
+Download ElasticSearch 7 for openMDM 5.1.0++: +
+https://www.elastic.co/products/elasticsearch
+or +
+https://www.elastic.co/de/downloads/past-releases#elasticsearch
+
+For openMDM 5.0.x and 5.1.Mx use version 2.x., e.g.
+https://www.elastic.co/de/downloads/past-releases/elasticsearch-2-4-2
+
+For testing purpose, it can be simply started by executing:
+
+ <elasticsearch_root>$ ./bin/elasticsearch
+
+=== Database for ODS-Server
+
+The database product is dependent of the ODS Server you use. To start an ODS Server you need a loaded ASAM ODS Application Model in the DB.
+
+
+**Embedded Apache Derby Database and Peak ODS Server:**
+
+If you use a Peak ODS Server from Peak Solutions GmbH:
+they provide an embedded demo Derby Database with an Application Model and Data. Follow their instructions.
+
+
+=== ODS Server
+ASAM ODS-Server e.g. from
+
+* Peak Solution: http://www.peak-solution.de/de/produkte-leistungen/versuchs-messdatenmanagement/softwareloesungen/peak-ods-server/
+* HiQSoft:
+https://www.highqsoft.com/de/avalon-asam-ods-server/
+* or another compliant data source (e.g. PAK adapter)
+* Get a (test) license from the vendors and follow the installation instructions.
+* If you already imported an Application Model to your database and database is running, then the ODS Server should start.
+
+**Notes for running a Peak ODS Server: **
+
+* You need two additional plugins copy them to $odsserver_root/plugins:
+** Put peakcorbafileserver-VERSION.jar into plugins
+** Put notification-plugin-VERSION.jar into plugins
+* Configure parameters in $odsserver_root/cfg/server.properties:
+** Add the following line to enable the notification service: JMS_FORWARDER.PORT=8089
+** The Peak ODS Server can run its own ORB daemon. Just leave the following parameter blank: NAMESERVICE=
+* Use the Peak demo Derby DB (MDMNVH DB) in embedded mode, the database starts automatically with the Peak ODS Server startup. +
+Username and password are the same must be the name of the schema.
+
+ DB_DRIVER = DERBY_EMBEDDED
+ DB_URL = jdbc:derby:/<path_to_MDMNVH_DerbyDB>/MDMNVH;create=false
+ DB_USER = MDMNVH
+ DB_PASSWORD = MDMNV
+
diff --git a/doc/src/070_installApplication.adoc b/doc/src/070_installApplication.adoc
new file mode 100644
index 0000000..830d9b6
--- /dev/null
+++ b/doc/src/070_installApplication.adoc
@@ -0,0 +1,138 @@
+== 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 is not 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
+
+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> +
diff --git a/doc/src/080_startApplication.adoc b/doc/src/080_startApplication.adoc
new file mode 100644
index 0000000..1f3aa57
--- /dev/null
+++ b/doc/src/080_startApplication.adoc
@@ -0,0 +1,27 @@
+== Start application
+
+Start application:
+
+* start ORB ($JAVA_HOME/bin/orbd -ORBInitialPort 2809)
+(skip this if you are using Peak ODS Server with no NAMESERVICE specified in the server.properties)
+* start the database for the ODS Server (if necessary)
+* start the ODS server
+* start Elasticsearch
+* start Glassfish (including database for UPS)
+* start Glassfish
+** `asadmin start-database`
+** `asadmin start-domain`
+
+THe browser URL is http://localhost:8080/org.eclipse.mdm.nucleus. +
+
+You should see the openMDM LoginPage. Lock in with for user/ password from the userXX table in zhe database, e.g. sa/sa.
+
+=== Troubleshooting
+Look into the Logfiles:
+
+Glassfish:
+$glassfish_root/domains/domain1/logs/server.log
+Derby DB for User Preference Service:
+$glassfish_root/databases/derby.log
+The Logfiles of your ODS compatible datasource
+
diff --git a/doc/src/090_knownProblems.adoc b/doc/src/090_knownProblems.adoc
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/src/090_knownProblems.adoc
diff --git a/doc/src/100_ExtendedRunConfig.adoc b/doc/src/100_ExtendedRunConfig.adoc
new file mode 100644
index 0000000..2edee96
--- /dev/null
+++ b/doc/src/100_ExtendedRunConfig.adoc
@@ -0,0 +1,15 @@
+== Extended configurations (run & IDE)
+
+=== Deployment via Eclipse IDE
+
+To deploy the nucleus in Glassfish asadmin can be configured as an External Tool in Eclipse:
+
+image::images/RunConfig3.png[]
+
+=== Angular Live Development Server
+
+During development a full build of the MDM5 Webclient, which is part of the nucleus, is quite time consuming. It is more efficient to skip the client build entirely by using the parameter -Pheadless, which excludes the JavaScript-Code from being build and included in the war file. For the UI you can start the "NG Live Development Server".
+It is started by invoking "npm start" in the root path of the angular application (org.eclipse.mdm/nucleus/webclient\src\main\webapp). After successful compilation you are able to see the webclient under http://localhost:4200/. +
+Changes to the angular application will trigger an incremental compile of the changed sources. +
+Additionally the the live development server implements a proxy, which forwards all requests to http://localhost:4200/org.eclipse.mdm.nucleus/* to http://localhost:8080/. So if the Glassfish with the MDM5 backend does not run on port 8080, you have to change the proxy configuration in org.eclipse.mdm/nucleus/webclient/src/main/webapp/proxies/development.config.json.
+To avoid issues with the form based authentication, it is easier to switch to basic authentication by changing the web.xml in this scenario. Otherwise you may get errors for the backend requests, because you are not automatically forwarded to the login page.
diff --git a/doc/src/110_DevelopmentRules.adoc b/doc/src/110_DevelopmentRules.adoc
new file mode 100644
index 0000000..8c0cfa4
--- /dev/null
+++ b/doc/src/110_DevelopmentRules.adoc
@@ -0,0 +1 @@
+== Development Rules
\ No newline at end of file
diff --git a/doc/src/120_TippsAndTricks.adoc b/doc/src/120_TippsAndTricks.adoc
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/src/120_TippsAndTricks.adoc
diff --git a/doc/src/900_Appendix.adoc b/doc/src/900_Appendix.adoc
new file mode 100644
index 0000000..c108699
--- /dev/null
+++ b/doc/src/900_Appendix.adoc
@@ -0,0 +1 @@
+== APPENDIX
\ No newline at end of file
diff --git a/doc/src/images/CopyrightTool1.png b/doc/src/images/CopyrightTool1.png
new file mode 100644
index 0000000..0befb74
--- /dev/null
+++ b/doc/src/images/CopyrightTool1.png
Binary files differ
diff --git a/doc/src/images/CopyrightTool2.png b/doc/src/images/CopyrightTool2.png
new file mode 100644
index 0000000..e67ab86
--- /dev/null
+++ b/doc/src/images/CopyrightTool2.png
Binary files differ
diff --git a/doc/src/images/GitPerspective.png b/doc/src/images/GitPerspective.png
new file mode 100644
index 0000000..926d8ce
--- /dev/null
+++ b/doc/src/images/GitPerspective.png
Binary files differ
diff --git a/doc/src/images/RunConfig.png b/doc/src/images/RunConfig.png
new file mode 100644
index 0000000..f4ef454
--- /dev/null
+++ b/doc/src/images/RunConfig.png
Binary files differ
diff --git a/doc/src/images/RunConfig2.png b/doc/src/images/RunConfig2.png
new file mode 100644
index 0000000..338c4ee
--- /dev/null
+++ b/doc/src/images/RunConfig2.png
Binary files differ
diff --git a/doc/src/images/RunConfig3.png b/doc/src/images/RunConfig3.png
new file mode 100644
index 0000000..cc7cfc0
--- /dev/null
+++ b/doc/src/images/RunConfig3.png
Binary files differ
diff --git a/doc/src/index.adoc b/doc/src/index.adoc
index df399b2..3b7bd27 100644
--- a/doc/src/index.adoc
+++ b/doc/src/index.adoc
@@ -1,8 +1,32 @@
= Installation and Setup Guide for the openMDM(R) Application
-Eclipse mdmbl project
+Eclipse mdmbl project
+
+ Copyright(c) 2017-2021, A. Wittek and others. Made available under the Eclipse Public License 2.0
:toc:
-include::releases.adoc[]
+include::010_documentHistory.adoc[]
-include::introduction.adoc[]
\ No newline at end of file
+include::020_releases.adoc[]
+
+include::030_introduction.adoc[]
+
+include::040_prerequisites.adoc[]
+
+include::050_getAndBuildCode.adoc[]
+
+include::060_preInstallations.adoc[]
+
+include::070_installApplication.adoc[]
+
+include::080_startApplication.adoc[]
+
+include::090_knownProblems.adoc[]
+
+include::100_ExtendedRunConfig.adoc[]
+
+include::110_DevelopmentRules.adoc[]
+
+include::120_TippsAndTricks.adoc[]
+
+include::900_Appendix.adoc[]
\ No newline at end of file
