Wiki-Quellcode von FORMCYCLE-Deploy-Plugin

Zeige letzte Bearbeiter
1 {{content/}}
2
3 Mit dem Deploy-Plugin können Plugins automatisch in die FORMCYCLE-Anwendung hochgeladen und dort installiert werden. Dies hat gegenüber der manuellen Installation über das entsprechende [[Menü im Backend>>doc:Formcycle.UserInterface.Client.Plugins]] einige Vorteile:
4
5 * Plugin-Entwickler können beim Maven-Build das Plugin automatisch am Ende des Builds hochladen. So kann der Entwickler schneller testen.
6 * Eine Installation auf einem Live-System kann so weiter automatisiert werden.
7
8 Das Deploy-Plugin kann sowohl als Mandant-Plugin als auch als System-Plugin installiert werden. Es enthält eine [[Servlet-Aktion>>doc:Formcycle.PluginDevelopment.Types.IPluginServletAction]]. Per HTTP-Post-Request wird eine Plugin-JAR-Datei an den FORMCYCLE-Server gesendet. Die weiteren Parameter im HTTP-Request bestimmen, was nun weiter mit dem Plugin geschieht, etwa ob es nur installiert oder auch aktiviert werden soll.
9
10 Falls das hochgeladene Plugin bereits existiert, ist es in der Regel ist es sinnvoll, dieses zu ersetzen. Dazu ist es erforderlich, anzugeben, über welchen Identifikator ein Plugin identifiziert wird. Es gibt hierbei vier Möglichkeiten, die dieses Plugin erlaubt:
11
12 * (**empfohlen**) Das Plugin wird anhand eines Eintrags im Manifest identifiziert. Dieses muss in der Plugin-JAR-Datei im Pfad //META-INF/MANIFEST.MF// liegen. Beim Bau der JAR-Datei muss ein entsprechender eindeutiger Eintrag in das Manifest geschrieben werden, etwa die Group-ID und Artifact-ID. Diese Methode hat den Vorteil, dass der Identifikator sich nie ändern wird und unabhängig von internen IDs und Dateinamen ist.
13 * Das Plugin wird anhand seines Namens identifiziert, also dem Namen der ursprünglich hochgeladenen JAR-Datei. Dies ist der Name, wie er auch [[in der Oberfläche>>doc:Formcycle.UserInterface.Client.Plugins]] zu sehen ist.
14 * Das Plugin wird anhand seiner internen Datenbank-ID identifiziert. Diese ist aktuell nicht an der Oberfläche zu sehen. Diese Option sollte nur von Entwicklern genutzt werden.
15 * Das Plugin wird anhand seiner internen UUID identifiziert. Diese ist aktuell nicht an der Oberfläche zu sehen. Diese Option sollte nur von Entwicklern genutzt werden.
16
17 Standardmäßig ist eine Servlet-Aktion für alle frei zugänglich. Da es in der Regel unerwünscht ist, dass jeder (auch unangemeldete) Nutzer Plugins installieren kann, kann das Deploy-Plugin durch ein Passwort abgesichert werden. Dazu muss in der Plugin-Konfiguration der Passwort-Hash hinterlegt werden und das Passwort dann im HTTP-POST-Request mitgesendet werden.
18
19 == Plugin-Konfiguration ==
20
21 == HTTP-Request-Aufbau ==
22
23 Im Folgenden wird der Aufbau des HTTP-Requests beschrieben, um ein Plugin zu installieren, zu aktualisieren oder zu löschen.
24
25 Es muss immer ein HTTP-Post-Request verwendet werden und [[sich an folgende URL richten>>doc:Formcycle.PluginDevelopment.Types.IPluginServletAction]] (Namen des FORMCYCLE-Servers entsprechend anpassen):
26
27 {{code language="none"}}
28 POST http://localhost:8080/formcycle/plugin?name=deploy-plugin&client-id=154 HTTP/1.1
29 {{/code}}
30
31 Die //client-id// muss nicht angegeben werden, wenn das Plugin als System-Plugin installiert ist.
32
33 === Request-Parameter ===
34
35 Die Parameter können direkt als URL-Parameter, als //multipart/form-data// oder als //application/x-www-form-urlencoded// übergeben werden. Folgende Parameter werden vom Deploy-Plugin unterstützt und können übergeben werden:
36
37 ; deploy-action
38 : Aktion, welche mit dem Plugin durchgeführt werden soll. Erlaubte Werte sind //save//, //update-properties//, //activate//, //deactivate// und //delete//. Ein Erklärung zu diesen Aktionen findet sich unten.
39 ; client-id
40 : ID des Mandanten, in dem ein Plugin installiert, aktualisiert oder gelöscht werden soll. Es darf nur entweder //client-id// oder //client-uuid// angegeben werden
41 ; client-uuid
42 : UUID des Mandanten, in dem ein Plugin installiert, aktualisiert oder gelöscht werden soll. Es darf nur entweder //client-id// oder //client-uuid// angegeben werden. Es ist zu beachten, dass der Aufruf eines als Mandant-Plugin installierten Servlet-Aktion immer der Parameter //client-id// erforderlich ist.
43 ; jar-file
44 : Binärdaten mit der JAR-Datei des Plugins, welches aktualisert oder installiert werden soll.
45 ; token
46 : Das Token (Password) für die Authorisierung des Requests. Nur erforderlich, wenn in der Plugin-Konfiguration ein Token festgelegt wurde.
47 ; plugin-ident
48 : Die Art, wie nach einem vorhandenen Plugin gesucht wird (siehe oben). Folgende Werte sind erlaubt:
49 :; manifest
50 :: Identifiziert ein Plugin anhand eines Eintrags im Manifest.
51 :; id
52 :: Identifiziert ein Plugin anhand seiner Datenbank-ID.
53 :; name
54 :: Identifiziert ein Plugin anhand seines Namens (Dateiname der JAR-Datei)
55 :; uuid
56 :: Identifiziert ein Plugin anhand seiner UUID.
57 ; plugin-identifier
58 : Identifikator des Plugins, welches aktualisiert oder gelöscht werden soll. Die konkrete Bedeutung dieses Parameters ist abhängig von dem Wert von //plugin-ident//:
59 :; plugin-ident=manifest
60 :: //plugin-identifier// muss den Namen der Manifest-Eigenschaft und dessen Wert enthalten, im Format //ATTRIBUTE_NAME=VALUE//. Wird zum Beispiel //Implementation-Title=com.example.fc.plugin:my-plugin// übergeben wird, wird nach einem existierenden Plugin gesucht, welches im Manifest in der Eigenschaft //Implementation-Title// den Wert //com.example.fc.plugin:my-plugin// stehen hat.
61 :; plugin-ident=id
62 :: //plugin-identifier// muss die gewünschte ID des Plugins enthalten, etwa //53// oder /893//.//
63 :; plugin-ident=name
64 :: //plugin-identifier// muss den gewünschten Names des Plugins enthalten, etwa //my-plugin.jar// oder /foobar.jar//.//
65 :; plugin-ident=uuid
66 :: //plugin-identifier// muss die gewünschte UUID des Plugins enthalten, etwa //03022599-903d-429b-9822-80a324a542fc//.
67 Andernfalls wird das Plugin installiert, falls noch nicht vorhanden, oder aktualisiert, falls vorhanden.
68 ; clear-properties
69 : Entweder //true// oder //false//. Wenn //true//, werden alle Plugin-Eigenschaften entfernt beziehungsweise deren Werte geleert. Dies wird ausgeführt, bevor die neu zu setzenden Plugin-Eigenschaften (Parameter ///property//) angewendet werden.
70 ; property
71 : Name und Wert einer Plugin-Eigenschaft, die an der Plugin-Konfiguration gesetzt werden soll, im Format //key=value//. Dieser HTTP-Parameter kann mehrfach angegeben werden, um mehrere Plugin-Eigenschafte zu setzen. Wird etwa //database.username=max// übergeben, wird die Plugin-Eigenschaft //database.username// auf //max// gesetzt.
72 ; disallow-install
73 : Entweder //true// oder //false//. Ist diese Option auf //true// gesetzt und existiert das Plugin noch nicht (bezüglich der angegebenen //plugin-ident// und //plugin-identifier//), wird das Plugin nicht neu installiert und eine Fehlermeldung zurückgegeben. ; locale
74 : Die Sprache, welche während der Installation, Aktualisierung oder Löschung des Plugins verwendet werden soll, etwa //en// oder //de//. Beeinflusst nur einige Fehlermeldungen und kann in der Regel weggelassen werden.
75
76 === Deploy-Action ===
77
78 Der Wert des Parameters //deploy-action// gibt an, was genau mit dem Plugin geschehen soll. Es gibt dabei die folgenden Möglichkeiten:
79
80 ; save
81 : Überträgt das angegebene Plugin auf das FORMCYCLE-System. Es muss hierbei eine JAR-Datei übertragen werden. Falls das Plugin noch nicht existiert (und der Parameter //disallow-install// nicht gesetzt ist), wird das Plugin neu installiert und ist dann aktiviert. Andernfalls, falls das Plugin bereits existiert, wird es aktualisiert, dabei bleibt das Plugin aktiviert oder deaktiviert.
82
83 (((
84 {{code language="bash"}}
85 curl -X POST \
86 # These options are required
87 -F deploy-action=save \
88 -F token=admin \
89 -F plugin-ident=manifest \
90 -F plugin-identifier=Implementation-Title=com.example:plugin \
91 -F "jar-file=@my-plugin.jar" \
92 "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
93 {{/code}}
94 )))
95
96 ; delete
97 : Löscht das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
98
99 (((
100 {{code language="bash"}}
101 curl -X POST \
102 # These options are required
103 -F deploy-action=delete \
104 -F token=admin \
105 -F plugin-ident=manifest \
106 -F plugin-identifier=Implementation-Title=com.example:plugin \
107 "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
108 {{/code}}
109 )))
110
111 ; activate
112 : Aktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
113
114 (((
115 {{code language="bash"}}
116 curl -X POST \
117 # These options are required
118 -F deploy-action=activate \
119 -F token=admin \
120 -F plugin-ident=manifest \
121 -F plugin-identifier=Implementation-Title=com.example:plugin \
122 "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
123 {{/code}}
124 )))
125
126 ; deactivate
127 : Deaktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
128
129 (((
130 {{code language="bash"}}
131 curl -X POST \
132 # These options are required
133 -F deploy-action=deactivate \
134 -F token=admin \
135 -F plugin-ident=manifest \
136 -F plugin-identifier=Implementation-Title=com.example:plugin \
137 "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
138 {{/code}}
139 )))
140
141 ; update-properties
142 : Aktualisiert die Eigenschaften des angegebenen Plugins. Es darf hierbei keine JAR-Datei übertragen werden. Entweder die Eigenschaft //clear-properties// oder //property// sollte gesetzt sein. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
143
144 (((
145 {{code language="bash"}}
146 # Löscht alle vorhandenen Plugin-Eigenschaften und setzt dann die Eigenschaft "foo" auf den Wert "bar"
147 curl -X POST \
148 -F deploy-action=update-properties \
149 -F token=admin \
150 -F plugin-ident=manifest \
151 -F plugin-identifier=Implementation-Title=com.example:plugin \
152 -F clear-properties=false \
153 -F property=foo=bar \
154 "http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
155 {{/code}}
156 )))
157
158 == Response ==
159
160 Das Deploy-Plugin liefert einen Statuscode und ein JSON-Objekt mit den Details zurück. Der Status-Code ist 2xx, falls das Deploy-Plugin erfolgreich ausgeführt wurde.
161
162 Das JSON-Objekt hat dabei [[die folgende Struktur>>https://json-schema.org/]]:
163
164 {{code language="json"}}
165 {
166 "$schema": "http://json-schema.org/schema",
167 "description": "Represents the response of the deploy plugin servlet.",
168 "required": [
169 "success",
170 "statusCode",
171 "details",
172 "message",
173 "requestParameters"
174 ],
175 "properties": {
176 "success": {
177 "type": "boolean",
178 "title": "Success status",
179 "description": "true if the deploy plugin servlet was executed successfully, or false otherwise"
180 },
181 "statusCode": {
182 "type": "number",
183 "title": "HTTP status code",
184 "description": "The status code of the HTTP request that contains this response."
185 },
186 "details": {
187 "type": "object",
188 "title": "Result details",
189 "description": "Detailed information about the plugin processed by the deploy plugin servlet.",
190 "oneOf": [
191 {
192 "description": "If the deploy plugin servlet was successful, details about the successfully executed action.",
193 "required": [
194 "id",
195 "uuid",
196 "name",
197 "active",
198 "message"
199 ],
200 "properties": {
201 "id": {
202 "type": "number",
203 "title": "Plugin ID",
204 "description": "The database ID of the processed plugin."
205 },
206 "uuid": {
207 "type": "string",
208 "title": "Plugin UUID",
209 "description": "The UUID of the processed plugin."
210 },
211 "name": {
212 "type": "string",
213 "title": "Plugin name",
214 "description": "The name of the processed plugin, i.e. the file name of the plugin JAR file."
215 },
216 "active": {
217 "type": "boolean",
218 "title": "Plugin activation status",
219 "description": "true if the plugin is now active, false if it is now inactive."
220 },
221 "message": {
222 "type": "string",
223 "title": "Result message",
224 "description": "Human-readable message describing the performed action."
225 }
226 }
227 },
228 {
229 "required": [
230 "exceptionType",
231 "exceptionMessage"
232 ],
233 "description": "If the deploy plugin servlet was unsuccessful, details about the error that occurred.",
234 "properties": {
235 "exceptionType": {
236 "type": "string",
237 "title": "Exception type",
238 "description": "The type of the error that occurred, a fully-classified name of the Java exception class."
239 },
240 "exceptionMessage": {
241 "type": "string",
242 "title": "Exception message",
243 "description": "The human-readable message of the error that occurred."
244 }
245 }
246 }
247 ]
248 },
249 "message": {
250 "type": "string",
251 "title": "Result message",
252 "description": "A human-readable message that describes this result."
253 },
254 "requestParameters": {
255 "type": "object",
256 "title": "Request parameters",
257 "description": "The parameters of the request that triggered this response."
258 }
259 }
260 }
261 {{/code}}
262
263 == Beispiel für Maven ==

Navigation

Copyright 2000-2025