LSPS documentation logo
LSPS Documentation
Configuration and Monitoring

You can configure and monitor the LSPS Server via JMX or in the LSPS_SETTINGS database table and can be changed via JMX:

  • Monitoring (HealthCheck) provides statistics on LSPS Server
  • Settings exposes server and database related setting
jmxlspssetting.png
LSPS Server settings in jconsole

Monitoring the LSPS Application

To check the health of the LSPS Application, open a JMX-compliant monitoring tool, such as JConsole, and check the attributes under com.whitestein.lsps.HealtCheck:

  • JMXQueueSize: current amount of JMX messages queued for processing
  • NumberOfMICorrectInvocations: the number of successful invocations on all model instances since server start
  • NumberOfMIFailedInvocations: the number of failed invocation on all model instances since server start
  • AverageTimeOfAllCorrectInvocations: the average execution time of all successful invocations in milliseconds
  • AverageTimeOfLastTenCorrectInvocations: the average execution time of the last 10 invocations in milliseconds
  • AverageMILockWaitTime and AverageOfLastTenMILockWaitTimes: total average and average of the last 10 waiting times when accessing model instances

    Model instances run in a single thread and can be hence accessed by one entity at a time. While accessed, the instance is locked and other entities wait for the lock to be released: this time is used to calculate the average model-instance-lock wait time. when synchronizing model instances

  • NumberOfMaxLoopExceeded: the number of times that a loop exceeded the maximum allowed number of loop runs

    The maximum number of loops is set by the MaxNumberOfEngineLoops setting.

  • NumberOfThresholdLoopExceeded: the number of times that a loop exceeded the threshold number of loop runs
  • DBResponseTime: time to receive database response
  • NumberOfCurrentActiveUsers: number of active users (only relevant if user tracking is enabled.)
jconsole_healthcheck.png

Server and Database Settings

LSPS configuration is generally stored in the LSPS_SETTINGS database table and can be changed directly in the database or via JMX. For some setting changes, the server needs to be restarted: the applicable information is provided with individual settings.

Note that some settings, such as debugging settings, are passed as system properties to the server, that is, in the format -Dkey=value.

jconsole_settings.png
LSPS settings in MBeans
db_settings.png
LSPS setting in database

General Settings

SSO_ENABLED (SsoEnabled): Enabling SSO in UI

When true and the application server is configured to use SSO, the application checks if the current user exists in the application and is active when creating a new Vaadin UI.

CUT_LONG_STRINGS (CutLongString): Cutting a String in Database

  • When true, strings longer that the length defined in database are cut.
  • When false, write of such strings results in an error.

Default setting: false

The setting is loaded on server startup and can be changed in the LSPS_SETTINGS table or via JMX. When changed via JMX, the database value remains unchanged.

REPLACE_UNSUPPORTED_XML_CHARACTERS (ReplaceUnsupportedXMLCharacters): Replacing Unsupported XML Characters

  • When true, unsupported XML characters are replaced with the replacement character \uFFFD on model-instance marshalling.
  • When false, unsupported XML characters cause an exception on model-instance marshalling.

Default setting: false

The setting is loaded on server startup and can be changed in the LSPS_SETTINGS table or via JMX. When changed via JMX, the database value remains unchanged.

Model Related Settings

ENABLE_DROP_CREATE: Enabling Drop-Create Database-Schema Update

  • When true, models with the drop-create strategy can be uploaded.
  • When false and the user attempts to upload a model with the drop-create strategy, the upload fails with an exception.

Default setting: true

When changed in the LSPS_SETTINGS table, the change is reflected in runtime immediately.

INITIAL_MODELS_SQL: SQL with Model IDS loaded on Launch

SQL that returns IDs of model that should be loaded on server launch.

The setting is loaded only on server launch.

CONFIRM_MODEL_UPLOAD (ConfirmModelUpload): Requiring Confirmation on Model Update

  • When true, the user is prompted to confirm model upload on each upload.

The setting is loaded on server launch and can be changed in runtime via JMX (When changed via JMX, the database value remains unchanged).

Default setting: false

SERIALIZE_MODEL_UPLOAD: Serializing Models on Upload

  • When serialize, models are serialized on upload.

Default setting: serialize

When changed in the LSPS_SETTINGS table, the change is reflected in runtime immediately.

MaxNumberOfEngineLoops and ThresholdNumberOfEngineLoops: Preventing Infinite Looping

A single execution step in a model instance is referred to as a loop: A loop moves tokens and checks repeatedly the status of various elements and data to make sure that the data, such as goal statuses, is correct when the loop finishes.

If the loop ends up in an infinite loop, for example, if one condition is switched from true to false within the loop continuously, the server terminates the looping based on the MaxNumberOfEngineLoops and ThresholdNumberOfEngineLoops setting:

  • When a loop is repeated for more times than the number defined by ThresholdNumberOfEngineLoops, the NumberOfThresholdLoopExceeded attribute is bumped.
  • When a loop is repeated for more time than the number defined by MaxNumberOfEngineLoops, the execution fails with a runtime exception, the transaction is rolled back and the NumberOfThresholdLoopExceeded attribute is bumped.

User Tracking

USER_ACTIVITY_TRACKING (UserActivityTracked): Enabling User-Activity Tracking

  • When true, periods when the user is active are logged in the LSPS_USER_ACTIVITY_TRACK table.

Default setting: false

On change, restart the server to apply the change.

USER_ACTIVITY_TRACKING_TIMEOUT (UserActivityTrackingTimeout): Setting Timeout for User Activity

  • Time period in milliseconds: if a user is idle for the specified time period, logged period of activity is finished (the user is considered inactive).

Default setting: 600000 (10 minutes)

Note: You can access the user-activity data through the UserTrack shared record.

Performance

INTERPRETATION_STRATEGY (InterpretationStrategy): Setting Interpretation Strategy of a Goal Process

Interpretation strategy of the LSPS Execution Engine

  • When set to FULL_PARALLEL, Goal conditions are checked whenever any of the Goals changes its status or a token is moved.
  • When set to BPMN_FIRST, the engine first pushes all the tokens in Plans as far as possible and only then checks Goals and their conditions.

Default setting: FULL_PARALLEL

The setting is loaded on server startup and can be changed in runtime via JMX (When changed via JMX, the database value remains unchanged).

TIMER_INTERVAL (TimerInterval): Setting Interval for Timed Trigger

The smallest interval for sending a timed trigger in milliseconds. If there are multiple time notifications scheduled for a Model instance (for example, by multiple Timer Intermediate Events), and the time difference between the notifications is smaller that the TIMER_INTERVAL value, the notifications are merged into one (multiple Timer Intermediate Events are notified by a single timer notification)

If set to 0, timer notifications are not merged.

Default setting: 0

The setting is loaded on server startup and can be changed in runtime via JMX (When changed via JMX, the database value remains unchanged).

STATISTICS_ENABLED: Enabling Hibernate Statistics

Availability of Hibernate statistics (equivalent of hibernate.generate_statistics)

The option is by default disabled. You can enable it from JConsole: you can enable the setting for individual modules from the MBeans tab under com.whitestein.lsps > Statistics > MODULE > Attributes > StatisticsEnabled. To enable the setting for the entire application, modify the server.properties file in the application EAR (lsps-app-ear/lsps-app-ejb.jar/server.properties)

Do not enable the setting in production environments since it can cause performance issues.

jconsole_statistics.png

Logging and Exceptions

DUMP_MODEL_INSTANCE_ON_EXCEPTION (DumpModelInstanceOnException): Dumping A Module Instance on Exception

If set to true, model instance state is dumped when an exception occurs. The setting is loaded on server startup and can be changed in runtime via JMX (When changed via JMX, the database value remains unchanged).

Default setting: false

CREATE_PROCESS_LOGS(CreateProcessLog): Creating Process Logs

The setting defines whether events that occur during model-instance execution are logged. The events include such information as when the model and process started, when a process elements was executed, etc.

They are stored in the LSPS_PROCESS_LOGS system-database table. The data is used, for example, by views in the Management Perspective and Management Console.

Note: If you are looking for information on other logging mechanisms, please, refer to FAQ

Possible values:

  • MODULE: the setting of the module is respected.
  • YES: process logs are created for all modules regardless of the Create process log module setting.
  • NO: process logs are not created for any modules regardless of the Create process log module setting.

Default setting: MODULE

To clean old entries from the process log, use the delete-old-process-logs.<DB_NAME>.sql script available in <LSPS-RUNTIME>/scripts/lsps/<YOUR_DB>/

Important: If you set the property to NO, information about model-instance status and execution history, such as, when a model instance started, a to-do was submitted, timer event triggered, etc. will not be available. As a result:

  • Model Instance details in the Management Perspective and Management Console will not be available.
  • BAM reports might not contain correct data.

LINES_OF_EXPRESSION_LOGGED_IN_EXCEPTION (LineOfExpressionLoggedAtException): Numbers of Expression Lines in Exception

Number of lines before and after the statement with the problem included in the stack trace (0 means all: the entire expression is returned). The setting is loaded on server startup and can be changed in runtime via JMX (When changed via JMX, the database value remains unchanged).

Default setting: -1

Note: You can display SQL statements issued by PDS to the server in the console to troubleshoot the statements. Refer to information on performance tuning.

Debugging

Important: In production, the debugging parameters must not be active.

The debugging parameters are passed as JVM properties -Dkey=value.

  • com.whitestein.lsps.vaadin.ui.debug

If true, the modeling ID set on form components is used as Vaadin debug ID on all Vaadin components.

  • lspsDebug

If true, the Execution Engine runs in debug mode (usually activated in combination with remote socket debugging).

  • lspsProfile

If set to true, profiler is enabled.

Authentication

LSPS uses the authentication mechanism of the underlying application server. The users are authenticated against the LSPSRealm.

If you want to authenticate users against other directory services, modify the configuration of your application server.

For example, to authenticate against LDAP in WildFly, add another login module to the security domain.

Note that you need to make sure that all persons from your directory service have their counterpart in the LSPS: For example, insert a new person to the LSPS using the web service API. Similarly, remove any removed persons.

Example WildFly login module configuration

<subsystem xmlns="urn:jboss:domain:security:1.1">
    <security-domains>
        <security-domain name="lspsRealm" cache-type="default">
            <authentication>
                <login-module code="com.whitestein.lsps.security.jboss.LSPSRealm" flag="optional" module="com.whitestein.lsps.security">
                    <module-option name="password-stacking" value="useFirstPass" />
                    <module-option name="dsJndiName" value="/jdbc/LSPS_DS" />
                </login-module>
                <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="optional">
                    <module-option name="password-stacking" value="useFirstPass" />
                    <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" />
                    <module-option name="java.naming.provider.url" value="ldap://myurl:111" />
                    <module-option name="bindDN" value="cn=SA_LDAPReadOnly,ou=Service Accounts,dc=uss,dc=net" />
                    <module-option name="bindCredential" value="passwd" />
                    <module-option name="baseCtxDN" value="ou=INCOMM,dc=uss,dc=net" />
                    <module-option name="baseFilter" value="(sAMAccountName={0})" />
                    <module-option name="rolesCtxDN" value="ou=INCOMM,dc=uss,dc=net" />
                    <module-option name="roleFilter" value="(sAMAccountName={0})" />
                    <module-option name="roleAttributeID" value="memberOf" />
                    <module-option name="roleAttributeIsDN" value="true" />
                    <module-option name="roleNameAttributeID" value="cn" />
                    <module-option name="parseRoleNameFromDN" value="false" />
                    <module-option name="allowEmptyPasswords" value="false" />
                    <module-option name="searchScope" value="SUBTREE_SCOPE" />
                    <module-option name="allowEmptyPasswords" value="false" />
                    <module-option name="throwValidateError" value="false" />
                </login-module>
                <login-module code="org.jboss.security.auth.spi.RoleMappingLoginModule" flag="optional">
                    <module-option name="rolesProperties" value="../standalone/configuration/roles.properties" />
                    <module-option name="replaceRole" value="false" />
                </login-module>
            </authentication>
        </security-domain>