Please create a backup of the database before the update. Also create a snapshot of the server where formcycle/Tomcat is installed.

If you use the print service plugin, it must be updated to version 4.4.4 or higher before the update. The new version can be found in the Customer Cloud.

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.

No special preparations are required for the update. You can proceed exactly as for a normal update. However, before updating, check whether the system requirements for V8 are still met by your system environment.

Update

• The current formclyce version can be downloaded from the release notes. The links are in the header of the relevant version page.
• Log on to the server on which Tomcat is installed. Delete the file "formcycle.war" in the "webapps" directory and wait until the "formcycle" directory is deleted.
• Copy the new file "formcycle.war" into the "webapps" directory of the Tomcat. The update will now start automatically and will take between 2 and 20 minutes. The time depends, among other things, on the number of forms, processes ...
• If you have activated the option "Automatically apply pending database updates at system start" in the area "System settings -> Database", the system will be available immediately after the update. If the option was not selected, the corresponding database update must still be carried out after logging in as "sadmin". Only then will the V8 be fully available!
• After the update, please log in as "sadmin", change to "System settings -> Licence" and update the version status.
• Now switch to "System settings -> Plugins" and update the plugins via the icon "Check for updates". After a successful check, the plug-ins can be updated. Please update the plugins individually, as it takes longer with the first initial update.
• The update is now complete.

One of the biggest changes from V7 to V8 is the user management. The following articles will go into this in more detail.

Contents

How do users sign in?

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

There is no more client selection on the login page. For the system login, i.e. the login with the password assigned for formcycle, the following identifier can be used with version 8:

• The email address of the user
• The user name of the user

A login of the form username@clientname is no longer possible. This also applies to LDAP users.

The update merged users with the same email address from different clients. All users of the system are manageable for system administrators in the system settings. These users can be part of (multiple) clients. For more information about the new user management see here.

Reset password

If a user was in several clients before the update, i.e. a user with the same email address existed in several clients, then their password will be reset by the update. This user will then be prompted to enter a new password when logging into the formcycle administration interface for the first time. A link for assigning a new password will be sent to the user's email address.

For system administrators, users whose password has been reset can be recognized in the overview of all users by the fact that they are marked with the note "Cannot sign in". System administrators can also assign a random password to these users by clicking on "Generate new password". More information about the administration of users can be found here.

Changed username

The username of users may have changed due to the update. This happens if the same username existed in several clients before the update. A random suffix is appended to the username in this case. The user name can be changed by the user at any time via My Profile and used for login with password.

It is recommended that users log in to formcycle with their email address after the update. If users cannot log in with their username after the update, this may be due to a changed username.

Inactive users

Inactive users cannot log in to formcycle. If a user is marked as inactive after the update, then this user was inactive in one of their clients before the update. System administrators can identify inactive users via the overview of all users by the note "Inactive" and reactivate them. Active users can log in again and have access to the clients to which they were assigned before the update. System administrators can see which clients a user is assigned to via the user information in the overview of all users (see figure).

Forgotten email address

If users are unable to log in after the update because they should have forgotten or no longer have access to their email address used for formcycle, system administrators can assign a new email address to these users via the system settings.

Profile language

The profile language of users results from the first client in which the user was found during the update. Users can change the language of their profile at any time from the Profile menu or My Profile. See here.

Use of client LDAP connections

For installations running multiple clients with configured LDAP connections for logging in to the management interface, the following section should be read carefully.

If LDAP connections are configured on several clients for logging on to the administration interface, these should definitely be checked before the V8 update. What happens to these LDAP connections as well as the LDAP groups during the update to V8, how and why the connections should be checked and adjusted if necessary, will be described in the following.

If no clients or only one client with an LDAP connection is used for logon, this section can be skipped.

What happens to the client LDAP connections during the V8 update?

LDAP connections for login are no longer configured directly on the client in version 8. Instead, LDAP connections are configured as LDAP login services. This means that LDAP login services will be created for all existing LDAP connections that have been configured for login at the client up to now in the course of the V8 update. However, no login services are created twice. This means that several identical client LDAP connections are combined to a new LDAP login service.

What happens to the LDAP groups during the V8 update?

LDAP groups no longer exist in version 8. Instead, LDAP user filters are created in V8. When updating to version 8, a new equivalent LDAP user filter is created for each LDAP group, which uses the newly created LDAP login service (see previous section).

Ensure identical LDAP login services

LDAP users and LDAP groups therefore depend on the configured client LDAP connection. To ensure a smooth login of the users after the V8 update it is necessary that identical client LDAP connections are matched before the V8 update. How this is done exactly is described in the following section (What to do?). Before that, however, it should be explained why login problems can occur if identical client LDAP connections are not aligned:

After the update, all LDAP login services created by the update are available when logging in to the administration interface. If a user now tries to log in, all LDAP login services are tried one after the other with the entered login data until a user is found in one of the login services and successfully authenticated. However, if several LDAP login services were created for identical LDAP connections during the V8 update, the user is now only authenticated via one of the existing login services. Namely via the first of the newly created login services where the login can be successfully performed, although the user could also have authenticated via the other identical login services. The user then has access via the newly created LDAP user filters that use this login service. However, he does not get access via other LDAP user filters that use one of the other newly created LDAP login services, even though the user could authenticate via this one.

Therefore, it is important that identical LDAP connections are matched before the update so that they are combined into one new LDAP login service after the update.

Goal: Minimize created login services by matching identical client-LDAP connection.

What to do?

So, before the update, identical client LDAP connections should be matched. Identical LDAP connections use the same LDAP server, but may different in:

• User for user search
• BaseDN for user search
• Filter query

If LDAP connections for user search use the same LDAP server (and port), the other specifications should be adjusted if possible. How this information can be matched is described below.

Matching upper/lower case of LDAP server URL

When specifying the LDAP server, you may have to pay attention to upper/lower case. If identical LDAP servers differ in the upper/lower case of the specified LDAP server URL, several different LDAP login services are created during the update, which should be avoided. The case-sensitive URLs may be intentional, since URLs are generally case-sensitive according to the W3C. URLs that are only case-sensitive may point to the same LDAP server. These URLs should be matched before the update.

Matching of users for user search

If identical LDAP servers differ in the user for the user search, it should be checked whether the same user can be used for all identical LDAP connections. If identical LDAP connections differ in the user for the user search, several different LDAP login services are created during the update, which should be avoided.

Matching of the BaseDN for the user search

If identical LDAP servers differ in the BaseDN for the user search, it should be checked whether the same BaseDN can be used for all identical LDAP connections. If identical LDAP connections differ in the BaseDN for the user search, several different LDAP login services are created during the update, which should be avoided.

Matching of the filter queries

If identical LDAP servers differ in the filter query, the filter query should be removed from the LDAP connections and used instead in the LDAP groups of the client that use the client connection. If identical LDAP connections differ in the filter query, several different LDAP login services will be created during the update, which should be avoided.

Migration preparation missed

If this migration preparation was missed and users cannot log in correctly after the update, then the display of the login services with input mask should be set to "Input masks split into tabs", see Login page. This way the newly created LDAP login services of the individual clients are displayed as tabs on the login screen of the administration interface. This corresponds then to a certain extent to a client selection, since the LDAP login services originated from the LDAP connections to the clients.

In addition it should be tried to reduce the number of the LDAP Login services, as described above. To do this, the LDAP login services may have to be reassociated with the individual users. Depending on the number of LDAP users, this can mean a large additional administrative effort after the update.

In order to avoid possible additional administrative work after the update, care should be taken before updating to version 8 that the LDAP connections of the clients are checked and possibly adjusted as described above.

Kerberos

The configuration of Kerberos can now be found under Login Services in the system settings. In addition, the global LDAP user search configuration of Kerberos can now be overridden within clients. If a client Kerberos login service is used in forms, the Kerberos global authentication configuration is used with the LDAP user search configured in the client Kerberos login service. for more information, see Kerberos.

The Kerberos option "Use client LDAP server (if configured)" no longer exists. If this option was enabled before the update, a client Kerberos login service with the configured LDAP connection was created for each client that had a client LDAP server configured.

NTLM

NTLM can no longer be configured with version 8. NTLM can still be configured via the configuration file ldapauth.properties. However, this is strongly discouraged since Microsoft no longer supports NTLM.

LDAP groups

The "LDAP Groups" menu item no longer exists. The User menu item now combines the former "LDAP Groups" and "Users" menu items. For all configured LDAP groups a user filter of type LDAP is created by the update. For more information about user filters see here.

MySQL 5

MySQL 5 is no longer supported in any version. If MySQL 5 is still used, the database must be updated first before the formycle update.

Plugin development

In principle, plugins still work with version 8, even if they were compiled against version 7. However, some maintenance work should be done to ensure that plugins will work in future versions. Depending on the type of plugin, further adjustments may also be required.

Furthermore, we always recommend compiling plugins against the version of formcycle in which the plugin is installed. Firstly, this allows you to check if there are any compilation errors that need to be fixed. Secondly, even if API compatibility (source code compatibility) exists, it is possible in Java that there is no byte code compatibility. Thirdly, this can also look at deprecated warnings and adjust the plugin code accordingly.

Entering a unique ID

Each plugin must have a unique ID from version 8 of formcycle, which must be in the MANIFEST.MF of the plugin JAR in the entry Plugin-Key. In version 8.0 plugins without such an ID are still recognized and only marked as legacy plugin in the plugin menu. In a future version such plugins will no longer be supported.

The ID itself can have any value as long as it is unique. We recommend either the combination of <Group-ID>:<Artifact-ID> or a randomly generated UUID.

If a plugin consists of multiple JAR files, then all JAR files must have the same value for Plugin-Key in the MANIFEST.MF and different value in the Plugin-File-Key manifest attribute.

Furthermore, each plugin should specify in the Plugin-Repository entry in the MANIFEST.MF whether and to which remote repository it is connected. Currently only the values none and xfc-proma are possible for the official repository of formcycle. External plugin developers should usually specify the value none here. This avoids that updates are searched unnecessarily, which cannot exist. If the plugin repository entry is missing, xfc-proma is still taken as default in version 8.0 of formcycle, but this will be changed to none soon.

If the Maven assembly plugin is used to build the fat JAR, the manifest entries can be set as follows:

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

Checking the provided dependencies

From formcycle dependencies are provided, which are only used by plugins and declared in the scope provided when using Maven. For version 8, some dependencies have been updated, so it is necessary to check if the classes and methods used in the plugin still work with the new dependencies.

Some known points to consider when doing this:

• Pac4J, the framework for authentication and authorization, has been updated Plugins that provide authenticators should definitely be tested.
• The UI framework PrimeFaces has been updated to version 12. Plugins that provide their own interfaces should be checked. See also the PrimeFaces migration guide.
• The CK editor component <pe:ckEditor> has been removed from PrimeFaces Extensions. formcycle now provides the <xi:htmlEditor> component. The options here are the same, so replacing <pe:ckEditor> with <xi:htmlEditor> should be sufficient in most cases. The namespace for xi is
  xmlns:xi="http://www.xima.de/taglib/xfc"
• The Apache commons lang library is no longer shipped, only Apache commons lang3. In most cases it should be sufficient to change imports from org.apache.commons.lang.* to org.apache.commons.lang3.*.
• The Apache Commons Configuration bilibrary was installed from version 1 to version 2. The API is not compatible, and the package paths have changed. See also the release notes and the migration guide of Apache-Commons-Configuration. From formcycle the wrapper de.xima.cmn.props.FileBasedPropertiesConfiguration is provided, which has the same methods as org.apache.commons.configuration.PropertiesConfiguration from version 1. The type of the constant de.xima.fc.config.XfcConfig.APPLICATION for example has been changed to the new class FileBasedPropertiesConfiguration, so there is API compatibility, so no changes have to be made to the source code. However, it is necessary to recompile the plugin because the byte code still points to the wrong class.

To facilitate this check, it is recommended to import the parent POM from formcycle so that when compiling, it automatically checks against the appropriate versions of the dependencies that formcycle provides:

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

Check for compatibility with new user management

Due to the modifications regarding the new user management, some profound changes were necessary. Plugins that work with users or the user management should definitely be checked. In addition, some classes and methods were marked as deprecated in the course of the conversion. It should be checked in the plugin whether such classes and methods are used and these are adapted accordingly to the JavaDocs.

The entity de.xima.fc.entities.Benutzer may no longer be used. The class itself still exists, but has no effect anymore. There are no instances of this entity stored in the database anymore. The interface IUser should be used instead. The class VirtualUser can be used to access the anonymous and the system user. The new entities for user management are UserIdentity (see menu System -> User) and AClientAuthorization with subtypes DirectClientAuthorization and IndirectClientAuthorization (see menu Client -> User).

For plugins with their own interfaces, the beans should be checked. Within the bean, access to the current client is now done via private @Inject ViewContextBean viewContext. Access to the current user is done via @Inject SessionUserManager userManager. Checking for permissions works via the UserAccess class, for example:

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

Adjusting the menu items of portal plugins

Using a plugin of type de.xima.fc.plugin.interfaces.backend.IPluginMenuEntries it is possible to add custom menu entries in the backend. Most often such a plugin is used as a part of a portal plugin.

This plugin returns a set of menu entries (de.xima.fc.interfaces.plugin.retval.backend.IPluginMenuEntry). A large part of the existing methods in the IPluginMenuEntry interface are now deprecated and should no longer be implemented. Some of these methods also do not work as described, but to maintain compatibility, they behave just as incorrectly as in version 7.

Instead, the new method IPluginMenuEntry#getPluginView should be used. This also allows much more flexible control of where and when the menu entry is displayed.

In the following still another example, how a menu entry could look approximately:

  /**
   * @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());
      }
    };
  }

Customize build configuration for server and deploy plugin

The Maven plugins for deploying plugins (Maven coordinates de.xima.fc.maven.plugin:fc-deploy-plugin-maven-plugin) and for starting a formcycle server (Maven coordinates de.xima.fc.maven.plugin:-server-maven-plugin) have been revised and slightly adapted.

Deploy Plugin Plugin

The default value for the pluginIdent configuration parameter is now key. This means that the plugin must have a unique ID in the manifest entry plugin-key as described above. Otherwise, the plugin can no longer be identified during deployment and will be installed multiple times. If necessary, the previous behavior can be restored by setting pluginIdent=manifest and pluginIdentifier=Implementation-Title=${project.groupId}:${project.artifactId}. Since there is now a standardized method for identifying plugin, the pluginIdent and pluginIdentifier configuration parameters have been deprecated and will be removed in a future release.

Previously, it was also necessary to run the package or install phase before deployment. In addition, the deployment URL and deployment token always had to be specified. The deploy command looked something like this:

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

The specification of package is no longer necessary, this is now done automatically by the plugin. For the deployment URL and the deployment token default values are now stored as in the above command. Only in case of deviations they have to be specified. Now the deployment can be done as follows:

mvn fc-deploy:deploy

In addition, support for multi-module Maven projects has been improved. When the fc-deploy:deploy goal is executed on a multi-module project, the deployment is skipped for the modules that are not a formcycle plugin.
Note: Since there is no unique identifier for whether a module is a formcycle plugin, this is determined based on some heuristic criteria (which can change):

• The Maven module must have at least one dependency on de.xima.fc:fc-plugin-common in the scope provided.
• The Maven module must use either the maven-assembly-plugin with the goal single or the maven-shade-plugin with the goal shade to build a fat jar.

If this is not given, the following plugin configuration parameters can be used:

• <skip>true</skip> to force the deploy plugin not to run.
• <skipNonPluginProject>false</skipNonPluginProject> to disable heuristic checking for a formcycle plugin.

formcycle-Server-Plugin

The demo license should now be updated automatically at startup, so this is no longer necessary manually.

The H2 database has been updated to version 2.x. Existing H2 database files in the target folder may no longer be readable. In that case, the target folder should be removed. This plugin is intended for testing and development purposes, not for long-term data storage or live operation. However, see H2's migration guide on how to transfer data from version 1 to version 2 in principle.

Also the Goals of the plugin have been revised a bit, as Maven requires this. There are now 3 different Goals for different purposes:

• mvn fc-server:ms - standalone command that can be used outside a Maven project to launch a formcycle instance.
• mvn fc-server:run-ms-war - command that can be executed only within a Maven project and starts a formcycle instance with the plugin. By default, this command blocks until the server is terminated.
• fc-server:start-ms-war - Goal for manual inclusion of the server plugin in a Maven build. Should be bound to the desired phase in the pom.xml. This Goal does not block, so other Maven plugin can be executed even after server start. In a future version of the plugin there will be another stop-goal to stop a server started this way again.

Since the command to launch within a plugin project has remained the same, no customization should be required for this use case.

Just as with the deploy plugin, the package or install phase no longer needs to be executed manually. The startup of the server can thus simply be done via the following command:

mvn fc-server:run-ms-war