Configuration

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

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.

Warning

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.

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:

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.

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.

Rename

Renames the currently selected configuration.

Warning

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.

Delete

Deletes the currently selected configuration node.

Warning

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

Copy

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

Note

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.

Refresh

Refreshes the configurations below the selected node.

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.

Tip

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.

Features:

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.

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.

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:

Symbol	Description
{|<}	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

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

Purpose

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.

Examples:

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

Editor

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.

Tip

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).

Option

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.

Preview

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

Style Configurations

Purpose

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.

Note

The dependent projects are browsed by a breadth first algorithm.

Editor

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.

Note

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.

General

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).

Warning

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

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

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.

Size

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

Purpose

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.

Editor

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

General Settings

Description

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.

Format

Defines 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

Format

Defines 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

Format

Defines 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

Format	Defines the format on how the value will be presented to the user on the UI. Select a format out of your format configurations.
Max	Maximally permitted number value.
Min	Minimally required number value.

Table 8.5. Number Validation Type

Format

Defines 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 Expression	A regular expression that the entered input must match. This expression is not evaluated until the field loses focus.
Input Filter Expression	A 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

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.

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

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.

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:

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 a remote REST Service”.

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

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

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).

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:

Details of currently selected web service configuration node are displayed on the right hand side. In this editor details of an tree element (web service group, web service configuration or web service environment configuration) can be changed.

In the configuration editor you can define different Environments. Special setups can be defined this way for different environments web services are running in, e.g. production, test or development environments. This is the place where traditionally alternative authentication methods and endpoint URIs are configured for other execution environments.

Environments can be added to existing web service configurations. Depending on the active environment the associated environment configuration will used. The default configuration will be used if no or no matching environment configuration is specified for the web service.

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.

+ 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')

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.

Figure 8.4. 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.

New

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

Add

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

Remove

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.

Sort

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

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.

Figure 8.5. 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.

New

Creates a new user with the specified name.

Remove

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

Sort

Sorts the user list in alphabetical order

Import

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.

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.

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.

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

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.