Installation

The Installation section describes all steps necessary to install and configure the Portal. If you install your application the first time, then it is important to start with the Basic installation. This section describes all initial steps that must be done for the first installation. If the application is already installed and configured, refer to Migration notes to migrate it.

Basic Installation

Project Modules

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

  • portal-components

  • portal

  • AxonIvyExpress

The deployment of Ivy projects is described in project deployment .

Installation

Designer

Import Portal modules to Designer.

Engine Without License (Demo Mode)

The engine automatically deploys the Portal application with the following set of default users:

Username

Password

Description

admin

admin

This user has all Portal permissions, can access Portal Admin Settings.

demo

demo

This user has permission to manage user absences.

guest

guest

Default normal user of the portal.

Engine With License (Production Mode)

The engine does not deploy anything, you need to deploy and configure the Portal application manually.

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

If you call any Portal API which is not mentioned in the API documentation, it may have changed or have been removed. Don’t forget to re-implement the APIs concerned in your own project.

To migrate the Portal, you need to migrate Axon Ivy first. Refer to the Axon Ivy Migration Notes. Changes in Axon Ivy could lead to problems if a customer project is not migrated properly.

In Designer

  1. Replace all Portal projects with the versions of the new release.

  2. Update portal dependency of the customer project in pom.xml.

  3. Follow detailed migration notes for each version below.

  4. If customization needs copying code from Portal, merge changes between the two versions of the Portal for copied code.

In Engine

  1. Convert database schema if needed.

  2. Redeploy Portal projects and customer project.

  3. Follow detailed migration notes for each version below.

Migrate 9.3 To 9.4

PortalStyle, PortalKit and PortalTemplate have been replaced by portal-components and portal from 9.4, refer to Architecture.

  1. If you have customized PortalStyle, please refer to Customization Portal Logos And Colors to override login background, favicon & logo images. If you have changed the CMS in PortalStyle, please adapt the portal CMS accordingly.

  2. If you configured Process widgets in your own dashboards as described in Configure Process Widget, you need to adapt JSON as follows:

    • Search text "type":"process", then find related displayMode of that Process widget.

    • If displayMode is COMPACT_MODE, change type to compact-process.

    • If displayMode is COMBINED_MODE, change type to combined-process.

    • If displayMode is FULL_MODE, change type to full-process.

    • If displayMode is IMAGE_MODE, change type to image-process.

    For example:

    In 9.3, JSON is

    {"type":"process","displayMode":"COMPACT_MODE","id":"process_1","name":"Your Processes1",
"layout":{"id":null,"styleClass":null,"style":null,"w":3,"h":8,"x":5,"y":0}}

    In 9.4, update JSON to

    {"type":"compact-process","displayMode":"COMPACT_MODE","id":"process_1","name":"Your Processes1",
"layout":{"id":null,"styleClass":null,"style":null,"w":3,"h":8,"x":5,"y":0}}

  3. The customization.css file has been removed, in case you use it in your project, please switch to using Engine Branding to customize styling

  4. Sub processes related to documents are moved to the independent project portal-components. If you customized these processes, please override the correspond sub process again and added your customization to it.

    Below is a list of deprecated processes in project portal and new processes in project portal-components.

    New subprocess

    Deprecated subprocess

    GetDocumentItems

    GetDocumentList

    UploadDocumentItem

    UploadDocument

    DeleteDocumentItem

    DeleteDocument

    DownloadDocumentItem

    DownloadDocument

  5. Some classes of the Portal have been moved to the independent project portal-components. Please refer to below table to migrate them correctly

    PortalKit

    portal-components

    ch.ivy.addon.portalkit.dto.RoleDTO

    com.axonivy.portal.components.dto.RoleDTO

    ch.ivy.addon.portalkit.dto.SecurityMemberDTO

    com.axonivy.portal.components.dto.SecurityMemberDTO

    ch.ivy.addon.portalkit.dto.UserDTO

    com.axonivy.portal.components.dto.UserDTO

    ch.ivy.addon.portalkit.ivydata.bo.IvyDocument

    com.axonivy.portal.components.ivydata.bo.IvyDocument

    ch.ivy.addon.portalkit.document.IvyDocumentTransformer

    com.axonivy.portal.components.document.IvyDocumentTransformer

    ch.ivy.addon.portalkit.enums.DocumentType

    com.axonivy.portal.components.enums.DocumentType

    ch.ivy.addon.portalkit.enums.BasicDocumentType

    com.axonivy.portal.components.enums.BasicDocumentType

    ch.ivy.addon.portalkit.enums.UploadDocumentCheckStatus

    com.axonivy.portal.components.enums.UploadDocumentCheckStatus

  6. Some components of the Portal have been moved to the independent project portal-components. Please follow these steps to migrate them:

  7. Portal dashboard widgets only support the CustomFields declared in the custom-fields.yaml file. If your CustomFields are used in the dashboard widget, please follow the Custom Fields Meta Information to adapt the data.

  8. The DefaultChartColor.p.json sub process has been removed, in case you use it in your project, please remove override this sub process and switch to using Engine Branding to customize chart, data labels, legend color. Refer to Default chart colors.

  9. Deploy portal-migration-9.4.0.iar project to your Ivy application and run it by access link your_host/your_application/pro/portal-migration/175F92F71BC45295/startMigrateConfiguration.ivp

    Important

    • If you have many applications, deploy to only one application and run it by access the migration link, for example: https://portal.io/Portal/pro/portal-migration/175F92F71BC45295/startMigrateConfiguration.ivp

    • Use an administrator account to sign in

    • Run migration process only once

    • You must remove some process models: portal-migration, PortalStyle, PortalKit and PortalTemplate after successfully migrating.

Migrate To 9.3

  1. Deploy portal-migration.iar project to your Ivy application and run it by access link your_host/your_application/pro/portal-migration/175F92F71BC45295/startMigrateConfiguration.ivp

    Important

    • If you have many applications, deploy to only one application and run it by access the migration link, for example: https://portal.io/Portal/pro/portal-migration/175F92F71BC45295/startMigrateConfiguration.ivp

    • Use an administrator account to sign in

    • Run migration process only once

  2. We changed the way to navigate to Task Analysis component. Process Start Processes/TaskAnalysis/start.ivp is moved to new place Start Processes/PortalStart/showTaskAnalysis.ivp. Refer to Task Analysis call for details.

  3. We moved the configuration of announcement, thirdparty applications, default statistic charts, application favorite processes, public external links and express processes from the BusinessData tovariables.

  4. Copy the PortalStart process from PortalTemplate to your project because we changed something relate to DefaultApplicationHomePage.ivp and PortalDashboardConfiguration.ivp. Then apply your customization to the PortalStart in your project.

  5. Portal date filter such as TaskCreationDateFilter, CaseCreationDateFilter… messages <p:messages for="..." /> have been added for each calendar component to validate date format. If you use have any customized date filters in your project, update template accordingly.

  6. The callable process DefaultChart.p.json, DefaultUserProcess.p.json has been removed. They are replaced by the Variables configuration approach, refer to Default Chart and Default User Process for more information

Migrate 9.1 To 9.2

  1. Deploy MigrateData.iar project to your Ivy application and run it by access link your_host/your_application/pro/MigrateData/175F92F71BC45295/startMigrateConfiguration.ivp

    If you have many applications, deploy to only one application and run it by access link your_host/your_application/pro/MigrateData/175F92F71BC45295/startMigrateConfiguration.ivp

    Example: https://portal.io/Portal/pro/MigrateData/175F92F71BC45295/startMigrateConfiguration.ivp

    Important

    Run migration process only once

  2. We remove implementation of Portal multiple applications. So that you need to adapt some points below:

    • Adapt start process signature of PasswordService in ChangePassword.mod if you overrode this callable.

    • If you are using ProcessStartCollector, replace constructor ProcessStartCollector(application) with ProcessStartCollector().

    • If you have TaskLazyDataModel, CaseLazyDataModel customization, remove setInvolvedApplications() method, setInvolvedUsername in search criteria.

  3. In PortalNavigatorInFrame.java, change the methods from non-static to static.

  4. CaseDetails component in PortalTemplate is removed.

  5. If you have TaskLazyDataModel, CaseLazyDataModel customization, follow How to override export feature of Task list and How to override export feature of Case list to customize label and value of custom columns that will be exported.

  6. Deprecated callable processes: OpenPortalSearch.mod, OpenPortalTasks.mod, OpenPortalTaskDetails.mod, OpenPortalCases.mod, OpenPortalCaseDetails.mod process.

    Portal recommends using Axon Ivy HtmlOverride wizard to customize Portal HTML Dialog

    Important

    The callable process which is supporting to open customization dialog will be removed in the future, do not use it in the new project

  7. We remove ivy-icon.css and replace current classes with new classes from Streamline icons. So that you need to update your files that are using classes in ivy-icon.css.

  8. If you have taskItemDetailCustomPanelTop, taskItemDetailCustomPanelBottom customization, follow How to override TaskItemDetail to add custom widgets.

  1. If you have caseItemDetailCustomTop or caseItemDetailCustomMiddle or caseItemDetailCustomBottom customization, follow How to override CaseItemDetail to add these custom widgets.

Migrate 8.X To 9.1

  1. Remove the views field in SubMenuItem.java. Adapt it if you overrode the LoadSubMenuItems callable process

  2. Add parameter <ui:param name="viewName" value="TASK" /> to your customized PortalTasksTemplate to displayed breadcrumb of Task list.

  3. Add parameter <ui:param name="viewName" value="CASE" /> to your customized PortalCasesTemplate to displayed breadcrumb of Case list.

  4. Ivy core has enhanced the Ivy URI, so Portal needs to make a migration. For each of your applications, execute the following steps:

    1. Deploy process model PortalUrlMigration.iar to your Ivy Application.

    2. run migratePortalUrl.ivp once and wait until it is redirected to another page (i.e. the Homepage) without error.

    3. Remove the process model migratePortalUrl.ivp after successfully migrating.

  5. HOMEPAGE_URL (single Portal app mode) and registered application link (multi Portal app mode) are not available anymore. To let Portal know where your new Portal home page is, you have to set default pages in your project. Follow this chapter to customize default-pages: Default Pages

  6. Portal now uses CSS Variable instead of SASS. Therefore, you have to convert the SASS syntax to the new CSS variables or use online tools such as SASS to CSS Variables to convert it.

  7. If the Engine Administrator activates the Portal.Cases.EnableOwner setting and you have a customized case list, customize this field to this case list, e.g. add filter, column configuration, header.

  8. Starting in 9.1, the Ivy engine uses a new mechanism to synchronize user data. Therefore, the Portal has to adapt some data related to users. Some data has to be migrated to work properly. Please follow these steps to migrate the existing data of your application:

    • Deploy process model MigrateRelatedDataOfUserTo9.iar to your application.

    • Run migratePrivateChat.ivp to migrate private chat messages.

    • Run migrateGroupChat.ivp to migrate group chat.

    • Run migrateUserProcessesAndExternalLinks.ivp to migrate user processes and external links.

    • Run migrateExpressProcesses.ivp to migrate Express processes. Please skip this step if your application does not include Express.

    • Restart Ivy engine.

  9. Use pageContent to define your section in BasicTemplate.xhtml instead of simplePageContent.

  10. TaskTemplate-7 has been removed, change it to TaskTemplate-8. TaskTemplate has been removed, too, change it to frame-8 (provided by Ivy).

  11. The MenuKind enum has one more entry: EXTERNAL_LINK. Use it if your item is an external link. Use CUSTOM if it is an internal link.

  12. The PortalNavigatorInFrameAPI#navigateToPortalHome method is deprecated, redirect to ivy.html.applicationHomeRef() in your page instead.

Migrate 8.x To 9.x

You need to do all steps starting at Migrate 8.x To ... up to and including Migrate ... To 9.x

Release notes

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

Changes in 9.4

  • Combined projects PortalStyle, PortalKit, and PortalTemplate to one project named portal.

  • Introduced the Portal.Tasks.BehaviourWhenClickingOnLineInTaskList Portal setting to set behaviour when clicking on a line in task list, task widget in new dashboard and related tasks in case details, each user can change it via user profile.

  • Introduced the Portal.StatisticChartScalingInterval Portal setting to set the interval in seconds to do periodic statistic chart scaling requests.

  • Introduced the Portal.LoginPage.ShowFooter Portal setting to control visibility of the footer on the login page.

  • Introduced the Portal.Theme.Mode Portal setting to set the default theme mode: Light or Dark.

  • Introduced the Portal.Theme.EnableSwitchThemeModeButton Portal setting to control state of the switch theme button on the top-bar.

  • Introduced new Task ID, Task Name, Case ID and Case Name filter in the Portal full task list and case list.

  • Introduced the Process Viewer page, user can get the visual viewer of the process start. See details Show Process Viewer

  • Introduced the Formatting language setting to format values, for example the decimal separator is displayed differently in different regions of the world.

  • Removed sub process DefaultChartColor.p.json, introduced some Portal variables for customizing the default chart color. See details: Default chart colors.

  • Introduce some components in new portal-components project.

Changes in 9.3

  • No need to update PortalGroupId variable when you change group id of Portal.

Changes in 9.2

  • Included new TaskState such as Destroyed, Failed, Join failed and Waiting for event in Portal Task list, also in Task State filter.

  • Included new CaseState Destroyed in Portal Case list, also in Case State filter.

  • Introduced Workflow Events table, user who has permission WORKFLOW_EVENT_READ_ALL can see all WORKFLOW_EVENTS.

  • Introduced the Portal.Homepage Portal setting to set the default homepage, each user can change it via user profile.

  • Introduced new approach to customize Portal Case Item details. Now, your case information in Case details page and Case Info dialog is the same

  • Introduced new approach to customize Portal Task item details.

  • Introduced new Portal Setting Portal.ShowButtonIcon to control visibility of icon of button in Portal.

  • Introduced new variable named PortalLoginPageDisplay to show Login page or hide it then show error page instead.

  • No multiple applications anymore, Portal now only works in current application. It means administrator can not add new Ivy application.

  • Statistic charts support multiple names for each supported languages.

  • Portal supports multilingual user favorites

  • Portal supports logos in SVG format.

Changes in 9.1

  • Refactored style customization approach. From now on, Portal use CSS Variable as technology to customize CSS.

  • Introduced the User Guide feature, using the Portal.Dashboard.ShowUserGuide Portal Setting to activate/deactivate it, and follow Customize user guide for your customization.

  • Introduced new Portal Setting Portal.ShowButtonIcon to control visibility of icon of button in Portal.

  • Introduced new Portal dialog with icon decorator. Refer to this section for detail.

  • TaskTemplate-7, TaskTemplate and TwoColumnTemplate have been removed.