Übersicht

Die Anbindung der Service Archivierung an das NSCALE Archiv durch die folgenden Microservices realisiert

• dem archive-writer-nscale (zur Erstellung der NSCALE Archivdateien)
• optional dem nscale-message-zipper (zur Erstellung von ZIP-Files aus den NSCALE Archivdateien, was die Datenübertragung zwischen Servern beschleunigt)
• dem nscale-request-importer (zur Bereitstellung eines REST Endpunkt zum Import der Rückmeldungen aus der NSCALE Archivierung)
• dem archive-searcher-nscale (zur Suche in den NSCALE Archivdateien)

Die Zusammenarbeit der Archivierungs-Services sieht hier dann leicht angepasst wie folgt aus:

Archiv-Writer-Nscale

Der Microservice konsumiert die Nachrichten aus der Persistence Queue und archiviert die Nachrichten und sendet die Nachrichten zum Indizieren in die Index Queue.

Die Konfiguration des Microservices geschieht über die im “docker-compose”-Datei angegebene “application.yml”.

Konfiguration

# Queues for RabbitMQ messaging
consumer-queue: persistence_queue
producer-queue:
  index: index_queue
  error: error_queue

# NSCALE Archive configuration
nscale:
  # The root folder for the archive files (inside the container). The folder should be mounted to the host.
  rootFolderOut: ./data/
  # NSCALE Archive document area (defined in created metadata xml files)
  docArea: B2B
  # Folder Ids (of B2B message year) defined in NSCALE. If not set, the a query implementation is provided.
  folderIds:
    2019: B2B$NOTSET$57023089$1$NOTSET
    2023: B2B$NOTSET$1165554$1$NOTSET
  # If set to true, the service won't fallback to the query implementation and does not process messages of not configured folderId year. Default: false.
  useQueryIfNoConfiguredFolderId: false

# RabbitMQ configuration
spring:
  rabbitmq:
    host: localhost
    port: 5672
    user: guest
    password: guest

Für die Konfiguration der Placeholder siehe Installation.

Reindex-Modus

Der Archive-Writer-Nscale kann neben dem Standard-Archivierungsmodus auch im Reindex-Modus betrieben werden. In diesem Modus werden bereits archivierte Nachrichten gesucht und erneut zur Indexierung in die Index-Queue gesendet.

Service-Modi

Die Anwendung verwendet die Eigenschaft service.mode zur Steuerung des Verhaltens:

• service.mode=archive (Standard): Aktiviert die Verarbeitung der Persistence Queue zur Archivierung eingehender Nachrichten in nscale.
• service.mode=reindex: Deaktiviert die Archivierung, aktiviert aber REST-Endpunkte zur Neuindexierung bereits archivierter Nachrichten.

Funktionsweise

Im Reindex-Modus ist der RabbitMQ-Consumer deaktiviert und REST-Endpunkte werden aktiviert. Dies erfordert:

• Eine Verbindung zur B2B-Datenbank zum Abrufen ausstehender Nachrichten
• Eine Verbindung zum Archive-Index-Searcher-Service zur Suche nach bereits indizierten Nachrichten

Im Dry-Run-Modus (Standard: false) werden die Nachrichten nicht in die Index-Queue gesendet, sondern nur protokolliert.

Vor dem Start des Reindexierungsprozesses wird die Größe der Index-Queue gegen den konfigurierten Grenzwert producer-queue.index-max-size geprüft. Bei Überschreitung wird der Vorgang abgebrochen.

Konfigurationsbeispiel für Reindex-Modus

service:
  mode: reindex 

reindex:
  dry-run: true
  archive-index-base-url: http://localhost:8280

producer-queue:
  index-max-size: 1000

nscale:
  docArea: LIEF_B2B
  user: nli
  password: <password>
  instance: edidokb2b
  host: 10.57.43.198
  port: 9001
  clientAppID: 8664294161252487602

logging:
  level:
    root: INFO

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://pgdb0543p01.postgres.database.azure.com:5432/db_43_b2bp01_b2b?targetServerType=master
    username: tu_u_b2bp01_b2bbp
    password: <password>
  rabbitmq:
    host: localhost
    port: 5672
    user: guest
    password: guest

REST-Endpunkte

Folgende Endpunkte stehen im Reindex-Modus zur Verfügung:

• GET /reindex/archive-messages?day=YYYY-MM-DD - Listet archivierte Nachrichten für einen Tag auf
• GET /reindex/get-difference?day=YYYY-MM-DD - Zeigt Unterschiede zwischen Archiv und Index
• GET /reindex/count-difference?fromDay=YYYY-MM-DD&toDay=YYYY-MM-DD - Zählt Unterschiede über einen Zeitraum (CSV)
• POST /reindex/reindex-day?day=YYYY-MM-DD - Triggert die Neuindexierung für einen Tag und gibt ein JSON-Objekt ReindexResult zurück:
  • day: verarbeiteter Tag
  • totalInIndex: Anzahl eindeutiger Nachrichten-IDs bereits im Index (vor Neuindexierung)
  • totalInArchive: Anzahl eindeutiger Nachrichten-IDs im nscale-Archiv
  • notArchivedInDatabase: Anzahl ausstehender Nachrichten (STATE <> ‘ARC’)
  • reindexedMessages: Anzahl in die Queue eingereihter Nachrichten (bzw. die im Dry-Run-Modus eingereicht worden wären)
  • Gibt HTTP 503 (Service Unavailable) zurück, wenn die aktuelle Index-Queue-Größe den konfigurierten producer-queue.index-max-size überschreitet

Automatisierungsskript

Ein Hilfsskript zur Neuindexierung eines kontinuierlichen Datumsbereichs ist unter scripts/reindex_range.sh verfügbar.

Funktionen:

• Iteriert von START_DATE bis END_DATE (inklusiv) und ruft POST /reindex/reindex-day für jeden Tag auf
• Wiederholungsversuche bei HTTP 503 (Index-Queue voll) mit 60 Sekunden Wartezeit
• Bricht bei anderen HTTP-Fehlern oder JSON-Parse-Fehlern ab
• Schreibt Betriebsprotokolle in reindex_range.log
• Schreibt erfolgreiche Ergebnisse in reindex_results.csv (Tabulator-getrennt)

Konfiguration (am Anfang des Skripts zu editieren):

• START_DATE, END_DATE
• BASE_URL (Standard: http://localhost:8380/reindex/reindex-day)
• Dateinamen: LOG_FILE, CSV_FILE
• RETRY_SLEEP_SECONDS (Wartezeit nach einem 503)

CSV-Spalten: day notArchivedInDatabase totalInIndex totalInArchive reindexedMessages

Verwendung (Linux):

chmod +x reindex_range.sh
./reindex_range.sh

Das Skript erwartet einen laufenden Service im service.mode=reindex.

Releases

Der Service wird in den folgenden Versionen als Docker Container aus dem Repo docker-nob-erp.next-level-apps.com/archive-writer-ncsale bereitgestellt.

2023-03-16

2025-10-31

Nscale-Message-Zipper

Der Microservice kann optional eingesetzt werden, um die NSCALE Archivdateien in ZIP-Files zu packen. Dies beschleunigt eine Datenübertragung zwischen Servern, wenn die B2B Archivierung auf einem anderen Server als das NSCALE Archiv liegt.

Der Zipper wird dabei per Cron-Steuerung gestartet und packt die erstellten NSCALE Archivdateien der archive-writer-nscale Services in ZIP-Files.

Dabei werden in der Service-Ausführung nur Dateien in ZIP-Files gepackt, die älter als “minimal-subfolder-age-in-hours” (Default/Minimum: 1 Stunde) und 5 Minuten (festes Zeitfenster zur Beendigung von Schreibprozessen von archive-writer-nscale Services) sind. Damit wir sichergestellt, dass es zu keinen weiteren Schreibeprozessen in die stündlich angelegten Unterverzeichnisse der archive-writer-nscale Services kommt.

Die ZIP-Files werden anschließend in einen gemountete Ordner vom NSCALE Archiv-Server abgelegt und übertragen.

Konfiguration

Die Konfiguration wird über die application.yml vorgenommen.

# folder configuration for NSCALE files
folder:
  input:
    # folder of the NSCALE archive files (inside the container) to be zipped
    directory: ./archive/tempData
    # minimal age of subfolder in hours (default/minimal for productive systems: 1)
    minimal-subfolder-age-in-hours: 1
  output:
    # folder for the zipped NSCALE archive files (inside the container). The folder should be mounted to the host (of the NSCALE archive).
    zip-file-directory: ./archive/zipNscale

Für die Konfiguration der Placeholder siehe Installation.

Konfiguration der Cron-Steuerung

Zur Cron-Steuerung kann das folgende bereitgestellte .sh-Skript verwendet werden:

#!/usr/bin/env bash
# List (ps) the container id (--quiet) of container that (--filter) have "nscale-message-zipper" in the name
docker start $(docker ps --quiet --all --filter name=nscale-message-zipper)
# 

Dies muss dazu ins $HOME-Verzeichnis des ausführenden Dockernutzers kopiert werden. Hinweis: Diese müssen auch vom Dockernutzer ausführbar gespeichert werden.

Das Skript wird dann über die Cron-Configuration ausgeführt, welche über den Konsolenbefehl crontab -e (ausgeführt mit dem Dockernutzer!) eingestellt werden kann. Hinweis: Mit # kann man Zeilen auskommentieren.

Beispiel: Start einer Cron-Steuerung (über crontab -e):

# cron for controlling nscale-message-zippers
# start at 6 past every hour
6 * * * * $HOME/bin/nscale-message-zipper.sh > $HOME/nscale-message-zipper.log 2>&1

Releases

Der Service wird in den folgenden Versionen als Docker Container aus dem Repo docker-nob-erp.next-level-apps.com/nscale-message-zipper bereitgestellt.

2023-02-24-02

Nscale-Request-Importer

Der Microservice stellt (OAuth2 abgesichert über den Keycloak) eine Schnittstelle zur Verfügung, um die Rückmeldung der NSCALE Archivierung der Dateien je Nachricht entgegenzunehmen und zu verarbeiten.

REST Schnittstelle

Der Service bringt den POST-Endpunkt /nscale-message-importer/status-receive mit, bei dem im Request-Body eine Liste an B2B Nachrichten-Ids und deren Archivierung-Status entgegengenommen werden kann. Im Fehlerfall kann auch ein Fehler-Code und eine Fehler-Beschreibung mitgeliefert werden, die dann an die B2B Nachricht (in den technischen Details) übermittelt werden.

Der Endpunkt ist zudem über eine eigene Keycloak Rolle B2B-Archiving-NSCALE abgesichert, welche einem (technischer) Nutzer der Schnittstelle (im Keycloak) zugewiesen werden muss.

Die volle OpenAPI Dokumentation lautet wie folgt (ist auch unter /v3/api-docs verfügbar):

{
    "openapi": "3.0.1",
    "info": {
        "title": "Endpoints to receive message states from NSCALE archiving."
    },
    "servers": [{
            "url": "https://b2b-mainova-netz.level-365.com/nscale-request-importer",
            "description": "Generated server url"
        }
    ],
    "paths": {
        "/nscale-request/status-receive": {
            "post": {
                "tags": ["archive-request-controller"],
                "summary": "Receives message status of NSCALE archiving.",
                "operationId": "receive",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/ArchiveMessageRequest"
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "*/*": {
                                "schema": {
                                    "type": "boolean"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "ArchiveMessageRequest": {
                "type": "object",
                "properties": {
                    "messageId": {
                        "type": "string"
                    },
                    "archivingState": {
                        "type": "string",
                        "enum": ["SUCCESSFUL", "ERROR"]
                    },
                    "nscaleError": {
                        "$ref": "#/components/schemas/NscaleError"
                    }
                }
            },
            "NscaleError": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string"
                    },
                    "stacktrace": {
                        "type": "string"
                    }
                }
            }
        }
    }
}

Konfiguration

Die Konfiguration des Microservices geschieht über die im “docker-compose”-Datei angegebene “application.yml”.

# Swagger-UI configuration
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
server:
  # only needed if swagger-ui should be used from https url
  #forward-headers-strategy: framework
  # configurabel context path for the endpoint/Swagger-UI
  servlet:
    context-path: /nscale-request-importer

# Messaging configuration
production-queue:
  success: success_queue
  error: error_queue
  
# RabbitMQ configuration
spring:
  rabbitmq:
    host: localhost
    port: 5672
    user: guest
    password: guest

Weiter muss zur Absicherung des Services über den Keycloak ein Client zu dem Service in der Keycloak Administration angelegt werden:

Die keycloak.json des so erstellten Clients muss dann in den Docker-Container (unter /app/lib/keycloak.json bzw. dem gemounteten Pfad config/nscale-request-importer/keycloak.json) abgelegt werden.

Damit ein Benutzer auch berechtigt ist den Endpunkt zu nutzen, muss die Rolle B2B-Archiving-NSCALE des Services im Keycloak angelegt und dem Benutzer zugewiesen werden.

Releases

Der Service wird in den folgenden Versionen als Docker Container aus dem Repo docker-nob-erp.next-level-apps.com/nscale-request-importer bereitgestellt.

2023-03-01-02

Archiv-Searcher-Nscale

Der Microservice nimmt Anfragen von der B2B zum Suchen der Nachrichten-Details/Dateien aus dem Archiv entgegen und lädt diese aus dem Archiv.

Dazu werden aus dem NSCALE über Archiv-Ids konkrete Dateien angefragt.

Konfiguration

Die Konfiguration des Microservices geschieht über die im “docker-compose”-Datei angegebene “application.yml”.

# NSCALE configuration
nscale:
  user: username
  password: password
  docArea: B2B
  instance: edidokb2b
  host: 11.11.11.11
  port: 9000
  # Client App ID for the NSCALE Request API
  clientAppID: 2323232323232323

Releases

Der Service wird in den folgenden Versionen als Docker Container aus dem Repo docker-nob-erp.next-level-apps.com/archive-searcher-nscale bereitgestellt.

2023-03-01-02