Plugin development

Content [ Hide ]

API documentation
Project setup
Maven project setup
Maven-Archetypes
Deploy-Plugin
FC-Server-Plugin

Plugins let you extend Xima® Formcycle and add new features. Various different plugin type exist, such as plugins for adding custom workflow actions ands 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.

API documentation

The API documentations for Xima® 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 Xima® 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">


<profiles>
   <profile>
     
     <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>
     
     <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>


<activeProfiles>
   <activeProfile>xima-artifactory</activeProfile>
</activeProfiles>


<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 Xima® 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 Xima® 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>7.0.10</xfc.version>
</properties>

<dependencies>
   <dependency>
    <groupId>de.xima.fc</groupId>
    <artifactId>fc-plugin-common</artifactId>
    <version>${xfc.version}</version>
    <scope>provided</scope>
   </dependency>
</dependencies>

For more complicated plugins, you can also include fc-logic, which provides more Xima® 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>
  <version>${xfc.version}</version>
  <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 used by Xima® Formcycle, e.g. certain Apache Common libraries or guava.

Manifest und Fat JAR

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

formcycle-version-requirement: Required. The version of Xima® Formcycle against which the plugin was compiled. This is required for Xima® 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 oder Build-Timestamp: Optional. This is displayed in the UI when the plugin version is a SNAPSHOT.
Implementation-Title: Optional. This is used e.g. by the deploy plugin to identify the plugin.

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 Xima® 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:

maven-assembly-plugin in pom.xml

<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>
             <finalName>${project.artifactId}</finalName>
             <appendAssemblyId>false</appendAssemblyId>
             <descriptorRefs>
               <descriptorRef>jar-with-dependencies</descriptorRef>
             </descriptorRefs>
             <archive>
               <manifest>
                 <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
               </manifest>
               <manifestEntries>
                 <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 enough:

mvn clean install

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

See the deploy plugin to upload the plugin to a running Xima® Formcycle server during the Maven build process.

See the FC server plugin for starting a simple Xima® Formcycle server.

Maven-Archetypes

Hinzufügen des Archetypes-Katalogs in Eclipse

Auswahl eines Archetypes beim Erstellen eines Maven-Projekts in Eclipse

Für einige häufig verwendete Plugin-Typen stehen Maven-Archetypes bereits, um schnell ein Maven-Projekt aufsetzen zu können.

Voraussetzung für die Verwendung ist, dass in den ~/.m2/settings.xml wie oben beschrieben das XIMA-Artifactory eingerichtet wurde. Dann kann etwa über die Kommandozeile wie folgt eine Archetype generiert werden:

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

Es werden dann einige wenige Informationen wie die gewünschten Maven-Koordinaten des neuen Plugin-Projekts abgefragt und anschließend ein neues vorkonfiguriertes Projekt erstellt.

Alle vorhandenen Archetypes und deren Versionen können im Archetype-Katalog eingesehen werden.

In Eclipse kann der Archetype-Katalog in den Einstellungen hinzugefügt werden. Bei der Erstellung eines neuen Maven-Projekt werden dann alle verfügbaren Archetypes angezeigt:

https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml

Deploy-Plugin

Um beim Entwickeln nicht jedes Mal eine neue Plugin-Version manuell über die Oberfläche hochladen zu müssen, kann das Deploy-Plugin verwendet werden. Dieses besteht aus 2 Teilen:

Ein Maven-Plugin, welches nach dem Bauen das Plugin via HTTP an einen laufenden Xima® Formcycle-Server sendet
Ein Plugin für Xima® Formcycle, welche die Gegenstelle in Xima® Formcycle bereitstellt und das Plugin aus dem HTTP-Request in Xima® Formcycle installiert.

Weitere Details können im Hilfe-Artikel zum Deploy-Plugin nachgelesen werden. Für die meisten Fälle reicht folgende Konfiguration in der pom.xml des Plugin-Projekts aus:

  <properties>
   <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version/>
<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>
       <executions>
         <execution>
           <id>upload</id>
           <phase>install</phase>
           <goals>
             <goal>deploy</goal>
           </goals>
         </execution>
       </executions>
     </plugin>
   </plugins>
</build>

Sofern das Deploy-Plugin bereits in Xima® Formcycle installiert ist, kann das Plugin-Projekt dann beim Bauen wie folgt hochgeladen werden:

mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin

Wird Eclipse benutzt, kann auch eine Launch-Configuration mit den fcDeployUrl und dem fcDeployToken angelegt werden.

FC-Server-Plugin

Zum Testen eines Plugins ist es erforderlich, einen laufenden Xima® Formcycle-Server zu haben. Zur Vereinfachung der Entwicklung gibt es das fc-server-maven-plugin, welches mittels eines einzigen Befehls ein fertig eingerichtetes Xima® Formcycle lokal startet, wo auch bereits das Deploy-Plugin vorinstalliert ist.

Sofern wie oben beschrieben in ~/.m2/settings.xml die pluginGroup hinterlegt wurde, kann in einem beliebiegen Verzeichnis wie folgt ein Xima® Formcycle-Server per Maven gestartet werden:

mvn fc-server:run-ms-war -DxfcVersion=7.0.10

Nach kurzer Wartezeit (beim ersten Mal kann es länger dauern) ist dann ein Xima® Formcycle-Server gestartet. Die URL steht am Ende in der Kommandozeile, standardmäßig http://localhost:8080/xima-formcycle

Dies funktioniert auch in einem Ordner ohne Maven-Projekt. Falls keine Xima® Formcycle angegeben ist, wird eine Standard-Version genommen. Wird der Befehl innerhalb eines Plugin-Maven-Projekts ausgeführt, wird versucht, die Version von Xima® Formcycle aus dem Plugin-Projekt auszulesen.