1) Server Ressourcen Information (Discovery)

Zugang über Webseite

Um eine Übersicht über die auf einem JAXForms Server vorhandenen Mandanten und deren Formulare, Datapools, Codelisten sowie globalen Komponenten zu erhalten. Bietet JAXForms eine integrierte Informationsseite an, welche auf jedem JAXForms Server (ab der Version 9.0.8) aufgerufen werden kann. Der Zugang erfolgt über Oauth2 Credentials: https://xyz.jaxforms.com/formservice/serverInfo/

Zweck

Diese Schnittstelle, welche mit der Version 9.0.8 eingeführt wurde, liefert eine zentrale Übersicht über die auf dem Server verfügbaren Ressourcen je Mandant. Neben allgemeinen Serverinformationen (Name, Version, Stage) enthält die Antwort strukturierte Listen zu Formularen, Global Components, Datapools und Code-Listen inklusive Links und CRC32-Hashes zur schnellen Änderungs- und Integritätsprüfung. 

HTTP Request

GET /server/info/ressource

Liefert Server-Infos sowie eine Übersicht der Ressourcen pro Mandant (Formulare, Global Components, Datapools, Code-Listen) inklusive Hashes (CRC32) zur Change Detection / Cache-Invalidierung.

Berechtigungslogik (wichtig)

• Normaler Mandant-User: bekommt nur Informationen zu seinem eigenen Mandanten (auch wenn mandant-ids gesetzt ist).

• System-Mandant-User: kann mehrere Mandanten abfragen und bekommt dann die jeweiligen Informationen zurück.

Query Parameter

mandant-ids (optional)

Typ: string (Comma-separated list)
Beispiel: SHOWCASE,MY-MANDANT

Verhalten:

• Wenn nicht gesetzt:

  • Normaler User → nur eigener Mandant

  • System-Mandant-User → alle Mandanten

• Wenn gesetzt:

  • System-Mandant-User → genau diese Mandanten (sofern existent)

  • Normaler User → trotzdem nur eigener Mandant (Parameter wird ignoriert)

Response

200 application/json

Die Response besteht aus zwei Hauptbereichen:

• serverInformation: Metadaten zur Instanz (Name, Link, Version, Stage) sowie ein serverCrc32Hash zur schnellen Erkennung, ob sich serverrelevante Informationen geändert haben (z.B. neues Deployment).

• mandantResources[]: Liste der Ressourcen pro Mandant. Abhaengig von Berechtigung und Query-Parameter (mandant-ids) enthaelt diese Liste entweder nur den eigenen Mandanten oder mehrere/alle Mandanten.

Innerhalb eines Mandanten (mandantResources[i]) sind die Ressourcen in vier Kategorien gruppiert:

1. formResources[]
   Enthält Formulare inklusive Status (active), Zeitstempel (lastUpdate), Gruppierung (group), Links zur aktiven Ressource (activeResourceLink, baseResourceLink) sowie Versionshistorie (formVersions[]).
   Pro Formular steht zusätzlich ein crc32Hash zur Verifikation/Cache-Invalidierung auf Formularebene zur Verfügung.

2. globalComponents[]
   Wiederverwendbare Komponenten (z.B. globale Bausteine). Der Block reference zeigt, wo die Komponente verwendet wird (Form- und Component-Referenzen). Auch hier gibt es einen crc32Hash pro Komponente.

3. datapoolResources[]
   Datapools inkl. Aktiv-Flag und Gruppierung. previewLink ist ein Key/Value-Objekt (flexibel erweiterbar), das z.B. mandant- oder systemabhängige Preview-URLs enthalten kann.

4. codeListResources[]
   Code-Listen mit key, resourceLink, lastUpdate und crc32Hash.

Zusätzlich enthält der Mandant-Block aggregierte CRC32-Hashes:

• mandantCrc32Hash: Hash über den gesamten Mandant-Block

• formsCrc32Hash, globalsCrc32Hash, codesCrc32Hash: Hashes je Ressourcentyp

JSON-SCHEMA 

{
  "serverInformation": {
    "serverName": "string",
    "serverLink": "string",
    "version": "string",
    "stage": "string",
    "serverCrc32Hash": "string"
  },
  "mandantResources": [
    {
      "mandantId": "string",
      "formResources": [
        {
          "id": "string",
          "name": "string",
          "lastUpdate": "string",
          "active": true,
          "group": "string",
          "activeVersion": "string",
          "activeResourceLink": "string",
          "baseResourceLink": "string",
          "formVersions": [
            {
              "version": "string",
              "uuid": "string"
            }
          ],
          "formLink": "string",
          "expirationDate": "string",
          "crc32Hash": "string"
        }
      ],
      "globalComponents": [
        {
          "id": "string",
          "category": "string",
          "refId": "string",
          "componentType": "string",
          "lastUpdate": "string",
          "resourceLink": "string",
          "reference": {
            "formReferences": [
              "string"
            ],
            "componentReferences": [
              "string"
            ]
          },
          "crc32Hash": "string"
        }
      ],
      "datapoolResources": [
        {
          "name": "string",
          "lastUpdate": "string",
          "active": true,
          "guid": "string",
          "group": "string",
          "previewLink": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          }
        }
      ],
      "codeListResources": [
        {
          "name": "string",
          "key": "string",
          "lastUpdate": "string",
          "resourceLink": "string",
          "crc32Hash": "string"
        }
      ],
      "mandantCrc32Hash": "string",
      "formsCrc32Hash": "string",
      "globalsCrc32Hash": "string",
      "codesCrc32Hash": "string"
    }
  ]
}

2) Ressource herunterladen (Binary Download)

Zweck

Dieser Endpoint liefert den eigentlichen Datei-/Ressourceninhalt zu einer Ressource aus der Übersicht.
In der Praxis wird er nicht “frei” verwendet, sondern über die in /server/info/ressource gelieferten resourceLink-Felder (z.B. bei globalComponents[] und codeListResources[]).

Pfadparameter

• mandantId (string)
  Mandant, z.B. MY-MANDANT,SHOWCASE,SYSTEM

• type (string)
  Ressourcentyp (z.B. jfd für Global Components oder Formular-Definitionen, codes für Code-Listen)

• uuid (string)
  ID der konkreten Ressource innerhalb des Typs

Authentifizierung & Autorisierung

• Bearer Auth erforderlich (bearerAuth)

• Endpoint ist mit @RolesAllowed("Credential") abgesichert

• Zusaetzliche serverseitige Pruefung:

  • Wenn kein User im Security Context: 401 Unauthorized

  • Danach wird eine Admin-Autorisierung erzwungen (intern wird gegen ROLE_ADMIN geprüft)

Praktische Konsequenz: Download ist nur mit gültigem Token und ausreichenden Rechten möglich.

Response

• 200 OK
  Liefert den Ressourcenkontent als Stream.

  • Content-Type: application/octet-stream

  • Content-Disposition: attachment; filename="<dateiname>"

  • Der filename wird serverseitig aus der internen resourceId abgeleitet (alles nach dem letzten /).

• 404 Not Found
  Ressource existiert nicht (Kombination aus mandantId/type/uuid nicht gefunden).

• 401 Unauthorized
  Kein/ungültiger User (z.B. fehlender Token).

Resource Link zusammenbauen

resourceLink (bzw. activeResourceLink bei Formulardefinitionen) ist die vollständige Download-URL zu einer Ressource. Sie folgt immer dem gleichen Muster und wird aus festen und variablen Bestandteilen zusammengesetzt.

URL-Schema

{baseUrl}/formservice/services/rest/resource/{mandantId}/{type}/{uuid}

Bestandteile

Versionen-Link 

Bei FormResources gibt es zusätzlich zu activeResourceLink auch baseResourceLink ist die Basis-URL, um den Download-Link für eine beliebige konkrete Formular-Version zusammenzubauen.

Die uuid für die verschiedenen Versionen sind unter formVersions[i].uuid und können wie folgt zusammengebaut werden:

{baseResourceLink}/{uuid}