FORMCYCLE deploy-plugin plugin

1

[[**Plugin download**>>url:https://customer.formcycle.eu/index.php/apps/files/?dir=/FORMCYCLE%20-%20Plugins%20Customer/fc-plugin-deploy-plugin&fileid=12657||target="_blank"]] (requires login)

2

3

This is a plugin for deploying plugin to {{formcycle/}}, hence the name //FORMCYCLE deploy-plugin plugin//.

The deploy plugin lets you upload and install plugins to {{formcycle/}} automatically. Compared with a manual installation via [[the backend menu>>doc:Formcycle.UserInterface.Client.Plugins]], this offers several advantages:

8

9

* Plugin developers can integrate the deployment process into the Maven build process. This allows for faster testing, rapid development and does not necessitate a context switch that might slow down developers.

10

* It allows the installation of {{formcycle/}} tob e automated even further.

11

12

You can install the deploy plugin both as a client as well as a system plugin. If the former, you can only modify plugin of that cilent. It contains a [[servlet action>>doc:Formcycle.PluginDevelopment.Types.IPluginServletAction]] for sending a plugin JAR file via an HTTP POST request. Depending on the other HTTP parameters, the plugin is either installed, updated, or deleted.

13

14

The uploaded plugin may already exist in the system. In this this, you usually want to update plugin - not have it installed twice. This requires a way to identify whether a plugin exists already. The servlet action allows for four different possibilities:

15

16

* (**recommended**) The plugin is identified based on an entry in its manifest. The manifest needs to be located at //META-INF/MANIFEST.MF// in the plugin JAR file, such as the group ID or artifact ID. Make sure you prepare the JAR file properly when building the plugin. This method is slightly harder to setup, but offers the advantage that the identifier always remains the same and does not depend on the file name or some internal ID.

17

* The plugin is identified based on its name, i.e. the file name of the upload JAR file. This is also the name [[as it is shown in the plugin menu>>doc:Formcycle.UserInterface.Client.Plugins]].

18

* The plugin is identified based on its internal database ID. This ID is not shown in the UI currently and should only be used by developers.

19

* The plugin is identified based on its UUID. This ID is not shown in the UI currently and should only be used by developers.

20

21

By default, a servlet action is accessible to everybody. Usually, you do not want anonymous users to modifying the installed plugins. To secure the servlet, you can specify a password in the plugin configuration. You then need to include this password in the HTTP POST request.

22

23

== Plugin configuration ==

24

25

You can optionally set a password for securing the access to the plugin deploy servlet. If you do, you need to include the password in the HTTP POST request to authorize that request.

26

27

Specify the token by entering a value for the plugin property //token//. It must be entered in the following format:

28

29

30

hash_method:hashed_value

31

32

33

The following hash methods are available.

34

35

; plain

36

: Identity function. Lets you enter a plain text password.

; sha256

: SHA-256 algorithm.

; sha384

: SHA-384 algorithm.

; sha512

: SHA-512 algorithm.

To enter the password //admin// as plain text, use:

plain:admin

To enter the password //admin// hashed with SHA-256, use:

51

52

53

sha256:S+32GI3fWXwHHulUMtWmjpQ15EqMvgVYguuO9SKxfNw+ckAGQljP6tKlf1EITnU7

54

55

56

The hash is salted. You can generate a valid hash for a given password via the //create-token// servlet, see below.

== Deploy servlet ==

The following describes the structure of the HTTP request you need to adhere to in order to install, update, or delete a plugin.

61

62

The HTTP method must be POST, other methods will result in an error. The [[endpoint URL is as follows>>doc:Formcycle.PluginDevelopment.Types.IPluginServletAction]] (change the name of the FORMCYCLE server and the client ID):

63

64

65

POST http://localhost:8080/formcycle/plugin?name=deploy-plugin&client-id=154 HTTP/1.1

66

67

68

The //client-id// is not required in case the plugin is installed as a system plugin.

69

70

=== Request parameter ===

71

72

You can specify the parameters either directly as URL parameters, or as //multipart/form-data// or //application/x-www-form-urlencoded//. The following parameters are available and supported by the plugin deploy servlet:

73

74

; deploy-action

75

: Action to be performed on the plugin. Allowed values are //save//, //update-properties//, //activate//, //deactivate// and //delete//. See below for a description of each method.

76

; client-id

77

: ID of the client where the plugin is installed, updated, or deleted. You must specify only one of //client-id// or //client-uuid//.

78

; client-uuid

79

: UUID of the client where the plugin is installed, updated, or deleted. You must specify only one of //client-id// or //client-uuid//. Please note that a plugin installed as a client plugin always required the parameter //client-id//.

80

; jar-file

81

: Binary data of the JAR file with the plugin (required only when installing or updating the plugin).

82

; token

83

: The token (password) for authorizing the request. Required only when the a token was set in the plugin configuration.

84

; plugin-ident

85

: The method used for searching an already existing plugin, see above. The following methods are supported:

86

:; manifest

87

:: Identifies a plugin based on an entry in its manifest.

88

:; id

89

:: Identifies a plugin based on its database ID.

90

:; name

91

:: Identifies a plugin based on its name (the file name of the plugin JAR file).

92

:; uuid

93

:: Identifies a plugin based on its UUID.

94

; plugin-identifier

95

: Identifier of the plugin that should be installed, updated, or deleted. The exact meaning of this parameter depends on the chosed //plugin-ident// method:

96

:; plugin-ident=manifest

97

:: //plugin-identifier// must contain the name of the manifest property and its value, in the format //Attribute-Name=value//. For example, if this property is set to //Implementation-Title=com.example.fc.plugin:my-plugin//, this will search for a plugin with a manifest entry //Implementation-Title// set to //com.example.fc.plugin:my-plugin//.

98

:; plugin-ident=id

99

:: //plugin-identifier// must contain the data base ID of the target plugin, such as //53// or //893//.

100

:; plugin-ident=name

101

:: //plugin-identifier// must contain the name of the target plugin, such as //my-plugin.jar// or //foobar.jar//.

102

:; plugin-ident=uuid

103

:: //plugin-identifier// must contain the UUID of the target plugin, such as //03022599-903d-429b-9822-80a324a542fc//.

104

; clear-properties

105

: Either //true// or //false//. If set to //true//, all plugin property values are cleared. This is done before the new properties (see parameter //property//) are applied.

106

; property

107

: Name and value of a plugin property to set, in the format //key=value//. This HTTP parameter may be specified multiple times if you want set multiple properties. For example, if set to //database.username=john//, this sets the plugin property //database.username// to //john//.

108

; disallow-install

109

: Either //true// or //false//. When this is set to //true// and the plugin does not exists yet (as determined by the given //plugin-ident// and //plugin-identifier// parameters), the plugin is not installed and an error is returned. Otherwise, when set to //false//, the plugin is installed if it does not exists yet and updated if it does.

110

; locale

111

: The language to be used when the plugin is modified, such as //en// or //de//. May affect some error messages. Usually this parameter is not neccessary.

112

113

=== Deploy actions ===

114

115

The value of the parameter //deploy-action// specifies what should happen with the selected plugin. The following actions are available:

116

117

; save

118

: Transmits the plugin to the {{formcycle/}} server. You need to specify a JAR file. If the plugin does not exists yet (and the parameters //disallow-install// is not set), the plugin is installed and activated. Otherwise, if the plugin exists already, it is only updated and left active or inactive. For example:

(((

# Installs or updates the given plugin.

123

curl -X POST \

124

-F deploy-action=save \

125

-F token=admin \

126

-F plugin-ident=manifest \

127

-F plugin-identifier=Implementation-Title=com.example:plugin \

128

-F "jar-file=@my-plugin.jar" \

129

"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"

)))

; delete

: Deletes the given plugin. You must not specify a JAR file. If the specified plugin does not exist yet, an error is returned. For example:

(((

# Löscht das Plugin mit dem Implementation-Title com.example:plugin

139

curl -X POST \

140

-F deploy-action=delete \

141

-F token=admin \

142

-F plugin-ident=manifest \

143

-F plugin-identifier=Implementation-Title=com.example:plugin \

144

"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"

)))

; activate

: Activates the given plugin. You must not specify a JAR file. If the specified plugin is already active, no action is performed an a success is returned. For example:

(((

# Activates the given plugin

154

curl -X POST \

155

-F deploy-action=activate \

156

-F token=admin \

157

-F plugin-ident=manifest \

158

-F plugin-identifier=Implementation-Title=com.example:plugin \

159

"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"

)))

; deactivate

: Deactivates the given plugin. You must not specify a JAR file. If the specified plugin is already inactive, no action is performed an a success is returned. For example:

(((

# Deactivates the given plugin

169

curl -X POST \

170

-F deploy-action=deactivate \

171

-F token=admin \

172

-F plugin-ident=manifest \

173

-F plugin-identifier=Implementation-Title=com.example:plugin \

174

"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"

)))

; update-properties

: Updates the properties of the given plugin. You must not specify a JAR file. You should specify at least one of //clear-properties// or //property//. If the given plugin does not exist yet, an error is returned. For example:

(((

# Delete all existing plugin properties and set the property //foo// to //bar//

184

curl -X POST \

185

-F deploy-action=update-properties \

186

-F token=admin \

187

-F plugin-ident=manifest \

188

-F plugin-identifier=Implementation-Title=com.example:plugin \

189

-F clear-properties=false \

190

-F property=foo=bar \

191

"http://localhost:8080/formcycle/plugin?client-id=154&name=deploy-plugin"

)))

=== Response ===

The plugin deploy servet returns a status code and a JSON object with the details. The status code is 2xx if (and only if) the deploy servlet was executed successfully.

198

199

The JSON object that is returned adheres to the following [[JSON schema>>https://json-schema.org/]]:

{

"$schema": "http://json-schema.org/schema",

204

"description": "Represents the response of the deploy plugin servlet.",

"required": [

"success",

"statusCode",

"details",

"message",

"requestParameters"

],

"properties": {

"success": {

"type": "boolean",

"title": "Success status",

216

"description": "true if the deploy plugin servlet was executed successfully, or false otherwise"

},

"statusCode": {

"type": "number",

"title": "HTTP status code",

221

"description": "The status code of the HTTP request that contains this response."

},

"details": {

"type": "object",

"title": "Result details",

226

"description": "Detailed information about the plugin processed by the deploy plugin servlet.",

227

"oneOf": [

228

{

229

"description": "If the deploy plugin servlet was successful, details about the successfully executed action.",

"required": [

"id",

"uuid",

"name",

"active",

"message"

],

"properties": {

"id": {

"type": "number",

"title": "Plugin ID",

241

"description": "The database ID of the processed plugin."

},

"uuid": {

"type": "string",

"title": "Plugin UUID",

246

"description": "The UUID of the processed plugin."

},

"name": {

"type": "string",

"title": "Plugin name",

251

"description": "The name of the processed plugin, i.e. the file name of the plugin JAR file."

},

"active": {

"type": "boolean",

"title": "Plugin activation status",

256

"description": "true if the plugin is now active, false if it is now inactive."

},

"message": {

"type": "string",

"title": "Result message",

261

"description": "Human-readable message describing the performed action."

}

}

},

{

"required": [

"exceptionType",

"exceptionMessage"

],

"description": "If the deploy plugin servlet was unsuccessful, details about the error that occurred.",

"properties": {

"exceptionType": {

"type": "string",

"title": "Exception type",

275

"description": "The type of the error that occurred, a fully-classified name of the Java exception class."

276

},

277

"exceptionMessage": {

278

"type": "string",

279

"title": "Exception message",

280

"description": "The human-readable message of the error that occurred."

}

}

}

]

},

"message": {

"type": "string",

"title": "Result message",

289

"description": "A human-readable message that describes this result."

290

},

291

"requestParameters": {

292

"type": "object",

293

"title": "Request parameters",

294

"description": "The parameters of the request that triggered this response."

}

}

}

Example for a response when a plugin was updated successfully:

{

"success": true,

"requestParameters": {

306

"plugin-ident": ["manifest"],

307

"name": ["deploy-plugin"],

308

"client-id": ["1"],

309

"deploy-action": ["save"],

310

"plugin-identifier": ["Implementation-Title=com.example:plugin"],

"token": ["admin"]

},

"details": {

"name": "my-plugin.jar",

315

"active": true,

316

"id": 203,

317

"message": "Plugin saved successfully.",

318

"uuid": "2fe3e1ba-cb32-434e-9f59-4422f8dabcad"

319

},

320

"message": "Plugin saved successfully.",

"statusCode": 200

}

Example for a response when a plugin could not be deleted:

{

"success": false,

"requestParameters": {

331

"plugin-ident": ["manifest"],

332

"name": ["deploy-plugin"],

333

"client-id": ["1"],

334

"deploy-action": ["delete"],

335

"plugin-identifier": ["Implementation-Title=com.example:plugin"],

"token": ["admin"]

},

"details": {

"exceptionType": "java.lang.IllegalArgumentException",

340

"exceptionMessage": "Deploy action 'delete' requires an existing pluign, but none was found."

341

},

342

"message": "class java.lang.IllegalArgumentException: Deploy action 'delete' requires an existing pluign, but none was found.",

"statusCode": 404

}

== Create token servlet ==

349

350

This servlet lets you create a hash for a password that you can enter in the plugin property //token//. Make an HTTP GET request to the following URL (change to path to the {{formcycle/}} server and the client ID):

351

352

353

http://localhost:8080/formcycle/plugin?client-id=1&name=create-token&token=<PASSWORD>&method=<METHOD>

; token

: The password to hash.

358

; method

359

: Hash method, default to //sha256//. Supported values are //plain//, //sha256//, //sha384// and //sha512//.

360

361

This returns a JSON object with the same schema as returned by the plugin deploy servlet. For example:

{

"success": true,

"requestParameters": {

367

"name": ["create-token"],

"client-id": ["1"],

"token": ["admin"]

},

"details": {

"method": "sha256",

"token": "sha256:S+32GI3fWXwHHulUMtWmjpQ15EqMvgVYguuO9SKxfNw+ckAGQljP6tKlf1EITnU7"

374

},

375

"message": "Hash token created successfully",

"statusCode": 200

}

== Maven deploy plugin ==

381

382

To upload a plugin to {{formcycle/}} after building a plugin project via Maven, you can use the maven deploy plugin. It is available from the XIMA artifactory (please note you may need the correct permissions to access this artifact).

=== Confguration ===

<groupId>de.xima.fc.maven.plugin</groupId>

389

<artifactId>fc-deploy-plugin-maven-plugin</artifactId>

390

391

392

<url>http://localhost:8080/formcycle</url>

393

<pluginName>deploy-plugin</pluginName>

<token>admin</token>

<pluginIdentifier>my-plugin.jar</pluginIdentifier>

399

400

<disallowInstall>false</disallowInstall>

<property1>value1</property1>

405

<property2>value2</property2>

</configuration>

</plugin>

The plugin offers the following configurable settings:

412

413

; url [Default value: //${fcDeployUrl}//]

414

: URL to the {{formcycle/}} server, including the context path, such as //{{{http://localhost:8080/formcycle}}}//

415

; pluginName [Default value: //deploy-plugin//]

416

: Name of the deploy plugin, the value for the parameter //name//. Usually you do not need to change this.

417

; clientId [Default value: //${fcDeployClientId}//]

418

: ID of the client with the plugin to be installed, updated, or deleted. Corresponds to the parameter //client-id// of the plugin deploy servlet, see above.

419

; clientUuid

420

: Alternative for //clientUUID//. The UUID of the client with the plugin to be installed, updated, or deleted.Corresponds to the parameter //client-uuid// of the plugin deploy servlet, see above.

421

; token [Standardwert: //${fcDeployToken}//]

422

: Password for the plugin deploy servlet, if one was set in the plugin configuration.

423

; deployAction [Default value: //save//]

424

: Method to be executed. Allowed values are //save//, //update-properties//, //activate//, //deactivate// and //delete//. Corresponds to the parameter //deploy-action// of the plugin deploy servlet, see above.

425

; pluginIdent [Default value: //manifest//]

426

: The method for identifying existing plugins. Corresponds to the parameter //plugin-ident// of the plugin deploy servlet, see above.

427

; pluginIdentifier [Default value: //Implementation-Title=${project.groupId}:${project.artifactId}//]

428

: Identifier of the plugin to be installed, updated, or deleted. Corresponds to the parameter //plugin-identifier// of the plugin deploy servlet, see above.

429

; jarFile [Default value: Haupt-Build-Artifakt des Maven-Projekts]

430

: Path to the JAR file to be uploaded, relative to the base directory of the maven project.

431

; disallowInstall [Default value: //false//]

432

: When set to //true// and the plugin does not exists yet, the plugin is not installed and an error is returned. Corresponds to the parameter //disallow-install// of the plugin deploy servlet, see above.

433

; locale [Standardwert: //en//]

434

: Language for the installations. Corresponds to the parameter //locale// of the plugin deploy servlet, see above.

435

; clearProperties [Default value: //false//]

436

: Clears all properties of the plugin. Corresponds to the parameter //clear-properties// of the plugin deploy servlet, see above.

437

; properties

438

: Key value pair with the properties to be set on the plugin. Corresponds to the parameter //property// of the plugin deploy servlet, see above.

439

440

=== Recommendations for your plugin project ===

441

442

While the Maven plugin offers a wide variety of options, the default settings are usually sufficient. We recommend the following steps for your plugin:

443

444

Add this code snippet to the profile section of the //pom.xml//:

<fc-deploy-plugin-maven-plugin.version>1.1.0</fc-deploy-plugin-maven-plugin.version>

</properties>

<build>

<groupId>de.xima.fc.maven.plugin</groupId>

455

<artifactId>fc-deploy-plugin-maven-plugin</artifactId>

456

<version>${fc-deploy-plugin-maven-plugin.version}</version>

</plugin>

</plugins>

</build>

The plugin is identified based on the entry //Implementation-Title// in its //Manifest.MF// file. For this to work, you need to prepare the manifest correctly. You can do so either with the //maven-jar-plugin// or with the //maven-assembly-plugin//, depending on which plugin your project uses.

<xfc.version>6.4.0-SNAPSHOT</xfc.version>

467

<maven-jar-plugin.version>3.2.0</maven-jar-plugin.version>

468

<maven-assembly-plugin.version>3.2.0</maven-assembly-plugin.version>

</properties>

<build>

475

476

<groupId>org.apache.maven.plugins</groupId>

477

<artifactId>maven-jar-plugin</artifactId>

478

<version>${maven-jar-plugin.version}</version>

479

480

<outputDirectory>${basedir}</outputDirectory>

481

<finalName>${project.artifactId}</finalName>

</manifest>

<formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>

488

<Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>

489

<Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>

490

<Implementation-Version>${project.version}</Implementation-Version>

491

<Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>

</manifestEntries>

</archive>

</configuration>

</plugin>

498

499

<groupId>org.apache.maven.plugins</groupId>

500

<artifactId>maven-assembly-plugin</artifactId>

501

<version>${maven-assembly-plugin.version}</version>

<phase>package</phase>

<goals>

<goal>single</goal>

</goals>

<outputDirectory>${basedir}</outputDirectory>

511

<finalName>${project.artifactId}</finalName>

512

513

<descriptorRef>jar-with-dependencies</descriptorRef>

514

</descriptorRefs>

515

<appendAssemblyId>false</appendAssemblyId>

516

517

518

<Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>

519

<Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>

520

<Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>

521

<Implementation-Version>${project.version}</Implementation-Version>

522

<formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>

</manifestEntries>

</archive>

</configuration>

</execution>

</executions>

</plugin>

</plugins>

</build>

Now you can build the plugin via Maven and upload it to a {{formcycle}} server. The URL, the client ID and the token (password) can be passed to Maven via command line parameters:

535

536

537

mvn package fc-deploy:deploy -DfcDeployUrl="http://localhost:8080/xima-formcycle" -DfcDeployClientId="1" -DfcDeployToken="admin"

538

539

540

If you do not pass these parameters, the deploy plugin is not executed and the plugin is not uploaded.

541

542

On a side note: IDE such as Eclipse and IntelliJ let you create a build configuration for your plugin project, where you can enter the parameters //fcDeployUrl//, //fcDeployClientId// and //fcDeployToken//. This way you can upload the plugin simply by running the build configuration.

== Changelog

This is a list of available version of this plugin and which changes took place in which version.

=== 7.0.1 ===

* Minor improvement when handling errors