= openKonsequenz - How to run the module "gridFailureInformation@openK"

:Date: 2020-03-24
:Revision: 1

:icons:
:source-highlighter: highlightjs
:highlightjs-theme: solarized_dark

:imagesdir: ../img
:iconsdir: ../img/icons

:lang: en
:encoding: utf-8

<<<

IMPORTANT: Please be sure that you have first *Portal (Auth n Auth)* and *ContactBaseData* installed and configured!

== Requirements
* Browser (Chrome or Edge suggested)

== Prerequisites

* *To see this application running you have to run Portal and ContactBaseData application too.*
The reason is the authentication, which happened in the Portal login phase. Additionally
contacts that are used in the gridFailureInformation application are maintained in the
ContactBaseData module.

* A developing and administrating software for databases

** To work with a postgreSQL database is pgAdmin suggested

*** Download and install pgAdmin (version 4 is used during developing process) from:
        https://www.pgadmin.org/download/

*** Create a database

*** To initialize the database schema run the latest sql script:

 /src/resources/db/migration/V0_??__CREATE_GFI_DB.sql


== How to run the Backend
To run the backend you to create a separate directory for each backend microservice
you want to use, get the **.jar* file from the *target* directory of the java-project (which should exists after
a successful maven-build) and copy it to the new directory (i.e. "gfsBackService").

Depending on which services you want to use, you have to install different microservices:

* *addressImport* (Importer for address and station data)
* *gfsBackend* (Main backendservice - always needed)
* *mailExport* (Export messages via e-mail)
* *SAMOInterface* (Import interface for the SAMO System)
* *StoerungsauskunftInterface* (Import and export interface for the site "Stoerungsauskunft.de")

Once you created a directory and copied the **.jar* file you need to configure each service. Please
read the architecture documentation to get information about the possible configurations of the services.

* Open a command line and navigate to the root folder of the service you want to start
* Run the command

[source,command]
----
   $  java -jar <servicename>.jar
----
{blank}


== How to run the Frontend
To run the frontend project you need to have installed and updated Node.js and npm Angular-CLI.

=== Compile the Frontend

To compile say Angular-CLI to start.

* Open a command line and navigate to the root folder of the frontend project
* Run the command

[source,command]
----
   $  npm start
----
{blank}

* Open a browser and type:

[source,http]
----
    http://localhost:4200
----
{blank}

IMPORTANT: The reason you maybe don´t see the application running properly, is that you have not even logged in.
To do so, run first the Portal project, where you can log in and then open the elogbook.

== How to run the SIT-Web-Cache-Service
=== Prerequirements
* SIT-Web-Cache-Service is built properly. Otherwise following the instructions in the *howtoBuild* file!
* Your secured DMZ (demilitarized zone) can host the SIT-Web-Cache-Service.
* SIT-Web-Cache-Service needs *nodejs* and *nestjs*. Both have to be installed as described in the *howtoBuild* file.
* The SIT-Web-Cache-Service should be reachable from the SIT_BE. 

=== Run the service
* Copy all files from the build output to the provided folder in the DMZ.
* Open a command line and navigate to this folder. 
* Start the service with the following commands:
+
[source,command]
----
    $ node dist/main
----
{blank}

== How to run SIT-Web-FE (map- and table-component)
=== Prerequirements
* SIT-Web-FE is built properly. Otherwise following the instructions in the *howtoBuild* file!
* SIT-Web-Cache-Service runs properly. 
* Your secured DMZ (demilitarized zone) can host the SIT-Web-FE.
* The SIT-Web-FE have to communicate with the SIT-Web-Cache-Service and both parts should be in the same DMZ.
* If you do not have a web server in your environment (e.g. in a development environment) you can use *http-server*. To install this free and lightweight http server run the following command in a command line:
+ 
[source, command]
----
    $ npm install -g http-server
----
* If you want to run SIT-Web-FE with *http-server* you need *nodejs* which have to be installed as descrbed in the *howtoBuild* file.

IMPORTANT: The description below use *http-server* as an http server. +
In many cases you will have your own web server - like *tomcat*, *apache*, *IIS* etc. - 
and you have to configure proxy settings and the http communication between all SIT components within this web server.

=== Run the map and/or table component (e.g. with http-server)
* Copy all files from the build output ('_dist/grid-failure-information-web-comp_') to the provided folder in the DMZ.
* Open a command line and navigate to this folder. 
* Start the service with the following commands:
+
[source,command]
----
    $ http-server dist/grid-failure-information-map-app/ -P http://localhost:3003 -p 3001
----
{blank}
+
CAUTION: Take care about this parameters: +
*-P*: The proxy for requesting the SIT-Web-Cache-Service. +
*-p*: TCP-Port of SIT-Web-FE

* Open a browser and open the address to your SIT-Web-FE with the correct TCP-Port:
+
[source,http]
----
    http://{SIT-Web-FE Adress}:3001
----
{blank}
+
=> A map and a table with all grid failure appears in your browser.

== How to use SIT-Web-FE

To show all grid failure on a map or in a table inside your own web application you can run SIT-Web-FE beside your application.

=== Prerequirements
* To have an access to the failure information you have to had installed the cache service as well.

=== Integrate the map/table component

* Copy all files and the _assets_ folder from the build output (_/dist/grid-failure-information-web-comp_) to your own web application folder. ([lime]#*green boxes*# in the image below.)
* Reference the *.js* and *.css* files in your web application ([yellow]#*yellow boxes*# in the image below).
* Use the map/table like an html component with the following tags: +
*<openk-grid-failure-information-map-comp></openk-grid-failure-information-map-comp>* +
*<openk-grid-failure-information-table></openk-grid-failure-information-table>* +
([red]#*red box*# in the image)

.Neccessary files for map integration
[options="header"]
image::SIT_mapAppUsage.png[]

=== Filter the shown grid failure information with postcode

To Filter the shown information (table and/or map) you can set the postcode to the map/table component.

The following example describes the usage in an example.

.Neccessary files for map integration
[options="header"]
image::SIT_mapAppUsagexFilter.png[]

The example has an text input box. Each change of this textbox will fire an event and within this event a javascript function is called with the entered value. 
Within this function we reference the map/table components and set the value to the *postcode* attributes. 
The filtering will be done immediatly.

TIP: This attribute can also be bound to a data model in a javascript framework manner (e.g. angular).