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 .

Server configuration

  • The minimum required engine version is 6.0.0.49863

Add required libraries

Portal needs Apache POI for exporting to Excel features. Follow these steps to add Apache POI libraries:

  1. Copy libraries below and then paste into webapps/ivy/WEB-INF/lib folder located on AxonIvyEngine, AxonIvyDesigner.

    Note

    You can find libraries inside AxonIvyDesigner folder, under configuration/org.eclipse.osgi (search libraries in this directory), or download from this site.

  2. Restart AxonIvy Designer/Engine.

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

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

Manually configure servers, applications

Refer Setup multi portals .

Default user credentials

Portal provides 3 default users:

UsernamePasswordDescription
adminadminThis user has all Portal permissions, can access to Portal Admin Settings.
demodemoThis user has permission to manage user absences.
guestguestDefault normal user of portal.

Table 2.1. Default user credentials

Tip

You can change these accounts info in the AdminUI.

Role configuration

PortalKit rolesRights
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.

Substitute

  • CREATE OWN SUBSTITUTE

    This function will be disabled if session user does not have IPermission.USER_CREATE_OWN_SUBSTITUTE and IPermission.USER_CREATE_SUBSTITUTE.

  • MANAGE EVERY USER SUBSTITUTES

    This function will be disabled if session user does not have IPermission.USER_CREATE_SUBSTITUTE or IPermission.USER_READ_SUBSTITUTES.

Personal task permission

  • DELEGATE

    User can delegate his personal or group tasks if he has permission TaskWriteActivatorOwnTasks (This permission belongs to Portal permission group). User can delegate all the tasks he see in his task list if he 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.
  • SEE RELATED TASKS OF CASE

    Session user can see all related tasks of case if he has IPermission.TASK_READ_OWN_CASE_TASKS or IPermission.TASK_READ_ALL .

    Important

    Case state cannot to be: DESTROYED.

Upload/delete document permission

Upload/delete document function will be enabled if session user has IPermission.DOCUMENT_WRITE or IPermission.DOCUMENT_OF_INVOLVED_CASE_WRITE.

Express Workflow permission

  • CREATE EXPRESS WORKFLOW

    Create Express Workflow function will be enabled if session user has PortalPermission.EXPRESS_CREATE_WORKFLOW (This permission belongs to Portal permission group, assigned to role Everybody by default).

Statistics permission

  • ADD DASHBOARD CHART

    Add new charts function will be enabled if session user has PortalPermission.STATISTIC_ADD_DASHBOARD_CHART (This permission belongs to Portal permission group, assigned to role Everybody by default).

  • ANALYZE TASK

    Filter tasks and export data to excel for advanced analysis. This function will be enabled if session user has PortalPermission.STATISTIC_ANALYZE_TASK (This permission belongs to Portal permission group, assigned to user admin by default).

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

VariableDefault valueDescription
PortalStartTimeSynchUserExpression0 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 . Restart Ivy engine after changing this variable.
PortalCallWebserviceMaxRetry10 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.
PortalSearchDelayInMilliseconds500The delay time of search function at top menu.
PortalStartTimeCleanObsoletedDataExpression0 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 . Restart Ivy engine after changing this variable.

Table 2.3. Global variables

Look and feel

Portal doesn't use Modena theme from version 6.3.

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

  1. Replace all Portal projects
  2. Update PortalTemplate dependency of customer project in pom.xml.
  3. If PortalStyle is customized, copy logo, customization.less, font-faces.less, customized stuff from old to new PortalStyle, run maven to compile CSS.
  4. Follow migration notes.
  5. 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

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

Migrate 7.1.0 to 7.2.0

Portal needs Apache POI for exporting to Excel features. Refer to Add required libraries.

If you overrode task widget's data query described at How to override task widget's data query, follow these steps to migrate

  • Add new start method with signature buildTaskJsonQuery(Boolean) in your overridden file of BuildTaskJsonQuery.mod (refer to original file BuildTaskJsonQuery.mod).
  • If you customized TaskLazyDataModel, change withStartSignature("buildTaskJsonQuery() to withStartSignature("buildTaskJsonQuery(Boolean)").withParam("isQueryForHomePage", compactMode) in your customized TaskLazyDataModel class.

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

Important

In case you already have PortalStart process in your project, delete all elements in that process and copy everything from PortalStart process of Portal Template (to prevent start link id change). Do not delete PortalStart proccess in your project and copy new again.

Check map param result of callable process after copy to make sure it's the same as original process.

EXPIRY_CHART_LAST_DRILLDOWN_LEVEL global variable is removed. User now can use a context menu to drilldown Task By Expiry chart.

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, 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 customized Default user process, 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.

Important

In case you already have PortalStart process in your project, delete all elements in that process and copy everything from PortalStart process of Portal Template (to prevent start link id change). Do not delete PortalStart proccess in your project and copy new again.

Check map param result of callable process after copy to make sure it's the same as original process.

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, 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. 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, 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, deploy MigrateTaskCategorySample.iar to your application and run Migrate Task Category process to:

  1. Migrate data from column customVarCharField5 to category for all tasks in the application.

  2. Delete leftover data in customVarCharField5 of all tasks in the application.

  3. 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, refer to PortalStyle customization (logos, colors, date patterns) .

Steps to migrate

  1. Copy PortalStyle/webContent/resources of Portal 6.4 to PortalStyle/webContent/resources of the current Portal.

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

  3. Put custom styles to PortalStyle/webContent/resources/less/customization.less.

  4. Add properties and plugins which are defined in PortalStyle/pom.xml of Portal 6.4 to PortalStyle/pom.xml of the current Portal.

  5. Run the maven command mvn lesscss:compile in PortalStyle to build CSS file.

  6. PortalStyle/webContent/resources/css/theme.css is obsolete, 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.2

  • Introduced the variables to customize task priority and state colors and header bar colors

  • Introduces the new page: Global search result, and supports the customization

  • Overrides the DefaultApplicationHomePage.ivp, DefaultLoginPage.ivp, DefaultEndPage.ivp processes, refer to Replacement Project, check migration notes if you have the customized PortalStart.ivp process.

  • Portal checks permission when upload/delete document. User needs permission IPermission.DOCUMENT_WRITE or IPermission.DOCUMENT_OF_INVOLVED_CASE_WRITE to upload/delete document.

  • Support to disable upload/delete document when a case is done. This function can be configured by HIDE_UPLOAD_DOCUMENT_FOR_DONE_CASE setting.

  • Support to configure upload file extension whitelist. Only file extensions appear in this list are allowed to upload to Portal. This function can be configured by UPLOAD_DOCUMENT_WHITELIST_EXTENSION setting.

  • Support script checking function for upload file. You can enable/disable this function by configuring ENABLE_SCRIPT_CHECKING_FOR_UPLOADED_DOCUMENT setting.

Changes in 7.1

  • Portal supports client side timeout: informs user when session is about to expire and auto logout when expired.

  • Hide technical cases (the HIDE additional property is set), so that they and their related task are not displayed in any Portal case lists.

  • More search criteria for user in Case list are added and allowed to customize.

  • User can add new language. Refer to Language settings for detail.

  • Axon ivy express has custom end page. It can be turned off or customized.

  • User can create default start process with permission check. If the user doesn't have permission to start the process, it won't appear in favorite processes. Refer to Default user process for detail.

Changes in 7.0 (Jakobshorn)

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

    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. 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. Refer to Responsiveness for more details.

  • Some customizations are not supported in this release: main menu, case header.