Migration Notes for Axon.ivy Designer 7.0 (Jakobshorn)

This document informs you in detail about incompatibilities that were introduced between Axon.ivy 6.0 (Säntis) and Axon.ivy 7.0 (Jakobshorn) and tells you what needs to be done to get your existing 6.0 projects working with Axon.ivy 7.0.

Table of Content:

Html Dialog

PrimeFaces (Html Dialog)

Migration not needed for 6.7..7.0

PrimeFaces and its supporting libraries have been updated:

There were minor changes that might force you to adjust existing Html Dialogs in order to run them in the latest version.

Moved components

Most users are affected by the movement of some components from the PrimeFaces-Extensions to PrimeFaces. To detect them fast we suggest to execute a search and replace query over your designer workspace. Replace the prefix from <pe:xyz> to <p:xyz>.

The following components were migrated from PrimeFaces Extensions to PrimeFaces:

Strict execution

There are reports that the new Primefaces version 6.1 is more strict than 5.3. This means that in 5.3 a UI component worked correct even if an attribute value was configured wrong (e.g. rendered="hello" instead of rendered="true"). In 6.1 this could now lead to an error or misbehave of the UI component. As soon as you fix the wrong configuration the UI component will work as expected again.

Components as Label target

If you use p:outputLabel, which targets a composite component, the composite component must use cc:editableValueHolder to identify the target input component. NOTE: a label must actually target a input component! If you don't use cc:editableValueHolder, a NullPointerException will occur.

Example:
Usage of the component. The output label references the component in the for attribute:

<p:outputLabel value="Name" for="firstName"/>
<ic:MyTextField id="firstName" textValue="#{data.text}"/>

Old component:

<cc:interface>
  <cc:attribute name="textValue"/>
</cc:interface>
<cc:implementation>
  <p:inputText id="input" value="#{cc.attrs.textValue}"/>
</cc:implementation>

This will no longer work and throws a NullPointerException.
To fix this exception the component must now define a cc:editableValueHolder. The name attribute must reference a widget inside the component:

<cc:interface/>
  <cc:attribute name="textValue"/>
  <cc:editableValueHolder name="inputWidget"/>
</cc:interface/>
<cc:implementation/>
  <p:inputText id="inputWidget" value="#{cc.attrs.textValue}"/>
</cc:implementation/>
Workaround for Bug in SelectOneMenu

The SelectOneMenu is disabled when f:selectItem has an empty label. This bug is currently not fixed by Primefaces. A quick workaround is to set the itemLabel. 

<f:selectItem itemLabel="[Select One]" itemValue=""/>
Look at the issue #2366 for further information.

Full Migration Guide

The full migrations notes from PrimeFaces are as follows:

Bean Validation

Migration not needed for 6.7..7.0

The libraries that supply bean validation features have been changed. In detail the java.validation library has been updated from version 1.0 to 1.1 and myfaces.ext-val libraries have been replaced by hibernate-validator.

This slightly changes the validation behaviour:

Error Handling

Migration needed for all versions

The error handling in html dialogs have been improved. To benefit from these changes, you can configure ajax exceptions handlers.

Urls

The urls of the html dialogs have been changed. This should ease the configuration of access rules.
Before 7.0:
http://localhost:8081/ivy/faces/instances/15E571C7871ED0B0/FormDemo.xhtml
Since 7.0:
http://localhost:8082/ivy/faces/instances/designer/HtmlDialogDemos$1/15E571AB033FE9EB/ch.ivyteam.htmldialog.demo.input.FormDemo/FormDemo.xhtml

PrimeExceptionHandlerELResolver

If you defined org.primefaces.application.exceptionhandler.PrimeExceptionHandlerELResolver or org.primefaces.application.exceptionhandler.PrimeExceptionHandlerFactory in faces-config.xml, remove it. This el resolver and an ivy specific exception handler factory is now already configured per default.

See Help > Designer Guide > User Dialogs > Html Dialogs > Error Handling for more information.

Business Case impact on CaseQuery, IWorkflowSession and IWorkflowContext API

Migration not needed for 6.5..7.0

With the introduction of Business Cases the CaseQuery API and the methods that return cases on the IWorkflowSession and IWorkflowContext API will now return Business and Technical (Sub) Cases. Note, that end users are normally only interested in Business and not in Technical (Sub) Cases. To do so, use the new business case filter API methods.

CaseQuery Example:

import ch.ivyteam.ivy.workflow.query.CaseQuery;
import ch.ivyteam.ivy.workflow.ICase;

List<ICase> allCases = CaseQuery.create().executor().results();
List<ICase> businessCasesOnly = CaseQuery.create().where().isBusinessCase().executor().results();
List<ICase> subCasesOnly = CaseQuery.create().where().not(CaseQuery.create().where().isBusinessCase()).executor().results();

IWorkflowSession Example:

import ch.ivyteam.ivy.workflow.IPropertyFilter;
import ch.ivyteam.logicalexpression.RelationalOperator;
import ch.ivyteam.ivy.workflow.CaseProperty;
import ch.ivyteam.ivy.workflow.ICase;

IPropertyFilter businessCaseFilter = ivy.wf.createCasePropertyFilter(CaseProperty.BUSINESS_CASE_ID, RelationalOperator.IS, null);
IPropertyFilter subCaseFilter = ivy.wf.createCasePropertyFilter(CaseProperty.BUSINESS_CASE_ID, RelationalOperator.IS_NOT, null);

List<ICase> myStartedCases = ivy.session.findStartedCases(null, null, 0, -1, true).getResultList();
List<ICase> myStartedBusinessCases = ivy.session.findStartedCases(businessCaseFilter, null, 0, -1, true).getResultList();
List<ICase> myStartedSubCases = ivy.session.findStartedCases(subCaseFilter, null, 0, -1, true).getResultList();

JPA Date persistence

Migration not needed for 6.4..7.0

Ivy Date type fields, which we're auto initialized by ivyScript, are now persisted as null values in the database. Affected are fields of type ch.ivyteam.ivy.scripting.objects.Date, ch.ivyteam.ivy.scripting.objects.DateTime and ch.ivyteam.ivy.scripting.objects.Time.

If your code relies on the old behavior, where auto initialized values we're written into the database, you can switch back to this implementation by setting the System Property Persistence.JPA.defaultInitializedAsNull to OFF.

Qualified Workflow Links

Migration not needed for 6.3..7.0

The ivy.html context provides several methods to generate links to well known workflow sites. Namely the methods ivy.html.applicationHomeRef(), ivy.html.processStartListRef(), ivy.html.taskListRef().

These links are now qualified with a scheme host and port (e.g. http://myivyhost:8080/ivy/wf/myapp/applicationHome). Before 6.3 these links we're absolute root paths (e.g. /ivy/wf/myapp/applicationHome).

Links which are directly used on a WebPage activity, should still behave as before. If you manually did any string concatenation to add the scheme and host to this URI, your script may need an adjustment.

Portal

Migration needed for all versions

The Portal application that is bundled with the Engine has been improved in many areas. If you have customized the Portal or use a Portal html dialog layout please refer to the chapter Migration Notes in the PortalKit Documentation.

Session attributes cleaned after user logs out

Migration not needed for 6.4..7.0

Session attributes are cleaned after the logout of a user. Projects should not depend on values stored in a session after a logout.

Display name of roles and users

Migration not needed for 6.6..7.0

The method ISecurityMember::getDisplayName() which is implemented by Role and User returns now always a name.

Additionally, the display name of the default role Everybody has changed from Top level role to Everybody.

Project compilation classpath

Migration not needed for 6.5..7.0

Before 6.5 ivy projects had access to many internal ivy libraries which are normally not required by the project. We now removed them by default from Axon.ivy libraries classpath container.

If you migrate your project from 6.0 or older you may have used CXF or AXIS2 libraries in your code and therefore compilation errors arise for these java files. You can get rid of these compilation problems in two ways:

Axon.ivy CI Plugin

Migration needed for all versions

If you use the com.axonivy.ivy.ci:project-build-plugin for continuous integration it is recommended to develop and build your ivy projects with the same Axon.ivy version. To do so ensure that the plugin you are using has the same major and minor version as the Axon.ivy Designer you are using for development. The version of the plugin can be specified in the pom.xml of your ivy Projects.

<plugins>
  <plugin>
    <groupId>com.axonivy.ivy.ci</groupId>
    <artifactId>project-build-plugin</artifactId>
    <version>7.0.0</version>
  </plugin>
   ...
</plugins>

Removal of deprecated Public API

Migration not needed for 6.1..7.0

The following Public API has been removed:

It was marked as deprecated for several years. The API was used for programmable process elements (Program Start Event, Program Intermediate Event, Program Interface Activity). Bean implementations using this class must be rewritten to use the new editor class ch.ivyteam.ivy.process.extension.impl.AbstractProcessExtensionConfigurationEditor.

tools.jar and package com.sun.tools removed

Migration needed for all versions

tools.jar has been removed. Axon.ivy doesn't provide classes of package com.sun.tools anymore. This jar is part of the JDK. You didn't usually use it anyway. But if you do, the designer will draw your attention to it. In this case you can eliminate these dependencies or, if that's not possible, add the tools.jar to your project as a library.

Axon.ivy Extensions (*.extensions file deprecated)

Migration not needed for 6.1..7.0

Like Axon.ivy Designer the Engine now also supports the Eclipse extension point mechanism. Therefore, extensions can be registered in the plugin.xml that is located in your Axon.ivy extension bundle (*.jar file). It is no longer necessary to write a *.extensions file and put it into the configuration/extensions directory.

Old Axon.ivy extensions with a *.extensions file still work but are deprecated. We suggest to refactor Axon.ivy extensions to use the plugin.xml file instead. Support for *.extensions file will be removed in future versions.

Deprecated Public API

Migration needed for all versions

There are new API's to categorize Tasks and Cases (getCategory(), setCategoryPath(...), ch.ivyteam.ivy.workflow.category.CategoryTree). The following old API's to categorize Tasks and Cases are now deprecated. They should no longer be used and will be removed in future versions:

ch.ivyteam.ivy.workflow.ITask

ch.ivyteam.ivy.workflow.ICase

ch.ivyteam.ivy.workflow.query.TaskQuery

ch.ivyteam.ivy.workflow.query.CaseQuery

ch.ivyteam.ivy.workflow.TaskProperty

ch.ivyteam.ivy.workflow.CaseProperty

ch.ivyteam.ivy.workflow.IWorkflowSession

ch.ivyteam.ivy.workflow.IWorkflowContext

REST path parameter

Migration only needed for 6.2..7.0

Prior to 7.0.0 all REST resources had to be annotated with the prefix {applicationName}. Otherwise an authentication on this path was not possible.
Now this application name is added to the resource URI without the need for the project developer to explicitly declare it.
Classes that contain the old parameter should remove it as it causes the problem, that such resources can only be deployed to a single application.

6.2 resource 7.0.0 resource
/**
* Provides the resource
* on the path /ivy/api/myApplicationName/person
*/
@Path("{applicationName}/person")
public class CustomProjectResource {
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public Person get() {
    return new Person("Renato", "Stalder");
  }
}
 
/**
* Provides the resource
* on the path /ivy/api/myApplicationName/person
*/
@Path("person")
public class CustomProjectResource {
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public Person get() {
    return new Person("Renato", "Stalder");
  }
}

Business Data format migration required

Migration only needed for 6.3..7.0

The stored JSON format of the Business Data values has been changed. Therefore, productive Business Data values, written with a previous version on an Engine, are no longer accessible with the BusinessDataRepository until they are explicitly migrated.

To migrate your stored Business Data to the latest version you must add a new process in your ivy project that owns the root Business Data class. This process should call ch.ivyteam.ivy.business.data.store.migration.BusinessDataJsonFormatMigrator.migrate(com.workflow.MyBusinessData.class, false) in a script activity. Re-deploy the project and start an instance of this process to apply the migration. Ensure that you call the migration method for each root Business Data classes of your application.

See WorkflowDemos > Processes > BusinessData > MigrateData for an example