Die UserMessages werden auch SystemMessages genannt.

Funktionalität

Mit den UserMessages kann ein Admin Nachrichten an UI-User schicken.

Architektur

Das Feature wurde entkoppelt und benötigt nun keinen Tomcat mehr. Stattdessen gliedert es sich in eine B2B-UserMessages-UI & einen B2B-UserMessages-Service. Die UI greift auf den Service zu. Der Service greift auf die bestehende Datenbank zu. (Alternativ kann auch eine eigene Datenbank genutzt werden.)

Alle beteiligten Komponenten sind über Keycloak abgesichert.

Alle andern UIs greifen auf den B2B-UserMessages-Service zu.

Voraussetzungen

• Docker einsatzbereit
• Keycloak installiert

Installation

Das Setup der hier beschriebenen Umgebung basiert auf einem docker-compose file. Diese Konfiguration definiert einen Container.

Die docker-compose Umgebung besteht letztlich aus einer Verzeichnisstruktur, die die einzelnen im Folgenden beschriebenen Dateien enthält. Die Verzeichnisstruktur stellt sich wie folgt dar:

| base/
  |- usermessages-service/
  |  |- application.yml
  |- b2b-usermessages-ui/
  |  |- keycloak.json
  |- docker-compose.yml
  |- .env
  |- system.json

Diese Dokumentation basiert auf der folgenden docker-compose.yml:

version: '3.7'
services:
  notification:
    image: ${NEXUS}/notification-service:2021-02-22
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      - ./usermessages-service/application.yml:/lib/application.yml
  notification-ui:
    image: ${NEXUS}/notification-ui:2021-02-22
    restart: always
    ports:
      - 1190:8080
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      - ./b2b-usermessages-ui/keycloak.json:/usr/share/nginx/html/User-Messages-UI/assets/config/keycloak.json
      - ./b2b-usermessages-ui/system.json:/usr/share/nginx/html/User-Messages-UI/assets/config/system.json
      - ./b2b-usermessages-ui/logs/host.access.log:/var/log/nginx/host.access.log
      - ./b2b-usermessages-ui/logs/host.error.log:/var/log/nginx/host.error.log
    depends_on:
      - notification

Bitte folgen Sie unseren Konventionen für Servicenamen (aus denen sich dann die Hostnamen ergeben).

Achten Sie beim image darauf, eine aktuelle Version gemäß unserer Kompatibilitätsübersicht anzugeben.

Die oben aufgeführte docker-compose.yml beinhaltet verschiedene Variablen “${Variable}”. Diese Variablen sind in der Datei .env enthalten.

NEXUS=docker-nob-erf.next-level-apps.com
TIME_ZONE=Europe/Berlin

Notification (B2B-Messages-Service)

./usermessages-service/application.yml

Mit dieser Konfigurationsdatei werden die Einstellungen für den Backend-Service der B2B-UserMessages festgelegt:

server:
  port: 8080
spring:
  main:
    allow-bean-definition-overriding: true
  datasource:
    driverClassName: org.postgresql.Driver
    url: [JDBC-URL]
    username: [DB-User]
    password: [DB-Passwort]
    hikari:
      maximumPoolSize: 2
keycloak:
  enabled: true
  auth-server-url: http://[dockerhost]:8080/auth
  realm: [realm]
  resource: b2b-usermessages
  bearer-only: true
  public-client: false
  cors: true

Eine Oracle Datenbank kann wie folgt konfiguriert werden:

spring:
  jpa:
    hibernate:
      ddl-auto: none
      naming:
        physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
    database-platform: org.hibernate.dialect.OracleDialect
  datasource:
    driver-class-name: oracle.jdbc.OracleDriver
    url: jdbc:oracle:thin:@[server]:[port]:[schema]
    username: admin
    password: password
    hikari:
      maximumPoolSize: 2

DNS

Falls die DNS Namen nicht aufgelöst werden können, hilft es, folgende Datei in den Container zu mounten:

    volumes:
      - /etc/resolv.conf:/etc/resolv.conf

Konfiguration der maximal genutzen Datenbankverbindungen

Um die maximal genutzen Datenbankverbindungen festzulegen, aktualisieren Sie die maximumPoolSize unter dem Abschnitt application.yml> datasource. Wir empfehlen eine maximumPoolSize von 2.

  datasource:
    url: {url}
    username: {username}
    password: {password}
    hikari:
      maximumPoolSize: {maximumPoolSize}

optionale Docker-Compose Konfiguration

Wenn Sie einen vom Standard abweichenden Service in Ihrer Reverse-Proxy-Konfiguration konfigurieren möchten, folgen Sie bitten den Hinweisen in der Docker-Compose-Dokumentation

Verwendung von Umgebungsvariablen

Die Konfiguration der Datenbank sowie des Keycloak ist ebenfalls über Umgebungsvariablen möglich. Ein Mounten der application.yml und/oder keycloak.json ist in diesem Fall nicht notwendig.

B2B-UserMessages-UI

./b2b-usermessages-ui/keycloak.json

Verwendung von Umgebungsvariablen (ab August 2023)

Wir empfehlen die Verwendung von Umgebungsvariablen in der keycloak.json, sofern keine zusätzlichen Eigenschaften konfiguriert werden sollen.

Die Standard keycloak.json für die B2B-UserMessages-UI sieht aktuell wie folgt aus:

{
  "realm": "${KC_REALM}",
  "auth-server-url": "${KC_URL}",
  "ssl-required": "${KC_SSL_REQUIRED}",
  "resource": "${KC_CLIENT}",
  "public-client": true,
  "confidential-port": 0
}

Die definierten Umgebungsvariablen werden beim Erzeugen des Docker-Containers gesetzt und verwendet, sofern keine keycloak.json-Datei in den Container gemountet wurde.

Bei allen Keycloak-Parametern müssen json-Sonderzeichen escaped werden, da sonst keine valide keycloak.json erzeugt wird.

Als gesamte Datei

Diese Datei konfiguriert die Anbindung der B2B-UserMessages-UI-Instanz an den keycloak. Folgende Konfiguration wurde für diese Dokumentation verwendet:

{
  "realm": "B2B",
  "auth-server-url": "http://keycloak:8080/auth/",
  "ssl-required": "none",
  "resource": "notification-ui",
  "public-client": true,
  "confidential-port": 0
}

Die Datei wird am besten direkt aus der Keycloak Admin-UI exportiert. In Keycloak muss dafür ein passender Client angelegt werden. Dies wird im Keycloak Abschnitt später genauer beschrieben.

./b2b-usermessages-ui/nginx.conf

Das Image bringt bereits eine Default nginx.conf mit. Es ist nicht nötig, diese zu überschreiben.

Sie kann aber über die folgenden Umgebungsvariablen individuell angepasst werden:

ENV PORTAL_UI_URL="http://portal-ui:8080"  # URL mit der die UserMessages-UI auf die B2B-Portal-UI zugreifen kann.
ENV B2B_URL="http://b2b:8080"  # URL mit der die UserMessages-UI auf das B2B Backend zugreifen kann.
ENV NOTIFICATION_URL="http://notification:8080"  # URL mit der die UserMessages-UI auf das Revision Backend zugreifen kann.
ENV SERVICE_PATH=/User-Messages-UI  # URL Pfad der UI. Achtung: Eine Änderung des Defaults muss in allen Konfigurationen der UI berücksichtigt werden (z.B. Keycloak Client und portal-config.json).

./system.json

Verwendung von Umgenungsvariablen

Wir empfehlen die Verwendung von Umgebungsvariablen in der system.json, sofern keine zusätzlichen Eigenschaften konfiguriert werden sollen.

Die Standard system.json für die B2B-UserMessages-UI sieht aktuell wir folgt aus:

{
  "systemName": "${SYSTEM_NAME}",  # Angezeigter Name in der UI. Default: B2B
  "backgroundColor": "${BACKGROUND_COLOR}",  # Farbe der UI in hex color code. Default: #008ECC (blau)
  "activateUserMessages": "${ACTIVATE_USER_MESSAGES}", # Wird das Feature für Benutzerbenachrichtigungen verwendent. Default: true
}

Die definierten Umgebungsvariablen werden beim Start des Containers gesetzt und verwendet, sofern eine eigene system.json nicht bereits keine Datei in den Container gemountet wurde.

Als gesamte Datei

Die Datei system.json kann als globale Konfiguration genutzt werden. Nach Möglichkeit sollte die gleiche Datei für alle Frontends verwendet werden.

In ihr können der angezeigte Systemname sowie die angezeigte Hintergrundfarbe festgelegt werden.

Ferner kann durch sie das Feature UserMessages aktiviert werden.

{
  "systemName": "B2B Dokusystem",
  "backgroundColor": "#008ECC",
  "activateUserMessages": true
}

Zugang seitens der anderen UIs

Die folgende Konfiguration für die nginx.conf ist bereits in den Images enthalten. Nutzen Sie unsere Images & folgen Sie unseren Servicenamenkonventionen, ist nichts zu tun.

Damit die anderen UIs (B2B-UI, B2B-Admin-UI, …) auf den Revision-Service zugreifen können, muss jeweils ein Eintrag in der nginx.conf ergänzt werden. Hier exemplarisch für die B2B-UI:

        location /B2B-UI/api/b2b-user-messages/system-messages {
              proxy_pass   http://notification:8080/system-messages;
              proxy_http_version 1.1;
              proxy_set_header Upgrade $http_upgrade;
              proxy_set_header Connection "upgrade";
              proxy_set_header Host $host;
              proxy_set_header        X-Real-IP $remote_addr;
              proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_set_header        X-Forwarded-Proto $scheme;
              proxy_cache_bypass $http_upgrade;
        }

Logging

Das access_log und das error_log werden in der nginx.conf definiert.

Damit das Log nicht mit einem weggeworfenen Container verloren geht, kann man das Log auch von außen in den Container mounten. Hierfür sind die Log-Files in den docker-compose/volumes mit anzugeben. Für diese Lösung müssen die Dateien vorher bereits auf dem Docker-Host angelegt und mit geeigneten Berechtigungen versehen sein.

Start docker container (UI & Service)

Mit dem folgenden Kommando können die Container im Docker gestartet werden:

:opt/docker/b2b/> docker-compose up -d

Mit folgendem Kommando können die Container im Docker gestoppt werden:

:opt/docker/b2b/> docker-compose stop

Keycloak Konfiguration

Keycloak Client Konfiguration

Notifcation (UserMessages Service)

Für den UserMessages-Service muss ein Keycloak Client angelegt werden.

Die ClientId kann von Ihnen selbst gewählt werden, z.B. usermessages-service.

Die RootURL ist die interne Docker Adresse: http://notification:8080.

Das Client Protocol bleibt auf openid-connect gestellt.

Es ist der Standardflow zu nutzen (standardmäßig aktiv).

Der Access Type ist auf bearer-only zu stellen.

Als Login-Theme kann das nli Thema gewählt werden.

Notification-UI (UserMessages-UI)

Für die UserMessages-UI muss ein Keycloak Client angelegt werden.

Die ClientId kann von Ihnen selbst gewählt werden, z.B. usermessages-ui.

Die RootURL entspricht der externen Adresse des Frontends.

Das Client Protocol bleibt auf openid-connect gestellt.

Es ist der Standardflow zu nutzen (standardmäßig aktiv).

Der Access Type ist public.

Als Login-Theme kann das nli Thema gewählt werden.

Keycloak Rollen & Attribute

Die Konfiguration der benötigten Rollen und Attribute wird hier beschrieben.

Anbindung der Umsysteme

Die folgende Konfiguration für die nginx.conf ist bereits in den Images enthalten. Nutzen Sie unsere Images & folgen Sie unseren Servicenamenkonventionen, ist nichts zu tun.

Alle anderen UIs müssen auf die UserMessages zugreifen können. Entsprechend muss bei allen anderen UIs in ihrer nginx.conf jeweils ein Eintrag ergänzt werden. Es folgt eine Beispielkonfiguration für die B2B-UI:

        location /B2B-UI/api/b2b-user-messages/system-messages {
            proxy_pass   http://b2b-messages-service:8080/system-messages;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header        X-Real-IP $remote_addr;
            proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header        X-Forwarded-Proto $scheme;
            proxy_cache_bypass $http_upgrade;
        }

Dies gilt auch für die Portal-UI, welche erst auf der nächsten Seite beschrieben wird.

Anhang

SQL Scripte

Falls die die benötigten Tabellen manuell anlegen möchten, finden Sie hier die Scripte:

Postgres

alter table b3p_adm_systemmessages add column messagesubject varchar(255);

alter table b3p_adm_systemmessages add column status varchar(50) default ‘ACTIVE’;

MSSQL

alter table B3P_ADM_SYSTEMMESSAGES add MESSAGESUBJECT varchar(255);

alter table B3P_ADM_SYSTEMMESSAGES add STATUS varchar(50) DEFAULT ‘ACTIVE’;

ORACLE

alter table B3P_ADM_SYSTEMMESSAGES add MESSAGESUBJECT varchar(255);

alter table B3P_ADM_SYSTEMMESSAGES add STATUS varchar(50) DEFAULT ‘ACTIVE’;