Installation

This guide covers Portal installation, configuration, and migration procedures. Whether you’re installing Portal for the first time or upgrading from a previous version, follow the appropriate sections below.

Overview

Installation Type

Description

Basic Installation

First-time Portal setup with initial configuration

Migration

Upgrade existing Portal to a new version

Multi-App Setup

Deploy Portal across multiple applications

Important

For first-time installations, follow the Basic Installation section. For existing Portal installations, refer to Migration Notes.

Basic Installation

Prerequisites

  • Axon Ivy Designer or Engine

  • Understanding of Portal architecture

  • For production: Valid Axon Ivy Engine license

Portal Modules

The Portal application consists of 2 process modules:

Module

Purpose

portal-components

Public UI components and APIs for reuse

portal

Portal-specific UI, templates, and pages

For detailed module information, refer to Architecture.

For project deployment procedures, see project deployment.

Installation by Environment

Designer

Import Portal modules (portal and portal-components) or download from The Axon Ivy Marketplace to your Axon Ivy Designer.

Demo Mode (Engine Without License)

The engine automatically deploys the Portal application with pre-configured demo users:

Username

Password

Description

admin

admin

Full Portal permissions, can access Admin Settings

demo

demo

Can manage user absences

guest

guest

Standard Portal user

Warning

Demo users are for development/testing only. Do not use in production environments.

Production Mode (Engine With License)

The engine does not deploy Portal automatically. You must deploy and configure Portal manually.

Dashboard Configuration

For dashboard configuration methods (deployment files, Engine Cockpit UI, or Portal import), see Dashboard Configuration in the Deployment guide.

Multi-Application Setup

Portal supports multi-application deployment where Portal and your business applications run separately within the same security context, enabling unified task and case management.

Architecture:

  • Application 1 (Portal): portal + portal-components

  • Application 2+ (Your Apps): your projects + portal-components (only if using Portal UI components)

Important

All applications must be in the same security context for Portal to display tasks and cases from all applications.

For detailed multi-app architecture and step-by-step deployment instructions, see Deployment.

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. Upgrade your projects to use the latest portal version by using the Convert Project feature. Please find more information here: Converting Projects

  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 11.3.2 To 12.0.0

1. Custom field values for business details pages are migrated silently from the process link relative path to its IWebStartable ID. You don’t need to do anything, this is just for your information.

2. We implemented a new feature to adjusting column widths in the Task and Case widgets. This change may slightly impact the column widths of Task and Case widgets from previous versions. To manually adjust column widths, please refer to the Task widget configuraiton, and Case widget configuraiton guides.

Migrate 11.1.0 To 11.2.0

The AxonIvyExpress module is renamed to axonivy-express and becomes an item on the Axon Ivy Market, To migrate it you need to do the following steps:

  • Open Portal, go to Setting -> Express Management. Export all Express configurations.

  • Open the Cockpit, stop the PM AxonIvyExpress in your Portal application.

  • Deploy the axonivy-express module which gets from the Axon Ivy Market into the Portal application.

  • Restart Engine.

  • Open Portal, go to Setting -> Express Management. Import the configuration which is exported at the first step.

  • If you override PortalStartTimeCleanObsoletedDataExpression variable, please update it to new Ivy CRON job pattern.

  • Refer to Axon Ivy CRON job pattern: CRON Expression.

  • Example: Change 0 0 1 * * ? to 0 1 * * * for job trigger 01:00 AM everyday.

Migrate 10.0.19 To 10.0.20

So far, Portal supports configuring process steps of Process chain with String or Array format. We deprecated the String format but still support it for backward compatibility. We recommend you use the Array format. You could change as follows:

  • Change window.processSteps = "Create Investment Request,Approve Investment Request"; to window.processSteps = ["Create Investment Request", "Approve Investment Request"];

  • Change window.processSteps = "#{fn:join(data.steps.toArray(), ',')}"; to window.processSteps = #{portalComponentUtilsBean.convertToJSON(data.steps)};

Migrate 10.0.12 To 10.0.13

  • Override HTML dialog UserWithEnvironmentInfo is removed and no longer supported, use GlobalFooterInfo dialog instead with the GlobalVariable.

  • Override HTML dialog PageHeader and PageFooter are no longer supported, use callable instead.

Migrate 10.0.11 To 10.0.12

  1. Portal no longer supports the override process approach for some subprocesses. Please follow the guidelines below to migrate your override subprocesses.

    • Customize Forgot Password

      • Remove subprocess override of ResetPassword and SendPasswordResetEmail` from your project.

      • Change the signature of your callable start as described below.

        Subprocess

        New signature

        ResetPassword

        portalResetPassword

        SendPasswordResetEmail

        portalSendPasswordResetEmail
    • Document Processes

      • Remove subprocess override of GetDocumentList, UploadDocument, DeleteDocument, and DownloadDocument from your project.

      • Change the signature of your callable starts as described below.

        Subprocess

        New signature

        GetDocumentList

        portalGetDocumentList

        UploadDocument

        portalUploadDocument

        DeleteDocument

        portalDeleteDocument

        DownloadDocument

        portalDownloadDocument
    • Customize Logout Process

      • Remove subprocess override of LogoutPage and Logout from your project.

      • Change the signature of your callable start as described below.

        Subprocess

        New signature

        LogoutPage

        portalGetLogoutPage

        Logout

        portalLogout
    • Customize Change Password Process

      • Remove subprocess override of ChangePassword from your project.

      • Change the signature of your callable start as described below.

        Subprocess

        New signature

        ChangePassword

        portalChangePassword
    • Task Delegation

      • Remove subprocess override of CalculateTaskDelegate from your project.

      • Change the signature of your callable start as described below.

        Subprocess

        New signature

        CalculateTaskDelegate

        portalCalculateTaskDelegate
    • Customize Menu Items

      • Remove subprocess override of LoadSubMenuItems from your project.

      • Change the signature of your callable start as described below.

        Subprocess

        New signature

        LoadSubMenuItems

        portalLoadSubMenuItems

      • To hide default menu items, you can utilize variables. Here’s a link Show/hide default menu items that provides instructions on how to do so.

      • Update index for each custom menu item.

      • Refer to process CustomLoadSubMenuItems in the project portal-developer-examples for an example of how to create custom menu items.

  2. We changed the External Link configuration for the field imageContent, refer to Portal Processes External Links for more information. Basically, you do not need any migration on your engine. In case you have overridden the variable Portal.Processes.ExternalLinks by deployment, update the field imageContent by removing the prefix like data:image/jpeg;base64, in your JSON variable Portal.Processes.ExternalLinks file.

Migrate 10.0 To 10.0.7

The ch.ivy.addon.portalkit.publicapi.PortalNavigatorInFrameAPI class is removed and no longer supported, use com.axonivy.portal.components.util.PortalNavigatorInFrameAPI instead.

Migrate 8.x To 10.0

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

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. The customization.css file has been removed, in case you use it in your project, please switch to using Engine Branding to customize styling

  3. Subprocesses related to documents are moved to the independent project portal-components. If you customized these processes, please override the correspond subprocess 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

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

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

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

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

  8. 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 9.2 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.

  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.

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

  6. We remove ivy-icon.css and replace current classes with new classes from Streamline icons, which can be found in the HTML Dialog Demo. So that you need to update your files that are using classes in ivy-icon.css.

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

  • Enhanced the document preview feature for the task and case detail. If you have DocFactory in the same security context, you can preview Word(doc, docx), Excel(xls, xlsx) and email(eml) documents.

  • Enhanced the Document Table component by adding the lazy loading functionality to the Document Table component, enabling efficient data loading through pagination.

Changes in 12.0.9

  • Introduced Renaming Document feature for the task and case detail. You can rename document in document table of task and case detail page, and the activity will be logged in history notes.

  • Enhanced the document preview feature for the task and case detail. If you have DocFactory in the same security context, you can preview Word(doc, docx), Excel(xls, xlsx) and email(eml) documents.

Changes in 12.0.6

  • Introduced the Portal Setting Portal.Cases.EnablePinnedCase and Portal.Tasks.EnablePinnedTask to enable the pinning feature for the case and task widgets on the dashboard.

Changes in 12.0.4

  • Introduced the Portal Setting Portal.Cases.BehaviourWhenClickingOnLineInCaseList to toggle between accessing case details or business details when clicking on a case in the case widget on the dashboard, global search, related cases, and the process widget in combined mode.

Changes in 12.0.1

  • Introduced the document preview feature for the task and case detail. You can preview images(png or jpeg), plain text(txt or log) and pdf documents.

  • Introduced the Portal Setting Portal.Document.EnablePreview to control visibility of the preview document icon in Portal.

Changes in 12.0.0

  • The old statistic chart is removed, use the new Statistic Chart instead.

  • Introduce the component IFrameTaskConfig to configure IFrame tasks. Refer to Configure IFrame Template for more information.

  • The full task list page and full case list page have been redesigned to align with the concept of a dashboard widget. It now functions as a dashboard with a single, full-width widget. To configure it, you can adjust it like any other widgets.

  • Support multiple case owners. The single case owner sort feature is removed.

Changes in 11.2.0

  • The ch.ivy.addon.portalkit.publicapi.ApplicationMultiLanguageAPI class is removed and no longer supported, use com.axonivy.portal.components.publicapi.ApplicationMultiLanguageAPI instead.

  • The ch.ivy.addon.portalkit.publicapi.CaseAPI class is removed and no longer supported, use com.axonivy.portal.components.publicapi.CaseAPI instead.

  • The ch.ivy.addon.portalkit.publicapi.PortalGlobalGrowInIFrameAPI class is removed and no longer supported, use com.axonivy.portal.components.publicapi.PortalGlobalGrowInIFrameAPI instead.

  • The ch.ivy.addon.portalkit.publicapi.PortalNavigatorAPI class is removed and no longer supported, use com.axonivy.portal.components.publicapi.PortalNavigatorAPI instead.

  • The ch.ivy.addon.portalkit.publicapi.ProcessStartAPI class is removed and no longer supported, use com.axonivy.portal.components.publicapi.ProcessStartAPI instead.

  • The ch.ivy.addon.portalkit.publicapi.RoleAPI class is removed and no longer supported, use com.axonivy.portal.components.publicapi.RoleAPI instead.

  • The ch.ivy.addon.portalkit.publicapi.TaskAPI class is removed and no longer supported, use com.axonivy.portal.components.publicapi.TaskAPI instead.

  • The com.axonivy.portal.components.util.PortalNavigatorInFrameAPI class is removed and no longer supported, use com.axonivy.portal.components.publicapi.PortalNavigatorInFrameAPI instead.

  • Introduced the sort feature for the process dashboard widget. User can sort the processes by index, alphabetical order or by custom order.

  • Introduced the taskId param for the component ic:com.axonivy.portal.components.ProcessViewer to highlight the current step in the Process Viewer.

  • Portal Legacy dashboard has been removed.

  • The AxonIvyExpress module is renamed to axonivy-express and becomes an item on the Axon Ivy Market.

Changes in 10

  • Introduced the Application filter and the Application column in the following places: full task list, full case list, dashboard task list, dashboard case list, and task analysis.

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 subprocess DefaultChartColor.p.json, introduced some Portal variables for customizing the default chart color.

  • 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 🔑WorkflowEventReadAll 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 new Portal Setting Portal.ShowButtonIcon to control visibility of icon of button in Portal.

  • Introduced new Portal dialog with icon decorator.

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