Configuration Management

This chapter explains the configuration concept of Axon.ivy and describes the configuration editor and the various configuration types.

Configuration Management

Axon.ivy allows for individual configuration of many of it's features, specifically for the following:


Define environments for your project

Global Variables

Define global variables for your project and assign environment values for global variables.

Widget Styles

Define logical GUI styles for all available Rich Dialog widgets and containers.

Output Format

Define output formats for various data types.

Input Validation

Define validation policies for user input.

The specifics of the above described configuration types are explained in more detail in a separate section.

A configuration is always associated with a type (the type of object that it configures) and with an unique name. When applying a configuration to an object, only the name of the configuration must be given, because the type is defined by the object being configured.

By consistently defining and using the logically named configurations instead of setting properties individually on each configurable object you can later easily change or redefine the looks and behavior of the application in a single place.

All configurations can be created, edited and deleted using the Configuration Editor.


In Axon.ivy, each project has it's own configuration database.

Lookup of any configurations is performed by an (type, configuration name) request. If the look-up of such a configuration fails for the current project then the configuration databases of the required projects are searched with the same query recursively. With this mechanism, configurations can effectively be shared among projects.

Since the current project is always asked first for a specific configuration, you can easily overwrite configurations that come from a required project, simply by re-defining them locally (on the same type with the same name).


When creating a new project with the New Project Wizard you will be asked if default configuration content should be created for the new project. You should always disable this option if you're creating a project that will be dependent on other projects. If you don't disable it then all of the default configurations that are defined in the base project will be redefined automatically in the new project (and thereby shadow the inherited configurations), which may lead to unexpected behavior of the application.

If you unintentionally forgot to disable the option in the wizard you can still manually delete all configurations that have been created in the content database using the Configuration Editor at a later point of time.

Configuration Editor

The configuration editor is used to add/edit/delete configurations in the hierarchically organized configuration database of a project.

The configuration editor consists of different parts that are described separately below:

  • Configuration Tree

  • Configuration Editor Area (with header showing Type/Name of currently selected configuration)

  • Multi-Language Selector (not for all configuration types) This part is only visible if you have enabled the multi-language feature in the Axon.ivy preferences. Axon.ivy preferences > Configuration > Show Multi language Configurations

Generally, configurations are selected from the tree on the left hand side of the editor and edited in the details area on the right hand side. Modification of the configuration tree is performed with various actions that are available from the tree's context menu.


Axon.ivy Project Tree > double click on the entry in the tree.

Configuration Tree

The configuration tree shows the currently defined configurations inside a hierarchically organized tree. Configurations () are associated with a configuration class or configuration type () which in turn are logically grouped in a hierarchical folder structure ().

Only configuration nodes can be edited in the tree, the structure of the configuration database (i.e. the folders and types) is given by the system and cannot be changed.

The following operations are available from the context menu of the various configuration tree nodes:

Add configuration

Adds a new configuration below the selected configuration class node.


Renames the currently selected configuration.


Renaming of a configuration does not update the objects that currently use the configuration with the old name. I.e. objects or scripts that used the old configuration name may not produce the expected outcome anymore, because the specified configuration does no longer exist. Typically this leads to the fallback of using the default configuration of the respective configuration class.


Deletes the currently selected configuration node.


Deleting configurations may lead to the same effects as renaming them. See warning above for a description of the possible consequences.


Copies the selected configuration into a new configuration with a name prompted from the user.


Please note that you don't have to paste the new configuration, it will be pasted automatically next to the selected source configuration, because a configuration is always associated with exactly one configuration class. It is not possible to copy a configuration of type A to a type B.


Refreshes the configurations below the selected node.

Configuration Editor Area

The editor area shows a different editor depending on the configuration type (also called configuration class) of the currently selected configuration. The individual editors are described in the configuration types section.

The title bar of the editor area shows the type (i.e. the configuration class) and the name of the currently selected configuration as <ConfigClassName>/<ConfigurationName>.

Multi language Configuration Selector

Enable the multi selection configuration by setting the flag in the Axon.ivy preferences.

Some configurations can be defined in multiple languages because they contain language specific settings. The validation configurations may have to validate input differently if it is entered in another language.


Use CMS references for the error message property in order to support multiple languages.

The language selector is shown only for configurations that support multiple language values per configuration. Use it to select the language of the configuration that you want to edit.


Add new language value

Adds a value in a new language to the currently selected configuration. The contents of the last shown value are copied as initial content to the new configuration value.

Delete language value

Clicking on this button removes the currently shown value from the set of values for this configuration. Only works if more than one language value are defined.

Renderers Configuration

Renderer Configurations are used for specific Content Object when they are rendered, the result then is displayed on the client browser.

Smart Table Configuration Editor

The Smart Table Configuration editor is part of the Configuration Management. See Configuration Editor for more information. A Smart Table Configuration can be added by using the add configuration function. The name is used in the Smart Table Content Object Editor for choosing a specific Configuration.

The Smart Table Content Editor

Figure 8.1. The Smart Table Content Editor

Table Settings

The HTML attributes settings for the table and the caption HTML elements.

Header Settings

The HTML attributes settings for the table header group (thead element), the header row (tr element) and the header cells (th elements).

Body Settings

The HTML attributes settings for the table header group (thead element), the header row (tr element) and the header cells (th elements).

Footer Settings

The HTML attributes settings for the table body group (tbody element), the body rows (tr elements) and the body cells (td elements). Here it is possible to define different configuration for the rows and cells depending if they are displayed on an even or odd row position. The cells can also be different if they are in a even or odd column, in the first or last column or if they are in the column which is actually sorted. The first and last column settings does override the even or odd columns settings and the sorted column setting does override all other settings.

Sort Settings

Enter the text which is displayed in the header if a column is sortable. Then Ascending and Descending values are shown. When a column actually is sorted then the Sorted ascending or Sorted descending values are shown.

Page Selector Settings

Enter the format of the page selector, where it is shown (default: bottom) and the values displayed for the first, previous, next and last page to show. For the format there are the following possibilities:

{|<}Link to jump to the first page is shown with the value configured with the setting "First page".
{<}Link to jump to the previous page is shown with the value configured with the setting "Previous page".
{123}Links to jump to every page is shown with the page number.
{>}Link to jump to the next page is shown with the value configured with the setting "Next page".
{>|}Link to jump to the last page is shown with the value configured with the setting "Last page".
{n}The number of the actual page is displayed.
{m}The number of the total amount of pages is displayed.
{x}The number of the first showed row is displayed.
{y}The number of the last showed row is displayed.
{z}The number of the total rows in the table source is displayed.

Table 8.1. Format Symbols

Configuration Types

The configuration database of a project contains configurations for various configurable targets (e.g. widgets, date or time values, input text fields, etc).

The user can define configurations for the following three aspects of an application: formats, styles and validation. Each of those aspects encompasses a number of configurable types (e.g. date or time or number) for each of which an arbitrary number of named configurations can be defined, which can then be referred from different locations in the configuration.

This section briefly discusses the different configuration types and explains the usage of their respective configuration editors.

Format Configurations


Format configurations define how values of a specific type will be rendered when output to the user. Formats can be defined for all the base types of IvyScript, i.e. Boolean, Date, DateTime, Time, Number, and String. All non-null values of those types may be output as formatted strings by calling the format("<format name>") within any script.


panel.label.text = in.selectedDate.format("long");
out.invoice.customerNumber = wsData.customer.format("customer_id");


The format configuration editor allows to specify various ways of formatting for the different IvyScript base type values. The formatting options (described below) vary from type to type; not all options are available on all types.


Format configurations are always language dependent. Just watch the Preview editor area after each selection or option that you enable for an understanding what the effects are for each language.

Format Type

Select a predefined kind of formatting. The selected format kind may be further specified in the editor areas Option, Format Pattern and Format Script (depending on which kind that was selected).


This editor area is only available for some of the Number format kinds. The number of digits for the integer and/or fraction part may be selected (-1 stands for as many as needed). If you select grouping then a group character will be inserted to group the integer digits of the formatted number.

Format Pattern

This group is only available if you have selected the PATTERN format from the Format Type list.

If Pattern is selected as format then this combo box allows for a selection from a number of predefined patterns. Use Script if you'd like to specify an own pattern format.

Format Script

This group is only available if you have selected the SCRIPT format from the Format Type list.

Specify your own format with a script. The value variable will contain the value to be formatted. If you want to specify different patterns for different languages you should use the language selector to create multiple configurations for various languages.


Shows an instant preview of the configured formatting applied to a default value.

Style Configurations


Style configurations define the appearance of widgets when rendered as part of an user interface. Styles can be defined for each widget and container type separately, e.g. for Label, TextField or BorderLayoutPane. You can also specify general Styles that can be used for all container and widget types.

The Look up for the right settings to apply to a specific widget takes place in a provided order. The first match wins. Each of the following six pints will be evaluated respective to the project dependency:

  1. Local Style set via the Widget Configuration.

  2. Widget style (e.g. for a RLabel) set by a reference in the Widget Configuration.

  3. The style with the same reference as for point (2) of the RWidget type.

  4. Default style of the specific widget (e.g. RLabel).

  5. Default style of the RWidget type.

  6. Styles set in the Properties view or in the Java source code.


The dependent projects are browsed by a breadth first algorithm.


The style configuration editor allows to specify style properties for each widget or container type. Not all widget types have the same properties that may be specified.


The layout style properties are layout dependent. They may not have an effect, if the widget is added to a different layout than the property is intended for (mostly GridBagLayout). For example, the property weightX will not have any effect if the widget is added to a BorderLayoutPane.


Define general properties such as the font, the foreground color and the background color. Setting of the background color may not have an effect, if the widget or container do not have opaque to true (this is look-and-feel dependent).


The Look&Feel may override your settings. Specially the Background is usually overridden by the Look&Feel.

Layout Style

Settings to be used when the configured component type is placed within a specific layout.


Insets (i.e. inner padding) that should be applied to the component. Padding will be applied within the specified size (i.e. the actual size of a component is given by it's specified size minus the inset values).


Margin (i.e. outer padding) that should be applied to the component. The specified margin will effectively be added to the specified size of a component.

Alignment Position

Arrangement definition for components that have a text label and an optional icon.


Define the maximum, minimum and preferred size of a component. The specified values will be taken into account by the layout manager of the container where the component is added.

Input Validation Configurations


Validation configurations can be specified for the following types of input data: Date, DateTime, Time, Number, Percent and Regular Expression. The validation type Regular Expression(formal String) can be used to validate any kind of data. The result of a validation is always either true (valid) or false (invalid).

Each validation configuration contains of a set of general settings and a set of specific settings that are dependent on the selected type of validation.


The validation configuration editor allows you to specify various kinds of input validation that can be applied to user text input.

General Settings

A short verbose description of the validation. This text will be shown in the widget configuration to help selecting the correct validation.

Validation Message

Enter the message that will be displayed to the user on a tool tip, if the entered input is not valid. Use CMS (Content Management System) references here, in order to support multi language messages.

Specific Settings

Specific setting vary between the different validation types The list below describes all available settings.

FormatDefines the format on how the value will be presented to the user on the UI. Select a format out of your format configurations.

Table 8.2. Date Validation Type

FormatDefines the format on how the value will be presented to the user on the UI. Select a format out of your format configurations.

Table 8.3. DateTime Validation Type

FormatDefines the format on how the value will be presented to the user on the UI. Select a format out of your format configurations.

Table 8.4. Time Validation Type

FormatDefines the format on how the value will be presented to the user on the UI. Select a format out of your format configurations.
MaxMaximally permitted number value.
MinMinimally required number value.

Table 8.5. Number Validation Type

FormatDefines the format on how the value will be presented to the user on the UI. Select a format out of your format configurations.

Table 8.6. Percent Validation Type

Validation ExpressionA regular expression that the entered input must match. This expression is not evaluated until the field loses focus.
Input Filter ExpressionA regular expression that the input must conform to in order to be set on the widget. Default value is '.*'
Max Length Maximum length of the input text.

Table 8.7. Regular Expression (String) Validation Type

Validation Framework

The validation framework enables a Rich Dialog developer to implement the needs for GUI widgets that give feedback to the user about its entries in the GUI widgets. E.g. it draws a red background into a RTextField if the entered value does not conform to a date if a date is expected.

Supplied Features by the Validation Framework

Background Coloring

The background of the supported widgets can be colored do to its validation or mandatory state.

Tool tip

The tool tip of the supported widgets is decorated do to its validation and mandatory state.

Server Side Validation

Its possible to set a error on a supported widget from the server side.

Supplied Widgets

The framework supplies two widgets that are not on the palette: RErrorHeader and RErrorView.

Widgets of the Validation Framework

WidgetMandatory StateValidation Types
all RContainersinheritedinherited

Table 8.8. Supported Widgets of the Validation Framework


A CollapsiblePaneContainer that shows the current errors of the observedContainer widget in a list. The list will be updated as soon as some content or state of the observed container or its children changes.

Important properties: ShowMandatoryErrors, VisibleMessages

RErrorViewA widget that shows the errors of the observed container in a list. The list will be updated on each client-server round trip.

Table 8.9. Supplied Widgets by Validation Framework (not on the palette)


General framework configurations

Edit the file %AXON_IVY_INSTALL%/configuration/validationconfig.any in order to configure the framework for your needs. The configuration file lets you configure the following properties:


The message that will be displayed on the tool tip to the user if the mandatory field has no user changes.


Color of the background if the field has no user changes.


Color of the background if the field has erroneous user changes.


Set this flag to true if the background feedback should be enabled.


Set this flag to true if the background feedback should be enabled even if the widget is disabled.


The configuration file validationconfig.any changes the validation behaviour for the whole designer/engine not only for selected project(s). This setting will not be uploaded automatically but has to be set up manually on the Engine just like on the Designer.

Programming Interface (API)

The API of the Validation Framework is very slim. It consist mainly of a IValidator object per supported widget. To access this IValidator object you can call the method ivy.rd.getValidator(widget). Some widgets offer special properties to get validated values (e.g. valueAsNumber on RTextField if validated for number). In case the entered value is not accepted by the actual validation, then a so called INVALID value of the specific IvyScript type is returned by the widget (e.g. Date.INVALID from RDatePicker's valueAsDate property).

All RContainers implements the IEnabler interface, that enables those widgets to act as enabler for other widgets (E.g. a submit button).

The IValidator object returns IvyErrorObjects if you ask for pending errors on a IValidator.



getErrors() : List<IvyErrorObject>

getError() : IvyErrorObject

showErrorMessage(String errorMessage, Serializable illegalValue)

addPropertyChangeListener(PropertyChangeListener listener)

removePropertyChangeListener(PropertyChangeListener listener)

Table 8.10. ch.ivyteam.ivy.richdialog.server.validation.IValidator


getMessage() : String

getParameter() : Object[]

getError() : IvyErrorObject

getIllegalValue() : Object

Table 8.11. ch.ivyteam.ivy.richdialog.shared.IvyErrorObject


Server side validation cannot be used alone, it must be combined with a client side validation!


This section briefly discusses the usage of environments in your projects .Developers should have the possibility to configure multiple environments (pointing to an infrastructure) and decide at deployment, runtime and/or design time which environment should be used for the application. Here are some examples where environments can be used

  • Companies provide different environments for their software products, like Development, Test and Productive. Each environment has its own infrastructure including databases, web services and other connections used by the project.

  • Multi Client Capability. When the user logged into the system he can choose the client (German: Mandant) (e.g. Company 1, Company 2, etc.) and works with the data of the selected company. In the background the right databases connections, web services and other services for the selected environment will be used.

Actual projects use the CMS functionality to manage global Constants and set these constants every time on the engine when a new version of the project will be deployed. Another solution for this problem is the usage of property files which will be loaded by the application. If you use environments, the user only change the environment and all configuration settings of the environment will be used (e.g. database, web service, etc.) once. The system switch the settings in the background.


The environment editor is part of the Configuration Management. The basic handling of the configuration editor will be described here. By using the add configuration function a new environment will be added. The name of the environment is the name of the configuration.

Description of the environment

Provide a description of the environment. The description can also be used to describe some server IPs, specifics of the infrastructure and other interesting stuff.


Remove Environments If environment configurations are removed all environment values for global variables, databases and web services will also be removed. If you environments removed from projects included in the Library the values will also be removed in your project.


Rename Environments If environment configurations are renamed all configurations for global variables, databases and web services will NOT be replaced by the new name. This will be supported in a future version.

Environment settings

After the environment is created you can now assign environment values for different project objects. The environment settings for the project objects are done in their associated editors. Environment setting can be done for:

Global Variables

Assign environment values to global variables


Add environment connection properties to databases

Web Services

Add environment connection properties to web services

Change environment for Simulation

It is possible to change the environment for the Simulation by setting the Environment in the Preferences.

Change environment at runtime

It is possible to change the environment at runtime on Case, Session and Application Level. This is an essential feature in order to fulfill the requirements of an multi-client capability application.

Scope How to set in IvyScript
Case Scope name)
Session Scope ivy.session.setActiveEnvironment(String name)
Application Scope name)


The setActiveEnvironment(String name) methods throw a runtime exception if no environment with the given name exist.


How does the system check which environment is active?

The environment determination is a follows:

  1. Environment that is set on the current case.

  2. Environment that is set on the current session.

  3. Environment that is set on the current application.

  4. Default environment

Global Variables

Global Variables acts as global constants which can be used in your application. Global Variables are simple Key/Value pairs which can be specified by the developer. Some examples for global variables are:

  • Company data (name, address, contacts)

  • Simple Rule Values (e.g. credit account)

  • Path values for saving files

  • Path values for 3rd party systems and some other variables


The global variable editor is part of the Configuration Management. See Configuration Editor for more information. A global variable can be added by using the add configuration function. The name of the global variable is the name of the configuration.

Default value

Provide a default value of the global variable. This can be a Number or a String. This value will be used if you access the global variable in the application.


Provide a description of the global variable.

Environment settings

In this section the default value of the global variable can be overridden/new assigned for the specific Environment.

Access global variables in IvyScript

In order the access the Global Variables in your code a new environment variable var was introduced in IvyScript which provides a comfortable access to your defined variables. This approach has the advantage that, if global variables are removed developers will immediately informed in which process element the variable was used.

Database Configuration

This chapter deals with the database configuration. To use databases in your business or User Dialog processes you need to define some database configurations first. After you have configured the databases (data sources) you can use them in your process steps. The process steps references only the database configuration ids. So you can use different database configuration settings on your productive server.

Database Configuration Editor


The Axon.ivy database configuration editor lets you configure the databases you use in your project and the extending projects.

The Database Configuration Editor

Figure 8.2. The Database Configuration Editor


Add a new database configuration

Add environment

Add an environment configuration for the selected database. Select one or more environments for the environment list. For new environment configurations the standard configuration is taken. Please note, existing environment configurations will be overridden, if you add an environment twice.


Remove the selected database configuration

Test Connection

Test database connection. A dialog shows the result status if the database can be connected or not. In the case of a failure the reason will be displayed


Opens a SQL editor in order to set up SQL Statements. The SQL Editor displays the result in a result table


Axon.ivy Project Tree > double click on the Persistence label.


In the configuration editor you can define different Environments. The environments can be added to existing database configurations. For example it is possible to define a Database for your development, test and production environment. Depending on the Active Environment the associated environment configuration will used. If no environment configuration for a database is available, the default configuration will be used.

If a new database configuration is added to the container, the system automatically adds empty environment database configurations for each environment found in the project.


The root database acts as the default configuration and must always be set


You don't must define environment configurations for every database. If the database configuration is the same for all environments, only the default configuration is necessary.


All Database Configurations

A list of all database configurations defined in this project. A red or green icon indicates the result of the automatically executed connection test.

Database Connection Configuration

Shows the state of the automatically executed connection test.


Select the type and driver of the database you use. Some often used and tested drivers are shipped with the Designer. Additional drivers can be added by copying its JDBC driver Jar into the jre/lib/ext folder of your Axon.ivy installation.

The field max. connections lets you specify the number of concurrent connections to your database.

Connection Properties

Specify the properties for the connection to your database.

Additional Connection Properties

If your database needs more information you can use this section to define the additional properties.

REST Clients Configuration

The REST Clients configuration contains the definition of all REST services, which can be consumed from a BPM process.

REST Client

A REST Client can be referenced by its name or by its universal unique identifier (uuid). The uuid is generated when a new REST Client is created and will never change. The name of a REST Client is given when a new REST Client is created. It can be changed later. By referencing a REST Client by its uuid ensures that renaming of the REST Client will not break the reference.

Further information about how to use the REST Clients can be found in the chapter “Call remote REST Service”.

Like other configurations a REST Client can be configured differently per environment.

REST Client Editor

The REST Client Editor allows to configure REST Client default and environments configurations.

REST Clients Tree Editor

Shows the REST Clients and its environment configurations.

Add Client

Adds a new REST Client.

Add Environment

Adds a new environment configuration for the selected REST Client.


Removes the selected environment or REST Client configuration.

REST Client Details Editor

Shows the currently selected REST Client or environment configuration.

REST Client Section

Universal unique identifier of the REST Client. The REST Client can be referenced by this uuid. Cannot be modified.


The name of the REST Client. The REST Client can be referenced by this name. Can be modified. Note that references using the name will break if you change it.


Description of the REST Client.


The base URI under which the remote service publishes its resources (e.g.

The URI can contain template placeholders which are resolved later by the client user (e.g.{version})."twitter").resolveTemplate("version", "1.1").get()


To consume a REST service running in the same Axon.ivy Engine / Application as the client a set of Axon.ivy placeholders can be used. These placeholders are automatically resolved: {}, {ivy.engine.http.port}, {ivy.engine.context}, {ivy.request.application}.

E.g. http://{}:}{ivy.engine.http.port}/{ivy.engine.context}/api/{ivy.request.application}/my/service

Authentication Section
HTTP Basic

Adds support for HTTP Basic authentication.

HTTP Digest

Adds support for HTTP Digest authentication.


The name of the user used to authenticate the client.


The password of the user used to authenticate the client.

Features Section

Adds a feature so that responses in JSON are mapped to Java Objects and Java Objects in requests are mapped to JSON.

Features List

Shows the configured "features" classes. The classes configured here are registered in the WebTarget using the method register(Class). The classes needs to implement a JAX-RS contract interface and must have a default constructor.


Adds a new feature class.


Removes the selected feature.

Properties Section
Properties Table

Properties can customize the settings of the REST Client or one of its features.

Client properties

Well known properties of the client are documented here: org.glassfish.jersey.client.ClientProperties.

JSON properties

The JSON feature knows many properties that customize the serialization from JSON to Java objects and vice versa.

It is for instance possible to read a very complex JSON object with many fields back to a Java object that contains only a subset of these fields. To allow this incomplete but efficient mapping the property Deserialization.FAIL_ON_UNKNOWN_PROPERTIES must be set to false.

Consult the Jackson documentation for a list of all configurable items:


Adds a new property.

Add Password

Adds a new password property. The value of a password property is not visible in the table and is stored decrypted in the configuration file.


Removes the selected property.

Web Service Configuration

This chapter shows how web service configurations are organized. You get to know web service configuration views, tree entries, configuration types, and how to use, group, set up, change, and refer them.


Web service configurations are stored together and are represented as a tree. This configuration tree contains as many elements as you need in a structure you like. This is a kind of web service repository. The right place to store web service settings. There are three types of web service configuration nodes:

  • Web service group

  • Web service configuration

  • Web service environment configuration

Web service configuration nodes define a referable unit. Such an entry typically holds a WSDL, service access URL(s), accessing protocol versions, and optionally security configurations. A web service configuration can be referred in multiple Web Service process elements, which actually do the web service invocation. Some of the configurations can be overridden by the Web Service process element (e.g. authentication). The name of the web service configuration can be changed any time. The name is only an attribute and not used as reference key. Each web service configuration is in one of following two states, either:

  • Not referable or

  • Referable

A configuration starts its life as not referable. It means that it can not (yet) be used by Web Service process elements. Axon.ivy - just like Java - needs some client side service stub classes to be able to access a web service. These classes are generated using a WSDL file. WSDL files describe how the targeted web service should be accessed like (data types to use, available operations, etc.). Once these necessary client classes are generated, the web service configuration becomes referable. Only referable configurations can be selected in Web Service process elements. Web service groups are just like normal folders in the filesystem. They can contain web service configurations or other groups. Therefore, user can build a practical hierarchy according to his own needs.

Web Service Configuration Editor

With the help of this master-details editor you can build up your own web service configuration tree: Add, remove, and change both groups and web service configurations.


This chapter describes how to use the web service configuration editor. At the end you will be able to add, delete, and change your web service configurations.

Web service configuration tree editor

Web service configurations are displayed in a tree hierarchy. The tree editor helps to add and delete existing tree elements (web service groups, web service configurations and web service environment configurations).

Web service tree editor part

Figure 8.3. Web service tree editor part

In the editor the groups are symbolized with a folder icon. The web service configuration elements are symbolized with a globe icon. On the right side there are buttons offer following functions:

Add Configuration

Adds a new web service Configuration

Add Environment

Adds an environment configuration to the selected web service configuration. Select one or more environments from the environment list

Add Group

Adds a new web service group. These can be used to structuring your services.


Remove the current selection.


Entries you want do erase, might still be in use. It is encouraged to remove generated client classes as well with your service entry, but take care: some of these classes might be referred by other web service configurations as well.

Web service detail editor

Details of currently selected web service configuration node will be displayed on the right hand side. This editor helps to change details of an existing element (web service group web service configuration or web service environment configuration).

Web service configuration details part

Figure 8.4. Web service configuration details part

The web service configuration detail editor helps to change attributes of an existing web service configuration.

The following attributes are available in the Web Service Section:


The attribute specifies the displayed name of a web service configuration. The name is not used as identifier, so feel free to rename existing entries.


Description attribute is for own textual descriptions. Not used anywhere in ivy, but you are encouraged to fill it out. It helps years later to understand the exact purpose of web service configuration and the way it should be accessed.


Service details and classes will be generated using the WSDL specified here. Please use protocol prefix like:



The library that is used to generate the web service client classes. Unless you have some special reasons to use the older Axis implementation, please select Axis 2.x (faster, less memory usage, etc.). Note that you have to regenerate the web service client classes if you change this setting. Otherwise the setting will be set back once you save your changes.

Generate WS classes

When you specified the necessary fields: WSDL URL, and Library (Axis 1.x or 2.0) then you have to read the WSDL and generate client side classes to be able to access the web service (e.g. use its data types, read its operations, etc.). These generated files will be pre-compiled to be tested, and packed in jar file together. These jar files are located in the lib/ws_server folder of ivy project.

Note: when you change the WSDL URL, the WSDL itself or the Library you always have to regenerate service classes.

The following attributes are available in the Authentication section:


If this check box is set, then authentication is used to access the web service.


If the Use is checked, then here you can choose authentication type to use. Currently HTTP Basic, HTTP Digest and NTLM is supported.


Name of the user that will be applied to get access to this web service. You can use IvyScript in this field.


Password that will be applied to get access to web service. IvyScript is also interpreted in this field.


The host is used for NTLM authentication only. IvyScript is also interpreted in this field.


The domain is used for NTLM authentication only. Specify the Windows domain of the user that should be used to authentication the user. IvyScript is also interpreted in this field.


When you specify authentication in a Web Service process element, these settings (Type, Username, Password, Host, Domain) will be overridden. Use Scripts like in.user carefully, since you might use this web serivce configuration in multiple processes with different data types.

The following atributes are available in the Session Handling section:

Session handling

You can choose the session handling mode for current web service configuration. There are 3 modes available now:

  • NO there will be no session handling when you use this configuration

  • WSELEMENT invoking the same service from the same Web Service process element existing sessions will be reused

  • APPLICATION Within ivy applications whenever you invoke the same service existing session will be reused

The following attributes are available in the Ports section:


The list of ports will become available when you have already generated web service client classes. (see: Generate WS classes)

The content of this list comes from the WSDL specified above, and being interpreted by Axis. So that your web service provider/architect can give more information about.

A port type is something like a group of operations according to some technical or business criteria. It has got nothing to do with TCP/IP, UDP or firewalls. Port types quite an often reflect only SOAP versions used to access the same operations. In such case you normally see your port names ending with SOAP12, SOAP13, etc. If so, select the latest (biggest number)

Default endpoint

A URL is expected to be specified here. This is the URL where the current web service is located, and going to be accessed from. After client generation you might see URL-s here, because they can be specified in WSDL. If not, you have to set it up on your own. Value of this field depends on the "Port" selection, so that when you select another "Port" you might see another URL in this field.

Fallback endpoints

A list of endpoints can be specified here. They are used as fallback endpoints if any error happens during the web service request. First, the server at default endpoint will be requested. Servers on the list are queried one by one until a successful web service access can be made. You find error messages in runtime log when some endpoint invocations fail. If a service invocation is successful then the process continues as normal. This list is optional. When some servers are specified, then they are used, when not, then only the server at default endpoint will be accessed. If not even the default endpoint is specified then an exception is raised. (process continues with error handling). Like default endpoints the fallback endpoints depend on the "Port" selection.


In the configuration editor you can define different Environments. The environments can be added to existing web service configurations. Depending on the active environment the associated environment configuration will used. If no environment configuration for the web service is available, the default configuration will be used. You can now define one web service with environment specific connection properties. For example it is possible to define different web service endpoints for your development, test and production environment.


The web service configuration acts as the default configuration and must always be set


You don't must define environment configurations for every web service. If the web service configuration is the same for all environments, only the default configuration is necessary.

Roles and Users

Role is a widely used term in the computer industry and means a group of users of a certain system which share a common property. This enables an administrator to define configurations for this groups (roles) of users at once instead of defining it for each and every user individually. Axon.ivy incorporates a sophisticated role and user model to support:

  • Authentication - Who may login into Axon.ivy

  • Authorization - Control who is allowed to do what

  • Task assignment - Decide who has to perform a task in a workflow

  • User dependent UI elements - Configure who can see and operate on UI elements

In the following two sections you will learn how to create, edit and remove roles and users and how to link users with roles and vice versa.

Role Concept

The hierarchy of the roles is built upon the principle of specialization. Each child role specialises its parent role(s) meaning that a role Team A always implicitly contains its parent roles. The role Everybody is the root for all roles, all roles specialize this role. For example in the figure below, a member user of role Team A also has the roles Development and Everybody.

Member Role

A Member Role can be added as a child of an existing Role and links to another existing Role. While resolving the role tree, to collect the specializations of each role, the Member Role is handled like a normal child Role. Basically this simplifies the configuration and administration of roles.


The concept with Member Roles allows to create a sub-tree of roles with 'company roles' and a sub-tree of roles with 'permission roles'. The sub-tree of 'company roles' represents typically the structure of the company. The sub-tree of 'permission roles' represents the use or execution permission of a specific part or feature of an application. With a Member Role it is possible to assign a permission to a 'company role' by linking the 'company role' as a member role of a specific 'permission role'.

The following configuration illustration that users of group First Level and Team B have the permission for Process N and users of both support groups and of the Support Group itself has the permission for Process M.

+ Everybody
  + Support Group
    + First Level
    + Second Level
  + Development
    + Team A
    + Team B

  + Application Permissions
    + Process M
      - First Level (Member Role linked to role 'First Level')
      - Team B (Member Role)
    + Process N
      - Support Group (Member Role linked to role 'Support Group')

Role Editor

The role editor allows to create a new role and to edit and/or to remove existing roles and to structure them into a hierarchy. It can be started by double clicking on the Roles node in the Axon.ivy Projects view.

The Role Editor

Figure 8.5. The Role Editor

The left side of the Role editor consists of a tree showing all the roles in a hierarchy order. A click on one of the roles will show the properties for the selected role on the right side of the editor. The role hierarchy can be manipulated by dragging a role and dropping it at the new place in the hierarchy.


A new role is created as a child of the selected role.


A role is added as a linked member role to the selected role.


The selected role and all its children roles are removed. The user is obliged to confirm the removal. Note that the role Everybody may not be deleted.

Import XML

A .roleconfig file from another project can be imported for convenience reasons.

Export XML

All roles are exported in a XML file with the extension .roleconfig to easily re-use the role hierarchy.


The selected roles are sorted alphabetically, if desired this is performed recursively on the children.


Roles created in the designer are uploaded to the Axon.ivy Engine not until the deployment of the project. They are merged with all other roles in the same application context. Consider that the deployment will fail if the same role exist in more than one project in different role hierarchies.

Test User Editor

Process designers can create, edit and remove test users in the user editor. Users need a password in order to authenticate themselves and they need to be assigned to at least on role. The editor can be started by double clicking on the Test Users node in the Axon.ivy Projects view.


Test users are only used in the process simulation within the Axon.ivy Designer and they are not uploaded to the engine at the deployment. Users for deployed processes on the Axon.ivy Engine need to be created and configured on the engine.

The User editor

Figure 8.6. The User editor

The left side of the editor you see all users with their user names (i.e. login name) and their full names. On the right side the specific properties for the selected user on the left side is displayed. A user can be assigned to several roles and he is implicitly assigned to the parent roles of the roles, he explicitly is assigned to (see Role Editor for more precise details). Additional properties can be added to each user in terms of string key-value pairs and be reused within process steps in IvyScript.


Creates a new user with the specified name.


Removes a user from the list. The process designer is obliged to confirm the removal


Sorts the user list in alphabetical order


A .userconfig file from another project can be imported for convenience reasons

Export XML

All users and their corresponding properties are exported in a XML file with the extension .userconfig to easily re-use the users in another project.


You do not see the user called Developer, because it is a built in user, that belongs to each groups, and owns all rights. The user is meant to be used for testing, so that it exists only in the Designer. The password of this user is Developer (in case you would like to log in using IvyScript)

Configuration files

This chapter deals with configuration files of the Axon.ivy Designer


Configuration files are located in the configuration folder under the %AXON_IVY_INSTALLATION% folder. These files you have to edit out of Axon.ivy, e.g. using a system editor. It is recommended to stop your designer before you start changing these configurations.

There are some configuration files with extension *.xml. These are normal XML files. Meanwhile the *.any files are so called any files. There are a couple of any implementations - so that there is no real standard. The intension behind this is to have an easily to understand configuration with simple structure, and practically unlimited parameter types.


It is recommended to make a backup copy before you start changing configurations.


Using this file you can change logging preferences. This files contains a Log4j configuration. Log4j is an open source framework for logging. You can change logging format, logging destination (file, console, etc.), logging level and control which packages should be logged on which level.


The official web page of Log4j is Meanwhile all around the Internet you can find many articles and documentations.


Using this file you can change properties of the JNLP file that will be sent to client computers to start an Axon.ivy Rich Internet Application.

jnlpconfig.any is devided into tree sections: information, java and application-desc


Configure general information about the application like title or its vendor.


Configure parameters used for the Java virtual machine on client side like memory parameters, additional jvm arguments and the download-mode of jars.


Configure technical attributes of the application like client-site logging, tooltip behavior or the rich dialog session timeout.


Have a look into the file jnlpconfig.any. The configuration options are described in detail there.


By default, the lazy download of jars is set to false. This means, that all jars requred by the application are downloaded at startup. With a good internet connection, this will not be a problem. The application will start quite fast. In case the client is connected by a slow internet connection, it makes sense to enable lazy download of jars. But if lazy download is enabled, it will cause an overhead in the security certifacte validiation - each jar will be verified individually. This also takes a cerain amount of time.


Using this file you can change server side logging properties for ULC components. You can configure log level and log file. Sub-configurations can be defined per process model that receives the first request. If no log-file is defined, then System.err will be used as output of JNLP file that will be sent to client computers to start Axon.ivy application.