Simulating process models

This chapter deals with Axon Ivy debugging and simulation features. Processes, workflows, User Dialogs and changes on these should be tested before being deployed on an Axon Ivy production Engine. Therefore the Designer allows to simulate processes on your local computer, to debug it in depth and to inspect the execution history of all variable values. Hereby the process flow can be animated to visually observe the actual process execution sequence.

Simulation

A simulation can be started directly on the Start or on the Designer Workflow UI Overview page displayed either in the browser view of the Process Development Perspective or in a separate browser window, depending on the setting in the corresponding preference. This Process Start Overview web page shows all processes that can be started by clicking on the link.

Also the Web Services are displayed on the Process Start Overview page. By clicking a Web Service Process link, the corresponding WSDL is displayed.

Start process on the Request Start element

Designer Workflow UI Overview Page

Tip

You can switch off the simulation of Process Start Events and Intermediate Process Events when you want to simulate or test other parts of a projects. Just set the corresponding options in the preferences.

Engine Actions

You are able to control the simulation and to influence the animation using the actions in the toolbar or the Axon Ivy menu.

Engine Sub-Menu

Starting the engine and show overview page

Select the entry in the menu or as button in the toolbar toolbar to start the Simulation Engine, open the Process Development Perspective and refresh the Process Start Overview page.

Starting the engine

Select the entry in the menu or as button in the toolbar to start the Simulation Engine and refresh the Process Start Overview page but without opening the Process Development Perspective.

Stopping the engine

Select the entry in the menu or as button in the toolbar to stop the Simulation Engine.

Adjust the engine animation speed

Select the entry in the menu or as button in the toolbar to show the slider to adjust the speed of the animation. This overwrites the corresponding setting in the preferences.

Suppressing the engine animation

Select the entry in the menu or as button in the toolbar to switch the engine animation on and off. This overwrites the corresponding setting in the preferences.

Content and Formatting Language Settings

This dialog allows to edit the content language and the formatting language. The language settings are used at design time for displaying the User Dialogs. If option Use settings while simulating is checked the settings are also used while simulating.

Accessibility

Press in the toolbar.

Settings

The following language settings can be configured:

Content Language

The content language is used to select the values of content objects.

Formatting Language

The formatting language is used when objects are formatted using the format() method.

Use settings while simulating

If checked then the content and the formatting language settings will be used while simulating. If not checked then the settings of the browser will be used.

How to use in IvyScript

To get or set the content or formatting language in IvyScript use ivy.session.contentLocale respectively ivy.session.formattingLocale.

Find out more about Axon Ivy’s scripting language IvyScript.

Breakpoints

A breakpoint is a marker that tells the simulation engine to pause the execution. It is then possible to inspect the execution history, to view the values of internal variables and evaluate user defined expressions without being interfered by the running execution. The execution must be resumed by the user explicitly over the functionality of the Debug View. You can see a list of your breakpoints and edit them in the Breakpoint View.

Process Element Breakpoints

A process element breakpoint is a breakpoint that can be set on a process element. The execution of the process will be interrupted before the process element is executed.

Add / Remove a breakpoint

You can add process element breakpoints in a Process editor or User Dialog Logic editor window by using the popup menu. Right-click on the process step on which you intend to set the breakpoint and go to the Breakpoint sub-menu.

Adding a conditional breakpoint allows you to define an expression in a input box which must evaluate to true in order to suspend the execution. In the expression you have access to the in variable and all other variables in the context of the process step. As you can see in the figure above, process element breakpoints are visualized in the Process editor as a small filled dot at the border of the process step .

Data Class Attribute Value Change Breakpoints

A data class attribute value change breakpoint is a breakpoint that can be set on a data class attribute. The execution of the process will be interrupted before the value of the process data attribute is changed. Data class attribute value change breakpoints can be added or removed in the Data Class Editor or the Entity Class Editor. The current available variables and the current debug context is available in the Variables View. The old and new value of the debugging field is displayed in the variable debug.

Note

The breakpoint only breaks if the value of an attribute is changed by an IvyScript write attribute operation (e.g. in.data.myField="Hello"). If the attribute is changed by a setter method then the breakpoint will not break (e.g. in.data.setMyField("Hello")).

Debugger

The debugger provides a set of views and features to inspect the execution (including its history) of your processes and User Dialogs. Akin to a debugger in an Integrated Development Environment (IDE) such as Eclipse, NetBeans or VisualStudio it is possible to set breakpoints to pause an execution, to iterate through executions step-by-step and to examine the history and the current state of the execution in depth.

Debug View

The Debug view shows in a tree per open project all the currently handled requests i.e. all processes under execution in the simulation engine.

Debug view in action

For each request to the engine the current state (i.e. the currently executed process step) are shown and can be manipulated individually with the following buttons on the toolbar:

Resume

Resumes the execution of the selected process/request until the end of the process to the next breakpoint

Terminate

Terminates the execution of the selected process/request

Step Into

This can be used to step into a (callable) process element. The current step is executed and then execution is suspended on the next step again.

Step Over

This can be used to step over a (callable) process element. The current step is executed and then execution is suspended on the next step in the current process.

Step Out

This can be used to step out of the current process, the execution is suspended again on the caller process element.

If you select a stack element then the process editor shows the process element that is executed at this stack element. Moreover, the Variables View will display the current values of the process data at the process element of the selected stack element.

History View

In this view you see the values of your process data (the in variable) during all runs of the currently selected process element in the process editor. The topmost tree entry shows the data of the first execution of the selected element during the first request whereas the entry at the bottom corresponds to the most current execution.

History view in action

The following buttons on the toolbar can be used to navigate to process elements and to configure the history:

Go to process element ()

Marks the process element in the process editor whose history is currently displayed.

Go to next process element ()

Shows the history of the next process element.

Go to previous process element ()

Shows the history of the previous process element.

History view preferences ()

Opens the preference page with the settings for the history.

Note

In case of memory shortage during simulation or due to history settings process data snapshots may be discarded. This is indicated by the message “history data no longer available”.

Breakpoints View

This view lists all the breakpoint which are currently set and offers some functionality to edit and filter single breakpoints.

Breakpoints view in action

You can configure and control the View with the toolbar and menu:

Remove Breakpoints ( )

You can remove either the selected process(es) or all processes.

Show Breakpoints Supported by Selected Target ()

Shows only the breakpoints in the list which are included in the process start under execution.

Go to File for Breakpoint ()

Opens an editor with the file containing the breakpoint or sets the focus on the corresponding editor window.

Skip all Breakpoints ()

If set, all breakpoints are skipped.

Tip

This is helpful when you need to debug only some executions of a process steps. You can skip the breakpoints at the beginning and switch this button off, when the execution reaches the part you are interested in.

Expand All / Collapse All ( )

If you have grouped the breakpoints together, you can quickly expand or collapse the whole tree

Link with Debug View ()

Links this view together with the Debug View.

Add Java Exception Breakpoint ()

Adds a breakpoint for a type of Java Exceptions, which will be used whenever this Java Exception is thrown throughout the execution.

Warning

Use this feature only if you are familiar with the Java programming language and its exception handling mechanism

Toolbar Menu ()

Here you can group the breakpoints according to some categories, select whether you want to restrict the view on a specific working set and set whether you want to see fully qualified names for breakpoints in Java code.

Variables View

This view shows a list of all variable in the context (or scope) of the currently executed process step. You are able to examine the structure, the types and the values of variables and it is even possible to change the values of variables which have a simple data type (such as String, Number, Boolean, Time, Date or DateTime). The view is divided into a variable tree showing the structure, value and type of each variable (including its members) and a detail pane that displays the values for deeper examination.

Variables View in action

Collapse All ()

Collapse the whole variable tree to its root items.

Toolbar Menu ()

Layout

You can switch on and off the detail pane, set its orientation (vertical or horizontal) and set whether and which columns should be displayed.

Detail pane

Setting for the size of the buffer for the detail pane, the higher the longer values you can examine (e.g. very long strings) but the more memory you use.

Wrap Text in Details Pane

Wrap text in details pane when it does not fit in the available space

Popup Menu

Select All

Selects all elements in the list.

Copy Variables

Copies all selected variables into the clipboard (e.g. for use in the Expressions View).

Find …

Allows to find a specific variable with a filter string.

Change Value …

The values of primitive Java data types may be changed here.

Create Watch Expression

Creates a new expression in the Expressions View.

Warning

Changing the value may cause exceptions or introduce undesired side effects with very weird behaviour in the continuation of the execution. Please use this feature with precaution!

Expressions View

In this view you can define expressions, evaluate them and examine their values (similar to the Variables View). In the expression you can use all valid IvyScript operators and language elements and at a certain point of time, only variables which are in the scope of the currently executed process step can be evaluated.

Expressions View in action

Show Type Names ()

Shows the type names of the variables in the front of the variable.

Collapse All ()

Collapse the whole expression tree to its root items.

Remove Selected Expressions / Remove All Expressions ()

You can remove either the selected or all expressions.

Toolbar Menu ()

Layout

You can switch on and off the detail pane, set its orientation (vertical or horizontal).

Detail pane

Setting for the size of the buffer for the detail pane, the higher the longer values you can examine (e.g. very long strings) but the more memory you use.

Wrap Text in Details Pane

Wrap text in details pane when it does not fit in the available space.

Popup Menu

Select All

Selects all elements in the list.

Copy Expressions

Copies all selected expressions and their state into the clipboard.

Find …

Allows to find a specific variable with a filter string.

Add Watch Expression …

Adds a watch expression into the expression view.

Reevaluate Watch Expression

Computes the current value of the expression (e.g. if expression reads data which was manipulated by concurrent threads).

Disable / Enable

Disables or enables the automatic evaluation of expressions when changes occur.

Edit Watch Expression …

Edits the selected watch expression.

Runtime Log View

The Runtime Log view displays a list of events. This events occur during the simulation. When you start the Axon Ivy process engine, this log view is opened by default and all entries are cleared.

Accessibility

Window > Show View > Runtime Log

Window > Show View > Other … > Other… > Axon Ivy > Runtime Log

Columns

The following columns are displayed in the Runtime Log view:

First narrow column without name

In this column an icon is displayed that symbolizes the type of logged event (info / warning / error message)

Request

The request (HTTP, etc. with its ID) is displayed in which the log message occurred.

Project

The name of the project the log event was logged in.

Element

The identifier of the process element which logged the event.

Category

The log category refers to the Axon Ivy part which has logged the event (e.g. user_code: ivyScript by user; process: log from/during process model execution).

Message

The event message is displayed here.

Logged Event Details

When you double click on a log entry, a detail window will appear.

Runtime Log View Event Details

The following fields are displayed in this window:

Time

Time, when the event was logged.

Request

The request (HTTP, etc. with its ID) in which the log message occurred.

Severity

Shows how serious the logged event is (debug, info, warning, or error).

Project

The name of the project the log event was logged.

Category

The log category refers to the Axon Ivy part which has logged the event (e.g. user_code: ivyScript by user; process: log from/during process model execution).

Element

The identifier of the process element which logged the event.

Message

The log message is displayed here.

Stack

If an exception was logged with the event, and it contains a stack trace (calling hierarchy), then it is displayed here.

On the right hand side the following buttons are located:

Previous event

Clicking on this button will open the previous event of the logged events list.

Next event

Clicking on this button will open the next event of the logged events list.

Goto User Dialog

This button is available only if the log event contains User Dialog information. Clicking on this button opens a new editor showing the User Dialog which that has logged the event.

Goto process element

If you click on this button a process is opened and the process element that has logged the event is selected.

Copy event details to clipboard

If you click on this button all log event information are copied to clipboard.

Save Error Report

If you click on this button an error report that contains information about the error, the designer machine and the current state of the Axon Ivy Designer.

How to log

This chapter describes how you can log to the runtime log.

Open any process elements that contain IvyScript (like: Step, Web Service, etc.) and type a script like the one you find in the figure below:

IvyScript to log into Runtime Log

Find out more about Axon Ivy scripting language IvyScript.

Process Performance View

The Process Performance View displays process performance statistics. This allows to analyse the performance and to detect long running and performance intensive process elements and processes. The view contains detailed information of each executed process element.

Process Performance View

Note

On the Axon Ivy Engine there is the possibility to dump out performance statistics to a comma separated value file (.csv). Check the Engine Guide for more information: *Monitoring > Process Element Performance Statistic and Analysis

Accessibility

Window > Show View > Other… > Axon Ivy > Process Performance

Analyse the Performance Statistic

All time values are in milliseconds. The execution of some process elements are separated in two categories internal and external.

Internal Category

The internal category is used for the execution time in the process engine itself without the external execution.

External Category

The external category is used for execution time in external systems. In the table below the process elements are listed which use the external category.

Process elements with usage of external category

Process Element	Internal Category	External Category
Database Step	Parameter-mapping, caching, output-mapping and ivyScript execution.	The execution of the SQL statement on the database server.
Web Service Call Step	Parameter-mapping, caching, output-mapping and ivyScript execution.	The execution of the Web Service on the web server.
E-Mail Step	Parameter-mapping	The interaction with the Mail-Server.
Program Interface		The execution of the defined Java-Class.

For each executed process element one entry in the view is created. See the table below which information is available.

Column Description

Name	Description
Entry ID	Entry ID, useful to order the entries by its execution
Process Path	The path to the process.
Element ID	The identifier of the process element.
Element Name	The first line of the process element name (display name).
Element Type	The type of the process element.
Total Time	Total time [ms] of internal and external execution.
Int. Executions	Total internal executions of the process element.
Total Int. Time	Total internal time [ms] of process engine executions.
Min. Int. Time	Minimum internal process engine execution time [ms].
Avg. Int. Time	Average internal process engine execution time [ms].
Max. Int. Time	Maximum internal process engine execution time [ms].
Ext. Executions	Total external execution count.
Total Ext. Time	Total external execution time [ms].
Min. Ext. Time	Minimum external execution time [ms].
Avg. Ext. Time	Average external execution time [ms].
Max. Ext. Time	Maximum external execution time [ms].