src/main/asciidoc/howto/howtoRun.adoc

= 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_60__CREATE_GFI_DB_Complete_V_1.0.0.sql


== How to run the Backend
To run the backend you need 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. "gfsBackendService" = [_deployFolder_]).

To configure each application (microservice) and adjust to your likings, we use the file *application.yml* for. +
Copy the file *application.yml* from [microservice]/src/main/resources/application.yml next to the **.jar* in your [_deployFolder_].
This step has to be done for *each* microservice but most of the configuration is done in the "main backend" (i.e.
"gfsBackendService"), so every microservice has its own *application.yml*. +
The folder *logs* is created at the first time you start the application.

.Deployment folder structure, folder logs is created at first start
image::deployStructure.png[]


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)
* *SARISInterface* (Import interface for the SARIS 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 via the *application.yml*. +
See *howtoConfigure* 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

IMPORTANT: Please be sure that you have first *Portal (Auth n Auth)* and *ContactBaseData* installed and configured!
Make sure you have added the module *gridFailureInformation* to the *Portal (Auth n Auth)* module configuration (see Portal Project: moduleConfig***.json)

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.

* Navigate to the root folder of the project. Adjust the parameter "target" in the file *proxy.conf.json* (root folder) accordingly, pointing to the main backend url and its port. +
Example: If you have started the main backend ("gfsBackendService") on the same machine with default values, then the "target" would be
"http://localhost:9165/".
* Open a command line and navigate to the root folder of the frontend project
* Run the command

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

* You can now access the application via the *Portal (Auth n Auth)* with a valid user who owns rights for the module *gridFailureInformation*.

{blank}

== 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).