Plugin development

Modified on Mon, 18 Mar at 11:01 AM

Plugins let you extend formcycle and add new features. Various different plugin type exist, such as plugins for adding custom workflow actions and triggers, or plugins for new form elements.

A plugin must be a JAR file with the appropriate class files. To create a custom plugin, you need to setup a Java project, such as via Maven. All plugins must have a unique ID in their MANIFEST.MF, via the entry Plugin-Key.

Contents

API documentation

The API documentations for formcycle can be found here: Javadocs

Project setup

To get started with developing plugins, you need to create and configure new project.

We recommend the build tool Apache Maven. Other build tools such as Gradle are possible, but you will not find any help for those tools here.

To access the formcycle dependencies, you need to use the Maven repository https://artifactory.xima-services.de/artifactory/fc-plugin-dev. This contains all Maven artifacts required for developing plugins.

To get Maven to recognize that repository, add it tot the Maven configuration file settings.xml. Usually, you can find this settings file in the .m2 folder in your home directory, i.e. ~/.m2/settings.xml for Linux and %homepath%\.m2\settings.xml for Windows:

~/.m2/settings.xml

<?xml version="1.0" encoding="UTF-8"?>

<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0
  http://maven.apache.org/xsd/settings-1.1.0.xsd"
  xmlns="http://maven.apache.org/SETTINGS/1.1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <!-- Add XIMA artifactory -->
  <profiles>
    <profile>
      <!-- formcyle dependencies -->
      <repositories>
        <repository>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
          <id>xima</id>
          <name>fc-plugin-dev</name>
          <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
        </repository>
      </repositories>
      <!-- Maven plugins for formcycle -->
      <pluginRepositories>
        <pluginRepository>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
          <id>xima</id>
          <name>fc-plugin-dev</name>
          <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
        </pluginRepository>
      </pluginRepositories>
      <id>xima-artifactory</id>
    </profile>
  </profiles>

  <!-- Enable XIMA artifactory by default -->
  <activeProfiles>
    <activeProfile>xima-artifactory</activeProfile>
  </activeProfiles>

  <!-- formcycle specific Maven plugins provided by XIMA -->
  <pluginGroups>
    <pluginGroup>de.xima.fc.maven.plugin</pluginGroup>
  </pluginGroups>
</settings>

Maven project setup

The following lists a few important steps required for setting up a Maven project for a formcycle plugin, but we assume you have basic knowledge of how to work with Maven.

To get started with a plugin, you can also use of of the available Maven archetypes.

Artekfakte und Abhängigkeiten

All dependencies to formcycle must be declared with the scope provided.

You can download a complete pom.xml for plugin development here.

The main artifact you need to include is the artifact fc-plugin-common. It contains all Java interfaces available for plugins. Add the following to the pom.xml of the plugin project to include that artifact:

<properties>
  <xfc.version>8.0.0</xfc.version>
</properties>

<dependencyManagement>
  <dependencies>
    <!-- Import all dependency versions from formcycle -->
    <!-- This fixes the version of the dependencies provided by formcycle -->
    <dependency>
      <groupId>de.xima.fc</groupId>
      <artifactId>fc</artifactId>
      <version>${xfc.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>


<dependencies>
  <dependency>
    <groupId>de.xima.fc</groupId>
    <artifactId>fc-plugin-common</artifactId>
    <scope>provided</scope>
  </dependency>
</dependencies>

For more complicated plugins, you can also include fc-logic, which provides more formcycle related classes, such as the database access objects when you need to access the database. If you want to use it, replace dependency to fc-plugin-common with:

<dependency>
  <groupId>de.xima.fc</groupId>
  <artifactId>fc-logic</artifactId>
  <scope>provided</scope>
</dependency>

Note that all dependencies must be declared with the provide scope. This prevents class path issues and keeps the plugin size small. When possible, use libraries already provided by formcycle, e.g. certain Apache Common libraries or Guava, by using the provided scope for such dependencies.

<dependency>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-lang3</artifactId>
  <scope>provided</scope>
</dependency>

When you declare the dependency you wish to use without a <version>...</version> tag, you won't get a build error if formcycle already provides that dependency. Otherwise you need to include the dependency in the plugin: Remove the provided scope and add the version.

Manifest und Fat JAR

The META-INF/MANIFEST.MF file in the plugin JAR should contain the following entries:

Plugin-Key: Required. The unique ID of the plugin. Each plugin must have a unique ID. Version 8 of formcycle still supports legacy plugins without an ID, but starting with version 9, an ID will be required.
Plugin-File-Key: Optional. Some plugins consist of multiple JAR files. For such files, you must use the same Plugin-Key and a different Plugin-File-Key for each JAR file.
Plugin-Repository: Required. The remote repository of the plugin. This is used, for example, to check for plugin updates. Use xfc-proma for the official plugin store. For plugins developed by external developers, this should usually be set to none.
formcycle-version-requirement: Required. The version of formcycle against which the plugin was compiled. This is required for formcycle to check the compatibility when the plugin is installed.
Implementation-Version: Required. The version of the plugin, which is for example shown in the UI.
Build-Time or Build-Timestamp: Optional. This is displayed in the UI when the plugin version is a SNAPSHOT.

You can use the maven-assembly-plugin to add these entries to the manifest.

Furthermore, it is required that you create a fat JAR. Dependencies provided by formcycle should be declared with the scope provided, as mentioned above. However, any additional dependencies that your plugin needs must be included in the JAR file.

This can be done via the maven-assembly-plugin or via the maven-shade-plugin. The latter one is meant for advanced use cases, such as when multiple dependencies have conflicting files and you need to merge those.

For many plugins, the maven-assembly-plugin is sufficient. You can configure this plugin in the pom.xml as follows:

pom.xml with the maven-assembly-plugin

<properties>
  <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
</properties>

<build>
  <finalName>${project.artifactId}</finalName>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-assembly-plugin</artifactId>
      <version>${maven-assembly-plugin.version}</version>
      <executions>
        <execution>
          <id>fat-jar</id>
          <phase>package</phase>
          <goals>
            <goal>single</goal>
          </goals>
          <configuration>
            <appendAssemblyId>false</appendAssemblyId>
            <descriptorRefs>
              <descriptorRef>jar-with-dependencies</descriptorRef>
            </descriptorRefs>
            <archive>
              <manifest>
                <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
              </manifest>
              <manifestEntries>
                <Plugin-Key>YOUR_PLUGIN_ID</Plugin-Key>
                <Plugin-Repository>none</Plugin-Repository>
                <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
                <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
                <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
                <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
                <Implementation-Version>${project.version}</Implementation-Version>
              </manifestEntries>
            </archive>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Build and install

In general, the command to build the plugin depends on the settings in the pom.xml. In most cases, however, the following standard command should be sufficient unless you have made special adjustments to the build pipeline:

mvn clean verify

This creates a JAR file in the target folder. You can then upload this plugin to a running formcycle server, either as a client plugin or as a system plugin.

See the deploy plugin to upload the plugin to a running formcycle server during the Maven build process.

See the FC server plugin for starting a simple formcycle server.

Maven archetypes

Adding an archetype catalog in Eclipse

Selecting an archetype in Eclispe when creating a new Maven project

For some common plugin types, we provide Maven archetypes to help you get started.

If you added the XIMA artifactory to the ~/.m2/settings.xml as described above, you can create a new plugin project from an archetype via the following CLI command:

mvn archetype:generate \
  -DarchetypeArtifactId=plugin-archetype-workflow-element-simple \
  -DarchetypeGroupId=de.xima.fc.archetype \
  -DarchetypeVersion=DESIRED_VERSION

This prompts for a few required details such as the desired Maven coordinates of the new project, then creates a new folder in the current working directory with a preconfigured Maven project.

See the archetype catalog for a list of available archetypes.

https://artifactory.xima-services.de/artifactory/fc-plugin-dev/archetype-catalog.xml

Deploy plugin

When developing a plugin, you often need to build a new snapshot version and upload it to a running formcycle server. To ease that process, the deploy plugin can be used to upload the plugin automatically as part of the Maven build process. It consists of two parts:

A Maven plugin, which is run at the end of the build process and sends the plugin JAR file to a running formcycle server via HTTP.
A formcycle plugin, which provides the endpoint that takes the plugin from the HTTP requests and installs it to formcycle.

For more details, see help page of the deploy plugin. For most cases, you do not need any configuration in your pom, but we recommend you at least pin the version to a specific release:

<properties>
   <fc-deploy-plugin-maven-plugin.version>8.0.0<fc-deploy-plugin-maven-plugin.version/>
</properties>

<build>
  <plugins>
    <plugin>
      <groupId>de.xima.fc.maven.plugin</groupId>
      <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
      <version>${fc-deploy-plugin-maven-plugin.version}</version>
    </plugin>
  </plugins>
</build>

Assuming the deploy plugin is installed as a system plugin of a formcycle server, you can build and upload your plugin project as follows:

mvn fc-deploy:deploy

If you run this command on a multi module Maven project, the plugin goal is skipped for sub modules that are not formcycle plugins. Also, the above command assumes that formcycle is running on the standard URL http://localhost:8080/xima-formcycle and that the deploy plugin uses the default password "admin". If that is not the case, you can also change these values:

mvn fc-deploy:deploy \
  -DfcDeployUrl=http://localhost:8080/xima-formcycle \
  -DfcDeployToken=admin

If you want to upload the plugin in a client scope, add the parameter -DfcDeployClientId=3 with the ID of the client.

Note: As there is no standardized way to identify a formcycle plugin Maven module, a fuzzy check algorithm is used. Currently, it uses the following criteria, which are subject to change:

The Maven module must at least have a (possibly transitive) dependency on de.xima.fc:fc-plugin-common in the provided scope.
The Maven module must be packaged as a fat JAR, i.e. the plugin must define a plugin execution either for the single goal of the maven-assembly-plugin, or for the shade goal of the maven-shade-plugin.

If these criteria do not apply to you, consider using the following configuration parameters:

<skip>true</skip>, to force the plugin to skip its execution.
<skipNonPluginProject>false</skipNonPluginProject>, to skip the above mentioned check and always execute the plugin.

FC server plugin

To test a plugin, you will need a running formcycle server. The fc-server-maven-plugin can be used to start a fully configured formcycle server with just a single command. It also comes with the deploy plugin preinstalled.

Usage

If you added the pluginGroup to the ~/.m2/settings.xml as described above, you can start a formcycle server with the following CLI command:

# Within a Maven project that pins the version of the plugin and formcycle
mvn fc-server:run-ms-war

# Standalone, outside a Maven project folder, you must specify versions
mvn de.xima.fc.maven.plugin:fc-server-maven-plugin:8.0.0:ms \
  -DxfcVersion=8.0.2

We recommend you use Java 17 or later LTS releases, but Java 11 is also supported by version 8 of formcycle.

The major and minor version of the Maven plugin should always be equal to the major and minor version of the formcycle application you are running. For example, to start formcycle 8.0.x, you should the Maven plugin version 8.0.x. To start formcycle 8.1.x, you should use the Maven plugin version 8.1.x etc.

After a short amount of time (may take longer when you start it for the first time), you have a local formcycle server running.

The URL is printed in the command line, and should be http://localhost:8080/xima-formcycle by default. The super user login is sadmin (password: admin), the client admin access is admin (password /admin_).

When you run the command in the root folder of a Maven project, the plugin project is packaged, uploaded to the server and installed. Also, the FC server Maven plugin tries to read the formcycle version from the plugin.

This command works even in a directory without a Maven project. You then need to use the goal ms instead of run-ms-war. When no formcycle version is given, a default one is used.

For advanced usage, see the attached README.md.

Troubleshooting

Some common issues that were reported to us in relation to the server plugin:

Message "Driver XY claims to not accept jdbcUrl" appears in the log

The database driver is unable to access the database as indicated by the JDBC URL. This usually happens when the driver type and the database type do not match (e.g. a MySQL driver with a postgreSQL database); or when the driver and database versions are incompatible.

By default, the server plugin includes an H2 driver and uses a file-based H2 database. This issue might occurr when you have configured a different database.

Check the database configuration in the pom.xml of the plugin, see the section "Use a different database" of the README.md. In particular, you need to make sure you included the proper database driver for the configured database.

Also check the "database.properties" file, located in the app directory. If the app directory was not changed via the "<appDir>" property in the pom.xml, you can find this file in the following location:

target/fc-server-maven-plugin/apps/<VERSION>/config/database.properties

Message "Error while decrypting property" appears in the log

This is most likely not an error, but only a harmless warning.

The properties files in the configuration directory (default: target/fc-server-maven-plugin/apps/<VERSION>/config/*.properties) may contain values both in encrypted and unencrypted form. When reading a value, formcycle always tries to decrypt the value with the current password. If that fails, a message is logged and the value is used as-is.

As the plugin is intended for development, properties files are created without any encryption. In this case, these harmless messages may appear in the log.

Database issues when updating from version 7 to version 8

Starting with version 8, formcycle uses version 2 of the H2 database system. H2 does not support a simple upgrade. See the H2 webpage for some notes regarding the migration from version 1 to 2.

Note however, that the plugin is intended only for development purposes. As such, you will often not have important data and it is much easier to just delete the app directory (default "target", see the section "Change app persistence directory" from the README.md) and restart the server.

If you have any important forms, you can export the forms beforehand and import them again afterwards.

Attachments (2)

xml

pom.xml
5.82 KB

README.md
18.9 KB