Zusammenfassung

• Seiteneigenschaften (1 geändert, 0 hinzugefügt, 0 gelöscht)

Details

Seiteneigenschaften

Inhalt

...	...	@@ -16,8 +16,44 @@
16	16
17	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	18
19		-== HTTP-Request-Aufbau ==
	19	+== Plugin-Konfiguration ==
20	20
	21	+Am Plugin selber kann konfiguriert werden, ob das Deploy-Servlet durch ein Passwort geschützt werden soll. Dieses Passwort muss dann im Klartext beim HTTP-POST-Request mit angegeben werden.
	22	+
	23	+Zur Konfiguration des Passworts gibt es die eine Plugin-Eigenschaft //token//, diese hat das folgende Format
	24	+
	25	+{{code language="none"}}
	26	+hash_method:hashed_value
	27	+{{/code}}
	28	+
	29	+Folgende Hash-Methoden stehen zur Verfügung:
	30	+
	31	+; plain
	32	+: Identitätsfunktion, das Passwort im Klartext angegeben.
	33	+; sha256
	34	+: SHA-256-Algorithmus.
	35	+; sha384
	36	+: SHA-384-Algorithmus.
	37	+; sha512
	38	+: SHA-512-Algorithmus.
	39	+
	40	+Um das Passwort im Klartext beispielsweise auf //admin// festzulegen, wird der folgende Wert für die Plugin-Eigenschaft //token// eingegeben:
	41	+
	42	+{{code language="none"}}
	43	+plain:admin
	44	+{{/code}}
	45	+
	46	+Um das Passwort mit SHA-256 beispielsweise auf //admin// festzulegen, wird der folgende Wert für die Plugin-Eigenschaft //token// eingegeben:
	47	+
	48	+{{code language="none"}}
	49	+sha256:S+32GI3fWXwHHulUMtWmjpQ15EqMvgVYguuO9SKxfNw+ckAGQljP6tKlf1EITnU7
	50	+{{/code}}
	51	+
	52	+Der Hash ist gesalzen. Ein gültiger Hash für ein bestimmtes Passwort kann mit dem //create-token//-Servlet erzeugt werden, siehe unten.
	53	+
	54	+
	55	+== Deploy-Servlet ==
	56	+
21	21	Im Folgenden wird der Aufbau des HTTP-Requests beschrieben, um ein Plugin zu installieren, zu aktualisieren oder zu löschen.
22	22
23	23	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):
...	...	@@ -28,7 +28,7 @@
28	28
29	29	Die //client-id// muss nicht angegeben werden, wenn das Plugin als System-Plugin installiert ist.
30	30
31		-=== Request-Parameter
	67	+=== Request-Parameter ===
32	32
33	33	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:
34	34
...	...	@@ -57,9 +57,9 @@
57	57	:; plugin-ident=manifest
58	58	:: //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.
59	59	:; plugin-ident=id
60		-:: //plugin-identifier// muss die gewünschte ID des Plugins enthalten, etwa //53// oder /893//.
	96	+:: //plugin-identifier// muss die gewünschte ID des Plugins enthalten, etwa //53// oder /893//.//
61	61	:; plugin-ident=name
62		-:: //plugin-identifier// muss den gewünschten Names des Plugins enthalten, etwa //my-plugin.jar// oder /foobar.jar//.
	98	+:: //plugin-identifier// muss den gewünschten Names des Plugins enthalten, etwa //my-plugin.jar// oder /foobar.jar//.//
63	63	:; plugin-ident=uuid
64	64	:: //plugin-identifier// muss die gewünschte UUID des Plugins enthalten, etwa //03022599-903d-429b-9822-80a324a542fc//.
65	65	Andernfalls wird das Plugin installiert, falls noch nicht vorhanden, oder aktualisiert, falls vorhanden.
...	...	@@ -71,16 +71,17 @@
71	71	: 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
72	72	: 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.
73	73
74		-=== Deploy-Action
	110	+=== Deploy-Action ===
75	75
76	76	Der Wert des Parameters //deploy-action// gibt an, was genau mit dem Plugin geschehen soll. Es gibt dabei die folgenden Möglichkeiten:
77	77
78	78	; save
79	79	: Ü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.
	116	+
80	80	(((
81	81	{{code language="bash"}}
	119	+# Installiert oder aktualisiert das Plugin mit dem Implementation-Title com.example:plugin
82	82	curl -X POST \
83		- # These options are required
84	84	-F deploy-action=save \
85	85	-F token=admin \
86	86	-F plugin-ident=manifest \
...	...	@@ -89,12 +89,14 @@
89	89	"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
90	90	{{/code}}
91	91	)))
	129	+
92	92	; delete
93	93	: Löscht das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
	132	+
94	94	(((
95	95	{{code language="bash"}}
	135	+# Löscht das Plugin mit dem Implementation-Title com.example:plugin
96	96	curl -X POST \
97		- # These options are required
98	98	-F deploy-action=delete \
99	99	-F token=admin \
100	100	-F plugin-ident=manifest \
...	...	@@ -102,12 +102,14 @@
102	102	"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
103	103	{{/code}}
104	104	)))
	144	+
105	105	; activate
106		-: Aktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
	146	+: Aktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Ist das Plugin bereits aktiviert, wird nicht getan und ein Erfolg zurückgegeben. Beispiel:
	147	+
107	107	(((
108	108	{{code language="bash"}}
	150	+# Aktiviert das Plugin mit dem Implementation-Title com.example:plugin
109	109	curl -X POST \
110		- # These options are required
111	111	-F deploy-action=activate \
112	112	-F token=admin \
113	113	-F plugin-ident=manifest \
...	...	@@ -115,12 +115,14 @@
115	115	"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
116	116	{{/code}}
117	117	)))
	159	+
118	118	; deactivate
119		-: Deaktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
	161	+: Deaktiviert das angegebene Plugin. Es darf hierbei keine JAR-Datei übertragen werden. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Ist das Plugin bereits deaktiviert, wird nicht getan und ein Erfolg zurückgegeben. Beispiel:
	162	+
120	120	(((
121	121	{{code language="bash"}}
	165	+# Deaktiviert oder aktualisiert das Plugin mit dem Implementation-Title com.example:plugin
122	122	curl -X POST \
123		- # These options are required
124	124	-F deploy-action=deactivate \
125	125	-F token=admin \
126	126	-F plugin-ident=manifest \
...	...	@@ -128,9 +128,10 @@
128	128	"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
129	129	{{/code}}
130	130	)))
	174	+
131	131	; update-properties
132	132	: 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:
133		- (((
	177	+(((
134	134	{{code language="bash"}}
135	135	# Löscht alle vorhandenen Plugin-Eigenschaften und setzt dann die Eigenschaft "foo" auf den Wert "bar"
136	136	curl -X POST \
...	...	@@ -141,10 +141,193 @@
141	141	-F clear-properties=false \
142	142	-F property=foo=bar \
143	143	"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"
144		-{{/code}})))
	188	+{{/code}}
	189	+)))
145	145
146		-== Response
	191	+== Response ==
147	147
	193	+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.
148	148
	195	+Das JSON-Objekt hat dabei [[die folgende Struktur>>https://json-schema.org/]]:
149	149
	197	+{{code language="json"}}
	198	+{
	199	+ "$schema": "http://json-schema.org/schema",
	200	+ "description": "Represents the response of the deploy plugin servlet.",
	201	+ "required": [
	202	+ "success",
	203	+ "statusCode",
	204	+ "details",
	205	+ "message",
	206	+ "requestParameters"
	207	+ ],
	208	+ "properties": {
	209	+ "success": {
	210	+ "type": "boolean",
	211	+ "title": "Success status",
	212	+ "description": "true if the deploy plugin servlet was executed successfully, or false otherwise"
	213	+ },
	214	+ "statusCode": {
	215	+ "type": "number",
	216	+ "title": "HTTP status code",
	217	+ "description": "The status code of the HTTP request that contains this response."
	218	+ },
	219	+ "details": {
	220	+ "type": "object",
	221	+ "title": "Result details",
	222	+ "description": "Detailed information about the plugin processed by the deploy plugin servlet.",
	223	+ "oneOf": [
	224	+ {
	225	+ "description": "If the deploy plugin servlet was successful, details about the successfully executed action.",
	226	+ "required": [
	227	+ "id",
	228	+ "uuid",
	229	+ "name",
	230	+ "active",
	231	+ "message"
	232	+ ],
	233	+ "properties": {
	234	+ "id": {
	235	+ "type": "number",
	236	+ "title": "Plugin ID",
	237	+ "description": "The database ID of the processed plugin."
	238	+ },
	239	+ "uuid": {
	240	+ "type": "string",
	241	+ "title": "Plugin UUID",
	242	+ "description": "The UUID of the processed plugin."
	243	+ },
	244	+ "name": {
	245	+ "type": "string",
	246	+ "title": "Plugin name",
	247	+ "description": "The name of the processed plugin, i.e. the file name of the plugin JAR file."
	248	+ },
	249	+ "active": {
	250	+ "type": "boolean",
	251	+ "title": "Plugin activation status",
	252	+ "description": "true if the plugin is now active, false if it is now inactive."
	253	+ },
	254	+ "message": {
	255	+ "type": "string",
	256	+ "title": "Result message",
	257	+ "description": "Human-readable message describing the performed action."
	258	+ }
	259	+ }
	260	+ },
	261	+ {
	262	+ "required": [
	263	+ "exceptionType",
	264	+ "exceptionMessage"
	265	+ ],
	266	+ "description": "If the deploy plugin servlet was unsuccessful, details about the error that occurred.",
	267	+ "properties": {
	268	+ "exceptionType": {
	269	+ "type": "string",
	270	+ "title": "Exception type",
	271	+ "description": "The type of the error that occurred, a fully-classified name of the Java exception class."
	272	+ },
	273	+ "exceptionMessage": {
	274	+ "type": "string",
	275	+ "title": "Exception message",
	276	+ "description": "The human-readable message of the error that occurred."
	277	+ }
	278	+ }
	279	+ }
	280	+ ]
	281	+ },
	282	+ "message": {
	283	+ "type": "string",
	284	+ "title": "Result message",
	285	+ "description": "A human-readable message that describes this result."
	286	+ },
	287	+ "requestParameters": {
	288	+ "type": "object",
	289	+ "title": "Request parameters",
	290	+ "description": "The parameters of the request that triggered this response."
	291	+ }
	292	+ }
	293	+}
	294	+{{/code}}
	295	+
	296	+Beispiel für die Antwort beim Aktualisieren eines Plugins:
	297	+
	298	+{{code language="json"}}
	299	+{
	300	+ "success": true,
	301	+ "requestParameters": {
	302	+ "plugin-ident": ["manifest"],
	303	+ "name": ["deploy-plugin"],
	304	+ "client-id": ["1"],
	305	+ "deploy-action": ["save"],
	306	+ "plugin-identifier": ["Implementation-Title=com.example:plugin"],
	307	+ "token": ["admin"]
	308	+ },
	309	+ "details": {
	310	+ "name": "my-plugin.jar",
	311	+ "active": true,
	312	+ "id": 203,
	313	+ "message": "Plugin saved successfully.",
	314	+ "uuid": "2fe3e1ba-cb32-434e-9f59-4422f8dabcad"
	315	+ },
	316	+ "message": "Plugin saved successfully.",
	317	+ "statusCode": 200
	318	+}
	319	+{{/code}}
	320	+
	321	+Beispiel für die Antwort beim Löschen, falls das angegebene Plugin nicht gefunden wurde:
	322	+
	323	+{{code language="json"}}
	324	+{
	325	+ "success": false,
	326	+ "requestParameters": {
	327	+ "plugin-ident": ["manifest"],
	328	+ "name": ["deploy-plugin"],
	329	+ "client-id": ["1"],
	330	+ "deploy-action": ["delete"],
	331	+ "plugin-identifier": ["Implementation-Title=com.example:plugin"],
	332	+ "token": ["admin"]
	333	+ },
	334	+ "details": {
	335	+ "exceptionType": "java.lang.IllegalArgumentException",
	336	+ "exceptionMessage": "Deploy action 'delete' requires an existing pluign, but none was found."
	337	+ },
	338	+ "message": "class java.lang.IllegalArgumentException: Deploy action 'delete' requires an existing pluign, but none was found.",
	339	+ "statusCode": 404
	340	+}
	341	+{{/code}}
	342	+
	343	+
	344	+== Create-Token-Servlet ==
	345	+
	346	+Mit diesem Servlet kann ein Hash für ein bestimmtes Klartextpasswort erzeugt werden, welcher dann in der Plugin-Eigenschaft //token// hinterlegt werden kann. Es muss hierbei ein HTTP-GET-Request verwendet werden (Pfad auf den FORMCYCLE-Servet und die Mandant-ID entsprechend ersetzen):
	347	+
	348	+{{code language="none"}}
	349	+http://localhost:8080/formcycle/plugin?client-id=1&name=create-token&token=<PASSWORT>&method=<METHOD>
	350	+{{/code}}
	351	+
	352	+; token
	353	+: Der Klartext des Passwort, zu dem ein Hash ermittelt werden soll.
	354	+; method
	355	+: Methode zum Berechnen des Hashes. Erlaubte Werte sind //plain//, //sha256//, //sha384// und //sha512//. Optional, Standardwert ist //sha256//.
	356	+
	357	+Als Antwort wird ein JSON zurückgeliefert, welches das gleiche Format wie die Antwort des Deploy-Plugins hat. Beispiel für eine Antwort:
	358	+
	359	+{{code language="json"}}
	360	+{
	361	+ "success": true,
	362	+ "requestParameters": {
	363	+ "name": ["create-token"],
	364	+ "client-id": ["1"],
	365	+ "token": ["admin"]
	366	+ },
	367	+ "details": {
	368	+ "method": "sha256",
	369	+ "token": "sha256:S+32GI3fWXwHHulUMtWmjpQ15EqMvgVYguuO9SKxfNw+ckAGQljP6tKlf1EITnU7"
	370	+ },
	371	+ "message": "Hash token created successfully",
	372	+ "statusCode": 200
	373	+}
	374	+{{/code}}
	375	+
150	150	== Beispiel für Maven ==
	377	+