From 5295f270561ddda420e590538e8dcc3db1bab695 Mon Sep 17 00:00:00 2001 From: Maksim Sandybekov Date: Fri, 2 Jun 2023 14:52:24 +0200 Subject: [PATCH 1/3] add tables, index and links no-ticket --- plugin.md | 225 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 144 insertions(+), 81 deletions(-) diff --git a/plugin.md b/plugin.md index e3ece17..8540679 100644 --- a/plugin.md +++ b/plugin.md @@ -1,3 +1,39 @@ +# Index + +1. [Ziele des Gradle-Plugins zur Prozessmodellierung](#ziele-des-gradle-plugins-zur-prozessmodellierung) +2. [System-Anforderungen](#system-anforderungen) +3. [Zugang](#zugang) +4. [Grundidee](#grundidee) +5. [Aktueller Funktionsumfang](#aktueller-funktionsumfang) +6. [Konfiguration und Projektstruktur](#konfiguration-und-projektstruktur) + 1. [Ordnerstruktur](#ordnerstruktur) + 1. [/config](#ordner-config) + 2. [/scripts](#ordner-scripts) + 3. [/commons](#ordner-commons) + 4. [/models](#ordner-models) + 5. [/forms](#ordner-forms) + 6. [/parameterdefinitions](#ordner-parameterdefinitions) + 2. [Ermittlung von Konfigurationswerten](#ermittlung-von-konfigurationswerten) + 1. [Umgebung](#umgebung) + 2. [Mandant](#mandant) + 3. [Name und Version des Prozessmodells](#name-und-version-des-prozessmodells) + 4. [Stufe der Prozessmodell-Version](#stufe-der-prozessmodell-version) + 5. [Prozess-Engine für Deployment](#prozess-engine-für-deployment) + 3. [Unterstützung von Gradle Multi-Project Builds](#unterstützung-von-gradle-multi-project-builds) +12. [Tasks](#tasks) + 1. [_mergeScripts_](#task-mergescripts) + 2. [_buildModel_](#task-buildmodel) + 3. [_uploadProcessModelFiles_](#task-uploadprocessmodelfiles) + 4. [_uploadParameterDefinition_](#task-uploadparameterdefinition) + 5. [_getActiveProcessEngines_](#task-getactiveprocessengines) + 6. [_deployProcessModelVersion_](#task-deployprocessmodelversion) + 7. [_uploadFormularFiles_](#task-uploadformularfiles) + 8. [_uploadAndDeployFormularFiles_](#task-uploadanddeployformularfiles) + 9. [_getAuthorizationToken_](#task-getauthorizationtoken) + 10. [_startLocalHttpServer_](#task-startlocalhttpserver) + 11. [_stopLocalHttpServer_](#task-stoplocalhttpserver) +3. [Breaking Changes/Migration Guide](#breaking-changesmigration-guide) + # Ziele des Gradle-Plugins zur Prozessmodellierung Dieses Gradle-Plugin schafft die Möglichkeit, einzelne Prozess-Teile @@ -50,23 +86,21 @@ Deployen übernehmen. # Aktueller Funktionsumfang -In diesem Release enthalten sind die Tasks - -* `mergeScripts` Fügt die einzelnen Bestandteile der Skripte zu kompilierbaren Groovy-Skripten - zusammen -* `buildModel` Fügt die Skripte in das Prozessmodell ein -* `uploadProcessModelFiles` Lädt Prozessmodell-Dateien in das Admincenter hoch -* `uploadProcessDefinitions` Lädt Prozessparameterdefinitionen in das Admincenter hoch -* `getActiveProcessEngines` Gibt die Liste der zur Verfügung stehenden Prozess-Engines aus -* `deployProcessModelVersion` Deployt eine (zuvor hochgeladene) Prozessversion -* `uploadFormularFiles` Lädt Formulardateien in das Admincenter hoch -* `uploadAndDeployFormularFiles` Lädt Formulardateien in das Admincenter hoch und deployt sie -* `getAuthorizationToken` Erstellt ein Token zum Authentifizieren. - Ein solches Token wird zum Hochladen und Deployen von Prozessen, - Prozessparameterdefinitionen und Formularen benötigt. -* `startLocalHttpServer` Startet einen lokalen Server, um lokale Formulardateien mit dem - Formulardesigner auf einer definierten Umgebung zu bearbeiten -* `stopLocalHttpServer` Stoppt den lokalen Server zum Bearbeiten von lokalen Dateien. +In diesem Release enthalten sind die Tasks: + +| Task | Beschreibung | +|---------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`mergeScripts`](#mergescripts) | Fügt die einzelnen Bestandteile der Skripte zu kompilierbaren Groovy-Skripten zusammen | +| [`buildModel`](#buildmodel) | Fügt die Skripte in das Prozessmodell ein | +| [`uploadProcessModelFiles`](#uploadprocessmodelfiles) | Lädt Prozessmodell-Dateien in das Admincenter hoch | +| [`uploadProcessDefinitions`](#uploadprocessdefinitions) | Lädt Prozessparameterdefinitionen in das Admincenter hoch | +| [`getActiveProcessEngines`](#getactiveprocessengines) | Gibt die Liste der zur Verfügung stehenden Prozess-Engines aus | +| [`deployProcessModelVersion`](#deployprocessmodelversion) | Deployt eine (zuvor hochgeladene) Prozessversion | +| [`uploadFormularFiles`](#uploadformularfiles) | Lädt Formulardateien in das Admincenter hoch | +| [`uploadAndDeployFormulariles`](#uploadanddeployformulariles) | Lädt Formulardateien in das Admincenter hoch und deployt sie | +| [`getAuthorizationToken`](#getauthorizationtoken) | Erstellt ein Token zum Authentifizieren. Ein solches Token wird zum Hochladen und Deployen von Prozessen, Prozessparameterdefinitionen und Formularen benötigt. | +| [`startLocalHttpServer`](#startlocalhttpserver) | Startet einen lokalen Server, um lokale Formulardateien mit dem Formulardesigner auf einer definierten Umgebung zu bearbeiten | +| [`stopLocalHttpServer`](#stoplocalhttpserver) | Stoppt den lokalen Server zum Bearbeiten von lokalen Dateien. | # Konfiguration und Projektstruktur @@ -118,14 +152,18 @@ Die Ordnerstruktur wird vom Gradle-Plugin wie folgt erwartet: Enthält die Konfigurationsdateien für das Gradle-Plugin. Die enthaltenen Dateien beeinflussen nur das Verhalten des Gradle-Plugins. -#### Ordner config - Datei project.json +
+ +#### **Datei project.json** Die Datei project.json enthält Informationen darüber, an welcher Stelle der Prozess im Admincenter abgelegt wird. Enthalten sind folgende Informationen: -* **projectName**: Der Name des Prozessmodells im Admincenter. -* **projectVersion**: Die Version des Prozessmodells, an der gerade gearbeitet wird. -* **mandant**: Die Id des Mandanten, unter dem das Prozessmodell und die Formulare - im Admincenter abgelegt werden. + +| Attribut | Beschreibung | +|-----------------|------------------------------------------------------------------------------------------------------| +| projectName | Der Name des Prozessmodells im Admincenter. | +| projectVersion | Die Version des Prozessmodells, an der gerade gearbeitet wird. | +| mandant | Die Id des Mandanten, unter dem das Prozessmodell und die Formulare im Admincenter abgelegt werden. | Beispielsweise könnte die Datei project.json so aussehen: ```json @@ -135,8 +173,9 @@ Beispielsweise könnte die Datei project.json so aussehen: "mandant": "1" } ``` +
-#### Ordner config - Datei auth.json +#### **Datei auth.json** Die Informationen in dieser Datei authentifizieren den Benutzer gegen die entsprechende Umgebung. Die Authentifizierungsinformationen sind sensitive persönliche Informationen @@ -181,8 +220,10 @@ die Prozesse zu deployen. Diese Beschränkungen werden über den Betrieb in Absprache mit dem IM/SK für jede Umgebung festgelegt. + +
-#### Ordner config - Datei default.json und andere Umgebungsdefinitionen +#### **Datei default.json und andere Umgebungsdefinitionen** Die Umgebungsdefinitionen dienen dazu, die Informationen für unterschiedliche Umgebungen abzulegen. Wird beim Aufruf der Tasks keine Umgebung angegeben, so wird die Umgebung "default" gewählt. @@ -190,24 +231,21 @@ Der Name der Umgebung ist in dem Dateinamen kodiert. So wird z.B. für die Umgeb die Umgebungsdefinitionsdatei prozesstest.json angezogen. Die Dateien enthalten folgende Informationen: -* **url**: Die URL des Servicegateways der Zielumgebung -* **projectStage**: Die Stufe, in die das Prozessmodell und die Formulare - auf der entsprechenden Umgebung abgelegt werden sollen. Gültige Werte sind prinzipiell - FUNCTIONAL_ANALYSIS, TECHNICAL_IMPLEMENTATION, QUALITY_ASSURANCE, CERTIFIED, es kann jedoch sein, - dass manche Werte auf manchen Umgebungen nicht zur Verfügung stehen. -* **mandant**: Die Id des Mandanten für diese Umgebung. - Wenn gesetzt, wird der Mandant aus der Datei project.json überschrieben. -* **processModelNameExtension**: Ein optionales Suffix, der beim Bauen der Prozessmodelle - an den Prozessnamen, der in der bpmn-Datei definiert ist, angehängt wird - (getrennt durch ein Leerzeichen). -* **processEngine:**: Die ID der Prozess-Engine, auf welche die Prozessmodell-Version deployt werden - soll. Ist der Parameter nicht gesetzt, wird die Standard-Prozess-Engine verwendet. + +| Attribut | Beschreibung | +|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| url | Die URL des Servicegateways der Zielumgebung | +| status | Der Status in der das Prozessmodell und die Formulare auf der entsprechenden Umgebung abgelegt werden sollen. Gültige Werte sind: Es kann jedoch sein, dass manche Werte auf manchen Umgebungen nicht zur Verfügung stehen. | +| mandant | Die Id des Mandanten für diese Umgebung. Wenn gesetzt, wird der Mandant aus der Datei project.json überschrieben. | +| processModelNameExtension | Ein optionales Suffix, der beim Bauen der Prozessmodelle an den Prozessnamen, der in der bpmn-Datei definiert ist, angehängt wird (getrennt durch ein Leerzeichen). | +| rocessEngine | Die ID der Prozess-Engine, auf welche die Prozessmodell-Version deployt werden soll. Ist der Parameter nicht gesetzt, wird die Standard-Prozess-Engine verwendet. | + Beispiel: ``` { "url": "https://sgwtest.service-bw.de", - "projectStage": "TECHNICAL_IMPLEMENTATION", + "stufe": "EDIT", "mandant": "42", "processModelNameExtension": "DEV", "processEngine": "secondEngine" @@ -271,24 +309,15 @@ automatisch statt default.json angezogen werden. die auch im Admincenter als Prozessparameterdefinitionen verwendet werden.** In einer Parameterdefinition werden die folgenden Informationen gespeichert -* **name**: Der programmatische Name des Prozessparameters, muss unique für ein Prozessmodell sein -* **description**: Die Beschreibung des Parameters für die Prozessverwalter, die den Parameter - setzen wollen. -* **type**: Der Typ des Prozessparameters. Erlaubt sind folgende Werte: - * **STRING**: Der im ProcessParameter gespeicherte String wird as is verwendet - * **JSON_STRING_MAP**: Der im ProcessParameter gespeicherte String wird im Prozess als - JSON-Map geparst - * **JSON_OBJECT**: Der im ProcessParameter gespeicherte String wird im Prozess als - JSON-Objekt geparst - * **BINARY**: Der im ProcessParameter gespeicherte String wird als Base64 kodierter Byte-Array - interpretiert und als Byte-Array zurückgegeben. -* **defaultValue**: Der Defaultwert des Parameters. Wird verwendet, falls der Prozessverwalter - bei der Aktivierung des Prozesses nichts anderes angibt. - Wenn defaultValue nicht gesetzt ist, gibt es keinen Defaultwert. -* **required**: true, falls der Aktivierung des Prozesses immer ein Wert angegeben werden muss, - oder false, wenn nicht. Default ist false. -* **hidden**: true, wenn der Prozessparameter bei der Aktivierung nicht sichtbar sein soll, - oder false, wenn der Prozessparameter bei der Aktivierung sichtbar sein soll. Default ist false. + +| Attribut | Beschreibung | +|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | Der programmatische Name des Prozessparameters, muss unique für ein Prozessmodell sein | +| **description** | Die Beschreibung des Parameters für die Prozessverwalter, die den Parameter setzen wollen. | +| **type** | Der Typ des Prozessparameters. Erlaubt sind folgende Werte: | +| **defaultValue** | Der Defaultwert des Parameters. Wird verwendet, falls der Prozessverwalter bei der Aktivierung des Prozesses nichts anderes angibt. Wenn defaultValue nicht gesetzt ist, gibt es keinen Defaultwert. | +| **required** | true, falls der Aktivierung des Prozesses immer ein Wert angegeben werden muss, oder false, wenn nicht. Default ist false. | +| **hidden** | true, wenn der Prozessparameter bei der Aktivierung nicht sichtbar sein soll, oder false, wenn der Prozessparameter bei der Aktivierung sichtbar sein soll. Default ist false. | Beispielhafter Inhalt einer Prozessparameterdefinitions-Datei: @@ -354,20 +383,21 @@ Authentifizierungsdaten, die vom Task _getAuthorizationToken_ geschrieben werden in die Datei config/auth.json des Root-Projektes geschrieben. Authentifizierungsdaten im Unterprojekt werden dabei vollständig ignoriert. -# Bereitgestellte Gradle-Tasks + +# Tasks ## Parameter für alle Tasks Die meisten vom Plugin bereitgestellten Gradle-Tasks können mit den folgenden Parametern konfiguriert werden: + +| Parameter | Required? | Beschreibung | +|-------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| mandant | false | Überschreibt den im config-Verzeichnis festgelegten Mandanten. | +| environment | false | Definiert die Umgebung, deren Konfiguration verwendet wird. Wird dieser Parameter nicht verwendet, so wird die Umgebung "default" verwendet. | +| debug | false | Wenn der Wert des Parameters "true" ist, werden weitere debug-Ausgaben durch das Plugin ausgegeben. | -* **mandant**: Optional. Überschreibt den im config-Verzeichnis festgelegten Mandanten. -* **environment**: Optional. Definiert die Umgebung, deren Konfiguration verwendet wird. - Wird dieser Parameter nicht verwendet, so wird die Umgebung "default" verwendet. -* **debug**: Optional. Wenn der Wert des Parameters "true" ist, werden weitere debug-Ausgaben - durch das Plugin ausgegeben. - -# Task _mergeScripts_ +## Task _mergeScripts_ Zweck dieses Tasks ist es, den Quellcode der Groovy-Skript-Tasks aus mehrere Dateien zusammenzufügen. @@ -408,11 +438,11 @@ und schon während der Entwicklung auf Fehler hinzuweisen. Hierfür sollten in d die Verzeichnisse `scripts` und alle Unterverzeichnisse des Verzeichnisses `commons` als Groovy-Quellverzeichnisse konfiguriert werden. -## Parameter +### Parameter Der globale Aufrufparameter **debug** beeinflusst den Task wie angegeben. -# Task _buildModel_ +## Task _buildModel_ Dieser Task fügt die (mit dem Task _mergeScripts_ zusammengefügten) Skripte in die Prozessmodelle ein, die im Verzeichnis `models` liegen, @@ -425,11 +455,11 @@ den Skript-Tasks zugeordnet. Die gebauten Prozessmodelle werden in das Verzeichnis `build/models` geschrieben. -## Aufrufparameter +### Aufrufparameter Die globalen Aufrufparameter **environment** und **debug** beeinflussen den Task wie angegeben. -# Task _uploadProcessModelFiles_ +## Task _uploadProcessModelFiles_ Dieser Task lädt die mit dem Task _buildModel_ gebauten Prozessmodell-Dateien ins Admincenter hoch. Dabei wird das Prozessmodell nicht sofort deployt; das Deployment erfolgt über den separaten @@ -452,11 +482,11 @@ Falls für das angegebene Prozessmodell und die angegebene Version * bereits Dateien in einer höheren als der angegebenen Stufe vorhanden sind, ist ein Hochladen in die angegebene Stufe nicht möglich. -## Aufrufparameter +### Aufrufparameter Alle globalen Aufrufparameter beeinflussen den Task wie angegeben. -# Task _uploadParameterDefinition_ +## Task _uploadParameterDefinition_ Dieser Task lädt eine Prozessparameterdefinition für einen Prozess in das Admincenter hoch. Eine eventuell bereits vorhandene Parameterdefinition wird überschrieben. @@ -475,17 +505,17 @@ Prozessparameterdefinitionen aus der Datei `parameterdefinitions/default.json` v Wenn das angegebene Prozessmodell oder die angegebene Version im konfigurierten Mandanten im Admincenter nicht existiert, wird ein Fehler geworfen. -## Aufrufparameter +### Aufrufparameter Alle globalen Aufrufparameter beeinflussen den Task wie angegeben. -# Task _getActiveProcessEngines_ +## Task _getActiveProcessEngines_ Dieser Task gibt die Liste der aktuell zur Verfügung stehenden Prozess-Engines aus. Die ID einer Prozess-Engine kann beim Deployment einer Prozessmodell-Version verwendet werden, um gezielt auf die gewünschte Prozess-Engine zu deployen. -# Task _deployProcessModelVersion_ +## Task _deployProcessModelVersion_ Dieser Task deployt ein im Admincenter vorhandenes Prozessmodell. Ist das Prozessmodell schon deployt, wird es undeployt und neu deployt. @@ -501,7 +531,7 @@ Aus der Menge, der zur Verfügung stehenden Prozess-Engines, kann die Engine, au Prozessversion deployt werden soll, ausgewählt werden. Ist keine Engine explizit angegeben, wird die Standard-Prozess-Engine verwendet. -# Task _uploadFormularFiles_ +## Task _uploadFormularFiles_ Dieser Task lädt die Formulare des Projekts in das Admincenter hoch. @@ -515,7 +545,7 @@ höher ist als die in der Konfiguration angegebenen Stufe, so ist ein Hochladen in die angegebene Stufe nicht möglich. Formulare, welche nicht dem Namensschema entsprechen, erzeugen einen Fehler. -## Benennung +### Benennung Die Informationen zu den Formularen können entweder als Ordnerstruktur oder über den Dateinamen* dem Task übergeben werden: @@ -529,11 +559,11 @@ Mandant und aktive Stufe für das Hochladen werden wie im Kapitel Dabei werden die beiden Stufen `FUNCTIONAL_ANALYSIS` und `TECHNICAL_IMPLEMENTATION` aus der ProjektKonfiguration im Admincenter auf die Stufe `Modellierung` gemappt. -## Aufrufparameter +### Aufrufparameter Alle globalen Aufrufparameter beeinflussen den Task wie angegeben. -# Task _uploadAndDeployFormularFiles_ +## Task _uploadAndDeployFormularFiles_ Dieser Task dient dazu, die Formulare im Projekt an eine Umgebung zu senden und anschliessend zu deployen. @@ -541,7 +571,7 @@ Ist ein Formular schon deployt, so wird es vor dem erneuten Deployment undeployt Die weitere Funktion ist analog zum Task _uploadFormularFiles_. -# Task _getAuthorizationToken_ +## Task _getAuthorizationToken_ Mit diesem Task kann ein neues Bearer-Token für eine Umgebung in die Konfigurationsdatei `auth.json` geschrieben werden. @@ -554,11 +584,11 @@ gelesen. Mandant und Umgebung, unter der der Key abgelegt werden soll, werden wie im Kapitel "Ermittlung von Konfigurationswerten" beschrieben aus der Konfiguration gelesen. -## Aufrufparameter +### Aufrufparameter Alle globalen Aufrufparameter beeinflussen den Task wie angegeben. -# Task _startLocalHttpServer_ +## Task _startLocalHttpServer_ Startet einen lokalen Server, um auf einer beliebigen Serviceportal-Umgebung die auf dem lokalen Rechner des Entwickler liegenden Dateien des Entwicklungsprojektes (Formulare und Prozesse) @@ -576,6 +606,39 @@ Es kann nur jeweils eine Instanz des Servers gestartet werden. Um den Server zu Übersichtsseite auf der entsprechende Link verwendet bzw. auf der Konsole der dazu bereitgestellte Task verwendet werden. -# Task _stopLocalHttpServer_ +## Task _stopLocalHttpServer_ + +Stoppt den lokalen Server zum Bearbeiten von lokalen Dateien. + + +# Breaking Changes/Migration Guide + +Mit der aktuellsten Version des Gradle Plugins wurden die Parameter für folgende Tasks angepasst: + +- `uploadFormularFiles` +- `uploadProcessModelFiles` + +Zu beachten ist das in der Konfiguration Datei jetzt statt dem Attribut `projectStage`, +das Attribut `status` mitgegeben muss. + +Die Status Werte haben sich hier auch geändert. Im folgenden eine Übersicht die Darstellt +welche `projectStage` Werte welchen `status` Werten entsprechen. + + +### Für Formulare + +| projectStage | status | +|-------------------|--------| +| MODELLING | EDIT | +| QUALITY_ASSURANCE | TEST | +| CERTIFIED | FINAL | + +### Für Prozesse + +| projectStage | status | +|--------------------------|--------| +| FUNCTIONAL_ANALYSIS | EDIT | +| TECHNICAL_IMPLEMENTATION | EDIT | +| QUALITY_ASSURANCE | TEST | +| CERTIFIED | FINAl | -Stoppt den lokalen Server zum Bearbeiten von lokalen Dateien. \ No newline at end of file From 6b9305e89b813d882fe3af89a56320d8076b365d Mon Sep 17 00:00:00 2001 From: Maksim Sandybekov Date: Fri, 2 Jun 2023 15:47:17 +0200 Subject: [PATCH 2/3] update docs SBW-25815 - replace information about "stufe" with information about "status" - add migration guide and deprecation warning to the documentation - update the config file --- config/default.json | 4 +- plugin.md | 82 +++++++++++++++++++++++++++------------ schnittstelle.md | 94 +++++++++++++++++++++++++++++++++------------ 3 files changed, 128 insertions(+), 52 deletions(-) diff --git a/config/default.json b/config/default.json index f1a0ff0..60f37ce 100644 --- a/config/default.json +++ b/config/default.json @@ -1,4 +1,4 @@ { - "url": "http://example.com:81/sgw", - "projectStage": "TECHNICAL_IMPLEMENTATION" + "url": "https://develop.sbw.imbw.dev.seitenbau.net:8887", + "status": "EDIT" } \ No newline at end of file diff --git a/plugin.md b/plugin.md index e3ece17..729c4b0 100644 --- a/plugin.md +++ b/plugin.md @@ -92,7 +92,7 @@ Die Ordnerstruktur wird vom Gradle-Plugin wie folgt erwartet: * **config**: Enthält die Konfigurationsdateien * **project.json**: Enthält allgemeine Informationen zum Projekt, z.B. Prozessname und Mandant * **auth.json**: Enthält Tokens zum Authentifizieren gegen die Serviceportal-Schnittstellen. - * **default.json**: Enthält die Definition der Standardumgebung (URL, Projektstufe, ...) + * **default.json**: Enthält die Definition der Standardumgebung (URL, Status, ...) * **${umgebungsname}.json**: Enthält die Definition der Umgebung ${umgebungsname} * **scripts**: Enthält die Skripte, die in die Prozessmodell-Dateien eingefügt werden sollen * **${prozessmodelId}**: Enthält die Skripte für den Prozess mit der Id ${prozessmodelId} @@ -176,7 +176,8 @@ Beispiel für die Authentifizierung für den Mandant 1 in der Umgebung default: Die Token können am bequemsten über den Task getAuthorizationToken geholt werden. Manche Umgebungen schränken aus Sicherheitsgründen einzelne Funktionen ein. -So wird beispielsweise es möglich sein, auf die Produktivumgebungen Prozesse in die Stufe QS hochzuladen, aber nicht in die Stufe Certified. Ebenso wird es nicht möglich sein mittels des Plugins +So ist es beispielsweise möglich, auf die Produktivumgebungen Prozesse im Status `TEST` +hochzuladen, aber nicht im Status `FINAL`. Ebenso ist es nicht möglich mittels des Plugins die Prozesse zu deployen. Diese Beschränkungen werden über den Betrieb in Absprache mit dem IM/SK für jede Umgebung @@ -191,10 +192,9 @@ die Umgebungsdefinitionsdatei prozesstest.json angezogen. Die Dateien enthalten folgende Informationen: * **url**: Die URL des Servicegateways der Zielumgebung -* **projectStage**: Die Stufe, in die das Prozessmodell und die Formulare +* **projectStage**: Der Status in der das Prozessmodell und die Formulare auf der entsprechenden Umgebung abgelegt werden sollen. Gültige Werte sind prinzipiell - FUNCTIONAL_ANALYSIS, TECHNICAL_IMPLEMENTATION, QUALITY_ASSURANCE, CERTIFIED, es kann jedoch sein, - dass manche Werte auf manchen Umgebungen nicht zur Verfügung stehen. + EDIT, TEST und FINAL. Es kann jedoch sein, dass manche Werte auf manchen Umgebungen nicht zur Verfügung stehen. * **mandant**: Die Id des Mandanten für diese Umgebung. Wenn gesetzt, wird der Mandant aus der Datei project.json überschrieben. * **processModelNameExtension**: Ein optionales Suffix, der beim Bauen der Prozessmodelle @@ -207,7 +207,7 @@ Beispiel: ``` { "url": "https://sgwtest.service-bw.de", - "projectStage": "TECHNICAL_IMPLEMENTATION", + "status": "EDIT", "mandant": "42", "processModelNameExtension": "DEV", "processEngine": "secondEngine" @@ -330,9 +330,9 @@ Dabei wird von oben nach unten vorgegangen und der erste nicht-null Wert verwend Name und Version des Prozessmodells werden aus der Datei `config/project.json` gelesen. -### Stufe der Prozessmodell-Version +### Status der Prozessmodell-Version -Die aktive Stufe des Prozessmodells wird aus der Konfigurationsdatei der Umgebung gelesen. +Der aktive Status des Prozessmodells wird aus der Konfigurationsdatei der Umgebung gelesen. ### Prozess-Engine für Deployment Die ID der Prozess-Engine, auf die eine Prozessmodell-Version deployt werden soll, wird, sofern @@ -435,22 +435,21 @@ Dieser Task lädt die mit dem Task _buildModel_ gebauten Prozessmodell-Dateien i Dabei wird das Prozessmodell nicht sofort deployt; das Deployment erfolgt über den separaten Task _deployProcessModelVersion_. -Mandant, Name, Version und aktive Stufe für das Hochladen werden wie im Kapitel +Mandant, Name, Version und aktiver Status für das Hochladen werden wie im Kapitel "Ermittlung von Konfigurationswerten" beschrieben aus der Konfiguration gelesen. Beim erstmaligen Hochladen wird für den konfigurierten Mandanten im Admincenter ein Prozessmodell mit dem konfigurierten Namen angelegt. In diesem wird die konfigurierte Version angelegt. -Anschließend werden alle Dateien im Ordner `build/models` für alle Stufen bis zur -konfigurierten Stufe importiert. +Anschließend werden alle Dateien im Ordner `build/models` für den konfigurierten Status importiert. Falls für das angegebene Prozessmodell und die angegebene Version -* bereits Dateien in der angegebenen Stufe vorhanden sind, so gilt: - * hat eine Datei in der Stufe den gleichen Namen wie eine Datei in `build/models`, wird diese +* bereits Dateien mit dem angegebenen Status vorhanden sind, so gilt: + * hat eine Datei mit einem Status den gleichen Namen wie eine Datei in `build/models`, wird diese ersetzt * alle anderen vorhandenen Dateien werden NICHT verändert oder gelöscht -* bereits Dateien in einer höheren als der angegebenen Stufe vorhanden sind, ist ein Hochladen in - die angegebene Stufe nicht möglich. +* bereits Dateien in einem höheren als dem angegebenen Status vorhanden sind, ist ein Hochladen mit + dem angegebenen Status nicht möglich. ## Aufrufparameter @@ -490,7 +489,7 @@ auf die gewünschte Prozess-Engine zu deployen. Dieser Task deployt ein im Admincenter vorhandenes Prozessmodell. Ist das Prozessmodell schon deployt, wird es undeployt und neu deployt. -Mandant, Name, Version und Stufe des zu deployenden Prozesses und die ID der Prozess-Engine, auf die +Mandant, Name, Version und Status des zu deployenden Prozesses und die ID der Prozess-Engine, auf die deployt werden soll, werden wie im Kapitel "Ermittlung von Konfigurationswerten" beschrieben aus der Konfiguration gelesen. @@ -508,11 +507,10 @@ Dieser Task lädt die Formulare des Projekts in das Admincenter hoch. Die hochzuladenden Formulare werden im Ordner `forms` gesucht. Alle dort liegenden und der Namenskonvention entsprechenden Formulare werden über die Schnittstelle an das Admincenter gesendet. Schon existierende Formulare werden überschrieben, -nicht existierende Formulare und Versionen werden angelegt. -Beim Neuanlegen werden alle Stufen bis zur angegebenen Stufe aufgefüllt. -Falls die aktive Stufe für die Version des Formulars im Admincenter -höher ist als die in der Konfiguration angegebenen Stufe, -so ist ein Hochladen in die angegebene Stufe nicht möglich. +nicht existierende Formulare und Versionen werden angelegt. +Falls der aktive Status für die Version des Formulars im Admincenter +höher ist als der angegebene Status in der Konfiguration, +so ist ein Hochladen in den angegebene Status nicht möglich. Formulare, welche nicht dem Namensschema entsprechen, erzeugen einen Fehler. ## Benennung @@ -524,10 +522,8 @@ Die Informationen zu den Formularen können entweder als Ordnerstruktur oder üb \* analog dem Namen beim Download eines Formulars aus dem Admincenter -Mandant und aktive Stufe für das Hochladen werden wie im Kapitel +Mandant und der Status für das Hochladen werden wie im Kapitel "Ermittlung von Konfigurationswerten" beschrieben aus der Konfiguration gelesen. -Dabei werden die beiden Stufen `FUNCTIONAL_ANALYSIS` und `TECHNICAL_IMPLEMENTATION` -aus der ProjektKonfiguration im Admincenter auf die Stufe `Modellierung` gemappt. ## Aufrufparameter @@ -578,4 +574,40 @@ Task verwendet werden. # Task _stopLocalHttpServer_ -Stoppt den lokalen Server zum Bearbeiten von lokalen Dateien. \ No newline at end of file +Stoppt den lokalen Server zum Bearbeiten von lokalen Dateien. + + +# Breaking Changes/Migration Guide + +Mit der aktuellsten Version des Gradle Plugins wurden die Parameter für folgende Tasks angepasst: + +- `uploadFormularFiles` +- `uploadProcessModelFiles` + +Zu beachten ist das in der Konfiguration Datei jetzt statt dem Attribut `projectStage`, +das Attribut `status` mitgegeben muss. Die Möglichen Werte die hier angegeben werden können, +haben sich auch geändert siehe folgendes Kapitel. + +## Migration + +Um das Plugin in der neusten Version nutzen zu können müssen die Konfigurationsdateien angepasst +werden, falls noch nicht geschehen. Hierzu das Attribut `projectStage` zu `status` umbennen. +Die Werte dees Attributes können anhand der nachfolgenden Tabelle in die neuen Status Werte +übertragen werden. + +### Für Formulare + +| projectStage | status | +|-------------------|--------| +| MODELLING | EDIT | +| QUALITY_ASSURANCE | TEST | +| CERTIFIED | FINAL | + +### Für Prozesse + +| projectStage | status | +|--------------------------|--------| +| FUNCTIONAL_ANALYSIS | EDIT | +| TECHNICAL_IMPLEMENTATION | EDIT | +| QUALITY_ASSURANCE | TEST | +| CERTIFIED | FINAl | \ No newline at end of file diff --git a/schnittstelle.md b/schnittstelle.md index ef7d796..8c419b9 100644 --- a/schnittstelle.md +++ b/schnittstelle.md @@ -44,14 +44,15 @@ Anlegen der Formulare im Admincenter deployt werden. `{pfad zum sgw}/formulare/management/formulare/api/upload` ### Headerparameter -| **Name** | **Beschreibung** | -| --------------------- | ----------------- | -| X-SP-Formular-Name | Name des Formulars | -| X-SP-Formular-Version | Version des Formulars | -| X-SP-Formular-Stage | WorkflowStage des Formulars
`MODELLING`, `QUALITY_ASSURANCE`, `CERTIFIED` | -| X-SP-Formular-Deploy | `true`, wenn das Formular deployt werden soll, default: `false` | -| X-SP-Mandant | ID des Mandanten | -| Content-Type | `application/zip` | +| **Name** | **Beschreibung** | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| X-SP-Formular-Name | Name des Formulars | +| X-SP-Formular-Version | Version des Formulars | +| X-SP-Formular-Stage | WorkflowStage des Formulars
  • `MODELLING`
  • `QUALITY_ASSURANCE`
  • `CERTIFIED`
*ACHTUNG: Header ist Deprecated. Migration erfoderlich falls noch genutzt,
siehe [Breaking Changes/Migration Guide](#breaking-changesmigration-guide) | +| X-SP-Formular-Status | Status des Formulars
  • `EDIT`
  • `TEST`
  • `FINAL`
| +| X-SP-Formular-Deploy | `true`, wenn das Formular deployt werden soll, default: `false` | +| X-SP-Mandant | ID des Mandanten | +| Content-Type | `application/zip` | ### Body Die Schnittstelle erwartet als Body eine ZIP-Datei. @@ -72,8 +73,9 @@ Um diese Schnittstelle aufrufen zu können benötigt der Benutzer folgende Recht Die Rechte sind in den oben genannten Rollen und Benutzergruppen enthalten. -Für jede Umgebung ist eine maximale Stufe definiert. Wird versucht -Formulare in eine Stufe höher der angegebenen hochzuladen und/oder zu deployen, wird ein Fehler zurückgegeben. +Für jede Umgebung ist ein maximaler Status definiert. Wird versucht +Formulare in einem Status hochzuladen und/oder zu deployen, der höher ist als der maximale, +wird ein Fehler zurückgegeben. ### Rückgabewerte @@ -98,13 +100,14 @@ im Backend an das Deplyoen eines Prozesses gekoppelt und wird automatisch mit au `{pfad zum sgw}/prozessmanagement/prozessmodelle/api/upload` ### Headerparameter -| **Name** | **Beschreibung** | -| -------------------- | ---------------- | -| X-SP-Process-Name | Name des Prozesses | -| X-SP-Process-Version | Version des Prozesses | -| X-SP-Process-Stage | WorkflowStage des Prozesses
`FUNCTIONAL_ANALYSIS`, `TECHNICAL_IMPLEMENTATION` , `QUALITY_ASSURANCE`, `CERTIFIED` | -| X-SP-Mandant | ID des Mandanten | -| Content-Type | `application/zip` | +| **Name** | **Beschreibung** | +|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| X-SP-Process-Name | Name des Prozesses | +| X-SP-Process-Version | Version des Prozesses | +| X-SP-Process-Stage | WorkflowStage des Prozesses
  • `FUNCTIONAL_ANALYSIS`
  • `TECHNICAL_IMPLEMENTATION`
  • `QUALITY_ASSURANCE`
  • `CERTIFIED`
*ACHTUNG: Header ist Deprecated. Migration erfoderlich falls noch genutzt,
siehe [Breaking Changes/Migration Guide](#breaking-changesmigration-guide) | +| X-SP-Process-Status | Status des Prozesses
  • `EDIT`
  • `TEST`
  • `FINAL`
| +| X-SP-Mandant | ID des Mandanten | +| Content-Type | `application/zip` | ### Body Die Schnittstelle erwartet als Body eine ZIP-Datei, welche vom Aufbau her dem Business Archive von Activiti entspricht (https://www.activiti.org/userguide/#_business_archives): @@ -125,8 +128,9 @@ Um diesse Schnittstelle aufrufen zu können benötigt der Benutzer folgende Rech Das Recht ist in den oben genannten Rollen und Benutzergruppen enthalten. -Für jede Umgebung ist eine maximale Stufe definiert. Wird versucht eine Prozessmodellversion in eine Stufe höher -als der angegebenen hochzuladen, wird ein Fehler zurückgegeben. +Für jede Umgebung ist ein maximaler Status definiert. +Wird versucht eine Prozessmodellversion in einem Status hochzuladen, der höher ist als der maximale Status, +wird ein Fehler zurückgegeben. ### Rückgabewerte @@ -146,10 +150,9 @@ Der Aufruf muss als POST ausgeführt werden. ### Headerparameter | **Name** | **Beschreibung** | -| -------------------- | ---------------- | +|----------------------| ---------------- | | X-SP-Process-Name | Name des Prozesses | | X-SP-Process-Version | Version des Prozesses | -| X-SP-Process-Stage | WorkflowStage des Prozesses
`FUNCTIONAL_ANALYSIS`, `TECHNICAL_IMPLEMENTATION` , `QUALITY_ASSURANCE`, `CERTIFIED` | | X-SP-Process-Engine | ID der Prozess-Engine, Standard-Prozess-Engine wenn nicht gesetzt | | X-SP-Mandant | ID des Mandanten | @@ -163,8 +166,8 @@ Um diese Schnittstelle Aufrufen zu können benötigt der Benutzer folgende Recht Das Recht ist in den oben genannten Rollen und Benutzergruppen enthalten. -Für jede Umgebung ist eine maximale Stufe definiert. Wird versucht eine Prozessmodellversion in eine Stufe höher -der angegebenen deployt, wird ein Fehler zurückgegeben. +Für jede Umgebung ist ein maximaler Status definiert. Wird versucht eine Prozessmodellversion in einem Status +zu deployen, der höher ist als der maximale, wird ein Fehler zurückgegeben. ### Rückgabewerte @@ -206,8 +209,8 @@ daher die Möglichkeit eines Deployments implizit enthält, wird zum Hochladen d | X-SP-Mandant | ID des Mandanten | | Content-Type | `application/zip` | -Da Prozessparameterdefinitionen zu einer Prozessmodellversion und nicht einer spezifischen Stufe gehören, -muss keine Stufe angegeben werden +Da Prozessparameterdefinitionen zu einer Prozessmodellversion und nicht einem spezifischen Status gehören, +muss kein Status angegeben werden. ### Body Die Schnittstelle als Body eine JSON-Datei, welche vom Aufbau her derjenigen des Hoch- und Herunterladens im Admincenter entspricht. @@ -257,3 +260,44 @@ Eine Liste mit den IDs und Namen der Prozess-Engines (`application/json`). } ] ``` + +# Breaking Changes/Migration Guide + +Mit der letzten version des Gradle Plugins wurden die Projektstufen entfernt und durch +Status werte ersetzt. Übergangsweise können die Schnittstellen sowohl mit der Stufe +als auch dem neuen Status genutzt werden. + +Es sollte jedoch beachtet werden das die Stufen ab einem Zeitpunkt X, vollständig ausgebaut werden +und deren Nutzung nicht mehr möglich ist. + +Daher sollte auf die Nutzung der neuen Stufen umgestellt werden. + +Was sollte gemacht werden um um die Funktionsweise zu gewährleisten? + +1. Beim Ansprechen der Schnittstellen nur noch den Status Wert verwenden + - Dieser wird über die entsprechenden Header `X-SP-Process-Status` und `X-SP-Formular-Status` übertragen +2. Konfigurationsdateien anpassen. Statt dem Attribut `projectStage` sollte das Attribut `status` verwendet werden +3. Die neuen Statuswerte statt den ehemaligen Stufen verwenden. Siehe hierfür die folgenden Tabellen + + +## Mapping der alten Stufen auf neue Status Werte + +Die folgenden Tabellen stellen dar welcher Status Wert die selbe Funktionalität bieten wie eine +bestimmte Stufe. + +### Formular Stufen <--> Status + +| projectStage | status | +|-------------------|--------| +| MODELLING | EDIT | +| QUALITY_ASSURANCE | TEST | +| CERTIFIED | FINAL | + +### Prozess Stufen <--> Status + +| projectStage | status | +|--------------------------|--------| +| FUNCTIONAL_ANALYSIS | EDIT | +| TECHNICAL_IMPLEMENTATION | EDIT | +| QUALITY_ASSURANCE | TEST | +| CERTIFIED | FINAl | From c5900be3fc22d51294264d02d9a1dab55524a69f Mon Sep 17 00:00:00 2001 From: Maksim Sandybekov Date: Tue, 6 Jun 2023 14:13:17 +0200 Subject: [PATCH 3/3] Correct merge of documentation no-ticket - choose better wording "deprecated" instead of "warning" - correct links to migration guide, because moved to separate file --- plugin.md | 1 - readme.md | 1 + schnittstelle.md | 34 +++++++++++++++++----------------- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/plugin.md b/plugin.md index 71e0f3f..c5f1523 100644 --- a/plugin.md +++ b/plugin.md @@ -32,7 +32,6 @@ 9. [_getAuthorizationToken_](#task-getauthorizationtoken) 10. [_startLocalHttpServer_](#task-startlocalhttpserver) 11. [_stopLocalHttpServer_](#task-stoplocalhttpserver) -3. [Breaking Changes/Migration Guide](#breaking-changesmigration-guide) # Ziele des Gradle-Plugins zur Prozessmodellierung diff --git a/readme.md b/readme.md index 364fa69..6b9416f 100644 --- a/readme.md +++ b/readme.md @@ -7,6 +7,7 @@ Die Dokumentation besteht aus folgenden Teilen: * [Gradle-Plugin (aus Gradle-Plugin-Repository)](plugin.md) * [Schnittstellendokumentation](schnittstelle.md) * [Änderungen](changelog.md) +* [Breaking Changes & Migration Guides](migration.md) # Projektvorlage diff --git a/schnittstelle.md b/schnittstelle.md index b0c5e4d..e08023d 100644 --- a/schnittstelle.md +++ b/schnittstelle.md @@ -44,15 +44,15 @@ Anlegen der Formulare im Admincenter deployt werden. `{pfad zum sgw}/formulare/management/formulare/api/upload` ### Headerparameter -| **Name** | **Beschreibung** | -|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| X-SP-Formular-Name | Name des Formulars | -| X-SP-Formular-Version | Version des Formulars | -| X-SP-Formular-Stage | WorkflowStage des Formulars
  • `MODELLING`
  • `QUALITY_ASSURANCE`
  • `CERTIFIED`
*ACHTUNG: Header ist Deprecated. Migration erfoderlich falls noch genutzt,
siehe [Breaking Changes/Migration Guide](#breaking-changesmigration-guide) | -| X-SP-Formular-Status | Status des Formulars
  • `EDIT`
  • `TEST`
  • `FINAL`
| -| X-SP-Formular-Deploy | `true`, wenn das Formular deployt werden soll, default: `false` | -| X-SP-Mandant | ID des Mandanten | -| Content-Type | `application/zip` | +| **Name** | **Beschreibung** | +|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| X-SP-Formular-Name | Name des Formulars | +| X-SP-Formular-Version | Version des Formulars | +| X-SP-Formular-Stage | WorkflowStage des Formulars
  • `MODELLING`
  • `QUALITY_ASSURANCE`
  • `CERTIFIED`
*Deprecated: Header wird mit folgenden Versionen vollständig entfernt. Migration erfoderlich falls noch genutzt,
siehe [Migration Guide](migration.md) | +| X-SP-Formular-Status | Status des Formulars
  • `EDIT`
  • `TEST`
  • `FINAL`
| +| X-SP-Formular-Deploy | `true`, wenn das Formular deployt werden soll, default: `false` | +| X-SP-Mandant | ID des Mandanten | +| Content-Type | `application/zip` | ### Body Die Schnittstelle erwartet als Body eine ZIP-Datei. @@ -100,14 +100,14 @@ im Backend an das Deplyoen eines Prozesses gekoppelt und wird automatisch mit au `{pfad zum sgw}/prozessmanagement/prozessmodelle/api/upload` ### Headerparameter -| **Name** | **Beschreibung** | -|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| X-SP-Process-Name | Name des Prozesses | -| X-SP-Process-Version | Version des Prozesses | -| X-SP-Process-Stage | WorkflowStage des Prozesses
  • `FUNCTIONAL_ANALYSIS`
  • `TECHNICAL_IMPLEMENTATION`
  • `QUALITY_ASSURANCE`
  • `CERTIFIED`
*ACHTUNG: Header ist Deprecated. Migration erfoderlich falls noch genutzt,
siehe [Breaking Changes/Migration Guide](#breaking-changesmigration-guide) | -| X-SP-Process-Status | Status des Prozesses
  • `EDIT`
  • `TEST`
  • `FINAL`
| -| X-SP-Mandant | ID des Mandanten | -| Content-Type | `application/zip` | +| **Name** | **Beschreibung** | +|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| X-SP-Process-Name | Name des Prozesses | +| X-SP-Process-Version | Version des Prozesses | +| X-SP-Process-Stage | WorkflowStage des Prozesses
  • `FUNCTIONAL_ANALYSIS`
  • `TECHNICAL_IMPLEMENTATION`
  • `QUALITY_ASSURANCE`
  • `CERTIFIED`
*Deprecated: Header wird mit folgenden Versionen vollständig entfernt. Migration erfoderlich falls noch genutzt,
siehe [Migration Guide](migration.md) | +| X-SP-Process-Status | Status des Prozesses
  • `EDIT`
  • `TEST`
  • `FINAL`
| +| X-SP-Mandant | ID des Mandanten | +| Content-Type | `application/zip` | ### Body Die Schnittstelle erwartet als Body eine ZIP-Datei, welche vom Aufbau her dem Business Archive von Activiti entspricht (https://www.activiti.org/userguide/#_business_archives):