src/main/asciidoc/architectureDocumentation/architectureDocumentation.adoc

////
 *******************************************************************************
 * Copyright (c) 2018 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
 *******************************************************************************
////
openKonsequenz - Architecture of the module 'Planned Grid Measures'
===================================================================
:Author: Frank Dietrich
:Email: frank.dietrich@pta.de
:Date: 2018-03-19
:Revision: 1
:icons:
:source-highlighter: highlightjs
:highlightjs-theme: solarized_dark

This documentation is based on the ARC42-Template (v7.0):

<<<

== Introduction and Goals

=== Requirements Overview

The module 'Planned Grid Measures' supports the network operators by managing the required maintenance and repair work.
It has to provide an overview of all planned grid measures including its actual status. For that the service engineers must be
able to update the status of their tasks by using mobile clients (smartphone or tablet pc). To get an unique planning
of a grid measure, it is required to select the affected resources out of the network operator's inventory (network topology).
Therefore the inventory must be imported from the module 'CIM-Cache', which contains this information. Finally the planned grid
measures have to be transfered to the central network control unit (CNCU).

The full requirements of the module 'Planned Grid Measures' (in German: Modul 'Geplante Netzmaßnahme') is described in the document

* "Anfragespezifikation Modul Geplante Netzmaßnahme" from 12-09-2017.

=== Quality Goals
The module 'Planned Grid Measures' represents a user module that is based on the architecture platform of openKONSEQUENZ. The main quality
goals of the platform are:

* *Flexibility* The reference platform shall grant that different systems and modules from different vendors/developers can interact and interoperate, and may be exchanged or recombined.
* *Availability* All platform modules that are running on the platform can only be as available as the platform same for user modules that are based on platform modules.
* *Maintainability* (and testability as part of maintainability)  The platform and its platform modules shall be used longer than 15 years.
* *Integration performance* New implemented functionality of oK own modules and external modules shall be included fast / automatically.
* *Security* The platform and its modules need to underly security-by-design

The main quality goals of the user module planned grid measures are:

* *Functionality* The user module must fulfil the functional requirements mentioned in the section before
* *Ergonomics* The web interface must be realized according to oK-GUI-Styleguide.
* *Good documentation* (i.e. code and architecture documentation) makes code changes easier and automatic
tests facilitate rigorous verification.
* *Modifiability* (and testability as part of modifiability)
* *Integration performance* The user module must be easy integratable in different production environments.

The following documents contain the quality goals in detail:

* Architecture Committee Handbook v1.3.1 from 05-09-2017
* Quality Committee Handbook v1.1.1 from 11-09-2017

The architecture is based on the AC-Handbook. The quality demands are described in the QC-Handbook.
Both specifications were fully complied with in the project, so that a high quality is given.

The code quality regarding static code analysis and unit test code coverage on the backend and fronend sides
are ensured by the use of sonarqube. The rule set and the qualtity gate are defined by the default, the
so called "sonar way".

The module 'Planned Grid Measures' is part of the Eclipse project 'Eclipse openK User Modules'.
This project bases on the Eclipse Public Licence 2.0.

=== Stakeholders

.Stakeholders
[options="header,footer"]
|=========================================================
|Role/Name|Contact|Expectations
|Product Owner (represents the Distribution System Operators)|Rainer Fuhrmann, Benjamin Woboril, Oliver Tantu|The software must fulfil their functional and nonfunctional requirements.
|Module Developer|Michel Alessandrini, Jonas Tewolde, Frank Dietrich|All relevant business and technical information must be available for implementing the software.
|External Reviewer (represents the AC/QC)|Heiko Oberländer, Alexander Langold|The software and the documentation is realized according to the Quality and Architecture Handbook of openKONSEQUENZ.
|External Reviewer (represents the Eclipse-Requirements)|Angelika  Wittek|The software is  licensed under the EPL 2.0. It must be validated that all requirements are fulfilled.
|System Integrator|n.n.|A documentation for the integration of the module in the DSO specific environments must be available.
|=========================================================

== Architecture Constraints

The main architecture constraints are:

* *Public License* The module must be available under the “Eclipse Public License 2.0”.
* *Availability* The source code of the module must be accessible to any interested person/company.

Therefore the project is published under the following repositories:
•https://git.eclipse.org/r/openk-usermodules/org.eclipse.openk-usermodules.mics.centralService
•https://git.eclipse.org/r/openk-usermodules/org.eclipse.openk-usermodules.mics.homeService
•https://git.eclipse.org/r/openk-usermodules/org.eclipse.openk-usermodules.plannedGridMeasures.backend
•https://git.eclipse.org/r/openk-usermodules/org.eclipse.openk-usermodules.plannedGridMeasures.frontend

* *Standardization* The module must use standardized data structures (CIM) [if available] and the reference platform.

=== Technical Constraints

TODO: Bibliotheken und Versionen aktualisieren

The following technical constraints are given:

.Technical Contraints
[options="header,footer"]
|========================================================
|Component|Constraints
|Base components of the reference platform
a|* Application Server Tomcat
* JPA EclipseLink
* Database PostgreSQL

|Enterprise service bus
a|* ESB Talend
* Communication via RESTful Webservices

|Programming language frontend
a|* Angular
* Bootstrap
* jQuery
* REST/JSON Interfaces

|GUI design
a|* According to oK-GUI-Styleguide

|Java QA environment
a| * Sonarqube 5.6.6

|Programming language
a|* Backend: Java 1.8
* Frontend: Angular 4.0.0 (Javascript, Typescript, HTML5, CSS3)

|IDE
a|* Not restricted (Eclipse, IntelliJ, Microsoft Developer Studio, Microsoft Visual Code ...)

|Build system
a|* Backend: Maven
* Frontend: NodeJS + Angular/cli

|Libraries, frameworks, components
a|* Used Libraries/Frameworks have to be compatible to the Eclipse Public License

|Architecture Documentation
a|* According ARC42-Template
|========================================================


=== Technical Dependencies

==== Modules
The following modules are required to use the 'Planned Grid Measures':

.Modules
[options="header,footer"]
|=========================================================
|Name of the module|Purpose|Status of the module
|'Auth&Auth'|Authentification and Authorization|available
|'CIM-Cache'|Provision of the network operator's inventory|partly available
|'SCADA-Adapter'|Communication with the SCADA System|not available
|=========================================================


==== Libraries

The following libraries are used:

.Libraries
[options="header,footer"]
|=========================================================
|Name of the library|Version|Artefact-id|Usage|License|Tier


|io.dropwizard.dropwizard|1.3.1
a|
[source,xml]
----

----
||Apache License 2.0|Backend

|io.dropwizard.dropwizard-core|0.9.2
a|
[source,xml]
----
<dependency>
    <groupId>io.dropwizard</groupId>
    <artifactId>dropwizard-core</artifactId>
</dependency>
----
||Apache License 2.0|Backend

|org.apache.httpcomponents.httpclient|4.5.3
a|
[source,xml]
----
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>${httpclient.version}</version>
</dependency>
----
||Apache License 2.0|Backend

|com.google.code.gson|2.8.0
a|
[source,xml]
----
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>${gson-version}</version>
</dependency>
----
||Apache License 2.0|Backend

|commons-io|2.5
a|
[source,xml]
----
<dependency>
    <artifactId>commons-io</artifactId>
    <version>${commons-io.version}</version>
</dependency>
----
||Apache License 2.0|Backend

|org.eclipse.persistence.eclipselink|2.6.4
a|
[source,xml]
----
<dependency>
    <groupId>org.eclipse.persistence</groupId>
    <artifactId>eclipselink</artifactId>
    <version>${eclipselink-version}</version>
</dependency>
----
||Eclipse Public License|Backend

|postgresql.postgresql|9.1-901-1.jdbc
a|
[source,xml]
----
<dependency>
    <groupId>postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>${postgresql-version}</version>
</dependency>
----
||New BSD License|Backend

|junit.junit|4.12
a|
[source,xml]
----
<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>${junit.version}</version>
    <scope>test</scope>
</dependency>
----
||Eclipse Public License|Backend

|org.easymock.easymock|3.4
a|
[source,xml]
----
<dependency>
    <groupId>org.easymock</groupId>
    <artifactId>easymock</artifactId>
    <version>${easymock.version}</version>
</dependency>
----
||Apache License 2.0|Backend

|org.powermock.powermock|3.4
a|
[source,xml]
----
<dependency>
    <groupId>org.powermock</groupId>
    <artifactId>powermock-api-easymock</artifactId>
    <version>${powermock-api-easymock.version}</version>
    <scope>test</scope>
</dependency>
----
||Apache License 2.0|Backend

|org.jacoco.jacoco-maven-plugin|0.7.9
a|
[source,xml]
----
<dependency>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>${jacoco-maven-plugin.version}</version>
    <exclusions>
         <exclusion>
             <groupId>commons-beanutils</groupId>
             <artifactId>commons-beanutils</artifactId>
         </exclusion>
             <exclusion>
                  <groupId>commons-logging</groupId>
                  <artifactId>commons-logging</artifactId>
             </exclusion>
         </exclusions>
</dependency>
----
||Eclipse Public License|Backend

|angular2-uuid|1.1.1
a|
[source,xml]
----

----
||MIT License|Frontend

|core-js|2.4.1
a|
[source,xml]
----

----
||MIT License|Frontend

|arc42 template|
a|
[source,xml]
----

----
||MIT License|Sonstiges (Dokumentation, etc.)

|Source Sans Pro|
a|
[source,xml]
----

----
||SIL OPEN FONT LICENSE Version 1.1|Frontend

|dependencies/@angular/animations|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@angular/cdk|5.2.5
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@angular/common|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@angular/compiler|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@angular/core|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@angular/forms|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@angular/http|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@angular/platform-browser|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@angular/platform-browser-dynamic|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@angular/router|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/@auth0/angular-jwt|1.0
a|
[source,xml]
----

----
||MIT License|Frontend

|agdependencies/ag-grid|18.0.1
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/ag-grid-angular|18.0.1
a|
[source,xml]
----

----
|||Frontend

|dependencies/ajv|6.5.2
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/angular-calendar|0.23.7
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/bootstrap|3.3.7
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/bootstrap-toggle|2.2.2
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/classlist.js|1.1.20150312
a|
[source,xml]
----

----
||The Unlicense|Frontend

|dependencies/dependencies/core-js|2.5.7
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/file-saver|1.3.8
a|
[source,xml]
----
<dependency>

</dependency>
----
||MIT License|Frontend

|dependencies/font-awesome|4.7.0
a|
[source,xml]
----
<dependency>

</dependency>
----
||OFL-1.1 AND MIT|Frontend

|dependencies/jquery|3.3.1
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/ng2-daterangepicker|2.0.12
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/popper.js|1.14.3
a|
[source,xml]
----

----
||MIT License|Frontend

|dependencies/rxjs|5.5.11
a|
[source,xml]
----

----
||Apache License 2.0|Frontend


|dependencies/web-animations-js|2.3.1
a|
[source,xml]
----

----
||MIT License|Frontend


|dependencies/zone.js|0.8.26
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@angular-devkit/build-angular|0.6.8
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@angular-devkit/build-optimizer|0.6.8
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@angular-devkit/core|0.6.8
a|
[source,xml]
----

----
||MIT License|Frontend


|Dependencies/@angular-devkit/schematics|0.6.8
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@angular/cli|6.0.8
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@angular/compiler-cli|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@angular/language-service|5.2.11
a|
[source,xml]
----

----
||MIT License|Frontend


|dependencies/web-animations-js|2.3.1
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@types/bootstrap|4.1.2
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@types/file-saver|1.3.0
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@types/jasmine|2.8.8
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@types/jasminewd2|2.0.3
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@types/jquery|3.3.4
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/@types/node|6.0.113
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/codelyzer|4.4.2
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/jasmine-core|2.8.0
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/jasmine-spec-reporter|4.2.1
a|
[source,xml]
----

----
||Apache License 2.0|Frontend


|devDependencies/karma|2.0.4
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/karma-chrome-launcher|2.2.0
a|
[source,xml]
----

----
||MIT License|Frontend


|evDependencies/karma-coverage-istanbul-reporter|1.4.3
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/karma-jasmine|1.1.2
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/karma-jasmine-html-reporter|0.2.2
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/karma-junit-reporter|1.2.0
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/protractor|5.3.2
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/ts-node|4.1.0
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/tslint|5.9.1
a|
[source,xml]
----

----
||MIT License|Frontend


|devDependencies/typescript|2.5.3
a|
[source,xml]
----

----
||Apache License 2.0|Frontend


|SpinnerKit|1.2.5
a|
[source,xml]
----

----
||MIT License|Frontend


|swagger-jersey2-jaxrs|1.5.12
a|
[source,xml]
----
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jersey2-jaxrs</artifactId>
    <version>${swagger-jersey2-jaxrs}</version>
    <scope>compile</scope>
    <exclusions>
         <exclusion>
              <groupId>com.google.code.findbugs</groupId>
              <artifactId>annotations</artifactId>
         </exclusion>
    </exclusions>
</dependency>
----
||Apache License 2.0|Backend


|log4j|1.2.17
a|
[source,xml]
----

----
|||Backend


|powermock-api-easymock|1.6.6
a|
[source,xml]
----
<dependency>
    <groupId>org.powermock</groupId>
    <artifactId>powermock-api-easymock</artifactId>
    <version>${powermock-api-easymock.version}</version>
    <scope>test</scope>
</dependency>
----
||Apache License 2.0|Backend


|jacoco-maven-plugin|0.7.9
a|
[source,xml]
----
<dependency>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>${jacoco-maven-plugin.version}</version>
    <exclusions>
         <exclusion>
              <groupId>commons-beanutils</groupId>
              <artifactId>commons-beanutils</artifactId>
         </exclusion>
         <exclusion>
              <groupId>commons-logging</groupId>
              <artifactId>commons-logging</artifactId>
         </exclusion>
    </exclusions>
</dependency>
----
||Apache License 2.0|Backend


|sonar-maven-plugin|3.2
a|
[source,xml]
----
<plugin>
     <groupId>org.sonarsource.scanner.maven</groupId>
     <artifactId>sonar-maven-plugin</artifactId>
     <version>${sonar-maven-plugin.version}</version>
</plugin>
----
||LGPL|Backend


|flyway-maven-plugin|4.2.0
a|
[source,xml]
----
<plugin>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-maven-plugin</artifactId>
    <version>${flyway-maven-plugin-version}</version>
    <configuration>
        <sqlMigrationSeparator>__</sqlMigrationSeparator>
        <locations>
            <location>filesystem:db/migrations/</location>
        </locations>
        <url>${database.url}</url>
        <user>${database.user}</user>
        <password>${database.password}</password>
        <schemas>
            <schema>public</schema>
        </schemas>

    </configuration>
</plugin>
----
||Apache License 2.0|Backend


|maven-compiler-plugin|3.6.1
a|
[source,xml]
----
<plugin>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>${maven-compiler-plugin-version}</version>
    <configuration>
        <source>${java-source-target-version}</source>
        <target>${java-source-target-version}</target>
    </configuration>
</plugin>
----
||Apache License 2.0|Backend


|maven-jar-plugin|3.0.2
a|
[source,xml]
----
<plugin>
    <artifactId>maven-jar-plugin</artifactId>
    <version>${maven-jar-plugin-version}</version>
    <configuration>
        <archive>
            <manifest>
                <addClasspath>true</addClasspath>
                <mainClass>${mainClass}</mainClass>
            </manifest>
        </archive>
    </configuration>
</plugin>
----
||Apache License 2.0|Backend


|maven-project-info-reports-plugin|3.0.0
a|
[source,xml]
----
<plugin>
    <artifactId>maven-project-info-reports-plugin</artifactId>
    <version>${maven-project-info-reports-plugin-version}</version>
    <configuration>
        <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
        <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
    </configuration>
</plugin>
----
||Apache License 2.0|Backend


|maven-war-plugin|2.1
a|
[source,xml]
----

----
||Apache License 2.0|Backend


|maven-shade-plugin|2.4.1
a|
[source,xml]
----
<plugin>
    <artifactId>maven-shade-plugin</artifactId>
    <version>${maven-shade-plugin.version}</version>
    <configuration>
        <createDependencyReducedPom>true</createDependencyReducedPom>
        <transformers>
            <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
            <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                <mainClass>${mainClass}</mainClass>
            </transformer>
        </transformers>
        <!-- exclude signed Manifests -->
        <filters>
            <filter>
                <artifact>*:*</artifact>
                <excludes>
                    <exclude>META-INF/*.SF</exclude>
                    <exclude>META-INF/*.DSA</exclude>
                    <exclude>META-INF/*.RSA</exclude>
                </excludes>
            </filter>
        </filters>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
        </execution>
    </executions>
</plugin>
----
||Apache License 2.0|Backend


|maven-javadoc-plugin|2.10.3
a|
[source,xml]
----
<plugin>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>${maven-javadoc-plugin-version}</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>
----
||Apache License 2.0|Backend


|maven-source-plugin|2.4
a|
[source,xml]
----
<plugin>
    <artifactId>maven-source-plugin</artifactId>
    <version>${maven-source-plugin-version}</version>
    <executions>
        <execution>
            <id>attach-sources</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>
----
||Apache License 2.0|Backend


|io.swagger|1.5.12
a|
[source,xml]
----
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jersey2-jaxrs</artifactId>
    <version>${swagger-jersey2-jaxrs}</version>
    <scope>compile</scope>
    <exclusions>
        <exclusion>
            <groupId>com.google.code.findbugs</groupId>
            <artifactId>annotations</artifactId>
        </exclusion>
    </exclusions>
</dependency>
----
|||Backend


|swagger-maven-plugin|3.1.6
a|
[source,xml]
----
<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>${swagger-maven-plugin-version}</version>
    <configuration>
        <skipSwaggerGeneration>false</skipSwaggerGeneration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>
                    <location>org.eclipse.openk</location>
                </locations>
                <schemes>
                    <shema>http</shema>
                </schemes>
                <host>localhost:9050</host>
                <basePath>/mics/gridMeasures</basePath>
                <info>
                    <title>plannedGridMeasures@openK - Backend REST-Service documentation</title>
                    <version>v1</version>
                    <description>This documentation contains the description of all used REST services.</description>
                    <termsOfService>
                        .
                    </termsOfService>
                    <contact>
                        <email>nn@pta.de</email>
                        <name></name>
                    </contact>
                    <license>
                        <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
                        <name>Apache 2.0</name>
                    </license>
                </info>
                <outputFormats>yaml</outputFormats>
                <templatePath>${basedir}/templates/strapdown.html.hbs</templatePath>
                <outputPath>target/generated-docs/swaggerInterfaceDocumentation.html</outputPath>
                <swaggerDirectory>target/generated-docs</swaggerDirectory>
                <securityDefinitions>
                    <securityDefinition>
                        <json>/securityDefinitions.json</json>
                    </securityDefinition>
                </securityDefinitions>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>
----
||Apache License 2.0|Backend


|java-jwt|3.2.0
a|
[source,xml]
----
<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
    <version>${java-jwt-version}</version>
</dependency>
----
|||Backend


|gson|2.8.5
a|
[source,xml]
----
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>${gson-version}</version>
</dependency>
----
|||Backend


|commons-codec|1.11
a|
[source,xml]
----
<dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>${commons-codec-version}</version>
</dependency>
----
|||Backend


|eclipselink|2.6.4
a|
[source,xml]
----
<dependency>
    <groupId>org.eclipse.persistence</groupId>
    <artifactId>eclipselink</artifactId>
    <version>${eclipselink-version}</version>
</dependency>
----
||Eclipse Public License|Backend


|postgresql|9.1-901-1.jdbc4
a|
[source,xml]
----
<dependency>
    <groupId>postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>${postgresql-version}</version>
</dependency>
----
|||Backend


|asciidoctor-maven-plugin|1.5.3
a|
[source,xml]
----
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor-maven-plugin-version}</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>${asciidoctorj-pdf-version}</version>
        </dependency>
        <dependency>
            <groupId>org.jruby</groupId>
            <artifactId>jruby-complete</artifactId>
            <version>${jruby-complete-version}</version>
        </dependency>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj</artifactId>
            <version>${asciidoctorj-version}</version>
        </dependency>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-diagram</artifactId>
            <version>${asciidoctorj-diagram-versions}</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>src/main/asciidoc</sourceDirectory>
        <requires>
            <require>asciidoctor-diagram</require>
        </requires>
        <attributes>
            <imagesoutdir>${project.build.directory}/generated-docs/images</imagesoutdir>
            <imagesDir>${project.build.directory}/generated-docs/images</imagesDir>
        </attributes>
    </configuration>
    <executions>

        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <skip>${skip.asciidoc}</skip>
                <imagesDir>${project.build.directory}/generated-docs/images</imagesDir>
                <requires>
                    <require>asciidoctor-diagram</require>
                </requires>
                <sourceHighlighter>coderay</sourceHighlighter>
                <backend>html</backend>
                <doctype>book</doctype>
                <imagesDir>./images</imagesDir>
            </configuration>
        </execution>
        <!--execution>
            <id>output-pdf</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <skip>${skip.asciidoc}</skip>
                <imagesDir>${project.build.directory}/generated-docs/images</imagesDir>
                <requires>
                    <require>asciidoctor-diagram</require>
                </requires>
                <sourceHighlighter>coderay</sourceHighlighter>
                <backend>pdf</backend>
                <doctype>book</doctype>
                <imagesDir>./images</imagesDir>
                <attributes>
                    <icons>font</icons>
                    <pagenums />
                    <toc />
                    <idprefix />
                    <idseparator>-</idseparator>
                </attributes>
            </configuration>
        </execution-->
    </executions>
</plugin>
----
||Apache License 2.0|Backend


|asciidoctorj-pdf|1.5.0-alpha.11
a|
[source,xml]
----
<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj-pdf</artifactId>
    <version>${asciidoctorj-pdf-version}</version>
</dependency>
----
||MIT License|Backend


|asciidoctorj|1.5.4
a|
[source,xml]
----
<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>${asciidoctorj-version}</version>
</dependency>
----
||Apache License 2.0|Backend


|asciidoctorj-diagram|1.5.4.1
a|
[source,xml]
----
<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj-diagram</artifactId>
    <version>${asciidoctorj-diagram-versions}</version>
</dependency>
----
||Apache License 2.0|Backend


|jruby-complete|1.7.21
a|
[source,xml]
----
<dependency>
    <groupId>org.jruby</groupId>
    <artifactId>jruby-complete</artifactId>
    <version>${jruby-complete-version}</version>
</dependency>
----
|||Backend


|javax.mail|1.4.3
a|
[source,xml]
----
<dependency>
    <groupId>javax.mail</groupId>
    <artifactId>mail</artifactId>
    <version>${javax.mail.version}</version>
</dependency>
----
||Apache License 2.0|Backend


|greenmail|1.5.7
a|
[source,xml]
----
<dependency>
    <groupId>com.icegreen</groupId>
    <artifactId>greenmail</artifactId>
    <version>${greenmail.version}</version>
    <scope>test</scope>
</dependency>
----
||Apache License 2.0|Backend


|powermock-module-junit4|1.7.3
a|
[source,xml]
----

----
||Apache License 2.0|Backend


|javax.servlet-api|3.1.0
a|
[source,xml]
----

----
||Apache License 2.0|Backend


|jaxrs-ri|2.22.1
a|
[source,xml]
----

----
||Apache License 2.0|Backend


|jackson-annotations|2.5.4
a|
[source,xml]
----

----
||Apache License 2.0|Backend


|RabbitMQ AMQP client|5.2.0
a|
[source,xml]
----
<<dependency>
     <groupId>com.rabbitmq</groupId>
     <artifactId>amqp-client</artifactId>
     <version>${rabbitmq.version}</version>
 </dependency>
----
||Apache License 2.0|Backend


|=========================================================

== System Scope and Context

=== Business Context

The user module 'Planned Grid Measures' communicates via Restful Webservices with the follwowing modules
(see also figure 1):

* *Core Module 'Auth & Auth'* The 'Planned Grid Measures' can only be used by authorized users.
   Therefore, it is essential to invoke the module 'Auth & Auth' for authorization and authentication
   purposes.
* *Domain Module 'CIM-Cache'* The 'Planned Grid Measures' needs the information about the inventory
  (network topology) of the network operator.
  Therefore, it is essential to invoke the module 'CIM-Cache' to load this data.
* *Core Module 'SCADA Adapter'* The 'Planned Grid Measures' transfers information to the SCADA-system via
  the module 'SCADA-Apdapter'. Therefore, it must provide an interface for receiving the according data.

.System-Context of 'Planned Grid Measures'
[options="header,footer"]
[plantuml]
----


Node SCADA {
  component "SCADA Adapter"
}


Node AUTH_N_AUTH {
  component "Auth&Auth"
}


Node CIM_CACHE {
  component "CIM-Cache"
}


SCADA--sca_api
AUTH_N_AUTH--ana_api
CIM_CACHE--cim_api

Node PLANNED_GRID_MEASURES {
    component "Planned Grid Measures"
}


PLANNED_GRID_MEASURES-->ana_api : use
PLANNED_GRID_MEASURES-->cim_api : use
PLANNED_GRID_MEASURES-->sca_api : use



----







=== Technical Context

The following aspects have to be taken into account for external communication of the module 'Planned Grid Measures':

* RESTful web services are used as interface-technology.
* Each external interface (interfaces between modules or external systems) has to be documented.
* Dependencies of modules to services realized by other modules have to be specified and documented explicitly.
* When CIM is not appropriate (like access management), other standards in their respective domain shall be taken into account first to avoid proprietary and inaccurate interfaces. The interface has to be documented in the overall openKONSEQUENZ interface profile and it should use REST & XML.

The interfaces of the module 'Planned Grid Measures' are described in the interface documentation.

=== Solution Strategy

The module 'Planned Grid Measures' bases on a three-tier architecture:

. *Frontend* - The GUI is implemented as a web-frontend with rich-client functionalities.
. *Backend* - The business functionalities are implemented in the backend tier. It provides the business functions via RESTful Webservices.
. *Database* - The database stores all module specific data.

TODO: microservices ergänzen

== Building Block View

=== Whitebox Overall System

The module 'Planned Grid Measures' contains two components (see figure 2):

. *UI* - Represents the graphical user interface and consumes the services from the business logic component via RESTful webservices.
. *Business Logic* - Realizes the business functionality and the data storage of the module. The
module itself is split up in several components due to the requirement to use
microservices.

.Module components
[options="header,footer"]
[plantuml]
----
node Module {
    rectangle UI
    rectangle BusinessLogic

    interface REST

    UI -> REST
    REST -- BusinessLogic
}
----


Based on the abstract concept mentioned above, the following figure shows the concrete realization of the main components.
The mapping from the abstract to the concrete view is as follows:

. UI
 - plannedGridMeasuresFE
. Business Logic
 - MICS-HOME: (project independent webapplication)
 - MICS-CENTRAL: (project independent service distribution and
 service dispatcher.
 - planned-grid-measures.war (Backend: Rest-Service)
 - planned-grid-measures-DB

.Distribution of components
[options="header,footer"]
[plantuml]
----
node ClientComputer {
    node WebBrowser {
        component (PlannedGridMeasureFE SPA)
    }
}

node DMZ {
    node ApacheTomcat {
        component (mics-home.war RESTService)
    }
}

node openKonsequenz_LAN {


    node PostgresDMBS {
        component (PlannedGridMeasures database)
    }
    node MICS.CENTRAL {
        component (mics-central.jar)
    }
    node Auth_n_Auth.Module {
        component (auth_n_auth.war)
    }
    node PlannedGridMeasuresBackend {
        component (planned-grid-measures.jar)
    }
    node KeyCloak {
      component (Keycloak Server)
    }
    node CimCache {
          component (Cim Cache)
    }
}

WebBrowser --> ApacheTomcat
ApacheTomcat --> MICS.CENTRAL
MICS.CENTRAL --> PlannedGridMeasuresBackend
MICS.CENTRAL --> Auth_n_Auth.Module
MICS.CENTRAL --> CimCache
PlannedGridMeasuresBackend --> PostgresDMBS
Auth_n_Auth.Module --> KeyCloak
----

The communication between WebBrowser and Apache Tomcat is established via HTTP/HTTPS.
ApacheTomcat is connected to the data source (PostgresDBMS) via TCP/IP.

The structure of the backend is based on microservices. To realize this, the "Dropwizard" framework is used.
Dropwizard is an open source Java framework for developing high-performance RESTful backends.
Dropwizard provides the most useful Java libraries, which you need to deploy a RESTful application, into one embedded application package.
The most important are:

 * Embedded Jetty: Every application is packaged as a jar instead of war file and starts its own embedded jetty container. There is no WAR file and no external servlet container.

 * JAX-RS: Jersey (the reference implementation for JAX-RS) is used to write RESTful web services.

 * JSON: The REST services speaks JSON. Jackson library is used to do all the JSON processing.

 * Logging: It is done using Logback and SLF4J.

 * Hibernate Validator: Dropwizard uses Hibernate Validator API for declarative validation.

 * Metrics: Dropwizard has support for monitoring using the metrics library. It provides unparalleled insight into what our code does in production.

==== plannedGridMeasureFE

This component implements the presentation logic for the *planned-grid-measures*-module using the *Angular*-TypeScript
framework. The Frontend is a so called *Single Page Application* (SPA) because
it behaves like a single HTML-page. 


==== planned-grid-measures.jar (backend tier)

This component implements the business functionality of the planned grid measures. And it provides services, that the
plannedGridMeasureFE can use the functions in the frontend.

The "Dropwizard" framework is used to implement this application.

==== mics-central.jar (backend tier)

This component knows all relevant microservices. The microservices are configured here
and organized in "distribution clusters". Every microservice has a unique name
which identifies it. The main task of the "Mics-Central" is to receive a service request (for example from the
"Mics-Home" application) and to resolve the call. Knowing all configured services, the central
finds the matching service for the request using the "name", and forwards the request information. The
result of the service-request is returned to the caller thereafter.

This component is performing application health checks. That means that it  verifies if a specific component or responsibility is performing correctly.

We are using Dropwizard metrics to implement health checks.

==== mics-home.war (backend tier)

This component receives all service-calls from the frontend. It is placed in parallel to the
Frontend-SPA with the same HTTP-host and the same port. Any configuration for the
frontend is done in its home application.

==== PlannedGridMeasuresDev-DB (Database tier)

This component stores the data of the planned grid measures. It provides an interface to the planned-grid-measures.jar to create or
change data in the database.

The PlannedGridMeasuresDev-DB runs on a Postgres DBMS.
(The decision to use the Postgres DBMS was made by the openKONSEQUENZ architecture committee)

The pleannedGridMeasures needs information from the system "SCADA". Therefore, it must provide an interface for receiving the according data, see figure 1.
(see below "Import functionality")

=== Level 2

==== PlannedGridMeasureFE (frontend tier)

The frontend component implements the concept of a single-page application (SPA). The framework used is Angular5.

It divides the PlannedGridMeasureFE into three layers:

. *Components* - The components (pages, lists, dialogs, common comp.) represent the presentation layer and the control layer. A component contains the control logic (.ts-file), an HTML-fragment as presentation description (.html-file) and a style definition (.css-file).
. *Services* - The service component communicates with the interfaces of the backend via HTTP requests by using the model component.
. *Model* - The model corresponds to the view-model of the backend tier.

.Frontend tier
[options="header,footer"]
[plantuml]
----

node PlannedGridMeasure_Frontend  {
    component Model


    node Components {
        component "Pages"
        component Lists
        component "Common Components"
    }

    component Services

    Components --> Services
    Components --> Model
    Services --> Model
}

node "Planned Grid Measure Backend (simplified)" {
    component RestService
    component ViewModel_API
}

Services .. RestService
Model .. ViewModel_API
RestService --> ViewModel_API
----


==== planned-grid-measures.war (backend tier)

The backend tier contains five components which can be summarized in three layers:

. *Presentation layer* - Represented by
 .. REST-Srv
 .. View model
. *Controller layer* - Represented by
 ..	Controller
.	*Model layer* - Represented by
 ..	DAO
 ..	Model



.Backend tier
[options="header,footer"]
[plantuml]
----

node "Planned Grid Measure Backend"  {
    component Model


    component RestService

    component ViewModel_API

    component Controller

    component DAO

    RestService --> ViewModel_API
    RestService --> Controller
    DAO --> Model
    Controller --> DAO
 }

node DBMS {
    component PlannedGridMeasuresDB
}

DAO --> PlannedGridMeasuresDB
----

==== PlannedGridMeasures-DB (database tier)

The PlannedGridMeasures-DB is realized as a relational database system.

.Database tier
[options="header,footer"]
[plantuml]
----

node DBMS {
    component PlannedGridMeasuresDB
}
----


==== Program Configuration
In the root-directory of the planned-grid-measure backend there
is a configuration file named *backendSettings.json*.

[source, json]
{
  "reminderPeriod": 48,
  "bpmnGridConfig": {
      "skipForApproval": false,
      "endAfterApproved": false,
      "skipRequesting": false,
      "endAfterReleased": false,
      "skipInWork": false
  },
  "emailTemplateAddressesForNotification": "approvedEmailTemplate, canceledEmailTemplate",
  "reloadMailAddressesInMin": 1
}

The following configurations can be done in this file:

- reminderPeriod: Number of hours before now, used to highlight gridmeasures
- bmpnGridConfig.*: Switches for the process workflow:

 .. skipAfterApproval=true will skip the approval-subworkflow
 .. endAfterApproved=true will end the whole process when the gridmeasure is
 approved
 .. skipRequesting=true will skip the requesting-subworkflog
 .. endAfterReleased=true will stop the process, once the gridmeasure is has
 the status released
 .. skipAfterWork=true will jump over the process after work

[TIP]
The names of the workflow switches are also used in the *roleAccessConfiguration*
json file (see below).

- emailTemplateAddressesForNotification: Mail-addresses enlisted in these email-templates
  will automatically show up in the field 'E-Mail-Adresse' in a new grid measure.

- reloadMailAddressesInMin: There is a routine to load all available mail-addresses from
  the database into a cache (for autocomplete functionality of mail addresses). Here is set, in which
  time-intervall this routine shall start again (in minutes).



In he backend a JSON file is used to configure
the editing rights of a role and
the controlling rights of a user accordingly to the grid measure status.

This JSON file is located in *roleAccessConfiguration folder.

The structure of this JSON file is:

[source, json]
{
    "editRoles": [
        {
            "name": "planned-policies-measureapplicant",
            "gridMeasureStatusIds": [
                0
            ]
        },
        ...
    ],
    "controls": [
        {
            "gridMeasureStatusId": 0,
            "activeButtons": [
                "apply",
                "save"
            ],
            "inactiveFields": [
                "statusId",
                "modUser",
                "id",
                "applicantControl"
            ]
        },
         {
            "gridMeasureStatusId": 0,
            "activeButtons": [
                "apply",
                "save"
            ],
            "inactiveFields": [
                "statusId",
                "modUser",
                "id",
                "applicantControl"
            ]
        },
        {
            "gridMeasureStatusId": 1,
            "activeButtons": [
                "cancel",
                "[skipForApproval:false]forapproval",
                "[skipForApproval:true]approve",
                "save"
            ],
            "inactiveFields": [
                "createUserDepartment",
                "modUserDepartment",
                "id",
                "applicantControl",
                "statusId",
                "modUser",
                "titleControl",
                "removeglyphicon",
                "selectedFileName",
                "notSelectedFileName",
                "goToGridMeasureDetailBtn"
            ]
        },
        ...
    ]
}

There are two objects in this JSON file. The first one (*editRoles*) determins
which statuses (that means which grid measure with a specific status e.g New or Applied)
a role is allowed to edit. The second (*controls*) determins which buttons and fields are active
in the grid measure detail page for each status.

** *editRoles*: this object is an array. There are as many elements as roles.
Each element of this array has two members.
The *name* member contains the name of the role.
The *gridMeasureStatusIds* member contains the grid measures statuses,
which this role is allowed to edit. This member is an array, which means that a user-role can edit more than one status.

** *controls*: this object is also an array. It has as many
elements as there are statuses. Each of these elements has three members.
The first one, *gridMeasureStatusId*, is the status of the grid measure.
For each status the active buttons (*activeButtons*) and
the inactive fields (*inactiveFields*) are defined. Both, buttons and fields, are arrays.

[TIP]
The workflow switches can be used to toggle the visibility of buttons.
Example: Look at
the line *[skipForApproval:false]forapproval*. The button *forapproval* will
only be shown, if the workflow-switch is configured to *false*.



==== E-Mail configuration
The E-Mail is configured in the backend tier. There are 3 steps for the E-Mail configuration:

. *SMTP settings* are configured in the according yml-file found in the root folder of the microservice.
  (For example:  'prodserver.yml' is located next to 'planned-grid-measures.jar')
  "sender" is the general email sender address for every e-mail.

[source, yml]
{
  ...
  emailConfiguration:
    smtpHost: localhost
    port: 1025
    sender: testSenderDevServer@test.de
  ...
}

[start=2]
. *E-Mail template paths* are configured in the 'mailTemplatesPaths.json' in the folder 'emailConfiguration'. This can be
 found in the root folder.


[source, json]
{
  "appliedEmailTemplate": "emailConfiguration/emailTemplates/appliedEmailTemplate.txt",
  "cancelledEmailTemplate": "",
  "rejectedEmailTemplate": "",
  "approvalEmailTemplate": ""
}

[start=3]
. These *E-Mail-Templates* can be found where you have configured them in step 2.
  These templates are txt-files which must have the following structure:

....
To: test1Recipient@test.de, test2Recipient@test.de
CC: testCCRecipient@test.de, test2CCRecipient@test.de
Subject: Die Maßnahme $gridMeasureTitle$ mit Beginn: $plannedStarttimeFirstSinglemeasure$ wurde in den Status Beantragt geändert.

Body:

Sehr geehrte Damen und Herren,

die im Betreff genannte Maßnahme ist über folgenden Link erreichbar:

$directMeasureLink$

Mit freundlichen Grüßen

Ihr Entwickler-Team der PTA GmbH
....

*Structure keywords* are `To:` ,`CC:`,`Subject:`, and `Body:`. After `Body:` is where you put the content of your E-Mail the other
keywords are self-explanatory.

Then you have also *Content keywords* starting and ending in a dollar sign like '$directMeasureLink$'
these keywords will be replaced according to their scope of application.

*Content keywords list*

.Content keywords
|===
|Keyword |Explanation

|$gridMeasureTitle$
|Titel der Maßnahme

|$plannedStarttimeFirstSinglemeasure$
|Beginn der ersten geplanten Einzelmaßnahme

|$directMeasureLink$
|Direkter Link zur Netzmaßnahme

|===

==== RabbitMQ Configuration

. *Prerequisites:*

RabbitMQ Server is already installed and running

It is recommend to enable the 'Management Plugin' to be able to use the Web UI
(http://www.rabbitmq.com/management.html)

The initial user and password for the Web-UI is '"guest"' but you need to create
a new user since the initial user can  only connect via 'localhost'.

Create new user with admin rights.

[start=2]
. *RabbitMQ Configuration in the backend tier*

RabbitMQ is configured in the according yml-file found in the root folder of the microservice.
(For Example: prodserver.yml is located next to planned-grid-measures.jar)

[source, yml]
{
  ...
  rabbitmqConfiguration:
    host: 172.18.22.160
    port: 5672
    user: admin
    password: admin
    exchangeName: openk-pgm-exchange
    queueNames : pgm-applied-queue, pgm-forapproval-queue, pgm-canceled-queue, pgm-approved-queue, pgm-rejected-queue, pgm-requested-queue, pgm-released-queue, pgm-finished-queue, pgm-closed-queue
    unroutedMessagesExchangeName: openk-pgm-unrouted-exchange
    unroutedMessagesQueueName: pgm-unrouted-queue
  ...
}

- 'host' : Host adress of RabbitMQ Server
- 'port' : Port of RabbitMQ Server (Default: 5672)
- 'user' : Username you create in Step 1 (Prerequisites)
- 'password' : Password belonging to user you create in step 1 (Prerequisites)
- 'exchangeName' : The name of the 'Exchange' (https://www.rabbitmq.com/tutorials/tutorial-three-python.html)
- 'queueNames': Comma separated names of the Queues

All Queues will be created and bind to the Exchange defined by 'exchangeName' automatically.

CAUTION: You must define 8 Queuenames with the following pattern: 'someword-ROUTINGKEY-words' where 'ROUTINGKEY' is one of the 8
planned grid measure status
(Example for status 'applied': pgm-applied-queue)

Complete list of example Queuenames and their Routing keys:

[source]
Queuename: pgm-applied-queue    | Routing key:  applied
Queuename: pgm-canceled-queue   | Routing key:  canceled
Queuename: pgm-approved-queue   | Routing key:  approved
Queuename: pgm-rejected-queue   | Routing key:  rejected
Queuename: pgm-requested-queue  | Routing key:  requested
Queuename: pgm-released-queue   | Routing key:  released
Queuename: pgm-finished-queue   | Routing key:  finished
Queuename: pgm-closed-queue     | Routing key:  closed


- 'unroutedMessagesExchangeName' : Name of the Exchange which catches all failed messages.
- 'unroutedMessagesQueueName' : Name of the Queue which catches all failed messages.


== Runtime view

=== Login / authentication


There is no login page, since the openK-Portal-Application is responsible for authentication and
the whole SSO (single sign on) process.
Therefore the application has to be started by providing a valid authentication token.
This token is a JWT (JSON Web Token).

.plannedGridMeasure application is called by the *portal* application. The User is already logged in
[plantuml]
....
actor User
participant PortalFrontend
participant PortalBackend
participant GridMeasureFrontend
entity GridMeasureStorage
participant GridMeasureBackend


User->PortalFrontend: Start GridMeasure(JWT)
PortalFrontend->GridMeasureFrontend: nav. to frontend-URL with JWT
GridMeasureFrontend->GridMeasureStorage: Extract JWT and store token in session
... some delay ...
GridMeasureFrontend->GridMeasureBackend: Call any secured service with JWT
group Call secured service

    GridMeasureBackend->PortalBackend: "/checkAut(JWT)"
    group Authorization succeeded
        GridMeasureBackend->GridMeasureBackend: run service
        GridMeasureBackend->GridMeasureFrontend: return service result
    end
    group Authorization failed
        GridMeasureBackend->GridMeasureFrontend: return HTTP Code 401
    end
end
....

=== Plan and approve grid measures

The process how grid measures are planned, approved and requested is shown in the following diagrams:
The process described there is exactly represented in the code of the backend (package "bpmn/gridmeasure").

image::massnahme_planen_und_genehmigen_1.png[]

image::massnahme_durchfuehren_u_abschliessen_1.png[]

image::massnahme_durchfuehren_u_abschliessen_2.png[]

When the rest service "storeGridMeasure" is called on the backend, the process resumes at the
process step that corresponds to the existing status (in the database) of the "GridMeasure"
to be saved.

Example: the gridmeasure with id 5 has the status "FOR_APPROVAL" in the database.
Now the rest service "storeGridMeasure" is called with a grid measure (id=5) having the status "cancelled"
(="storniert") in the given object.

Because grid measure 5 still has the status "FOR_APPROVAL" in the database, the process resumes at
"<FOR_APPROVAL> Maßnahmeantrag und Ablauf prüfen". The next decision is made by looking at the status
of the grid measure object, passed to the service "storeGridMeasure" (which is "CANCELLED"). This results in "firing"
PORT2 in the diagram, etc

=== Deployment of the application components

==== Deployment of the frontend

The Frontend SPA is built as a folder, that contains all the required files for
the application. When deploying the frontend application, the content of the "dist"-folder
within the frontend development-directory has to be copied into the
target-directory of the apache-tomcat:

 <Apache-Tomcat>/webapps/plannedGridMeasuresFE

If the target folder does not exist, it has to be created manually.

==== Deployment of the backend
TODO:

==== Deployment of the database
The component "Flyway" is used to make to distribute structural
or content related changes to the database.

The database is built out of the scripts in the directory "db/migrations". Every sql
script contains the complete db script for the grid measure database (in different versions).
The highest version number indicates the currently valid script.

==== Configuration of the system

===== DB based configuration

TODO: _fd -> extract configuration script!

. Grid territories - The grid-territories have to be configured in the DB-Table *ref_grid_territory*

Please modify the "V0_<latest>__CREATE_PLGM_DB.sql" script (in "<grid-measures-mics-backend project
dir>\db\migrations" ) to change the
configuration. (This file is contained in the *oracle* folder as well.)

===== Configuration of the webserver

There is a file *context.xml* in the "conf" subdirectory (*<TOMCAT>/conf*) of the target apache tomcat installation.
Add the following parameter and resource in order to access the correct mics-home configuration:

.context.xml
[source,xml]
----
[...]
<!-- The contents of this file will be loaded for each web application -->
<Context>

    <!-- Default set of monitored resources. If one of these changes, the    -->
    <!-- web application will be reloaded.                                   -->
    <WatchedResource>WEB-INF/web.xml</WatchedResource>
    <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>

    <!-- Parameter for different backend configs  -->
    <Parameter name="OK_PORTAL_ENVIRONMENT" override="false" value="Production"/>
	<Parameter name="OK_MICS_HOME_ENVIRONMENT" override="false" value="Production"/>

[...]
----

If you configure the parameter "OK_MICS_HOME_ENVIRONMENT" to the value "Production", then
the configuration file "<TOMCAT>/webapps/mics-home-service/WEB-INF/classes/backendConfigProduction.json
will be used.

===== Configuration of the planned grid measures backend

When starting the microservice of the planned grid measures backend you have to provide a configuration "YML"
file.

TODO: Describe configuration possibilities.



=== CI- and CD-Components

==== GIT-Repository

Central service repository
http://http://git.eclipse.org/c/openk-usermodules/org.eclipse.openk-usermodules.mics.centralService.git/

Home service repository
http://git.eclipse.org/c/openk-usermodules/org.eclipse.openk-usermodules.mics.homeService.git/


Frontend repository:
http://git.eclipse.org/c/openk-usermodules/org.eclipse.openk-usermodules.plannedGridMeasures.frontend.git/

Backend repository (containing this documentation and the database creation scripts)
http://git.eclipse.org/c/openk-usermodules/org.eclipse.openk-usermodules.plannedGridMeasures.backend.git/


=== Continuous deployment

The continuous deployment is realized on two platforms:

 * the development platform (Dev-Environment)
 * the quality platform (Q-Environment)

The automatic deployment on both of the environments is
directly linked to the branches on the GIT-repositories:

. "SNAPSHOT" or "DEVELOP"
. "MASTER" or "TRUNC"

The running development is exclusively made on the Snapshot-Branch. Every time
a developer checks in (pushes) code to the repository, an automatic build
starts on the hudson ci-server. If the Snapshot-build is successful, then the result
of that build is directly deployed on the Dev-environment.

At the end of a scrum sprint or when a big user story is realized, all
the code changes are merged from the *Snapshot*-Branch to the *Trunc*.
This automatically triggers the build and the deployment on the
Q-environment.


== Design decisions

All architecture decisions are based on the Architecture Committee Handbook. There are no deviations.

== Risks and Technical Debts

(Currently there aren't any known issues)

<<<

== Glossary

.Abbreviations and glossary terms
[options="header,footer"]
|========================================================
|Short|Long|German|Description
|AC|Architecture Committee|Architektur-Komittee|Gives framework and constraints according to architecture for oK projects.
|CNCU|Central Network Control Unit||
|DAO|Data Access Objects||
|DSO|Distribution System Operator|Verteilnetz-betreiber (VNB)|Manages the distribution network for energy, gas or water.
|EPL|Eclipse Public License||Underlying license model for Eclipse projects like planned-grid-measures@openK
|ESB|Enterprise Service Bus||Central instance to exchange data to overcome point-to-point connections.
|GNM|Geplante Netzmaßnahme||German name of the module 'Planned Grid Measures'
|oK|openKONSEQUENZ|openKONSEQUENZ|Name of the consortium of DSOs
|QC|Quality Committee|Qualitätskomitee|Gives framework and constraints according to quality for oK projects.
|SCADA|Supervisory Control and Data Acquisition|Netzleitsystem|System, that allows DSOs view/control actual parameters of their power grid.
|========================================================