GNM-1021: Architekturdoku auf Rechtschreib- und Formulierungsfehler überarbeitet
diff --git a/src/main/asciidoc/architectureDocumentation/architectureDocumentation.adoc b/src/main/asciidoc/architectureDocumentation/architectureDocumentation.adoc
index 0068e20..e2ee1a8 100644
--- a/src/main/asciidoc/architectureDocumentation/architectureDocumentation.adoc
+++ b/src/main/asciidoc/architectureDocumentation/architectureDocumentation.adoc
@@ -19,7 +19,7 @@
:source-highlighter: highlightjs
:highlightjs-theme: solarized_dark
-This documentation bases on ARC42-Template (v7.0):
+This documentation is based on the ARC42-Template (v7.0):
<<<
@@ -27,7 +27,7 @@
=== Requirements Overview
-The module 'Planned Grid Measures' should support the network operators by managing the required maintenance and repair work.
+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).
@@ -39,7 +39,7 @@
* "Anfragespezifikation Modul Geplante Netzmaßnahme" from 12-09-2017.
=== Quality Goals
-The module 'Planned Grid Measures' represents a user module that bases on the architecture platform of openKONSEQUENZ. The main quality
+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.
@@ -78,9 +78,9 @@
[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.
+|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 the Quality and Architecture Handbook of openKONSEQUENZ.
+|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.
|=========================================================
@@ -106,16 +106,16 @@
[options="header,footer"]
|========================================================
|Component|Constraints
-|Basis components of the reference platform
+|Base components of the reference platform
a|* Application Server Tomcat
* JPA EclipseLink
* Database PostgreSQL
-|Enterprise Service Bus
+|Enterprise service bus
a|* ESB Talend
* Communication via RESTful Webservices
-|Programming Language Frontend
+|Programming language frontend
a|* Angular
* Bootstrap
* jQuery
@@ -127,7 +127,7 @@
|Java QA environment
a| * Sonarqube 5.6.6
-|Programming Language
+|Programming language
a|* Backend: Java 1.8
* Frontend: Angular 4.0.0 (Javascript, Typescript, HTML5, CSS3)
@@ -138,7 +138,7 @@
a|* Backend: Maven
* Frontend: NodeJS + Angular/cli
-|Libraries, Frameworks,Components
+|Libraries, frameworks, components
a|* Used Libraries/Frameworks have to be compatible to the Eclipse Public License
|Architecture Documentation
@@ -171,7 +171,7 @@
|=========================================================
|Name of the library|Version|Artefact-id|Usage|License|Tier
|Node.js|6.10.0 LTS||JavaScript Runtime (server side)|MIT License|Frontend
-|npm (in Node.js enthalten)|3.10.10||Node Package Manager (package manager for libraries)|Artistic License 2.0|Frontend
+|npm |3.10.10||Node Package Manager (package manager for libraries)|Artistic License 2.0|Frontend
|Angular|4.0.0||UI-Framework|MIT License|Frontend
|Angular Material|2.0.0-beta.2||Angular Material Design Components|MIT License|Frontend
|Bootstrap|3.3.7||CSS-Framework |MIT License|Frontend
@@ -456,7 +456,7 @@
* 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 also be documented in the overall openKONSEQUENZ interface profile and it should use REST & XML.
+* 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.
@@ -476,7 +476,7 @@
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.
+. *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.
@@ -497,11 +497,11 @@
----
-Bases on the abstract concept mentioned above, the following figure shows the concrete realization of the main components.
+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-SPA
+ - plannedGridMeasuresFE
. Business Logic
- MICS-HOME: (project independent webapplication)
- MICS-CENTRAL: (project independent service distribution and
@@ -560,7 +560,7 @@
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 do so we are using "Dropwizard" framework.
+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:
@@ -577,24 +577,24 @@
* Metrics: Dropwizard has support for monitoring using the metrics library. It provides unparalleled insight into what our code does in production.
-==== plannedGridMeasureFE SPA
+==== 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)
+==== planned-grid-measures.jar (backend tier)
This component implements the business functionality of the planned grid measures. And it provides services, that the
-GridMeasureFE – SPA can use the functions in the frontend.
+plannedGridMeasureFE can use the functions in the frontend.
The "Dropwizard" framework is used to implement this application.
-==== mics-central.jar (Backend tier)
+==== 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
+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
@@ -604,11 +604,11 @@
We are using Dropwizard metrics to implement health checks.
-==== mics-home.war (Backend tier)
+==== mics-home.war (backend tier)
-This component receives all service-calls from the frontend. It is placed parallel to the
-Frontend-SPA with the same HTTP-host and the same Port. Any configuration for the
-frontend is done in it's home application.
+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)
@@ -616,22 +616,22 @@
change data in the database.
The PlannedGridMeasuresDev-DB runs on a Postgres DBMS.
-(The decision to use the Postgres DBMS was made by the openKONSEQUENCE archtecture committee)
+(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
-==== GridMeasureFE – SPA (Frontend tier)
+==== PlannedGridMeasureFE (frontend tier)
The frontend component implements the concept of a single-page application (SPA). The framework used is Angular5.
-It divides the GridMeasureFE into three layers:
+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).
+. *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.
+. *Model* - The model corresponds to the view-model of the backend tier.
.Frontend tier
[options="header,footer"]
@@ -666,13 +666,13 @@
----
-==== planned-grid-measures.war (Backend tier)
+==== 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
+ .. View model
. *Controller layer* - Represented by
.. Controller
. *Model layer* - Represented by
@@ -711,7 +711,7 @@
DAO --> PlannedGridMeasuresDB
----
-==== PlannedGridMeasures-DB (Database tier)
+==== PlannedGridMeasures-DB (database tier)
The PlannedGridMeasures-DB is realized as a relational database system.
@@ -762,15 +762,15 @@
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 Gridmeasure.
+ 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 to a cache (for autocomplete function of mail-addresses). Here is set, in which
+ 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 Backend tier we are using a JSON file to configure
+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.
@@ -842,22 +842,22 @@
]
}
-There are two objects in this JSON file. The first one (*editRoles*) controls
-which statutes (with status is meaning a grid measure with a specific status e.g New or Applied)
-can a role edit and the second (*controls*) which buttons and fields are active
+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 the roles.
+** *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 role of the user and the *gridMeasureStatusIds* contains the grid measures statuses,
-which this role can edit.
-The second member is an array, which means that a user-role can edit more than one statuses.
+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. This array has as many
-elements as the statuses are. Each of these elements has three members.
+** *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 are the active buttons (*activeButtons*) and
-the inactive fields (*inactiveFields*) defined. Both, buttons and fields, are arrays.
+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.
@@ -867,11 +867,11 @@
-==== E-Mail Configuration
-The E-Mail is configured in the Backend tier. There are 3 steps for the E-Mail Configuration:
+==== 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')
+. *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]
@@ -885,8 +885,8 @@
}
[start=2]
-. *E-Mail Templatepaths* are configured in the 'mailTemplatesPaths.json' to be found in the folder 'emailConfiguration' also
- which is found in the root folder.
+. *E-Mail template paths* are configured in the 'mailTemplatesPaths.json' in the folder 'emailConfiguration'. This can be
+ found in the root folder.
[source, json]
@@ -898,8 +898,8 @@
}
[start=3]
-. These *E-Mail-Templates* are to be found where you have configured them in Step 2.
- These Templates are txt-files which have to have the following structure:
+. 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
@@ -916,18 +916,18 @@
Mit freundlichen Grüßen
-Ihre Entwickler-Team der PTA GmbH
+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
+*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 with a dollar sign like '$directMeasureLink$'
+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 list*
-.Content Keywords
+.Content keywords
|===
|Keyword |Explanation
@@ -948,7 +948,7 @@
RabbitMQ Server is already installed and running
-It's recommend to enable the 'Management Plugin' to be able to use the Web UI
+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
@@ -957,7 +957,7 @@
Create new user with admin rights.
[start=2]
-. *RabbitMQ Configuration in the Backend tier*
+. *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)
@@ -978,14 +978,14 @@
- '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)
+- '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)
- 'autoSetup' : If set to 'true' the Autosetup will fire once on application start.
Autosetup means the Planned Grid Measure Microservice will create the Exchange according to the name defined one line
above. All needed Queues will be created and bind to the Exchange.
-The automatically create Queues and their belonging routing keys are:
+The automatically created queues and their belonging routing keys are:
[source]
Queuename: pgm-applied-queue | Routing key: applied
@@ -1003,12 +1003,12 @@
(Example: 'applied' for the Applied-Queue).
-== Runtime View
+== Runtime view
-=== Login / Authentication
+=== Login / authentication
-There is no login page, since the openK-Portal-Application is responsible for Authentication and
+There is no login page, since the openK-Portal-Application is responsible for authentication and
the whole SSO (single sign on) process.
Therefore the elogbook application has to be started by providing a valid authentication token.
This token is a JWT (JSON Web Token).
@@ -1053,16 +1053,16 @@
image::massnahme_durchfuehren_u_abschliessen_2.png[]
-When the rest service"storeGridMeasure" is called on the backend, the process resumes at the
+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 gridmeasure (id=5) having the status "cancelled"
+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 gridmeasure 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 looking at the status
+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
@@ -1072,7 +1072,7 @@
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
+within the frontend development-directory has to be copied into the
target-directory of the apache-tomcat:
<Apache-Tomcat>/webapps/plannedGridMeasuresFE
@@ -1099,11 +1099,11 @@
. Grid territories - The grid-territories have to be configured in the DB-Table *ref_grid_territory*
Please modify the "03_config_DB_*.sql" script (in "<elogbook backend project dir>\db\postgreSQL" ) to change the
-configuration. (This file is contained in the *oracle* folder as well.
+configuration. (This file is contained in the *oracle* folder as well.)
===== Configuration of the webserver
-There exists the file *context.xml* in the "conf" subdirectory (*<TOMCAT>/conf*) of the target apache tomcat installation.
+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
@@ -1142,14 +1142,14 @@
==== GIT-Repository
-Frontend Repository:
+Frontend repository:
http://git.eclipse.org/c/elogbook/elogbookFE.git/
-Backend Repository (containing this documentation and the db creation scripts)
+Backend repository (containing this documentation and the database creation scripts)
http://git.eclipse.org/c/elogbook/elogbook.git/
-=== Continuous Deployment
+=== Continuous deployment
The continuous deployment is realized on two platforms:
@@ -1164,18 +1164,18 @@
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
-outcome of that build is directly deployed on the Dev-Environment.
+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 userstory is realized, all
+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.
+Q-environment.
-== Design Decisions
+== Design decisions
-All architecture decisions based on the Architecture Committee Handbook. There are no deviations.
+All architecture decisions are based on the Architecture Committee Handbook. There are no deviations.
== Risks and Technical Debts
@@ -1189,12 +1189,12 @@
[options="header,footer"]
|========================================================
|Short|Long|German|Description
-|AC|Architecture Committee|Architektur-Komittee|Gives Framework and Constraints according to architecture for oK projects.
+|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 elogbook@openK
-|ESB|Enterprise Service Bus||Central instance for exchange of data to overcome point-to-point connections.
+|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.
