LSPS documentation logo
LSPS Documentation
Frequently Asked Questions


What are logs?

In the context of LSPS, the term log can refer to one of the following:

  • A log entry made when a model instances executes the Log task or log() function call.

    Both, the task type and the function, are provided by the Standard Library and the entries are visible in the Logs view of the Management perspective and Management Console. These logs are stored in the LSPS_LOGS table of the LSPS system database.

  • A process log entry which is automatically created by model instances.

    These are logs about execution progress. They are stored in the LSPS_PROCESS_LOG table and are not visible from any client. Further information is available in the Server Installation and Upgrade Guide

  • The log message of the debugLog() function which is displayed in standard output.

LSPS Server

The server returns the ConnectorTracker XA exception.

The JBoss or Wildfly server returns the following XA exception:

WARN  [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery got XA exception javax.transaction.xa.XAException, XAException.XAER_RMERR

To remedy the situation, the database user has all required access rights:

For Oracle, make sure the Oracle user has access to the appropriate tables so they can accomplish the recovery:

GRANT SELECT ON sys.dba_pending_transactions TO user;
GRANT SELECT ON sys.pending_trans$ TO user;
GRANT SELECT ON sys.dba_2pc_pending TO user;
GRANT EXECUTE ON sys.dbms_xa TO user;

Substitute user with the user that connects from JBoss to Oracle. This solution works for Oracle 10g R2 (patched for bug 5945463) and 11g.

In an unpatched version older that 11g change the last GRANT EXECUTE to the following:

GRANT EXECUTE ON sys.dbms_system TO user;

Embedded Server starts with an Exception.

  • Make sure javac is on the classpath if the embedded server starts with the following exception:
    Starting database failed.
    IO Exception: " Cannot run program ""javac""
    The Java compliler binary might not be on the classpath: Create a JAVA_HOME environment variable and add it to the PATH environment variable.
  • Details, such as Model Instance details, in the Management perspective which are no longer valid might be open, for example, due to a database reset, and the data is no longer present in the database: Close any detail tab in the Management perspective.

SDK Embedded Server with MSSQL data source starts with java.lang.SecurityException exception

If you are using MSSQL data source in your SDK Embedded Server, the server might start with the following exception:

java.lang.SecurityException: Invalid signature file digest for Manifest main attributes
        at Source)
Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main"

This happens because pulls additional dependencies. Exclude the dependencies in the <YOUR__APP>-db-migration project pom.xml:

    <!-- Additional configuration. -->

SDK Embedded Server starts with an OpenEJBException

If you get the following exception, fix the jdbc url of LSPS_DS in <YOUR_APP>-embedded/conf/conf/openejb.xml to JdbcUrl jdbc:h2:tcp://localhost/./h2/h2;MVCC=TRUE;LOCK_TIMEOUT=60000.

WARN JdbcServicesImpl HHH000342: Could not obtain connection to query metadata : A file path that is implicitly relative to the current working directory is not allowed in the database URL "jdbc:h2:tcp://localhost/h2/h2;MVCC=TRUE;LOCK_TIMEOUT=60000". Use an absolute path, ~/name, ./name, or the baseDir setting instead. [90011-197]
Exception in thread "main" org.apache.openejb.OpenEJBException: Creating application failed: /home/eko/testing/3.2.1038/ekassa/ekassa/ekassa-embedded/Launcher.EAR: org.apache.openejb.OpenEJBRuntimeException: javax.persistence.PersistenceException: [PersistenceUnit: lsps-pm] Unable to build EntityManagerFactory: javax.persistence.PersistenceException: [PersistenceUnit: lsps-pm] Unable to build EntityManagerFactory
  at org.apache.openejb.assembler.classic.Assembler.createApplication(
  at org.apache.openejb.assembler.classic.Assembler.createApplication(
  at org.apache.openejb.assembler.classic.Assembler.createApplication(
  at com.whitestein.lsps.launcher.Launcher.launch(
  at com.whitestein.ekassa.embedded.LSPSLauncher.main(
Caused by: org.apache.openejb.OpenEJBException: org.apache.openejb.OpenEJBRuntimeException: javax.persistence.PersistenceException: [PersistenceUnit: lsps-pm] Unable to build EntityManagerFactory: javax.persistence.PersistenceException: [PersistenceUnit: lsps-pm] Unable to build EntityManagerFactory
  at org.apache.openejb.assembler.classic.Assembler.loadPersistenceUnits(
  at org.apache.openejb.assembler.classic.Assembler.createApplication(

How Do I Disable Remote Access to the SDK Embedded Server?

To disable remote access to the Application User Interface the SDK Embedded Server, add the following filter to the <YOUR-APPLICATION>/vaadin-war/src/main/webapp/WEB-INF/web.xml:

       <filter-name>Remote Address Filter</filter-name>
       <filter-name>Remote Address Filter</filter-name>

To do the same for Management Console, expand the application EAR you created and add the filter to the lsps-management/web.xml file. Then recreate the EAR.

Messages in JMS queue are stuck.

In your server logging configuration, activate the debug log level for com.whitestein.lsps.engine.CommunicationServiceBean and com.whitestein.lsps.engine.ProcessAgentImpl services and inspect the log.

Server returns "ISPN000299: Unable to acquire lock after 15 seconds"

Infinispan on JBoss and Wildfly returns the ISPN000299: Unable to acquire lock after 15 seconds: this occurs when an operation takes too long so the session is locked and fails to acknowledge the Vaadin heartbeat from the Application User Interface.

To remedy the problem, do the following:

  • set the active-timeout parameter of the server to 10m in the profile xml file, such as, standalone-full.xml:
    <cache-container name="web" default-cache="passivation" module="org.wildfly.clustering.web.infinispan">
         <local-cache name="passivation">
            <!-- CHANGED the acquire-timeout here: -->
            <locking isolation="REPEATABLE_READ" acquire-timeout="600000"/>
            <transaction mode="BATCH"/>
            <file-store passivation="true" purge="false"/>
  • increase the heartbeat interval in your Application User Interface in the web.xml of the application:

WebSphere returns "The messaging engine's unique id does not match that found in the data store."

When Websphere is configured to store JMS tables in the DB which already contains such tables, for example, as a result of a previous installation, it fails with the error:

[LSPS_BUS:websphereNode01.server1-LSPS_BUS] CWSIS1535E: The messaging engine's unique id does not match that found in the data store. ME_UUID=1B0B5DB0D21BFD75, ME_UUID(DB)=090BD5611CD4240C

To resolve the problem, delete the tables with the SIB prefix from the LSPS database: DROP TABLE "LSPS"."SIB000";DROP TABLE "LSPS"."SIB001";DROP TABLE "LSPS"."SIBCLASSMAP";

WebSphere returns "java.sql.SQLSyntaxErrorException: ORA-02089: COMMIT is not allowed in a subordinate session"

When timers are stored in the database that is accessed using an XA datasource, such as, LSPS_DS, WebSphere might return an exception with

Caused by: java.sql.SQLSyntaxErrorException: ORA-02089: COMMIT is not allowed in a subordinate session

This happens because WebSphere fails to create the tables.

To resolve the problem, create the scheduler tables using \<WASROOT>/Scheduler/createSchemaMod1\<YOUR_DB>.ddl

To check timer service properties:

  1. Expand Servers > Server Types > WebSphere application servers.
  2. Click [your_server].
  3. Under Container Settings, expand EJB Container Settings and click EJB timer service settings.

Disabling Update of the Database Schema of a Data Type Model

To prevent update of database schema when you upload a data-type model, you have the following options:

Application User Interface

Browser displays an error when accessing the application.

Clean cache of your browser.

Browser remains blank after login.

Delete the browser cookies.

The session of the Application User Interface is expired.

Make sure your browser does not use out-of-date cookies and cached data: Clean the cookies and cached data.

The user remains logged in even after the session timeout period has lapsed.

Make sure your lspsVaadinApp servlet in the web.xml of the Application User Interface contains the closeIdleSessions parameter:

<!-- Vaadin servlet -->

This prevents Vaadin from sending heartbeats to the server after the session-timeout period. The session timeout is set in minutes in web.xml.


Icons are missing in the top toolbar of PDS on my Linux machine.

This is caused by Eclipse issue 497705. To remedy the situation, create a new PDS launcher:

export SWT_GTK3=0


I accidentally deleted the methods file.

Right-click the module and go to Restore from Local History.

There is no Decision Table Definition option in the menu.

Go to Window > Perspective > Reset Perspective.

When should a Module be executable?

An executable Module can become a model instance, while a non-executable module is intended as a resource and cannot be instantiated: If you have a module where you define the data model only (like in the model in the MVC pattern), it is not intended for execution. Hence it does not require the execution flag.

Note that if you import an executable module to another executable module, and you instantiate the importing module (the parent), the imported executable module will be instantiated as part of the model instance.

There are validation problems even though the expressions are correct.

  • In the GO-BPMN Explorer, right-click the module with the problem and select Validate.
  • Clean the project: on the main menu, go to Project -> Clean

I cannot access a local variable in another local variable.

Make sure that the variable is in a context the other variable can access. If working with local variables of the same context, make sure the variable is already initialized: variables are initialized in the order they are defined in (make sure, the variables are not sorted alphabetically when using the Outline view).

How do I load and work with a file from my workspace.

  • To work with a file, load it to the File record:
    def File file := getResource(module -> "my-module", path -> "file.pdf");
    //to access the content binary: file.content.toString("UTF-8")
  • To work with a file in a form, load it into a FileResource object with the getResource() function:
    new FileResource({ -> getResource("form_components", "output/myfile.txt")})
  • To get the text content of a File, use the toString() function on the content of File:
    toString(file.content, "UTF-8")

An expression returns only the last collection item, last list item or last set item.

Check if you are not using a semi-colon (;) instead of a comma (,) as a separator of the collection items: the system returns the last expression as the collection content.

Typical case of a misplaced semi-colon

new CategoryDataSeries([
    //semi-colon at the end of the following line causes that
    //only the next line is returned as the content
    //of the collection:
    new CategoryDataSeriesItem("Pears", 1, 5);
    new CategoryDataSeriesItem("Apples", 2, 6);

I want to create a model instance from an expression.

If you want to create a model instance from an expression, call the createModelInstance() function:

createModelInstance(true, thisModel(), mySharedRecord := new MyRecord() , null);

When creating multiple instances, consider creating them asynchronously to prevent timeout of the transaction and its subsequent rollback.

foreach Integer i in 1..100 do
createModelInstance(false, getModel("myModule"), null)

I want to create a model instance over an entity.

If you want to create a model instance over an entity, pass the shared Record to the createModelInstance() function:

createModelInstance(true, thisModel(), mySharedRecord := new MyRecord() , null);

You can then get the Record with a getProcessEntity(MyRecord) function call.

I want to get all todos of a model instance.

To get to-dos of a model instance, create a query with the model instance as its parameter that return the Todo type and define a condition that will exclude to-dos of other model instances, for example, todoIterator.modelInstanceId ==;

What is the difference between the Upload As and Run As module command?

  • Upload As compiles and uploads the selected module and its module imports to the LSPS Module Repository of the server your PDS is connected to. In PDS, the modules uploaded to the server are managed in the Module Management view of the Management perspective.
  • Run As does the same and in addition creates a model instance of the executable module. Hence this option is not available for modules that are no executable since these cannot be instantiated. In PDS, the model instance that have been executed by the server can be managed from the Model Instances view of the Management perspective.

Data Types

How do I get all shared records of a type without creating a query?

Use the findAll() function of the Standard Library to get all the shared records of a particular type. Also note you can use the countAll() function to get the number of the shared records.

Proxy Writes Directly to Database or Does not Merge.

  • Make sure the proxy object really is a proxy with the isProxy() call.
  • In Forms forms, make sure the proxies are created before they are used; for example, use the preCreateWidget() method to create the proxies.
  • Check if your record name does not collide with a system record name.

Warning "Missing database index on foreign key" on a Data Relationship

Create indexes for foreign keys on the data relationship ends: select the relationship and in the Properties view, define the indexes on the Indexes tab. Alternatively, you can generate them automatically: in the Outline view, on the Tree tab,-click the root node Data Types and in its Properties view click the Generate Indexes button.

How Was the Database Schema of My Module Updated?

You can find information on how the schema was changed in the Module Management view of the Management Perspective: click the Schema Update Scripts tab.

Model upload fails with a hibernate exception.

Check whether the data type model meets the following:

  • The hierarchy uses "Each record to own table".
  • The top record has no property, only primary key.
  • There is a record with one-to-set relation to the top record.
  • The relation is one-directional.
  • The relation is sorted according to the primary key of the top record.

This occurs due to an issue in Hibernate. To work around it, do one of the following:

  • Add a property to the top record.
  • Remove sorting on the relationship.
  • Make the relationship bi-directional (the top record will have a property)

UI Forms

This section contains frequently asked questions concerning the forms created with the resources of the ui module of the Standard Library.

My local form variable has incorrect value.

If you are assigning a value to your variable in an InitListener, make sure the component with the InitListener is actually displayed. InitEvents are fired only on component display.

I cannot change properties of a listener.

Make sure the Listener is defined by expression option on the Expression tab is not selected.


This section contains frequently asked questions concerning the forms created with the resources of the forms module of the Standard Library.

Font Awesome icons disappeared, are missing or display incorrectly.

Since the support for font awesome has been deprecated by Vaadin, it is now delivered as part of the extensions of the vaadin project. If you are using your custom theme, include the @include lsps-extensions-at-root; statement in your styles.scss to remedy the situation.

A component ignores a size setting.

If a component ignores such calls as setWidthFull(), setWidthWrap() setHeightFull(), setHeightWrap(), it is probably due to default style settings in the theme.

For example, if you call setWidthFull() on a TextArea, the width will retain it width. Such default settings are provided to prevent cases where the component is not displayed unless its size is explicitly specified, for example, if you had a text area in a layout and the layout would wrap its content and the text area would fill its parent (this is equivalent to a setWidthFull() call).

To adapt the size of your component, create a custom theme and set the size of the component style as required.

Example of a text area scss that fills the parent and has a minimum width

/* from a dedicated _textarea.scss in the sass folder */
@mixin _textarea {
  .v-textarea {
    width: 100%;
    min-width: 100px;
/* the mixing is included in the styles.scss of the theme */

Add a Stylesheet File to a Module

To add a file with a style sheet to your module, do the following:

  1. Create the style sheet file with your rules in your module.
  2. Load the file into your form, for example, from the Init tab of the root component, and call addStyleSheet() on the file:
    def File file := getResource(module -> thisModel().name, path -> "MyTable.css");

To test the rules, you can use the addStyleName() component method.

Filter on a table column is not displayed.

If you are using the None value in the Filter value provider, make sure the type of the column value provide on the Detail tab of the column defines its value (in the case of Identity, the value should be set to the type, such as String).

Geolocator in the forms module is missing.

A document UI definition reports the error "Type mismatch. Cannot convert from <> to human::UIDefinition".

  • Import the forms module into your module. Check if your Record name does not collide with a system Record name.

Charts ignore plot options.

If a data series does not plot correctly, consider defining the values for all properties explicitly, for example, if you are changing the color of a decimal series, apart from the color parameter, set also the range to true and lineStyle to lineStyle.solid:

c.setPlotOptions(new PlotOptionsLineArea(color -> new Color(0, 0, 0), lineStyle -> LineStyle.solid, fillColor -> new Color(230, 200, 180),range -> true));

Modeling ID is ignored.

This happens on the root components of the Expression component: the modeling id of the root component returned by the expression in the Expression component uses the modeling id as set on the Expression Component in its properties. Calls to setModelingId() on the component that is the content of the Expression component are ignored.


I get "A parametric process cannot be instantiated automatically." on my process

A process that has parameters cannot run without its parameters; hence, it can be instantiated only by another entity which provides the parameters. To solve the situation, display the properties of the process and on the Detail tab unselect Instantiate Automatically.

I want to instantiate a process from a document.

A document is not part of a model instance and process instances can exist only as part of a model instance. Hence this is not possible. However, you can create a model instance with the createModelInstance() call.


How do I check if the current user has a role?

Typically when setting access rights for to-dos and documents, you want to check if the user who is working with the application at the given moment has the required modeled role. Use the isPersonIn() function.

//Example setting of access rights:
isPersonIn( getCurrentPerson(), common::Client() )

RESTful Webservices

I get "The restful Webservice definition is not valid. See Problems view for details." dialog box.

Close and reopen the editor.


I get "The symbol <TYPE> is undefined." validation error.

Validation reports an error of an undefined symbol for an expression that should result in in a Type: This happens if the type contains <>. To solve the problem, wrap the type in the type() function.


I want to format a Date.

  • To format a Date object, call the formatDate() method with the date format as it parameter; the formatter uses the DateTimeFormat with the pattern and time zone.
    now().formatDate("EEEEEEEEEE, MMM d", "Pacific/Auckland")
  • To format a local date, use format():
    def LocalDate ld :=ld'2019-01-24';
    //returns "24.1.2019"

I want to preform action on each item of a Collection or Map.

Though you can use the foreach construct, consider the collect() function of the Standard Library, especially if you create new collections in the cycle: the collect() function runs a closure on each item and returns a list with the outputs from the closures.

Example over List

//list with lists of values and names for the ListDataSeriesItem:
def List<List<Object>> itemList1 := [[1, "I am item 1 with value 1"], [3, "I am item 2 with value 3"], [1.3, "I am item 3 with value 1.3"]  ];
def ListDataSeries ls1 :=
//Collect returns a list of ListDataSeriesItem; it is then passed to the ListDataSeries constructor:
   new ListDataSeries (collect(itemList1, { i -> def ListDataSeriesItem li := new ListDataSeriesItem(i[0] as Decimal); := i[1] as String; li}));

Example over Map

//map of values and names for the ListDataSeriesItem:
def Map<Decimal, String> mapsOfItems := [1 -> "I am item 1.", 3 -> "I am item 2.", 1.3 -> "I am item 3."];
//Creating a list of data series:
  new ListDataSeries (collect (mapsOfItems,
           { k,v -> def ListDataSeriesItem li := new ListDataSeriesItem(k, v)}


MS SQL server reports deadlocks.

If your MS SQL Server reports deadlocks, the problem might by cause by orphaned transaction: make sure to kill any hanging orphaned transactions that block database resources if such transactions are present.

Example of a select that returns orphan transactions

select request_owner_guid as [UoW ID] from sys.dm_tran_locks where request_session_id = -2

Migration or initialization of LSPS tables fails on MySQL 5.6.

When running on MySQL 5.6 with multibyte encoding (UTF-8), check if your database uses Barracuda as file format: SHOW VARIABLES LIKE 'innodb_file_format' If it is not the case, set the global innodb_file_format=Barracuda;set global innodb_large_prefix=on;ROW_FORMAT DYNAMIC

If you are not using Barracuda, the initialization of the LSPS database will fail with the exception:

SEVERE: Migration of schema `lsps` to version <DB_VERSION> failed! Please restore backups > and roll back database and code!

This occurs because MySQL uses the InnoDB engine which restricts the column length and LSPS requires wider columns than allowed by MySQL.

Migration of MySQL fails with an exception.

When migrating the LSPS database on MySQL from an LSPS version older than 3.3.2069, the following exception occurs:

Exception in thread "main" org.flywaydb.core.api.FlywayException: Validate failed. Migration Checksum mismatch for migration 2.6
-> Applied to database : -1913434156
-> Resolved locally    : 68228300
  at org.flywaydb.core.Flyway.doValidate(
  at org.flywaydb.core.Flyway.access$300(
  at org.flywaydb.core.Flyway$1.execute(
  at org.flywaydb.core.Flyway$1.execute(
  at org.flywaydb.core.Flyway.execute(
  at org.flywaydb.core.Flyway.migrate(
  at com.whitestein.lsps.dbmigration.DbMigration.runFlywayCommand(
  at com.whitestein.lsps.dbmigration.DbMigration.migrate(
  at com.whitestein.lsps.dbmigration.DbMigration.main(

This happens due to the required change of the database character set to utf8mb4 and collation to utf8mb4_unicode_ci which is a 4-byte encoding as opposed to the previously recommended utf8 with utf8_general_ci which is a deprecated 3-byte encoding. As a result the indexes of the database had to be shortened.

To remedy the problem, run the migration with --flyway repair and then migrate again:

~/lsps-runtime-33/cli-tools $ java -jar lsps-db-migration-lsps-3.3.2069-full.jar --databaseUrl jdbc:mysql://localhost/lsps --user lsps --password lsps --flyway repair
Nov 26, 2019 1:40:43 PM org.flywaydb.core.internal.util.logging.slf4j.Slf4jLog info
INFO: Flyway 3.2.1 by Boxfuse
Nov 26, 2019 1:40:43 PM org.flywaydb.core.internal.util.logging.slf4j.Slf4jLog info
INFO: Database: jdbc:mysql://localhost/lsps (MySQL 5.7)
Nov 26, 2019 1:40:43 PM org.flywaydb.core.internal.util.logging.slf4j.Slf4jLog info
INFO: Repair of failed migration in metadata table `lsps`.`LSPS_SCHEMA_VERSION` not necessary. No failed migration detected.
Nov 26, 2019 1:40:43 PM org.flywaydb.core.internal.util.logging.slf4j.Slf4jLog info
INFO: Updating checksum of 2.6 to 68228300 ...
Nov 26, 2019 1:40:43 PM org.flywaydb.core.internal.util.logging.slf4j.Slf4jLog info
INFO: Metadata table `lsps`.`LSPS_SCHEMA_VERSION` successfully repaired (execution time 00:00.146s).
Nov 26, 2019 1:40:43 PM org.flywaydb.core.internal.util.logging.slf4j.Slf4jLog info
INFO: Manual cleanup of the remaining effects the failed migration may still be required.
~/sps-runtime-33/cli-tools $ java -jar lsps-db-migration-lsps-3.3.2069-full.jar --databaseUrl jdbc:mysql://localhost/lsps --user lsps --password lsps

Migration or Initialization of Database fails with an SQLNonTransientConnectionException exception on MySQL 8.

When migrating or initializing the LSPS database on mysql8, the process might fail with the following exception:

Exception in thread "main" org.flywaydb.core.api.FlywayException: Unable to obtain Jdbc connection from DataSource
  at org.flywaydb.core.internal.util.jdbc.JdbcUtils.openConnection(
  at org.flywaydb.core.Flyway.execute(
  at org.flywaydb.core.Flyway.migrate(
  at com.whitestein.lsps.dbmigration.DbMigration.runFlywayCommand(
  at com.whitestein.lsps.dbmigration.DbMigration.migrate(
  at com.whitestein.lsps.dbmigration.DbMigration.main(
Caused by: java.sql.SQLNonTransientConnectionException: Public Key Retrieval is not allowed
  at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(
  at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(
  at com.mysql.cj.jdbc.exceptions.SQLExceptionsMapping.translateException(
  at com.mysql.cj.jdbc.ConnectionImpl.createNewIO(
  at com.mysql.cj.jdbc.ConnectionImpl.<init>(
  at com.mysql.cj.jdbc.ConnectionImpl.getInstance(
  at com.mysql.cj.jdbc.NonRegisteringDriver.connect(
  at com.mysql.cj.jdbc.MysqlDataSource.getConnection(
  at com.mysql.cj.jdbc.MysqlDataSource.getConnection(
  at com.mysql.cj.jdbc.MysqlDataSource.getConnection(
  at org.flywaydb.core.internal.util.jdbc.JdbcUtils.openConnection(
  ... 5 more

To remedy the situation, remove the useSSL=false parameter from the database URL.


How should I structure my project?

The recommended best practise is to structure your project as follows:

  • java folder with customized Application User Interface resources (LSPS Application);
  • model folder with the following GO-BPMN modules:
    • main: imports all modules and does not contain any resources itself
    • common: resources required by all parts of the process, such as, data type models, general queries and functions, constraints, cache regions, etc.
    • init: module with processes that initialize the business data, that is, create your users, assign the users respective rights, update or create persisted business data, instantiate models, etc.
    • modules with your processes and other resources;

Example project structure

Recommended project structure

LSPS launcher icon is displayed incorrectly in the launcher bar in Gnome.

In the lsps-design_64.ini in $PDS_HOME, add the following before vmargs:


Alternatively, add set the SWT_GTK3 environment variable to 0:

export SWT_GTK3=0

To-dos and Documents is temporarily unavailable.

If a to-do or document returns an error similar to the following, reset the to-dos and delete the relevant documents from the database (currently no API for this action is provided).

Processing failed. The to-do is temporarily unavailable.