Installation

Release installation

Installation

The installation section describes all the steps, that are necessary to install and setup the Process Application.

If you install the application for the first time than it's important to start with the Basic installation . It describes all the initial steps, that must be done for the first installation.

Release Installation

If the application is already installed and initial prepared, than refer to the Release Installation Steps, that are provided, here you will only find those steps, that are necessary to install this release.

Basic installation

Project modules

The application consists of 5 process modules. For detailed information of each module, refer to Architecture .

PortalStyle
PortalKit
PortalTemplate
SelfServiceBPM
AxonIvyExpress

The project deployment of Ivy project are described in project deployment .

Important

Portal Connector is already part of Ivy engine, only import it to your designer, NEVER install it to your application on Ivy engine. Doing it causes malfunction and unexpected behavior.

Server configuration

The minimum required engine version is 6.0.0.49863

Specify servers, applications used in Portal

General concept

Portal has 3 different configurations:

Single mode : Only one Portal application on one engine. The Portal application must include portalKit, portalTemplate and portalStyle modules. By default, portalConnector is already deployed on the System application of Axon Ivy engine.
Multi applications on single engine mode : Multiple Portal applications on one engine. Each Portal application must include portalKit, portalTemplate and portalStyle modules. Only one portalConnector of the System application is needed.
Multi applications on multi engines mode : Single or multiple Portal applications on multiple engines. The engines will communicate with each other via the portalConnector of their System application (This mode is not supported yet).

Important

In single mode, if you deploy a new Portal application with a customer project, you need to deactivate the standard Portal application.
In multi applications on single engine mode, if you do not need overall dashboard, deactivate the standard Portal application. Otherwise, keep the standard Portal application activated.

Automatically detect servers, applications

By default, PortalKit will connect to PortalConnector using the address specified by the system property WebServer.HTTP.Address . If the property is not set, PortalKit will use the address localhost to connect to PortalConnector. All applications of the server which have the logged-in user are used in Portal.

Note

System property WebServer.HTTP.Address specifies the address that will listen on the ivy engine port.

Steps to set the system property WebServer.HTTP.Address

Open AdminUI and go to System Properties.
Set the WebServer.HTTP.Address property to the value of the address that will be used to connect to PortalConnector.
Restart the ivy engine.

Manually configure servers, applications

Refer Setup multi portals .

Default user credentials

Portal provides 3 default users:

Username	Password	Description
admin	admin	This user has all Portal permissions, can access to Portal Admin Settings.
demo	demo	This user has permission to manage user absences.
guest	guest	Default normal user of portal.

Table 2.1. Default user credentials

Tip

You can change these accounts info in the AdminUI.

Role configuration

PortalKit roles	Rights
AXONIVY_PORTAL_ADMIN	User belong to this role can handle AdminUI page, configure the internal role properties, create public filters. Users who own this role need some permissions. See Permission settings .

Table 2.2. Role configuration

Permission settings

Absences

READ

This function will be disabled if session user does not have IPermission.USER_READ_OWN_ABSENCES and IPermission.USER_READ_ABSENCES.
CREATE/MODIFY

This function will be disabled if session user does not have IPermission.USER_CREATE_OWN_ABSENCE and IPermission.USER_CREATE_ABSENCE.
DELETE

This function will be disabled if session user does not have IPermission.USER_DELETE_OWN_ABSENCE and IPermission.USER_DELETE_ABSENCE.
MANAGE EVERY USER ABSENCES

User can read, add, delete absences of all users. This function will be disabled if session user does not have all of the following permissions: IPermission.USER_CREATE_ABSENCE , IPermission.USER_DELETE_ABSENCE , IPermission.USER_READ_ABSENCES.

Personal task permission

DELEGATE

This function will be enabled if session user has permission IPermission.TASK_WRITE_ACTIVATOR .

Important
Task state cannot be one of the following: DONE , DESTROYED , RESUMED , FAILED .
ADD NOTE

No permission requires.

Important
Task state cannot be one of the following: DONE , DESTROYED , RESUMED , FAILED .
RESET

This function will be enabled if session user has permission IPermission.TASK_RESET_OWN_WORKING_TASK or IPermission.TASK_RESET .

Important
Task state has to be one of following: RESUMED , PARKED .
PARK

This function will be enabled if session user has permission IPermission.TASK_PARK_OWN_WORKING_TASK .

Important
Task state has to be RESUMED .
CHANGE TASK NAME

This function will be enabled if session user has IPermission.TASK_WRITE_NAME .

Important
Task state cannot be one of following values: DONE , DESTROYED , FAILED .
CHANGE TASK DESCRIPTION

This function will be enabled if session user has IPermission.TASK_WRITE_DESCRIPTION .

Important
Task state cannot be one of following values: DONE , DESTROYED , FAILED .
CHANGE DEADLINE

This function will be enabled if session user has IPermission.TASK_WRITE_EXPIRY_TIMESTAMP .

Important
Task state cannot be one of following values: DONE , DESTROYED , FAILED .
CHANGE PRIORITY

This function will be disabled if session user does not have IPermission.TASK_WRITE_ORIGINAL_PRIORITY .

Important
Task state cannot be one of following: DONE , DESTROYED , FAILED .

Personal case permission

ADD NOTE

Add note function will be enabled if case state is RUNNING .
DELETE CASE

Delete case function will be enabled if session user has IPermission.CASE_DESTROY .

Important
Case state has to be RUNNING .
CHANGE CASE NAME

Delete case function will be enabled if session user has IPermission.CASE_WRITE_NAME .

Important
Case state cannot to be: DESTROYED.
CHANGE CASE DESCRIPTION

Delete case function will be enabled if session user has IPermission.CASE_WRITE_DESCRIPTION .

Important
Case state cannot to be: DESTROYED.

Administrator permission can see all tasks/cases in the application

Normal users can only see their tasks/cases they can work on.

Administrator can see all tasks/cases in the application.

Permissions needed: IPermission.TASK_READ_ALL , IPermission.CASE_READ_ALL .

Administrator permission can interact with all workflows in the application

Normal users can updates and deletes workflows which created by him and can interact with workflow's task which assigned to him.

Administrator can creates, updates and deletes all workflows in the application.

Global variables

Variable	Default value	Description
PortalStartTimeSynchUserExpression	0 0 5 * * ?	Cron expression define the time to reload application user datas. E.g.: expression for at 5AM every day is `0 0 5 * * ?` . Refer to crontrigger . Please restart Ivy engine after changing this variable.
PortalCallWebserviceMaxRetry	10	Maximum time that PortalConnector will retry to synchronize data to Portal on the system. If beyond this limit, system will create a Task for `AXONIVY_PORTAL_ADMIN` role to handle this error.
PortalSearchDelayInMilliseconds	500	The delay time of search function at top menu.
PortalStartTimeCleanObsoletedDataExpression	0 0 6 * * ?	Cron expression define the time to clean up data of obsoleted users. E.g.: expression for at 6AM every day is `0 0 6 * * ?` . Refer to crontrigger . Please restart Ivy engine after changing this variable.
PortalDeleteAllFinishedHiddenCases	false	If set to `true`, the cron job runs daily (at 6.AM as default) will clean all finished hidden cases in engine. Otherwise, just hidden cases which were generated by Portal will be deleted.
PortalHiddenTaskCaseExcluded	true	By default, portal will query tasks and cases which don't have hide information. Set it to `false`, portal will ignore this addtional property.
PortalHiddenTaskCaseCustomField	CustomDecimalField5	Name of custom field which store value of hidden task, case. It can be CustomVarCharField1, CustomVarCharField2, CustomVarCharField3, CustomVarCharField4, CustomVarCharField5, CustomTimestampField1, CustomTimestampField2, CustomTimestampField3, CustomTimestampField4, CustomTimestampField5, CustomDecimalField1, CustomDecimalField2, CustomDecimalField3, CustomDecimalField4 or CustomDecimalField5. If empty, it will store hidden info to addtional property name "HIDE". It only effects when PortalHiddenTaskCaseExcluded is set to true

Table 2.3. Global variables

Email settings

Task notification mail

Users can receive standard Ivy new task email notification. More information about the email notification can be found here .

Individual Mails

List of individual mails, that are send in the process.
Application specific mail is stored in the user profile within the attribute useCustomMails .The value of this attribute is True/False .

If True then this user will receive notification email send out from the process, otherwise they will not receive email.

Look and feel

Portal doesn't use Modena theme from version 6.3.

Please notice that all dialogs in Portal and screens of Self service BPM and Axon Ivy Express have following buttons orders:

Yes/Ok buttons on the left, No/Cancel buttons on the right

Migration notes

This document informs you in detail about incompatibilities that were introduced between Portal versions and tells you what needs to be done to make your existing Portal working with current Axon Ivy engine.

How to migrate

Important

In order to migrate Portal, you need to migrate Axon Ivy, refer Axon Ivy migration notes. Changes in Axon Ivy could lead to problems if the customer project is not migrated properly.

In designer

Replace all Portal projects
Update PortalTemplate dependency of customer project in pom.xml.
If PortalStyle is customized, copy logo, customization.less, font-faces.less, customized stuff from old to new PortalStyle, run maven to compile CSS.
Follow migration notes.
If customization needs copying code from Portal, merge changes between 2 version of Portal for copied code.

Important

Scenario migrating one customer project without customization: Follow the guidelines to step 2.
Scenario migrating one customer project with supported customization: Follow the guidelines.
Scenario migrating one customer project with (un)supported customization: Follow the guidelines for supported customization. If unsupported customization needs copying code from Portal, merge changes between 2 versions of Portal for copied code. Take care your own unsupported customization.

In engine

Convert database schema if needed.
Deactivate standard Portal application if it is not needed.
Redeploy Portal projects (exclude PortalConnector) and customer project.
Follow migration notes to migrate data, if any.

Migrate 7.0.x to 7.0.10

Migrate hidden task and case

If you use feature hide technical task and case by set addtional property, Portal 7.0.10 has option to store it in custom field of task and case instead of additional property for better performance.

In case you don't want to change the place to store information of technical task, case from additional property to custom field. You just simply set global variable PortalHiddenTaskCaseCustomField to empty.

Otherwise, you need to follow these steps:

Make sure PortalHiddenTaskCaseExcluded is set to true in each application(default value)
In each application, set PortalHiddenTaskCaseCustomField to one available custom field of your task and case e.g CustomDecimalField5. This value must be the same for all applications.
Deploy this project MigrateHiddenTaskCase.iar to all your portal applications
In each application, run start process MigrateHiddenTaskCase to migrate.
After migration finishes succesfully, run start process RemoveHideAddtionalProperty in each application to clean up HIDE addtional property. It will delete HIDE additional property of all tasks and cases in current application. So be careful with it.

Migrate 7.0.3 to 7.0.5 (or 7.1.0)

There are some changes in PortalStart process of Portal Template. If you have customized this process in your project, please copy the new PortalStart from Portal Template to your project and re-apply your customization.

We introduce new method findStartableLinkByUserFriendlyRequestPath(String requestPath) in ProcessStartCollector class. If your project has cutomized Default user process, please use this method to generate link to your process. If user doesn't have permission to start the process, this method will return empty string.

Migrate 7.0.2 to 7.0.3

If you have additional columns in your customized task widget, refer Task widget to adapt your customization in taskHeader section.

Migrate 7.0.1 to 7.0.2

In PortalStyle\pom.xml, update project-build-plugin version to 7.1.0 and run maven to compile CSS.

If changing password is customized, change method call PasswordService.mod#changePassword(String,String) to PasswordService.mod#changePasswordService(String, String) in this customization.

Custom fields in Portal task list can now be sorted properly. The method extendSort() of TaskLazyDataModel is changed to have a taskQuery parameter. If you override this method, please change your code to use the new parameter instead of using the queryCriteria taskQuery.

Portal does not have separate full task list in the homepage anymore. It's mean that you don't have to customize the task list in /layouts/DefaultHomePageTemplate.xhtml. You can remove your task list customization code in PortalHome.xhtml.

If you have added new language to Portal by adding cms entry /AppInfo/SupportedLanguages in your project. Please move this entry to Portal Style.

Migrate 7.0.0 to 7.0.1

Ajax error handling: By default, Portal handles all exceptions from ajax requests. Old configuration, customization of ajax error handling should be removed.

Migrate 6.x to 7.0.0

If you copy the PortalStart process or the PortalHome HTMLDialog for customizations, please adapt the changes:

The whole process is refactored to be clearer. So it is recommended that you copy it again.
New process is introduced: restorePortalTaskList.ivp
PortalStart: some new ivy scripts are added to handle the navigation back to the same page before starting a task.
PortalHome: The taskView parameter is added to the start method.

SQL conversion

From Portal 7.0 , we use standard Axon Ivy Task Category field to store task category.

To migrate task categories, please deploy MigrateTaskCategorySample.iar to your application and run Migrate Task Category process to:

Migrate data from column customVarCharField5 to category for all tasks in the application.
Delete leftover data in customVarCharField5 of all tasks in the application.
Create CMS entries for task categories in the application.

If you have queries which referring to task category, plese replace customVarCharField5() part with category() part.

Migrate 6.4 or 6.5 to 6.6

Task header is supported to be customized. The useOverride param, which is used to override the task item's body, is changed to useOverrideBody
If you customize TaskLazyDataModel, remove that customized class and customize as How to override task widget's data query.

Migrate 6.4 to 6.5

If compilation error "The type org.apache.axis2.databinding.ADBBean cannot be resolved" occurs, refer Project compilation classpath to fix.
The relative link in default user processes starts with ivy context path instead of "pro". If there are customized default user proceses, append context path at the beginning. E.g. in Portal 6.4, it is /pro/.../PortalStart.ivp. In Portal 6.5, change it to /ivy/pro/.../PortalStart.ivp. You may use : ivy.html.startref(...) or RequestUriFactory.createProcessStartUri(...) to generate links.

Migrate 6.x (x < 4) to 6.4 (Jakobshorn)

Portal appearance

Portal 6.4 are redesigned. Therefore many components look different from the previous version like menu, task list, case list ... . Portal BasicTemplate does not use p:layout and p:layoutUnit anymore. You may need to adapt your pages to this change.

For now the menu customization is not supported.

From 6.4 , Portal applies LESS to support customizing Portal styles. You can customize colors, fonts and Portal's component styles. For more information about customizing Portal's style with LESS, please refer to PortalStyle customization (logos, colors, date patterns) .

Steps to migrate

Copy PortalStyle/webContent/resources of Portal 6.4 to PortalStyle/webContent/resources of the current Portal.
Modify PortalStyle/webContent/resources/less/theme.less, update value of @body-background-color for the background color and @menu-color for the menu, button color.
Put custom styles to PortalStyle/webContent/resources/less/customization.less.
Add properties and plugins which are defined in PortalStyle/pom.xml of Portal 6.4 to PortalStyle/pom.xml of the current Portal.
Run the maven command mvn lesscss:compile in PortalStyle to build CSS file.
PortalStyle/webContent/resources/css/theme.css is obsolete, please remove it.

Migrate 5.0 (Rothorn) to 6.0 (Säntis)

Database conversion

If you are using Portal 5.0 , you have to manual configure all settings (create servers, applications, variables) again since Portal now doesn't use external database. All settings on from Portal 6.0 are stored in Ivy system database. If you are using Portal 6.0 , you don't need to convert database.

Portal appearance

Portal now doesn't use Modena theme, it's a big difference to previous 6.0 . Therefore many things in Portal 5.0 and 6.0 will not look the same in new Portal. Many things have been redesigned like menu, task list, case list ...

Release notes

This part lists all relevant changes since the last official product releases of Axon Ivy.

Changes in 7.0.15

Portal variable for Global growl setting DISPLAY_MESSAGE_AFTER_FINISH_TASK displays growl message for two situations: finish task and leave task.

Changes in 7.0.10

Hide technical task / case can be configured using additional property or custom field (more performance).
Hide Statistic widget can be configured in Admin setting.

Changes in 7.0.9

Portal version 7.0.9 .. 7.0.x latest is compatible with Portal Connector latest (of 7.0.x latest engine).

Changes in 7.0 (Jakobshorn)

Introduced the variables to customize task priority and state colors
More search criteria for user in Task list are added and allowed to customize.
Task delegate customization is supported
The same task list is displayed before and after a task. Set default end page to another project to remove this feature.
Task category of Portal is now stored in new Task category field of ivy.

Please refer to Migration notes to learn how to migrate data from customVarCharField5 to new category field.
Hide technical tasks (the HIDE additional property is set), so that they are not displayed in any Portal task lists.
Change password is supported to be customized. Please refer to Change password process to know how to customize this feature.

Changes in 6.6 (Jakobshorn)

Task widget's customization is extended with task header and task data query.
Hide technical roles (the HIDE property is set), so that they are not displayed anywhere (e.g. delegate, absence mgmt). The default hidden role is AXONIVY_PORTAL_ADMIN

Changes in 6.0 (Säntis)

Portal has 2 level menu with animation.
All components such as button, text field ...have been re-styled, not applied Modena's styles.
Portal supports responsiveness with 3 screen widths: 1920, 1366 and 1024. Please refer to Responsiveness for more details.
Some customizations are not supported in this release: main menu, case header.