[BP-844] doc: cyclic report generation doc * added user documentation for cyclic report generation user interface * added architecture documentation parts for cyclic report generation * added description for new configuration parameters Signed-off-by: Tobias Stummer <stummer@develop-group.de>
diff --git a/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/images/ok_db_model_crg.png b/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/images/ok_db_model_crg.png new file mode 100644 index 0000000..258c621 --- /dev/null +++ b/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/images/ok_db_model_crg.png Binary files differ
diff --git a/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/src/01_introduction_and_goals.adoc b/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/src/01_introduction_and_goals.adoc index a696220..518257a 100644 --- a/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/src/01_introduction_and_goals.adoc +++ b/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/src/01_introduction_and_goals.adoc
@@ -31,6 +31,7 @@ |Role/Name|Contact|Expectations |Product Owner (represents the Distribution System Operators)|Oliver Frank, Heinrich Schubert|The software must fulfil their functional and nonfunctional Requirements. |Module Developer|Maximillian Ridder, Christoph Weber, Markus Wolf, Saverio Mancuso, Jan Gerste|All relevant business and technical information must be available for implementing the software. +|Cyclic Reports Developer| Tobias Stummer, Dr. Christopher Keim| All relevant business and technical information must be available for implementing the cyclic report generation feature. |External Reviewer (represents the AC/QC)|Thorsten Meyer|The software and the documentation is realized according 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.
diff --git a/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/src/05_building_block_view.adoc b/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/src/05_building_block_view.adoc index af4790b..a074129 100644 --- a/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/src/05_building_block_view.adoc +++ b/oKBereitschaftsplanungBackend/src/main/asciidoc/arch/src/05_building_block_view.adoc
@@ -46,6 +46,14 @@ .database_tables image:../images/ok_db_model_002.png[ok_db_model_002.png,600,600,align="center"] +===== Cyclic Report Generation + +The cyclic report generation configuration is stored in the database. +Each cyclic report generation trigger configuration is stored as one entry in the *reportgenerationconfig* table. + +.database_tables_cyclic_report_generation +image::../images/ok_db_model_crg.png[width=150] + ==== Program Configuration ===== Frontend Configuration @@ -62,5 +70,5 @@ } ===== Backend Configuration -====== E-Mail Configuration -Not defined yet. \ No newline at end of file +For details of the backend configuration please see the *config* documentation. +
diff --git a/oKBereitschaftsplanungBackend/src/main/asciidoc/howto/config.adoc b/oKBereitschaftsplanungBackend/src/main/asciidoc/howto/config.adoc index c8155b4..f1e6051 100644 --- a/oKBereitschaftsplanungBackend/src/main/asciidoc/howto/config.adoc +++ b/oKBereitschaftsplanungBackend/src/main/asciidoc/howto/config.adoc
@@ -127,7 +127,7 @@ basePath:"https://localhost:8080/spbe/webapi" -== Difine application properties[[ApplicationProperties]] +== Define application properties[[ApplicationProperties]] After deplying the backend war file to the server, you will find the folder *spbe*. If you have to configure for example the auth&auth URL, then see the application.properties under @@ -145,5 +145,36 @@ * SQL-init-scripts * Mail * placeholder user ids - - + +=== Cyclic report generation + +[option="header", cols="1,1"] +|=== +| Key | Description +|report.cyclic.datePattern | yyyyMMdd - +{Date}+ replacement pattern +|report.cyclic.timePattern | HHmm - +{Time}+ replacement pattern +|report.cyclic.weekPattern | ww - +{Week}+ replacement pattern +|report.cyclic.zoneName | Europe/Berlin - time zone +|report.cyclic.locale | de - Locale +|report.cyclic.archiveReport | true - enable/disable archive +|report.cyclic.archivePath | /opt/openkdg/reports - archive folder path +|report.cyclic.sendReportMail | true - enable/disable send mail +|report.mail.propertiesPath | /opt/openkdg/mail-notification.properties - mail config +|report.cyclic.checkCron | 15 0/5 * * * ? - cron schedule for trigger lookups +|report.cyclic.slotDeltaMin | 5 - trigger time slot minutes (should match cron schedule trigger delta) +|=== + +== Cyclic report generation mail properties + +The file referenced by the report.mail.propertiesPath in the application properies should contain a set of mail connection properties. + +* mail.imap.user = username username of the mail account +* mail.imap.password = password password of the mail account +* mail.smtp.host = smtp.host.tld SMTP host address +* mail.smtp.auth = true enable authentication +* mail.smtp.from = standbyplanningreports@company.tld email address of the sender +* mail.smtp.port = 465 port +* mail.smtp.socketFactory.port = 465 +* mail.smtp.socketFactory.class = javax.net.ssl.SSLSocketFactory +* mail.smtp.socketFactory.fallback = false +
diff --git a/oKBereitschaftsplanungBackend/src/main/asciidoc/userdoc/cyclic-reports.adoc b/oKBereitschaftsplanungBackend/src/main/asciidoc/userdoc/cyclic-reports.adoc new file mode 100644 index 0000000..84f7352 --- /dev/null +++ b/oKBereitschaftsplanungBackend/src/main/asciidoc/userdoc/cyclic-reports.adoc
@@ -0,0 +1,141 @@ += Benutzerhandbuch: OpenKONSEQUENZ Modul - Bereitschaftsplanung (Addendum Zyklische Reportgenerierung) +:Author: Tobias Stummer, Dr. Christopher Keim + +:icons: + +:source-highlighter: highlightjs +:highlightjs-theme: solarized_dark + +:lang: de + +:encoding: utf-8 + +:imagesdir: ./images +:iconsdir: ./images/icons + +:toc: preamble +:toc-title: Inhaltsverzeichnis +:chapter-label: Kapitel +:toclevels: 4 +:toc-placement!: +:sectanchors: +:numbered: +:table-caption: Tabelle +:figure-caption: Abbildung + +<<< + + +== Übersicht + +Die Erweiterung _Zyklische Reportgenerierung_ zu dem OpenKONSEQUENZ Modul _Bereitschaftsplanung_ umfasst eine +Automatisierung der bereits im Modul bestehenden Funktionalität zur Reporterzeugung. Im Folgenden wird eine +kurze Übersicht über die Erweiterung gegeben. + + +=== Rollen + +Die Konfiguration der Automatisierung kann nur von Nutzern mit Adminstrator-Rechten durchgeführt werden. +Alle anderen Nutzer ohne die Administrator-Rolle wird dieser Bereich verwährt. + + +=== Automatisierter Prozess + +Die Automatisierung der Reportgenerierung findet auf Grund einer vom Administrator durchgeführten Konfiguration statt. + +Für jeden Eintrag in der Konfigurationstabelle legt der Administrator einen Wochentag sowie eine Uhrzeit fest, an dem +die Erzeugung eines Reports jeweils automatisch gestartet wird. Diese Uhrzeit ist grundsätzlich in dem Modul nur in +jeweils 5-Minuten-Schritten frei wählbar. Weitere Konfigurationsparameter umfassen alle Einstellungsmöglichkeit zur +Erzeugung eines Reports, die auch bereits im Bereich _Abfrage und Reports_ zur Reporterzeugung vorhanden sind, wobei +die Gültigkeit des Reports relativ zum Auslösezeitpunkt angegeben wird. + +Nach der Erzeugung eines Reports wird die erstellte Datei jeweils an eine freikonfigurierbare Empfängerliste via Email +geschickt sowie an einem festen Dateiablageort unter einem der ebenfalls konfigurierbaren Dateinamen abgelegt. + +Grundsätzlich ausgenommen von der zyklischen Reportgenerierung sind persönliche Reports, die eine spezifische +Nutzerkennung erfordern. + +<<< + + +== Nutzeroberfläche + +Die Nutzeroberfläche für die zyklische Reportgenerierung ist zweigeteilt in eine +<<Übersicht der Konfiguration, Übersicht>> und ein <<Konfigurationsformular>> zur Erstellung, Bearbeitung und Löschung +von Konfigurationseinträgen. + +=== Übersicht der Konfiguration + +Die Übersichtsseite der Konfiguration kann durch den Administrator jederzeit über einen Eintrag im Navigationsmenü in +der Kopfleiste der Benutzeroberfläche betreten werden. + +.Übersicht der Konfiguration +image::cyclic-reports/overview.png[] + +Die Nutzeroberfläche zeigt in einer Tabelle alle bestehenden Konfigurationseinträge, die in der Anwendung +hinterlegt sind. Die Tabelle kann wie im restlichen Modul über den Tabellenkopf neu sortiert und gefiltert werden. +Durch Anklicken einer Tabellenzeile können Einzelheiten für den gewählten Konfigurationseintrag über das +<<Konfigurationsformular>> aufgerufen und verändert werden. + +Ein neuer Eintrag kann über die Schaltfläche _Neuer Eintrag_ angelegt werden. Hier öffnet sich ebenfalls das +Konfigurationsformular, wobei die meisten Eingabefelder erst noch befüllt werden müssen. + +.Tabellenaufbau Übersichtsseite +[options="header", cols="1,2"] +|=== +| Bezeichner | Beschreibung +| Name | Benutzerdefinierter Name für den Konfigurationseintrag. +| Planart | Planart der automatisch erzeugten Reports. +| Liste | Liste der automatisch erzeugten Reports. +| Auslösezeitpunkt | Zyklischer Auslösezeitpunkt der automatisch erzeugten Reports. +|=== + + +=== Konfigurationsformular + +Das Konfigurationsformular für einen bestehenden oder einen neuen Eintrag kann vom Administrator über die +<<Übersicht der Konfiguration, Übersicht>> aufgerufen werden. + +.Konfigurationsformular +image::cyclic-reports/form.png[] + +Wie im restlichen Modul kann die Konfiguration über einzelne Kontrollelemente des Formulas wie Textfelder, +Selektionsmenüs und Schaltflächen abgeändert werden. +Nach dem Ausfüllen aller Pflichtfelder kann der Administrator über die Schaltfläche _Speichern_ die neuen Werte +in der Anwendung hinterlegen. Ein bereits bestehender Eintrag kann über die Schaltfläche _Löschen_ auch wieder +gelöscht werden. Die Schaltfläche _Zurück_ führt den Administrator zurück zu der Übersichtsseite. + +Die folgende Tabelle umfasst alle möglichen Eingabefelder des Formulars. + +.Aufbau des Konfigurationsformulars +[options="header", cols="1,2"] +|=== +| Bezeichner | Beschreibung +| Name | Benutzerdefinierter Name für den Konfigurationseintrag. +| Planart | Planart der automatisch erzeugten Reports. +| Liste | Liste der automatisch erzeugten Reports. +| Ebene | Ebene der automatisch erzeugten Reports. +| Format | Dateiformat der automatisch erzeugten Reports. +| Empfänger | Emailempfänger der automatisch erzeugten Emails. +| Betreff | Emailbetreff der automatisch erzeugten Emails. +| Emailtext | Emailtext der automatisch erzeugten Emails. +| Dateiname | Dateiname der automatisch erzeugten Reports. +| Auslösezeitpunkt | Zyklischer Auslösezeitpunkt der automatisch erzeugten Reports. +| Gültigkeit von/bis | Gültigkeit der automatisch erzeugten Reports relativ zum Auslösezeitpunkt. +|=== + +In den Eingabefeldern für den Betreff, den Emailtext und den Dateinamen können Platzhalter gesetzt werden, die +automatisch von der Anwendung zum jeweiligen Auslösezeitpunkt ersetzt werden. +Alle möglichen Platzhalter werden in der folgenden Tabelle aufgelistet. + +.Platzhalter dynamischer Werte +[options="header", cols="1,2,3"] +|=== +| Platzhalter | Beschreibung | Beispiel (Auslösezeitpunkt 24.12.2020, 18:00) +| {Date} | Datum | 20201224 +| {Time} | Uhrzeit | 1800 +| {Week} | Kalenderwoche | 52 +|=== + +Zur Prüfung werden in einer Informationsbox die Platzhalter exemplarisch für den nächsten Auslösezeitpunkt +gemäß den bestehenden Eingaben ersetzt.
diff --git a/oKBereitschaftsplanungBackend/src/main/asciidoc/userdoc/images/cyclic-reports/form.png b/oKBereitschaftsplanungBackend/src/main/asciidoc/userdoc/images/cyclic-reports/form.png new file mode 100644 index 0000000..93671bd --- /dev/null +++ b/oKBereitschaftsplanungBackend/src/main/asciidoc/userdoc/images/cyclic-reports/form.png Binary files differ
diff --git a/oKBereitschaftsplanungBackend/src/main/asciidoc/userdoc/images/cyclic-reports/overview.png b/oKBereitschaftsplanungBackend/src/main/asciidoc/userdoc/images/cyclic-reports/overview.png new file mode 100644 index 0000000..f6e5505 --- /dev/null +++ b/oKBereitschaftsplanungBackend/src/main/asciidoc/userdoc/images/cyclic-reports/overview.png Binary files differ
