Bitte erstellen Sie vor dem Update ein Backup der Datenbank. Erstellen Sie auch einen Snapshot des Servers, auf dem Formcycle/Tomcat installiert ist.

Falls Sie das Print-Service-Plugin verwenden, muss dieses vor dem Update auf die Version 4.4.4 oder höher aktualisiert werden. Diese finden Sie wie gewohnt in der Customer Cloud.

Für das Update sind keine besonderen Vorbereitungen erforderlich. Sie können genau wie bei einem normalen Update vorgehen. Prüfen Sie jedoch vor dem Update, ob die Systemvoraussetzungen für V8 von Ihrer Systemumgebung noch erfüllt werden.

Der Download der aktuellen Version ist über die Release notes möglich.

Alternativ zur nachfolgenden Anleitung, werden die notwendigen Schritte auch In diesem Video gezeigt.

Update

• Die aktuelle formclyce Version kann unter den Release notes heruntergeladen werden. Auf der jeweiligen Versions-Seite sind die Links im Kopfbereich zu finden.
• Melden Sie sich auf dem Server an, auf dem Tomcat installiert ist. Löschen Sie im Verzeichnis "webapps" die Datei "formcycle.war" und warten Sie, bis das Verzeichnis "formcycle" gelöscht ist.
• Kopieren Sie die neue Datei "formcycle.war" in das "webapps" Verzeichnis des Tomcats. Das Update startet nun automatisch und dauert ca. zwischen 2 und 20 Minuten. Der Zeitraum ist u.a. abhängig von der Anzahl der Formulare, Vorgänge ...
• Wenn Sie im Bereich "Systemeinstellungen -> Datenbank" die Option "Ausstehende Datenbankupdates beim Systemstart automatisch anwenden" aktiviert haben, steht das System nach dem Update sofort zur Verfügung. Wurde die Option nicht gewählt, muss nach dem Anmelden als "sadmin" noch das entsprechende Datenbankupdate durchgeführt werden. Erst danach steht die V8 vollständig zur Verfügung!
  
• Nach dem Update melden Sie sich bitte als "sadmin" an, wechseln in "Systemeinstellungen -> Lizenz" und Aktualisieren den Versions-Status.
  
• Wechseln Sie nun in den Bereich "Systemeinstellungen -> Plugins" und aktualisieren Sie die Plugins über das Icon "Auf Updates prüfen". Nach erfolgreicher Prüfung können die Plugins aktualisiert werden. Bitte aktualisieren Sie die Plugins einzeln, da es beim ersten initialen Update länger dauert.
  
• Das Updates ist damit abgeschlossen.

Eine der größten Änderungen von V7 auf V8 ist das Benutzermanagement. In den folgenden Artikeln wird näher darauf eingegangen.

Inhalt

Wie melden sich Benutzer an?

Auf der Login-Seite gibt es keine Mandantauswahl mehr. Für die Systemanmeldung, also die Anmeldung mit dem für formcycle vergebenen Passwort, kann mit Version 8 folgende Kennung verwendet werden:

• Die E-Mailadresse des Benutzers
• Der Benutzername des Benutzers

Eine Anmeldung der Form username@mandantname ist nicht mehr möglich. Dies gilt auch für LDAP-Benutzer.

Durch das Update wurden Benutzer mit der gleichen E-Mailadresse aus verschiedenen Mandanten zusammengelegt. Alle Benutzer des Systems sind für Systemadminstratoren in den Systemeinstellungen verwaltbar. Diese Benutzer können Teil von (mehreren) Mandanten sein. Für mehr Informationen zur neuen Benutzerverwaltung siehe hier.

Zurückgesetztes Passwort

Hat sich ein Benutzer vor dem Update in mehreren Mandanten befunden, also es existierte ein Benutzer mit der gleichen E-Mailadresse in mehreren Mandanten, dann wird dessen Passwort durch das Update zurückgesetzt. Dieser Benutzer wird dann beim erstmaligen Login in die formcycle Verwaltungsoberfläche, dazu aufgefordert ein neues Passwort zu vergeben. Dabei wird dem Benutzer ein Link zur Vergabe eines neuen Passworts an dessen E-Mail gesendet.

Für Systemadministratoren sind Benutzer, deren Passwort zurückgesetzt wurde, in der Übersicht aller Benutzer dadurch erkenntlich, dass diese durch den Hinweis "Kann sich nicht anmelden" gekennzeichnet sind. Systemadminstratoren können diesen Benutzern auch durch einen Klick auf "Neues Passwort generieren" ein zufälliges Passwort zuordnen. Mehr Informationen zur Adminstration von Benutzer gibt es hier.

Geänderter Benutzername

Der Benutzername von Benutzern kann sich durch das Update geändert haben. Dies geschieht wenn der gleiche Benutername vor dem Update in mehreren Mandanten existiert hatte. Dem Benutzernamen wird in diesem Fall ein zufälliges Suffix angehangt. Der Benutzername kann vom Benutzer jederzeit über Mein Profil geändert und für die Anmeldung mit Passwort verwendet werden.

Es wird empfohlen, dass sich Benutzer nach dem Update mit ihrer E-Mailadresse an formcycle anmelden. Können sich Benutzer nach dem Update nicht mehr mit ihrem Benutzernamen anmelden, liegt dies mglw. an einem geänderten Benutzernamen.

Inaktive Benutzer

Inaktive Benutzer können sich nicht an formcycle anmelden. Ist ein Benutzer nach dem Update als inaktiv markiert, dann war dieser Benutzer vor dem Update in einem seiner Mandanten inaktiv. Systemadminstratoren können inaktive Benutzer über die Übersicht aller Benutzer durch den Hinweis "Inaktiv" identifizieren und diese wieder aktivieren. Aktive Benutzer können sich wieder anmelden und haben Zugriff auf die Mandanten, denensie vor dem Update zugewiesen waren. Welchen Mandanten ein Benutzer zugewiesen ist, können Systemadminstratoren über die Benutzerinformationen in der Übersicht aller Benutzer einsehen (siehe Abbildung).

E-Mailadresse vergessen

Sollten Benutzer sich nach dem Update nicht mehr anmelden können, weil sie ihre für formcycle  verwendete E-Mailadresse vergessen haben sollten oder keinen Zugriff mehr auf diese haben, können Systemadminstratoren diesen Benutzern über die Systemeinstellungen eine neue E-Mailadresse zuweisen.

Profilsprache

Die Profilsprache von Benutzern ergibt sich beim Update aus dem ersten Mandanten, in dem der Nutzer gefunden wurde. Benutzer können die Sprache ihres Profils jederzeit über das Profilmenü oder Mein Profil ändern. Siehe hier.

Verwendung von Mandant LDAP-Verbindungen

Bei Installationen, die mehrere Mandanten mit konfigurierten LDAP-Verbindungen für die Anmeldung an der Verwaltungsoberfläche betreiben, sollte der folgende Abschnitt genau durchgelesen werden.

Sind LDAP-Verbindungen an mehreren Mandanten für die Anmeldung an der Verwaltungsoberfläche konfiguriert, sollten diese vor dem V8-Update unbedingt überprüft werden. Was mit diesen LDAP-Verbindungen sowie den LDAP-Gruppen bei der Aktualisierung auf V8 geschieht, wie und warum die Verbindungen zu überprüfen und ggf. anzupassen sind, soll im folgenden beschrieben werden.

Werden keine Mandanten oder nur ein Mandant mit einer LDAP-Verbindung für die Anmeldung verwendet, kann dieser Abschnitt übersprungen werden.

Was passiert mit den Mandant-LDAP-Verbindungen beim V8-Update?

LDAP-Verbindungen für die Anmeldung werden in Version 8 nicht mehr am Mandanten direkt konfiguriert. LDAP-Verbindungen werden stattdessen als LDAP-Login-Dienste konfiguriert. Das heißt für alle existierenden LDAP-Verbindungen die bis jetzt am Mandanten also für die Anmeldung konfiguriert wurden, werden im Zuge des V8-Updates LDAP-Login-Dienste angelegt. Es werden aber keine Login-Dienste doppelt angelegt. Das bedeutet, dass mehrere identische Mandant-LDAP-Verbindungen zu einem neunen LDAP-Login-Dienst vereint werden.

Was passiert mit den LDAP-Gruppen beim V8-Update?

LDAP-Gruppen exisitieren in Version 8 nicht mehr. Stattdessen werden in der V8 LDAP-Benutzerfilter erstellt. Beim Update auf Version 8 wird für jede LDAP-Gruppe ein neuer äquivalenter LDAP-Benutzerfilter angelegt, welcher den neu erstellten LDAP-Login-Dienst verwendet (siehe vorherigen Abschnitt).

Für identische LDAP-Login-Dienste sorgen

LDAP-Benutzer und LDAP-Gruppen hängen also von der konfigurierten Mandant-LDAP-Verbindung ab. Um eine reibungslosen Login der Benutzer nach dem V8-Update zu gewährleisten ist es nötig, dass identische LDAP-Verbindungen an den Mandanten vor dem V8-Update angeglichen werden. Wie dies genau gemacht wird, wird im folgenende Abschnitt (Was ist zu tun?) beschrieben. Vorher soll aber noch erläutert werden, warum es zu Anmeldeproblemen kommen kann, wenn identische Mandant-LDAP-Verbindungen nicht angegelichen werden:

Beim Login an der Verwaltungsoberfläche stehen nach dem Update alle durch das Update neu erstellen LDAP-Login-Dienste zur Verfügung. Versucht ein Benutzer sich nun anzumelden werden alle LDAP-Login-Dienste nacheinander mit den eingegebenen Anmeldedaten durchprobiert bis ein Benutzer in einem der Login-Dienste gefunden und erfolgreich authentifiziert wurde. Wurden beim V8-Update nun aber mehrere LDAP-Login-Dienste für identische LDAP-Verbindungen erstellt, wird der Nutzer bei der Anmeldung nun aber lediglich über einen der existierenden Login-Dienste authentifiziert. Nämlich über den ersten der neu erstellten Login-Dienste bei dem die Anmeldung erfolgreich durchgeführt werden kann, obwohl der Nutzer sich auch über die anderen identischen Login-Dienste authentifizieren hätte könnne. Der Nutzer hat dann zwar über die neu erstellten LDAP-Benutzerfilter, die diesen Login-Dienst verwenden, Zugriff. Er bekommt aber keinen Zugriff über andere LDAP-Benutzerfilter, die einen der anderen neu erstellten LDAP-Login-Dienst verwenden, auch wenn der Benutzer sich über diesen authentifizieren könnte.

Daher ist es also wichtig, dass identische LDAP-Verbindungen vor dem Update angeglichen werden, sodass diese nach dem Update zu einem neuen LDAP-Login-Dienst zusammengefasst werden.

Ziel: Minimierung der erstellten Login-Dienste durch Angleichung identischer Mandant-LDAP-Verbindung.

Was ist zu tun?

Vor dem Update sollten also identische Mandant-LDAP-Verbindungen angeglichen werden. Identische LDAP-Verbindungen verwenden den gleichen LDAP-Server, aber mglw.

• unterschiedliche Benutzer für die Nutzersuche
• unterschiedliche BaseDN für die Nutzersuche
• unterschiedliche Filter-Abfragen

Verwenden LDAP-Verbindungen für die Benutzersuche also den gleichen LDAP-Server (und Port), sollte nach Möglichkeit die weiteren Angaben angeglichen werden. Wie diese Angaben angeglichen werden können, wird im folgenden beschrieben.

Angleichung Groß-/Kleinschreibung der LDAP-Server-URL

Bei der Angabe des LDAP-Servers ist mglw. auf Groß-/Kleinschreibung zu achten. Unterscheiden sich identische LDAP-Server in Groß-/Kleinschreibung der angegebenen LDAP-Server-URL entstehen beim Update mehrere unterschiedliche LDAP-Login-Dienste, was zu vermeiden ist. Die sich in Groß-/Kleinschreibung unterscheidenden URLs können gewollt sein, da bei URLs laut W3C generell auf Groß-/Kleinschreibung zu achten ist. Mglw. verweisen URLs, die lediglich in Groß-/Kleinschreibung variieren, aber auf den gleichen LDAP-Server. Diese URLs sollten vor dem Update unbedingt angeglichen werden.

Angleichung der Benutzer für die Nutzersuche

Unterscheiden sich identische LDAP-Server im Benutzer für die Nutzersuche, sollte überprüft werden, ob nicht der selbe Nutzer für alle identischen LDAP-Verbindungen verwendet werden kann. Unterscheiden sich identische LDAP-Verbindungen im Benutzer für die Nutzersuche enstehen beim Update mehrere unterschiedliche LDAP-Login-Dienste, was zu vermeiden ist.

Angleichung der BaseDN für die Nutzersuche

Unterscheiden sich identische LDAP-Server in der BaseDN für die Nutzersuche, sollte überprüft werden, ob nicht die selbe BaseDN für alle identischen LDAP-Verbindungen verwendet werden kann. Unterscheiden sich identische LDAP-Verbindungen in der BaseDN für die Nutzersuche enstehen beim Update mehrere unterschiedliche LDAP-Login-Dienste, was zu vermeiden ist.

Angleichung der Filter-Abfragen

Unterscheiden sich identische LDAP-Server in der Filter-Abfrage, sollte die Filter-Abfrage aus den LDAP-Verbindungen entfernt werden und stattdessen in den LDAP-Gruppen des Mandanten, die die Mandant-Verbindung benutzen, verwendet werden. Unterscheiden sich identische LDAP-Verbindungen in der Filter-Abfrage enstehen beim Update mehrere unterschiedliche LDAP-Login-Dienste, was zu vermeiden ist.

Migrationsvorbereitung versäumt

Wurde diese Migrationsvorbereitung versäumt und Benutzer können sich nach dem Update nicht mehr richtig anmelden, dann sollte die Darstellung der Login-Dienste mit Eingabemaske auf "Eingabemasken in Tabs aufgeteilt" gestellt werden, siehe Login-Seite. Dadurch werden die neu erstellten LDAP-Login-Dienste der einzelnen Mandanten als Tabs auf der Login-Seite der Verwaltungsoberfläche dargestellt. Dies entspricht dann gewissermaßen einer Mandantauswahl, da die LDAP-Login-Dienste aus den LDAP-Verbindungen an den Mandanten entstanden sind.

Außerdem sollte versucht werden die Anzahl der LDAP-Login-Dienste, wie oben beschrieben, zu reduzieren. Dazu müssen mglw. die LDAP-Login-Dienste mit den einzelnen Benutzern neu verknüpft werden. Abhängig von der Anzahl der LDAP-Benutzer kann dieses einen großen administrativen Mehraufwand nach dem Update bedeuten.

Um möglichen administrativen Mehraufwand nach dem Update zu vermeiden sollte vor dem Update auf Version 8 darauf geachtet werden, dass die LDAP-Verbindungen der Mandanten wie oben beschrieben überprüft und mglw. angeglichen werden.

Kerberos

Die Konfiguration von Kerberos ist nun unter Login-Dienste in den Systemeinstellungen zu finden. Außerdem kann die globale Konfiguration der LDAP-Benutzersuche von Kerberos innerhalb der Mandanten nun überschrieben werden. Wird ein Mandant-Kerberos-Login-Dienst in Formularen verwendet, so wird die global Authentifizierungskonfiguration von Kerberos mit der im Mandant-Kerberos-Login-Dienst konfigurierten LDAP-Benutzersuche verwendet. für mehr Informationen siehe Kerberos.

Die Kerberos-Option "Benutze Mandant-LDAP-Server (falls konfiguriert)" existiert nicht mehr. War diese Option vor dem Update aktiviert, wurde für jeden Mandanten, welcher einen Mandant-LDAP-Server konfiguriert hatte, ein Mandant-Kerberos-Login-Dienst mit der konfigurierten LDAP-Verbindung erstellt.

NTLM

NTLM kann mit Version 8 nicht mehr konfiguriert werden. NTLM kann weiterhin über die Konfigurationsdatei ldapauth.properties konfiguriert werden. Davon ist aber dringlich abzuraten, da Microsoft NTLM nicht mehr unterstützt.

LDAP-Gruppen

Der Menüpunkt "LDAP-Gruppen" existiert nicht mehr. Der Menüpunkt Benutzer vereinigt nun die ehemaligen Menüpunkte "LDAP-Gruppen" und "Benutzer". Für alle konfigurierten LDAP-Gruppen wrid durch das Update ein Benutzerfilter vom Typ LDAP erstellt. Für mehr Informationen zu Benutzerfiltern siehe hier.

MySQL 5

MySQL 5 wird in keiner Version mehr unterstützt. Sollte MySQL 5 noch verwendet werden, ist die Datenbank vor dem formycle Update zuerst zu aktualisieren.

Plugin-Entwicklung

Prinzipiell funktionieren Plugins noch mit Version 8, auch wenn diese gegen Version 7 kompiliert wurden. Einige Wartungsarbeiten sollten aber durchgeführt werden, um sicherzustellen, dass Plugins auch in künftigen Versionen funktionieren. Abhängig von der Art des Plugins können zudem weitere Anpassungen erforderlich sein.

Desweiteren empfehlen wir immer, Plugins gegen die Version von formcycle zu kompilieren, in der das Plugin installiert ist. Zum Einen lässt sich so prüfen, ob Kompilierfehler auftreten, die behoben werden müssen. Zum Zweiten, auch wenn API-Kompatibilität (Quellcode-Kompatibilität) besteht, ist es in Java möglich, dass keine Byte-Code-Kompatibilität besteht. Zum Dritten kann dabei auch auch Deprecated-Warnungen geschaut werden und der Plugin-Code entsprechend angepasst werden.

Einpflegen einer eindeutigen ID

Jedes Plugin muss ab Version 8 von formcycle eine eindeutige ID besitzen, welche im MANIFEST.MF der Plugin-JAR im Eintrag Plugin-Key stehen muss. In Version 8.0 werden Plugins ohne eine solche ID noch erkannt und nur als Legacy-Plugin im Plugin-Menü gekennzeichnet. In einer künftigen Version werden solche Plugins nicht mehr unterstützt werden.

Die ID selber kann einen beliebigen Wert haben, solange dieser eindeutig ist. Wir empfehlen entweder die Kombination von <Group-ID>:<Artifact-ID> oder eine zufällig generierte UUID.

Sollte ein Plugin aus mehreren JAR-Dateien bestehen, dann müssen alle JAR-Dateien im MANIFEST.MF den gleichen Wert für Plugin-Key haben und verschiedene Wert im Manifest-Attribut Plugin-File-Key.

Weiterhin sollte jedes Plugin im Eintrag Plugin-Repository in der MANIFEST.MF angeben, ob und mit welchen Remote-Repository es verbunden ist. Aktuell sind hier nur die Werte none und xfc-proma für das offizielle Repository von formcycle möglich. Externe Plugin-Entwickler sollten hier in der Regel den Wert none hinterlegen. Das vermeidet, dass unnötig nach Updates gesucht wird, dies es nicht geben kann. Fehlt der Eintrag Plugin-Repository, wird in Version 8.0 von formcycle noch xfc-proma als Default genommen, dies wird aber in Kürze auf none geändert werden.

Wenn das Maven-Assembly-Plugin zum Erstellen der Fat-JAR verwendet wird, lassen sich die Manifest-Einträge wie folgt setzen:

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

Prüfen der bereitgestellten Abhängigkeiten

Von formcycle werden Abhängigkeiten bereitgestellt, die von Plugins nur genutzt werden und bei Verwendung von Maven im Scope provided deklariert werden. Für Version 8 wurden einige Abhängigkeiten aktualisiert, es ist daher zu prüfen, ob die im Plugin verwendeten Klassen und Methoden noch mit den neuen Abhängigkeiten funktionieren.

Einige bekannte Punkte, die dabei zu beachten sind:

• Pac4J, das Framework zur Authentifzierung und Authorisierung, wurde aktualisiert Plugins, die Authentifikatoren bereitstellen, sollten unbedingt getestet werden.
• Das UI-Framework PrimeFaces wurde auf Version 12 aktualisiert. Plugins, die eigene Oberflächen bereitstellen, sollte geprüft werden. Siehe auch die Migrationsanleitung von PrimeFaces.
• Die CK-Editor-Komponente <pe:ckEditor>wurde aus PrimeFaces Extensions entfernt. formcycle stellt nun die Komponente <xi:htmlEditor> bereit. Die Optionen sind hierbei gleich, sodass ein Ersetzen von <pe:ckEditor> durch <xi:htmlEditor> in den meisten Fällen ausreichend sein sollte. Der Namespace für xi ist
  xmlns:xi="http://www.xima.de/taglib/xfc"
• Die Bibliothek Apache-Commons-Lang wird nicht mehr mit ausgeliefert, sondern nur noch Apache-Commons-Lang3. In den meisten Fällen sollte es ausreichen, Imports von org.apache.commons.lang.* zu ändern auf org.apache.commons.lang3.*
• Die Bilbiothek Apache-Commons-Configuration wurde von Version 1 auf Version 2 installiert. Die API ist nicht kompatibel, zudem haben sich die Package-Pfade geändert. Siehe auch die Release-Notes und die Migrationsanleitung von Apache-Commons-Configuration. Von formcycle wird dabei der Wrapper de.xima.cmn.props.FileBasedPropertiesConfiguration zur Verfügung gestellt, welcher über die gleichen Methoden verfügt wie org.apache.commons.configuration.PropertiesConfiguration aus Version 1. Der Typ der Konstante de.xima.fc.config.XfcConfig.APPLICATION beispielsweise wurde auf die neue Klasse FileBasedPropertiesConfiguration geändert, sodass API-Kompatibilität besteht, also keine Änderungen am Quellcode gemacht werden müssen. Es ist aber ein Neukompilieren des Plugins erforderlich, da der Byte-Code noch auf die falsche Klasse verweist.

Um diese Prüfung zu erleichtern, empfiehlt es sich, die Parent-POM von formcycle zu importieren, sodass beim Kompilieren automatisch gegen die entsprechenden Versionen der Abhängigkeiten geprüft wird, die formcycle bereitstellt:

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

Prüfen auf Kompatibilität mit neuer Benutzerverwaltung

Aufgrund der Umbauten bezüglich der neuen Benutzerverwaltung waren einige tiefgreifende Änderungen notwendig. Plugins, die mit Benutzer oder der Benutzerverwaltung arbeiten, sollten unbedingt geprüft werden. Zudem wurden einige Klassen und Methoden wurden im Zuge der Umstellung als deprecated markiert. Es sollte im Plugin geprüft werden, ob solche Klassen und Methoden verwendet werden und diese entsprechend den JavaDocs angepasst werden.

Die Entität de.xima.fc.entities.Benutzer darf nicht mehr verwendet werden. Die Klasse selber existiert noch, hat aber keinen Effekt mehr. In der Datenbank sind keine Instanzen dieser Entität mehr gespeichert. Anstelle sollte das Interface IUser genutzt werden. Über die Klasse VirtualUser kann auf den anonymen und den System-Benutzer zugegriffen werden. Die neuen Entitäten für die Benutzerverwaltung sind UserIdentity (siehe Menü System -> Benutzer) sowie AClientAuthorization mit den Untertypen DirectClientAuthorization und IndirectClientAuthorization (siehe Menü Mandant -> Benutzer).

Bei Plugin mit eigenen Oberflächen sollten die Beans geprüft werden. Innerhalb der Bean geschieht der Zugriff auf den aktuellen Mandanten nun über private @Inject ViewContextBean viewContext. Der Zugriff auf den aktuellen Benutzer erfolgt über @Inject private SessionUserManager userManager. Die Prüfung auf Berechtigungen funktioniert über die Klasse UserAccess, zum Beispiel:

final var userAccess = new UserAccess(
  APIProvider.LICENSE.getLicenseAccess(viewContext.getClient()
);
userAccess.hasClientAccess(
  userManager.getUser(),
  viewContext.getClient(),
  EAccessProperty.DATA_QUERY
);

Anpassen der Menüeinträge von Portal-Plugins

Über ein Plugin vom Typ de.xima.fc.plugin.interfaces.backend.IPluginMenuEntries ist es möglich, eigene Menüeinträge im Backend hinzuzufügen. Meistens wird solch ein Plugin als Teil eines Portal-Plugins verwendet.

Dieses Plugin gibt eine Menge von Menüeinträgen (de.xima.fc.interfaces.plugin.retval.backend.IPluginMenuEntry) zurück. Ein Großteil der bestehenden Methoden im Interface IPluginMenuEntry sind nun deprecated und sollten nicht mehr implementiert werden. Teilweise funktionieren diese Methoden auch nicht wie beschrieben, zur Wahrung der Kompatibilität verhalten diese sich aber genauso falsch wie in Version 7.

Stattdessen sollte die neue Methode IPluginMenuEntry#getPluginView verwendet werden. Diese erlaubt auch eine wesentlich flexiblere Steuerung des Menüeintrags, wo und wann dieser angezeigt wird.

Im Folgenden noch ein Beispiel, wie ein Menüeintrag etwa aussehen könnte:

  /**
   * @return Your custom menu entry.
   */
  public static IPluginMenuEntry storeConfigEntry() {
    return new IPluginMenuEntry() {
      @Override
      public String getIcon() {
        return "fa-gear";
      }

      @Override
      public EPluginMenuTargetType getTargetType() {
        return EPluginMenuTargetType.PORTAL;
      }

      @Override
      public String getTargetURL() {
        return "protected/formstore/store-config.xhtml";
      }

      @Override
      public String getText(Locale locale) {
        return "My menu entry";
      }

      @Override
      public boolean isOpenNewWindow() {
        return false;
      }

      @SuppressWarnings("serial")
      @Override
      public IPluginView getPluginView() {
        return new IPluginView() {
          @Override
          public IAvailabiltyResolver getStateResolver() {
            return AvailabilityResolverFactory.clientOrSystem( //
                AvailabilityResolverFactory.defaultClientViewResolver(), //
                AvailabilityResolverFactory.defaultSystemViewResolver() //
            );
          }

          @Override
          public IAuthorizer getAuthorizer() {
            return AuthorizerFactory.clientOrSystem( //
                AuthorizerFactory.defaultClientViewAuthorizer(AccessPropertiesFactory.storeConfig()), //
                AuthorizerFactory.defaultSystemViewAuthorizer(AccessPropertiesFactory.storeConfig()));
          }
        };
      }

      @Override
      public String toString() {
        return String.format("MenuEntry[type=%s,url=%s]", getTargetType(), getTargetURL());
      }
    };
  }

Anpassen der Build-Konfiguration für Server- und Deploy-Plugin

Die Maven-Plugins zum Deployen von Plugins (Maven-Koordinaten de.xima.fc.maven.plugin:fc-deploy-plugin-maven-plugin) und zum Start eines formcycle-Server (Maven-Koordinaten de.xima.fc.maven.plugin:-server-maven-plugin) wurde überarbeitet und leicht angepasst.

Deploy-Plugin-Plugin

Der Standardwert für den Konfigurationsparameter pluginIdent ist nun key. Das bedeutet, dass das Plugin wie oben beschrieben im Manifest eine eindeutige ID im Manifest-Eintrag Plugin-Key haben muss. Andernfalls kann das Plugin beim Deployment nicht mehr identifziert werden und wird mehrfach installiert. Falls notwendig, kann das bisherige Verhalten durch Setzen von pluginIdent=manifest und pluginIdentifier=Implementation-Title=${project.groupId}:${project.artifactId} wiederhergestellt werden. Da es nun eine standardisierte Methode zum Identifzieren von Plugin gibt, wurden die Konfigurationsparameter pluginIdent und pluginIdentifier deprecated und werden in einer künftigen Version entfernt werden.

Bisher war es außerdem notwendig, die Phase package oder install vor dem Deployment auszuführen. Zudem musste immer die Deployment-URL und das Deployment-Token angegeben werden. Der Befehl zum Deployen sah etwa wie folgt aus:

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

Die Angabe von package ist nun nicht mehr nötig, dies wird nun automatisch durch das Plugin getan. Für dei Deployment-URL und das Deployment-Token sind nun Default-Werte wie im obigen Befehl hinterlegt. Nur bei Abweichungen müssen diese noch angegeben werden. Damit kann das Deployment einfach wie folgt erfolgen:

mvn fc-deploy:deploy

Zudem wurde die Unterstützung für Multi-Modul-Maven-Projekte verbessert. Wenn das Goal fc-deploy:deploy auf ein Multi-Modul-Projekt ausgeführt wird, dann wird das Deployment für die Module übersprungen, welche kein formcycle-Plugin sind. 

Anmerkung: Da es keinen eindeutigen Identifikator dafür gibt, ob ein Modul eine formcycle-Plugin ist, wird dies anhand einiger heuristischer Kriterien festgemacht (welche sich ändern können): 

• Das Maven-Module muss mindestens eine Abhängigkeit auf de.xima.fc:fc-plugin-common im Scope provided haben.
• Das Maven-Modul muss entweder das maven-assembly-plugin mit dem Goal single oder das maven-shade-plugin mit dem Goal shade verwenden, um eine Fat-Jar zu bauen.

Ist dies nicht gegeben, können die folgende Plugin-Konfigurationsparameter verwendet werden:

• <skip>true</skip>, um zu Erzwingen, dass das Deploy-Plugin nicht ausgeführt wird.
• <skipNonPluginProject>false</skipNonPluginProject> um die heuristische Prüfung auf ein formcycle-Plugin zu deaktivieren.

formcycle-Server-Plugin

Die Demo-Lizenz sollte nun beim Start automatisch aktualisiert werden, sodass dies nicht mehr manuell notwendig ist.

Die H2-Datenbank wurde auf Version 2.x aktualisiert. Bestehende H2-Datenbank-Dateien im target-Ordner können eventuell nicht mehr gelesen werden. In dem Fall sollte der Target-Ordner entfernt werden. Dieses Plugin ist für Test- und Entwicklungszwecke gedacht, nicht für das langfristige Speichern von Daten oder für den Live-Betrieb. Siehe aber auch die Migrationsanleitung von H2, wie Daten prinzipiell von Version 1 nach Version 2 übernommen werden können.

Auch die Goals des Plugins wurden etwas überarbeitet, da Maven dies erfordert. Es gibt nun 3 verschiedene Goals für verschiedene Einsatzzwecke:

• mvn fc-server:ms - Standalone-Befehl, der außerhalb eines Maven-Projekts verwendet werden kann, um eine formcycle-Instanz zu starten.
• mvn fc-server:run-ms-war - Befehl, der nur innerhalb eines Maven-Projekts ausgeführt werden kann und eine formcycle-Instanz mit dem Plugin startet. Standardmäßig blockiert dieser Befehl, bis der Server beendet wurde.
• fc-server:start-ms-war - Goal für die manuelle Einbindung des Server-Plugins in einen Maven-Build. Sollte in der pom.xml an die gewünschte Phase gebunden werden. Dieses Goal blockiert nicht, sodass auch nach dem Server-Start weitere Maven-Plugin ausgeführt werden können. In einer künftigen Version des Plugins wird es noch ein Stop-Goal geben, um einen so gestarteten Server wieder zu stoppen.

Da der Befehl zum Start innerhalb eine Plugin-Projekts gleichgeblieben ist, sollten für diesen Anwendungsfall keine Anpassung erforderlich sein.

Ebenso wie beim Deploy-Plugin muss nun nicht mehr die Phase package oder install manuell ausgeführt werden. Das Starten des Servers kann damit einfach erfolgen über den folgenden Befehl:

mvn fc-server:run-ms-war