Miscellaneous

Rich Dialogs

Provide Custom ULC Widgets

The chapter Concepts > Extensions > Rich Dialog Clientside Libraries > Provide custom ULC Widgets in the Axon.ivy Designer Guide explains how to provide Custom ULC Widgets.

Provide Customer Rich Dialog Client Certificate

If a client starts the first time a Rich Dialog a security information dialog box pops up showing information about the publisher of Axon.ivy and its certificate. For some clients it may be confusing that a certificate from the provider of Axon.ivy is displayed instead of the certificate of the web site or the company they working for.

The chapter Extensions > Rich Dialog Clientside Libraries > Provide Customer Certificate in the Axon.ivy Designer Guide explains how to provide customer Rich Dialog client certificate.

Rich Dialog Session Timeout

The normal session timeout has no effect to Rich Dialogs because they send recurring requests to the server in shorter intervals than the session timeout. Therefore you can configure a special timeout feature for Rich Dialogs. It detects if an open Rich Dialog was not touched for the configured time and stops that Rich Dialog application. The user will receive a message so that he knows why the Rich Dialog has been closed. You can choose whether you want to have a Rich Dialog message box or if you want to see the message in your browser. With the former, the Rich Dialog and the session is closed only after the user confirmed the message. With the latter, the Rich Dialog and the session is closed immediately when the timeout happens thus freeing the server side memory. In this case you can even adapt the HTML file that is used. It is the file webapps/ivy/info/time_out.jsp.

To configure the Rich Dialog session timeout just go to the file configuration/jnlpconfig.any and adapt the settings for it.

Rich Dialog Look and Feel

The look and feel that is used for Rich Dialogs can be configured per applications. To change it open in the AdminUI the application and change the configuration property ria.lookandfeel.

Compressed client libraries

Rich Dialog clients download many jars during the first startup. If the network connection of the client is poor, it is possible to speed-up the download by sending compressed pack200 jars. It will speed-up the download time, but the client will require more resources to unpack the downloaded jars.

In order to send compressed jars they must be provided within the /clientlib directory of the engine. The following sample script will create these pack.gz files. The script must be run within the engines clientlib directory. Note that the pack200 binary comes from a JRE or JDK.

On Windows:

for /R %f in (.\*.jar) do pack200 "%f.pack.gz" "%f" 

On Linux:

for f in `find signed -name '*.jar'`; do
  echo "packing $f"
  pack200 $f.pack.gz $f
done

If the script runs successfully the clientlib directory contains files ending with pack.gz next to the normal jars.

ULC Load Tests

ULC Load is a product from Canoo Engineering AG to make load tests on ULC Applications (such as Rich Dialogs are). This chapter describes how to use ULC Load together with an Axon.ivy Engine.

Requirements

  • Axon.ivy Designer installation

  • Axon.ivy Engine installation

  • ULC Load 3.0.4

  • Java Runtime Environment (JRE) 1.6

Note

ULC Load is not shipped with Axon.ivy and needs a separate licence. It can be obtained from Canoo Engineering AG (http://www.canooo.com).

IvyTeam AG does not provide any support for ULC Load. Please contact Canoo Engineering AG to get support for ULC Load.

Note

If you run ULC Load with JRE 1.7 you cannot save your test plan. Ensure you have installed a JRE 1.6. If it is not possible to uninstall JRE 1.7 reconfigured the property lax.nl.valid.vm.list=1.5+ to lax.nl.valid.vm.list=1.6 in the property file bin/ULC Load 3.0.4 UI.lax of your ULC Load installation directory.

Install ULC Load

  • Start the installation of ULC Load.

  • At the Step Named Choose Canoo RIA Suite select the ulc directory of your Axon.ivy Designer Installation.

    Note

    The Axon.ivy Designer must have been started at least one time. Otherwise the ulc directory needed for the ULC Load installation is not available.

  • Finish the installation of ULC Load

  • Edit the File ULC Load 3.0.4 UI.lax in the bin directory of your UlcLoad installation.

    Look for the line which starts with lax.class.path=.

    Add an entry to the end of this line which points to the ivyUlcExtension-*.jar file in the clientlib/signed folder of your engine installation.

    Add an entry to the end of this line for each library in the clientlib/signed/windows_64_native folder of your engine installation. If you are using an other operating system than Windows 64 bit, use the libraries of the operating system you are running ULC Load with.

Prepare Engine

ULC Load will only work correctly with Axon.ivy Engine (Designer) if you change the following line in the context.xml file in the directory webapps/ivy/META-INF/ of the engine/designer installation directory:

<Context antiResourceLocking="false" privileged="true">

change to:

<Context antiResourceLocking="false" privileged="true" useHttpOnly="false">

Record a Test Scenario

  • Start ULC Load

  • Create a Recorder

  • Configure the Recorder

    • Add all jars in the clientlib/signed folder of your Axon.ivy Engine installation to the classpath.

    • Choose the IvyClientCoderRegistryProvider as Client Coder Registry Provider

    • Copy the URL of the process you want to start to the Application URL Field and replace the prefix /ivy/pro with /ivy/ulcload.

      Example: If you want to test the process with the URL http://localhost:8080/ivy/pro/abc/IvyDemos/1215975017F13818/demoRunner.ivp you have to use the Application URL http://localhost:8080/ivy/ulcload/abc/IvyDemos/1215975017F13818/demoRunner.ivp

  • Click the Record button. This starts the application and records every action you do. The recording automatically stops when the application is closed.

Note

It's not possible to change the look and feel for recording tests. The application will always start with the default swing look and feel. As ULC Load does not run any client side code when executing the tests, the look and feel wouldn't have any effect on the testruns anyway.

Warning

It's not possible to test processes which use Html Pages. When the process comes to an Html Page step ULC Load will display an error.

Run Load Test

  • There are no special configuration necessary to run a Load Test.

  • When recording a test, ULC Load creates a Thread Group which contains all recorded actions. With the menu Run -> Start these actions can be replayed.

  • On the Thread Group itself its possible to configure how often the actions are replayed and with how many concurrent users.

HTML Dialogs

Primefaces Theme

The default Primefaces theme that is used in Html Dialogs can be configured in the web.xml. It can also be configure per application. To change it open in the AdminUI the application and change the configuration property jsf.primesface.theme. Moreover, the theme can also be set per session. See Java class ch.ivyteam.ivy.jsf.primefaces.theme.IvyPrimefacesThemeResolver in Public API for details.

Replacing Java Runtime with newer version

If you want to use profiling tools such as VisualVM it may be required to replace the bundled Java Runtime (JRE) with a newer one. To do so, just perform the following steps:

  1. Download the full Java Development Kit (JDK) that suits best for your OS and Ivy-Installation (a 32 bit Ivy Engine cannot be run with a 64 bit runtime). It is important that you download the JDK and not the JRE. You will find the JDK at the Sun/Oracle Java website

  2. Install the downloaded JDK on the server (or on any computer with the same OS)

  3. Move the whole content of the directory jre in the installation folder of your Axon.ivy Engine to some other folder (to have a backup).

  4. Copy the whole content of the folder jre in the installation directory of the JDK to the jre folder in the installation folder of your Axon.ivy Engine (the one you moved in the step above)

Warning

Changing the Java Runtime that is packaged with Axon.ivy Engine is not recommended and should only be done when requested by Axon.ivy support or when required for testing purposes.

Update Notification

When newer Axon.ivy versions are available a message will be displayed on the Axon.ivy Engine main web page. The message contains information about the new versions and where those can be downloaded.

Note

While checking for new versions the following statistic information are sent to the update server. These information are only used to improve the product.

  • Engine (version, up time)

  • Configuration (number of: cluster nodes, users, licenced users, applications, process model, process model version, deleted process model version, running cases, running tasks)

  • Licence information (number, organisation, individual)

  • Operating system information (name, version, architecture, number of processors)

  • System database (product name and version, driver, identification number)

  • Java memory information (maximum heap memory, maximum non heap memory)

  • JVM (Java virtual machine) information (version, vendor, name)

  • Host information (host name, SHA-256 hashes of IP address and MAC address to identify the host without being able to read the original IP address and MAC address itself)

Note

If you do not want that update notification messages are shown or that statistic information are sent to the update server then you can set the system property UpdateChecker.Enabled in the Admin UI to false. This will turn of the whole update checker service.

Tool Reference

AxonIvyEngine

Axon.ivy Engine program. This program starts an instance of the Axon.ivy Engine.

Tip

On Windows Axon.ivy Engine can also be started as a Windows Service. More information about Axon.ivy Engine Windows Service can be found in the section AxonIvyEngineService tool reference chapter.

Tip

On Linux an instance of Axon.ivy Engine can also be started as a systemd service. More information how to install Axon.ivy Engine as a systemd service can be found in the section InstallService of the tool reference chapter.

Options

The following options are available for the Axon.ivy Engine program:

OptionDescriptionMandatory
-startStarts the engine. Same behaviour as if no options are given. Allows to stop the engine by pressing a key in the console if a console is available.no
-startdaemonStarts the engine. Does not allow to stop the engine by pressing a key in the console.no
-stopStops the engine. Only initiate the stop but will not wait until the engine has really stopped. no
-stopdaemonStops the engine. Will wait until the engine has really stopped.no
-statusPrints the current status of the engine.no

Table 8.1. AxonIvyEngineConfig Options


Launchers

The following program launchers are available for the Axon.ivy Engine program:

PlatformConsole supportLauncher
Windowsnobin/AxonIvyEngine.exe
Windowsyesbin/AxonIvyEngineC.exe
Linuxyesbin/AxonIvyEngine

Table 8.2. AxonIvyEngine Launchers


AxonIvyEngineConfig

Axon.ivy Engine Configuration program. The program is used to configure the Axon.ivy Engine. The program supports two modes:

  • graphical user interface mode and

  • headless mode which needs no graphical user interface on the server machine.

Note

More information can be found in the chapter Configuration

Options

The following options are available for the Axon.ivy Engine Configuration program:

OptionDescriptionMandatory
-headlessActivates the headless mode. Useful if no graphical user interface is installed on the server machine.no

Table 8.3. AxonIvyEngineConfig Options


Launchers

The following program launchers are available for the Axon.ivy Engine Configuration program:

PlatformConsole supportLauncher
Windowsnobin/AxonIvyEngineConfig.exe
Windowsyesbin/AxonIvyEngineConfigC.exe
Linuxyesbin/AxonIvyEngineConfig

Table 8.4. AxonIvyEngineConfig Launchers


AxonIvyEngineService

Axon.ivy Engine Windows Service. This program is the implementation of the Axon.ivy Engine Windows Service. But it can also be used to register, unregister, start and stop Axon.ivy Engine as Windows Service.

Note

You can also register, unregister, start and stop the Axon.ivy Engine Windows Service with the Control Center.

Options

The following options are available for Axon.ivy Engine Service program:

AxonIvyEngineService [-start|-stop|-register [username password]|-unregister]

OptionsParametersDescriptionMandatory
-start Starts the Axon.ivy Engine Windows Serviceno
-stop Stops the Axon.ivy Engine Windows Serviceno
-register Registers the Axon.ivy Engine Windows Service within Windowsno
 usernameThe user name of the user in which context the windows service should runno
 passwordThe password of the user in which context the windows service should runyes, if username is specified
-unregister Unregisters the Axon.ivy Engine Windows Service from Windowsno

Table 8.5. AxonIvyEngineService Options


Launchers

The following program launcher is available for the Axon.ivy Engine Service program:

PlatformLauncher
Windowsbin/AxonIvyEngineService.exe

Table 8.6. AxonIvyEngineService Launchers


EngineConfigCli

The console program is used to configure the Axon.ivy Engine. E.g. configure, create or convert the database.

Options

OptionDescription 
helpShows which commands and options are possible. 
<command> helpGet help to a specific command e.g. EngineConfigCli config-db help 

Table 8.7. EngineConfigCli Options


ControlCenter

The Control Center program. With Control Center program you can start and stop the different Axon.ivy Engine types. The Control Center allows you to change the configuration of the Axon.ivy Engine and on Windows even the configuration of Axon.ivy Engine Windows Service.

Note

More information can be found in the section Control Center of chapter Configuration

Launchers

The following program launchers are available for the Control Center program:

PlatformConsole supportLauncher
Windowsnobin/ControlCenter.exe
Windowsyesbin/ControlCenterC.exe
Linuxyesbin/ControlCenter

Table 8.8. ControlCenter Launchers


InstallService

The install service program helps to install the Axon.ivy Engine as a systemd Linux daemon. To install the service:

  1. cd to the bin/ directory of your Engine

  2. Run following command as root: ./InstallService.sh

  3. Accept the directory of your engine installation.

  4. Set the user and group under which the Engine service should run. Must not be root. Typically, a special user with limited access right should be used.

  5. Start the Engine service with systemctl start AxonIvyEngine.service to check if it works.

  6. Check the current status of the service with systemctl status AxonIvyEngine.service

  7. If you want to start the Engine service on the system start, execute following command: systemctl enable AxonIvyEngine.service

Tip

For more information about systemd services consult man systemd and man systemctl.

Launchers

PlatformConsole supportLauncher
Linuxyesbin/InstallService.sh

Table 8.9. InstallService Launchers


Windows Program Launcher Configuration

All windows program launchers can be reconfigured with an additional ivy launch control file (*.ilc). The ivy launch control file must have the same name like the launcher itself but instead of the extension *.exe it must use an extension *.ilc.

Tip

If you want to reconfigure the AxonIvyEngine.exe launcher, then copy the Example.ilc file and rename it to AxonIvyEngine.ilc.

The ivy launch control file is a text-based property file. The file has the following format:

# comment line
property=value
property=value

Open the file with a text editor to reconfigure it. Most properties found in the ivy launch control file are used to modify java virtual machine options. The following list shows all available options and explains them:

PropertyJVM OptionDescription
ivy.heap.max.ratioyesThe maximum heap size (-Xmx) in percentage of the physical memory of the machine.
ivy.heap.max.sizeyesThe maximum heap size (-Xmx) in megabytes.
ivy.heap.start.sizeyesStart heap size (-Xms) in mega bytes.
ivy.heap.free.max.ratioyesThe maximum free heap memory (-XX:MaxHeapFreeRatio) in percentage of the current heap size.
ivy.heap.free.min.ratioyesThe minimum free heap memory (-XX:MinHeapFreeRatio) in percentage of the current heap size.
ivy.heap.young.max.sizeyesThe maximum young heap size (-XX:MaxNewSize) in megabytes.
ivy.heap.young.min.sizeyesThe minimum young heap size (-XX:NewSize) in megabytes.
ivy.heap.eden.survivor.ratioyesThe survivor heap size as ratio between the eden and the survivor heap size (-XX:SurvivorRatio)
ivy.heap.tenured.young.ratioyesThe young heap size as ratio between the tenured and the young heap size (-XX:NewRatio).
ivy.jvm.typeyesThe Java virtual machine type to use (ClientHotspotJVM, ServerHotspotJVM).
ivy.dir.auxnoThe directory where the ivyTeam jars are located.
ivy.dir.jrenoThe directory where the java runtime environment is located.
ivy.java.main.classnoAn own Java class to launch instead of ivy engine's main starter class.
ivy.java.main.methodnoAnother Java static method to launch on the ivy.java.main.class instead of the default main method. The called method should take the same arguments as a Java main method.
ivy.vm.additional.optionsyesAdditional Java virtual machine arguments
ivy.garbage.collector.optionsyesAdditional garbage collector arguments. See too GC Optimization.
ivy.windows.service.namenoThe name of the Windows service (only for Windows service launcher).
ivy.application.namenoThe name of the application (only for application launcher).
ivy.application.singletonno Is the application a singleton (true, false; only for application launcher).

Table 8.10. Ivy Launch Control Properties


The properties that are bold are the most used properties.

Linux Launcher Configuration

The Java virtual machine (JVM) options for the Engine are configured in the AxonIvyEngine.conf file. For all other helper programs the JVM options are configured in the control.conf file.

Tip

If you want to configure the memory (-Xmx, -Xms, etc.) or optimize any other JVM options of the Engine then edit the AxonIvyEngine.conf file.