Administration

To create a new application, press the new application icon () in the Applications section. A dialog will prompt you to enter the following information:

Click Create to create the application. If you have chosen a security system other that Axon.ivy, a dialog will appear to configure it (see next section).

When you choose an external security system (e.g. Microsoft Active Directory) for a new application, you have to configure the connection to the directory server, to specify which users should be synchronized and how the attributes of these users should be mapped.

Users are synchronized as follows:

The user synchronisation is executed:

Figure 6.3. External security system configuration dialog

The external security system configuration can be changed by using the Edit button on Security System section of the application configuration screen.

This section contains the default settings for notification emails. The settings are used when a new user is created.

In this area of the Application Default User Settings dialog, you can select a deployed process model that contains notification processes for Daily Summary or for New Task notification respectively. Before you see any available processes in the combo box you have to deploy at least one PMV library including an Email Notification Process. Notification processes start elements has to conform the criteria described in the section Email Notification.

This section allows you to override the default pages (Application Home, Task List, Process Start List, Login and End) of an Axon.ivy web application.

You can create your own process model to display these pages or you can use the Axon.ivy Workflow UI (HTML Version). See section create new application to learn how to use the "Axon.ivy Workflow UI (Html Version)".

A process model can exist in multiple versions called process model versions. These versions allow you to make changes in a project and deploy it again without having to worry about the compatibility of currently running cases. If the new version is not working as expected, you can always go back to a previous working version.

To create a new process model, you have to select the application in which you would like to create it. Press the new process model button in the toolbar (). You will be asked for a name (typically you chose the name to be the same as the name of the project you intend to deploy within this process model) and an optional description.

Once you have created the process model, you can continue with adding a first process model version. To do so, select the process model from the tree on the left hand side and press the new process model version button (). You will be prompted to enter a name and an optional description again.

Applications, process models and process model versions all have an activation state. The process model version additionally has a release state.

Figure 6.5. Managing the activation state

To bring a process model version into the Active state, the process model version itself, the parent process model and the parent application have to be in the state Active. Furthermore, the release state of the process model version has to be in RELEASED or DEPRECATED. The same is necessary for all required libraries of that process model version.

When looking at the details of an application, process model or process model version you will always see a Configured state and a State. The Configured state is the one you can freely change and the State is the actual state that depends on the states of the parent process model and application and of the release state.

Figure 6.6. Managing the release state

Projects can depend on each other. The dependencies are configured in the deployement descriptor of the project. This dependencies are evaluated and resolved during the deployment of a project. On the process model version detail page you can press Dependencies... to see the resolved dependencies of the project deployed to the process model version. You see the process model versions that the current process model version requires. And also vice versa which process model versions require the current process model version.

To change a resolved dependency select the dependency and press Edit Selection. You can then select another version that fullfils the dependency requirements.

Figure 6.7. Project Dependencies

The deployment wizard can be started on the toolbar.

Figure 6.8. Command to Start the Deploment Wizard on the Toolbar

On the first page of the wizard select the projects that you want deploy. The projects can either be located on the server or on the client. If you select a folder then the wizard searches all packed (ivy archive) or unpacked projects located below that folders. If you select a *.zip file then the wizard searches all projects located inside the *.zip file. The found projects will be displayed. Select the projects you want to deployed and press Next.

Figure 6.9. Deployment Wizard - Source

On the second page of the wizard select the applications to which you want to deploy your projects and press Next.

Figure 6.10. Deployment Wizard - Target

On the third page of the wizard you see a preview of the actions the wizard will perform. Note, that the wizard automatically choose the process model and process model version where it deploys a project to. If everything is as you expect press Next. If you do not like the automatically default behaviour press Previous and then on the previous page Details to choose another configuration. More information about process model and process model version can be found in the previous chapter.

Figure 6.11. Deployment Wizard - Preview

On the fourth page of the wizard the projects are validated. If no errors are found you can press Next. If you get warnings please read them carefully and then decide if you want to proceed or not.

Figure 6.12. Deployment Wizard - Validate

On the last page of the wizard the projects are deployed. During the deployment a log is written which contains information about the tasks that are executed. Press Finish to close the wizard.

Figure 6.13. Deployment Wizard - Deploy

Makes simple deployment of Axon.ivy projects to an Axon.ivy Engine possible by copying the project into the deployment directory.

The deployment directory is by default the directory with the name 'deploy' in the Axon.ivy Engine root directory. It can be altered trough the system property 'Deployment.Directory'.

mvn com.axonivy.ivy.ci:project-build-plugin:6.1.0-SNAPSHOT:deploy-iar -Divy.deploy.iarFile=myProject.iar -Divy.deploy.engine.dir=c:/axonviy/engine -Divy.deploy.engine.app=Portal

<plugin>
	<groupId>com.axonivy.ivy.ci</groupId>
	<artifactId>project-build-plugin</artifactId>
	<extensions>true</extensions>
	<executions>
		<execution>
			<id>deploy.to.engine</id>
			<goals><goal>deploy-iar</goal></goals>
			<phase>deploy</phase>
			<configuration>
				<deployToEngineApplication>Portal</deployToEngineApplication>
				<deployEngineDirectory>c:/axonivy/engine</deployEngineDirectory>
			</configuration>
		</execution>
	</executions>
</plugin>

Business calendars are defined in a hierarchy. The children inherit all definitions of all its parents. All business calendars must directly or indirectly inherit from the Default business calendar.

The Start of Week defines the first day of a week. In Switzerland and its neighbour countries this is Monday. In other countries like Great Britain the week starts on Sunday.

The Working Time defines which time of a day is working time. E.g. 08:00-12:00, 13:00-17:00

The working time applies to all days which are not defined as free days. It is not possible to define different Working Times for different days.

The Free Days of Week define at which days of the week no work is done. E.g. Saturday, Sunday

The Free Days of Year define at which days of the year no work is done. These free days of the year will be free every year at the same day. E.g. 1.1. (New Years Day), 25.12 (Christmas).

The Free Easter Relative Days define days of the year no work is done. These free easter relative days will be free every year at another day depending on the easter day. E.g. 0 (Easter Day), 1 (Easter Monday), -2 (Good Friday).

The Free non-recurring Dates define non-recurring days when no work is done. These free non-recurring days will only be free once. E.g. 7.12.1931.

Environment configurations can be changed by double-click on the environment entry in the list. You will see that the environment acts as a container for global variables and external database configurations. The description of the environment can be used to provide important infrastructure information about the server, databases and other stuff, which can be relevant to other users.

Figure 6.15. Environment details

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:

Global variables must be defined at design time. It is not possible to create new variables on the engine. Each variable has a default value, configured at design time or in the default environment. In order to override the values of global variables for a environment just double-click the variable entry and override the values in the detail dialog. The default value of a global variable must be set in the Default environment.

Figure 6.16. Details of a global variable

If the global variable is a default one, the system asks you to override the value for the environment. If you press "yes" the value of the global variable is overridden for the environment. You can always reset the global variable, by pressing Reset to Default.

Figure 6.17. Question to override the default value of the global variable

If your projects use external databases, you have to configure the respective database connections on the engine. The first time you deploy a project that uses external databases, the database configurations of the project will automatically be added on the engine as well. Also available environment configurations which already done at design time, will be added. Since you probably use a test database during development and you want to use your production database on the engine, you can use the different environments to set a different configurations. Overridden Database configurations for an environment will be displayed with the icon . Default database configurations or database configurations which are not overridden for the environment will be displayed with the icon .

To change the connection settings, select on the entry for a database in the list. You will see the connection URL used to connect to the database in the selected environment, the maximum number of connections, all currently open connections and the last executed statements.

If the selected environment is not the default environment, and you select a database configuration, which has no environment connection settings, you only can configure it. If you press Configure, the system asks you to override the database configuration for the selected environment. Press Yes to override the database configuration for the environment. You can always reset the database configuration to the default one, by pressing the button Restore to Default in the detail dialog, or right click on the database in the list and use the Menu item Restore to Default.

Figure 6.18. Databases

You can directly edit the maximum number of connections that may be simultaneously used.

To change the connection settings, press the Configure button next to the driver and connection URL fields. This will bring up a dialog in which you can configure the database product, driver, hostname, database, username, password and additional connection properties.

Figure 6.19. Configuring the connection of an external database

If your projects use web services, you have to configure the respective Web Service on the engine. The first time you deploy a project that uses Web Services, the Web Service configurations of the project will automatically be added on the engine as well. Also available environment configurations which already done at design time, will be added. Since you probably use a test environment during development and you want to use your production environment on the engine, you can use the different environments to set a different configurations. Overridden Web Service configurations for an environment will be displayed with the icon: . Default Web Service configurations or Web Service configurations which are not overridden for the environment will be displayed with the icon .

In order to edit a Web Service configuration just select the Web Service from the list and the details of the selected Web Service will be displayed in the detail panel.

If your projects use REST Clients, you have to configure the respective REST Clients on the engine. The first time you deploy a project that uses REST Clients, the REST Client configurations of the project will automatically be added on the engine as well. Also available environment configurations which already done at design time, will be added. Since you probably use a test environment during development and you want to use your production environment on the engine, you can use the different environments to set a different configurations. Overridden REST Client configurations for an environment will be displayed with the icon: . Default REST Client configurations or REST Client configurations which are not overridden for the environment will be displayed with the icon .

In order to edit a REST Client configuration just select the REST Client from the list and the details of the selected REST Client will be displayed in the detail panel.

Each environment can define its own default business calendar which is going to be used to calculate time periods in working time if the environment is active. By default the global default business calendar is set.

Business calendars are defined on the Application (see chapter Application Business Calendar)

One or multiple environments can be exported into or be imported from a XML file. All configurations that belong to the selected environments will be exported or imported (see previous sub chapters). This can be used to transfer environment configurations from one Axon.ivy Engine installation to another. It is even possible to modify the exported XML before it is re-imported on the same or another engine.

The files can be chosen from the local computer that the user is working on or from the server.

Note, that the export/import log file does not have to be set. In any case, you will see an graphical log of the results during the export or import.

When clicking the Show... button next to number of users, you will be presented with a list of all existing users. You can create, edit and delete users. You can also set roles and permissions of any users individually.

Figure 6.21. List of all users

Creating a New User

To create a new user press the Create... button. Enter the information for the new user (the username must be unique within the application). All other fields are optional.

Figure 6.22. Creating a new user

For the email notification settings you can decide whether the user uses the defaults defined by the application (they are shown in light gray if you choose so) or whether you want to define specific settings for the user. Note that each user can manipulate these settings in the Workflow UI.

Edit roles

Click the Roles... button to change the roles of a user.

You can add a role to a user by selecting the role from the list and then pressing Add. To remove a role, select it and press Remove.

Some roles may not be editable. This can have multiple reasons:

• The role may be inherited (indicated by a grey checkbox and the text Inherited). A role is inherited if it is not explicitly set, but the user owns a sub role (see example: Role 1 is inherited because user owns Role 1.1 and Role 1.3).

• You are using an external security system (e.g. ADS). In this case, you can not edit roles that are linked to a group on the directory server. To add such a role, add the user to the corresponding group on the directory server.

Figure 6.23. Manage roles of a user

Properties

In this dialog it is possible to manipulate the properties of all users. Properties are key/value pairs that can be accessed at runtime trough IvyScript. If using the internal security system of Axon.ivy (see Configuring an External Security System for more information), then creation, editing and deletion are supported for all properties. If the users are synchronized with an external data source such as an MS Active Directory and a mapping between attributes from the corresponding user in the external system to the properties of the Axon.ivy user is configured, then editing and deletion of such properties is usually prohibited by the external security system and therefore not possible within Axon.ivy. Just use the interface to the external security system to manipulate the attributes directly there.

Figure 6.24. User properties

Just use the Add button to create new properties, the Edit button to manipulate the property value and the Delete button to remove the property again. Note, that editing of the value can be done directly in the table.

Press the Show... button next to the number of roles on the Security System section of an application to see a list of all existing roles.

The roles are defined in the projects that you deploy in your application. You can not add or delete roles on the engine!

The list shows the roles with their name plus, if available, the external security name in square brackets.

Figure 6.25. List of all roles

Users of a Role

To add or remove users of a role, click the Users... button. You should now see a list of users not owning the role on the left and a list of user that do own the role on the right. You can move users with the buttons in the middle from one list to another.

Note

When a user only inherits a role by owning a sub role thereof, the user will appear in the list of users not owning the role.

When a role is linked to a group in an external security system, you will not be able to edit the users of a role.

Figure 6.26. Users of a role

Use the system property DataCache.InvalidationJob.Interval to configure the time in seconds between two executions of the job that invalidates expired data cache entries.

Use the system properties EMail.Server.* to configure a SMTP mail server that is used to send mails. The available properties are similar to the Email preferences of the designer. For more information see Designer Guide > Introduction > Axon.ivy Preferences (Workspace Preferences) > Email Settings.

Use the system property Errors.ShowDetailsToEndUser to configure wether details about an error should be shown to an end user. For security reasons no details should be shown. For debugging reasons this option could be turned on temporary. For more information see Show Error Details to End Users.

Use the system properties ProcessEngine.FiringStatistic.* to configure the process element performance statistic. For more details see Process Element Performance Statistic and Analysis.

Use the system properties SSL.Client.* to configure the key and trust store used for the client side of SSL connections. The available properties are similar to the SSL Client preferences of the designer. For more information see Designer Guide > Introduction > Axon.ivy Preferences (Workspace Preferences) > SSL Client Settings.

Use the system property System.WorkDirectory to configure the directory where temporary work files are stored.

Use the system properties SystemDb.Cache.* to configure how many and how long entities from the system database are cached in memory.

Use the system property SystemTask.SearchJob.Interval to configure the time in seconds between two executions of the System Task Search Job. The job searches system tasks that were not executed because of failures and initiate their execution.

Use the system property SystemTask.Failure.Behaviour to configure the behaviour in case a System Task execution fails. A system task is a task that is executed by the system.

Use the system property ThreadPool.*.CorePoolSize to configure the number of threads that are at least used in the thread pool.

Use the system property ThreadPool.*.MaximumPoolSize to configure the maximum number of threads that are used in the thread pool. This property is not available for fixed sized thread pools.

Use the system property UpdateChecker.Enabled to configure if the update checker is enabled or disabled. The update checker checks if a new update release is available. It also sends some statistic information to the vendor. For more details see Update Notification.

Use the system properties WebServer.AJP.* to configure the AJP protocol used for the communication between IIS or Apache web server and the Axon.ivy Engine. For more information see Integration.

Use the system properties WebServer.HTTP.* to configure the HTTP protocol used for the communication with Web Browsers and Rich Dialog clients.

Use the system properties WebServer.HTTPS.* to configure the HTTPS protocol used for the communication with Web Browsers and Rich Dialog clients.

Use the system properties WebServer.External* and WebServer.IvyContextName to configure the external host name, port and protocol used to provide links in mails. For more information see Update external base URL.

Use the system property WebServer.WellKnownServerPorts to configure additionally well known external web servers that forwards requests to Axon.ivy engine. Format is host:protocol=port, host:protocol=port, ... . Example: developer.axonivy.com:http=80, developer.axonivy.com:https=443.

Use the system properties Elasticsearch.* to configure the bundled or external Elasticsearch server installation. For more details, see Elasticsearch installation.

Pressing the button Information in the Engine section of the left navigation bar will provide you with runtime information about the engine. This includes memory usage and stack-traces for all running threads.

Figure 6.30. Runtime information

Pressing the button About in the Engine section of the left navigation bar will provide you with information about the version of Axon.ivy Engine and your operating system.

Figure 6.31. About

In a HTML based workflow application there are certain pages displayed depending on the state of your application and/or workflow. You can override these default pages for each of your applications, to adopt it to your needs.

For each kind of page there is a predefined process start signature, which allows you to render the page in your own process instead of using the default page. The following table shows which signature is needed to override each type of page.

How to override the default pages:

By default Axon.ivy shows a page which simply says hello to the user.

Use a Request Start with the signature DefaultApplicationHomePage() to overwrite this behaviour.

This Request Start must either lead to an Web Page Element or an End Page Element.

By default this page displays all tasks the currently logged in user can work on. You can override this page to adopt it to your look and feel or to display your own list of tasks.

Use a Request Start with the signature DefaultTaskListPage() to overwrite this behaviour.

This Request Start must either lead to an Web Page Element or an End Page Element.

By default this page displays all Processes the currently logged in user can work on. You can override this page to adopt it to your look and feel or to display your own list of process starts.

Use a Request Start with the signature DefaultProcessStartListPage() to overwrite this behaviour.

This Request Start must either lead to an Web Page Element or an End Page Element.

By default Axon.ivy will show a page which says "You have successfully finished the task", when a task is finished and the process does not define a specific End Page.

Use a Request Start with the signature DefaultEndPage(Number endedTaskId) to overwrite this behaviour

This Request Start must either lead to an Web Page Element or an End Page Element.

By default Axon.ivy will show a simple login page, whenever a login is required. The page allows you to login with username and password and then redirects you to the original URL requested.

Use a Request Start with the Signature DefaultLoginPage(String originalUrl) to overwrite this behaviour

This Request Start must lead to an activity which does login a user. Normally this is done using a dialog which asks for username and password. But you are free to do anything to identify the user.

Normally the process should lead to an End Page which redirects to the original requested url. But you are free to do anything after the user is logged in.

Axon.ivy Engine is delivered with a sample HTML Workflow UI project. You can find it in the installation directory in the folder projects/HtmlWfUi.

If you want to use the sample project as it is, consult the section create a new application.

Axon.ivy Engine can send out email notifications on user task changes. These emails contain information on tasks that are available for users to work on. Notification subscriptions are configurable and the email content can be highly customized. In order to understand how it generally works it is recommended to read this section. This feature works only on engine versions, not in the Axon.ivy Designer. There are two types of notification emails:

Whether a user receives email notifications or not depends on application and user configurations. Engine administrators can set up initial settings for both notification types at user creation (see Application Default Settings). Later, users can specify their own notification settings using WorkflowUI (see WorkflowUI documentation). Email notification messages are created by the system and sent as email messages. Therefore make sure, that SMTP settings are set up correctly, check it in the System properties of your application.

Axon.ivy supports own email notification processes to influence the content of the emails. In case you set up such a notification process, then this process will be executed before the notification email is sent. There are two types of email notification processes:

Mentioned notification processes will be executed, and their HTML result will be used as email content.

Email Notification Process are used to customize the design and contnet of the mails sent if the standard mail notification is not proper for your company. It is advised to prepare the important details you want to display in the notification mails and prepare some screen designs as well.

Quick overview how to create notification processes:

More detailed description of non trivial steps are documented in the following section.

Create mail notification process

Create a normal process within your fresh Axon.ivy project. Place some process start element(-s), and put a simple process together. This process should display an HTML page, preferably using an Endpage process element to save engine resources. The HTML page defines the content of the notification mail while the <title> tag in the <header> section will be used as mail subject.

Figure 6.32. Example for both email notification process types

Notification process start elements must follow some naming and parameter conventions in order to be recognised by Axon.ivy Engine as potential email notification processes. Please create process starts as follows:

It is not supported to create multiple processes or process starts within the same project (PMV) for the same notification type (daily/new task). In case you create multiple matching process starts then it cannot be forecasted which process start will be used within the project (PMV library).

Created notification processes will be executed, and their HTML result - the page they display - will be used as content in the notification email.

Deploy

Start the Engine Administrator, deploy your project library as a process model and a PMV. It is important to deploy your notification project within the application you want to use it for.

Configure notification

Having deployed your notification process model in the application where you want to customize the notification make sure that the PMV is active. Go to the Application Default Settings, refresh GUI if necessary, and select the library ID of the PMV that implements the notification process you want to use for email notification. In case you implemented the process start properly, and the project including the notification process is deployed properly, you should see the library ID.

Having customized your email notification process(-es) users of specific application should receive their email notification prepared by your notification process.

You might still have some questions left: