Ü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”.

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

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.

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.

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

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

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"
                    }
                }
            }
        }
    }
}

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

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.

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.

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

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