Checklist for migrating from Intrexx 18.03 to Intrexx 19.03

Installation

1. General

With the release of Intrexx 19.03, fundamental parts of Intrexx have been refined to give Intrexx a long-lasting future. The most important changes are: These are only the most important changes to Intrexx but these alone express an impressive number of changes to the product. These changes are not an end unto themselves but rather are intended to future-proof the existing and future solutions that you as a customer or partner implement with Intrexx.

We are aware that the transition to Version 19.03 does not always go as smoothly as you have been used to with other releases of Intrexx in the past. It was and still is our goal to make this transition as simple as possible and to enable our customers to switch to the new release as a simple update. Therefore, every version has a lot of conversion code that is implemented solely to simplify the upgrade.

This version also has this code to a very large extent. However, it is impossible to recognize and convert every contingency. As soon as we can assume a possible need for conversion, we implemented the corresponding code at this point to decrease the need for manual adjustments. Unfortunately, this is not always possible due to the flexibility and comprehensive features of Intrexx. Especially when programming languages are implemented (JavaScript, Velocity, Groovy), Intrexx methods that are no longer supported are used, database table accesses are carried out and in some other cases, we are not able to perform an automatic conversion - the risk of incorrect implementation would be too high.

For this reason, we refer to the transition from Intrexx 18.03 to Intrexx 19.03 as a migration. We do not understand "migration" to mean a reimplementation of existing portals - but we want to point out that the transition to 19.03 is usually not possible without manual adjustments to applications and without changes to the underlying web servers. Please factor these modifications into your upgrade plans.

However, do not shy away from the transition but use this step-by-step guide to make the best possible preparations for it. Our partners and support team are also happy to help you take the step. Once the hard work is done, you will have access to numerous new functions for your digital transformation plans – it is worth it!

2. Before upgrading - What should you consider?

2.1. Test system and a virtual environment

Make sure you have a test system. From numerous highly professional customer projects, we can assure you that using one test and one live system provides a high level of security and provides for further enhancements to your environment. Especially version upgrades can be performed securely and without pressure in this way. Equally, software updates and various adjustments to applications, processes and layouts can be developed and tested in a non-critical test setting. The possibilities of virtual environments make things even more comfortable.

Knowledge Base Article No. 3050: Test system & live environment | Installation, benefits, info

2.2. System snapshot / backup

Make sure you have performed a complete backup of your system.
A portal export is not a backup!
A portal export can and will generally work well but does not provide 100% security. Only a backup of the entire system can provide you with the required security. Check, for example, whether the portal database runs on the same server - especially if you prepare for the migration by creating a snapshot in a virtual environment. More than expected, the directories are backed up but the database has been migrated to a different server. Returning to a previous state is then only possible with older database backups.

Knowledge Base Article No. 1864: Creating a data backup of Intrexx

2.3. Server performance

Since the introduction of the Solr search server (Intrexx 8.0 or higher), it is not atypical for an Intrexx server to use up more resources than previous Intrexx versions. Equally, the functions and features of Intrexx have changed significantly. Whereas older, simpler portals could be all means be run with less than 1GB memory and a dual-core processor, the server requirements are considerably higher now.

Our current recommendation both for live and test systems: Please make sure to upgrade your systems as needed before upgrading. Resource bottlenecks can lead to problems during the upgrade.

Knowledge Base Article No. 3326: Large consumption of resources like CPU, RAM and HDD | Performance

2.4. Update notes

Please refer to our update notes for Intrexx 19.03. These pages provide you with information about changes to custom programmings and possible workarounds known to us at this time.

2.5. SSL, web server modifications, Windows Authentication

The Online Help for Intrexx 19.03 and our Knowledge Base provide descriptions for the required modifications to web servers if they cannot be performed automatically via the setup. The update will attempt to automatically adjust as many configurations as possible. However, as many customers have highly customized configurations, automatic modifications are not always possible. If you deploy IIS as a reverse proxy, then you definitely need to adjust IIS and its configuration in advance. Please note that when deploying IIS, only Windows Server variants from 2012 R2 onwards are supported.

Preparations
HTTPS

If you are uncertain at any point here, do not hesitate to contact your Intrexx Partner or the United Planet support team - we are happy to help.

Knowledge Base Article No. 3334: IIS as the reverse proxy server with Intrexx 19.03

2.6. Modified features

We put functions to the test and may remove features that are hardly used - for example when the feature is no longer up to date, uses technologies that are disadvantageous for our customers (i.e. due to security aspects) or if a feature is used only rarely. A list of features that have reached the end of their lifetime and are therefore no longer available, can be found here:

Modified features

In the future, we will announce this sort of change in good time before an LTS release.

2.7. Current Intrexx version

Please make sure you use the latest Intrexx setup. If in doubt, we recommend re-downloading the setup from the United Planet homepage. You can check the setup by looking at the version file; this can be found at the top level of the unzipped setup.

Example: >= 9.2.0.20190823.xxxxx.version

2.8. Software update

United Planet enhances the product on a regular basis with online updates. The software update is one of the most important points to consider before upgrading. This is the only way we can support you fully. Make sure that you install all Online Updates during the upgrade process. Intrexx will try to install the Online Updates automatically. If you upgrade your server and it is not connected to the internet, this is of course not possible. In this case, you can download the Online Update manually and roll it out as a ZIP file.

Please always open the Portal Manager before installing Online Updates or upgrading to a new version by selecting "Run as administrator" from the context menu (right-click). In this way, you can ensure that Intrexx has all the permissions it needs to perform the update.

Software update
Knowledge Base Article No. 2000: Online Updates | Installation and information

2.9. How much time needs to be factored in for the migration? What definitely needs to be reworked?

Factor in a buffer of several days for the update. We cannot provide a reliable specification at this point as all Intrexx environments are highly different. The more custom programming you use in your applications, the more likely you will need to manually adjust your applications. In any case, you will need to manually adjust existing portal pages. When upgrading, it is not possible to absolutely ensure that your existing portal pages will be transferred to the new system. Portlets need to be repositioned in the grids. Familiarize yourself with the new features to this end. Even if you need to make manual adjustments to begin with, we are certain that you will very soon appreciate the diverse new possibilities.

Portlets

3. Update

Once all preparation points have been taken into account, you can start the upgrade. Important questions to ask beforehand: Start the installation by selecting "Run as administrator" from the context menu (right-click). Make absolutely certain that all Online Updates are installed. If this is not possible, please contact the United Planet support team.

The upgrade will take about 30 minutes depending on the size of the portal. If the portal is very large, this process can take longer than 60 minutes. Because the time need for the upgrade very much depends on the scope and number of the applications, we cannot make a reliable specification; the times stated should serve to give a rough idea.

4. After the update

The portal is now ready for any adjustments needed. Before you start, you should check the setup logfiles to ensure the automatic migration of the portals could be executed without errors. If there were errors during the automatic migration, please contact the United Planet support. Please do not revert the system yet - this is the only way for us to find the specific cause and fix it reliably. Depending on the error, we may still need to revert the system, which is exactly why a backup is required at this point.

  1. Check the Patch.log file

    You can find this file in the portal directory log/. You should always check the logfiles for errors after every version upgrade and software update by searching for the term "ERROR" in the files. This is an important step to ensure that there were not any errors caused during the upgrade or update. If the Patch.log file contains errors, please refer to Appendix a) (Errors in Patch.log: Cause, next steps, solutions).

  2. Check the files PublishAllApplications.log, PublishAllProcesses.log and PublishAllLayouts.log

    You can find these files in the portal directory log/. If there was an error while publishing an application, process or layout, then the corresponding item needs to be checked. Sometimes, it can be enough to republish the application (process/layout).

    If the files contain errors, please refer to Appendix b) (Errors in PublishAllApplikations.log: Cause, next steps, solutions).

    Many during the migration process can be fixed manually. Among other things, the Intrexx Application Designer now has a new tool for identifying existing problems. You can find this in the Problems area. If you were able to republish an application without errors, we recommend republishing all applications, processes and layouts afterwards. Frequently, errors during publishing are caused by consequential errors because there may be dependencies between the applications.

    Knowledge Base Article No. 2745: Online Updates | Publish all applications and processes via Batch
    or alternatively
    Knowledge Base Article No. 2738: Online Updates | Publish all applications and processes via CMD

  3. Test the availability of your portal

    Can the portal be opened in the Manager?

    If not, please check whether the portal services have been started first. Check the following Intrexx services: Portal services, Solr service and possibly the Supervisor service. If the services have not been started automatically, start them now.

    If you cannot start the services, please check the respective logfile (Portal.log or Portal_startup.log) to see if errors are listed at the attempted start time. If this is the case, contact United Planet support. If the services are running but the portal is still not available, please note that installed security systems like firewalls need to be configured accordingly to be able to establish the connection between a Portal Manager (potentially on a client PC) and the Intrexx server.

    Knowledge Base Article No. 2407: Network and Internet Connections | Firewall Configuration and Information

    Can the portal be opened in a browser?

    1. If not, access the portal in a browser directly on the server to begin with. If there are problems here as well, check the configuration of your web server as described here. If you need any help here, please contact United Planet support.
    2. What to do if the portal can be opened but authentication fails:
      • Please test whether the Intrexx authentication is functional
      • Please test whether it is possible to access the portal after reconfiguring the chosen authentication and restarting the portal.
    Knowledge Base Article No. 3259: Troubleshooting - User authentication | Windows authentication with IIS
    Knowledge Base Article No. 3335: Custom ("Other") authentication method with Intrexx 19.03

5. Important / Miscellaneous

Adjusting portal pages

  1. As mentioned above, portal pages need to be adjusted to the new framework. The new portlet framework is now a responsive grid that portlets can be positioned in. The portlets already in use are available after the update but the order, positioning and width may have changed. Start by configuring the grid so that you can position the portlets as needed. You also have the ability to optimize the grid for tablets and mobile devices at this point. You can move the portlets within the grid via drag & drop.
  2. On application portal pages, it may be the case that parameters or values from the request, etc. are not available in the portlet, which then causes errors. The update process tries to take over all known possibilities for you but we have seen that this cannot always work reliably as the possibilities are too diverse. If errors occur in individual portlets, start by checking whether all required parameters are transferred from the portlet container to the portlets.

Checking applications

  1. Once your portal is rolled out, you should check the logfiles regularly in the following days. This includes the portal.log file. This logfile provides an overview of problems in your applications. If this is the case, please contact your partner or the United Planet support as needed.
  2. If there are problems in your applications, you should definitely check if JavaScript or Velocity script, which may need to be adjusted as described here, is used in these applications. Even though United Planet takes great caution at this point, it may be the case that a required adjustment is missing from this document. Furthermore, it may well be that a function should have already been adjusted during a previous update. Please check the update document for Version 18.03 in this case - or even earlier versions. If in doubt, please contact our support team - they will provide you with the assistance needed.

Checking processes

Once your portal is rolled out, you should check the logfiles regularly in the following days. This includes the workflow.log file. This logfile provides an overview of problems in your processes. If this is the case, please contact your partner or the United Planet support as needed.

Checking the search server (Solr)

Click on Manage cores/collections to check whether all cores and collections can be assembled. You should see a green checkmark next to each core in the list. The cores need to be reconfigured otherwise.

Knowledge Base Article No. 3102: Solr | Reconfigure search configurations and cores/collections

Checking the server load

Since the introduction of the Solr search server (Intrexx 8.0 or higher), it is not atypical for an Intrexx server to use up more resources than previous Intrexx versions. Equally, the functions and features of Intrexx have changed significantly. Whereas older, simpler portals could be all means be run with less than 1GB memory and a dual-core processor, the server requirements are considerably higher now.

Knowledge Base Article No. 3326: Large consumption of resources like CPU, RAM and HDD | Performance

6. Appendix a

Errors in Patch.log: Cause, possible corrective actions and subsequent steps

As soon as there is a reference, the app cannot be published. 
ERROR 2019-08-30T08:34:12,317Z - de.uplanet.lucy.server.patch.FinishPortalPatcher[main]
Failed to add views to user applications.
de.uplanet.jdbc.StandardDbException: Error: 2627, SQLState: 23000: Violation of PRIMARY KEY constraint 'PK__LCAPPDG__0EF23BF8383528AF'. Cannot insert duplicate key in object 'dbo.LCAPPDG'. The duplicate key value is (DAF7CECF66481FCABE50E529828116EAFE906962).
    at de.uplanet.jdbc.sqlserver.SQLServerDescriptor.convertException(Unknown Source) ~[ix-server-common.jar:9.2.0.20190823.199961]
    at de.uplanet.jdbc.JdbcPreparedStatementImpl.executeUpdate(Unknown Source) ~[ix-server-common.jar:9.2.0.20190823.199961]
    at de.uplanet.lucy.server.businesslogic.adminapp.publish.user.UserApplicationSchemaPublisher.a(Unknown Source) ~[ix-server.jar:9.2.0.20190823.199961]
...
Solution: Search for the field in the Users application and remove the reference. Most references are shown in the Problems area. Existing references may be shown when publishing.

7. Appendix b

Errors in PublishAllApplication.log: Cause, possible corrective actions and subsequent steps

Error when validating the schema of one or more applications

  1. Identification

    Intrexx applications are XML files. These files contain all elements that belong to an application: Data groups, data fields, pages, edit and view elements, texts and much more. From Intrexx 19.03 onwards, the structures of this type of XML file is monitored exactly to ensure the validity of an application in the future. From a very large pool of applications, United Planet has created an almost complete picture of all possibilities and ensures this accordingly with so-called schema validation. However, if there are applications in your portal, whose XML structure has been adjusted for whatever reason, this can mean that the corresponding applications cannot be published until the schema violation is removed. A schema violation can be identified in the logfile by looking for the following pattern: 
    XML: B0128D0439003C858896C4E3F0A564DEB305CB74.xml
Cause:<radiocontrolgroup...><simplegroup dynamic-width = 'false' fixedpos = 'false' guid = '8489B4BC5F0448D60F284252D17E01FE9B01D0F9' html-structure = 'table' isNewControl = 'true' level = '1' name = 'simplegroup5504ADF6' rect = '0,0,140,60'>
cvc-complex-type.2.4.a: Invalid content was found starting with element '{"http://schemas.unitedplanet.de/intrexx/2016/application/element/":simplegroup}'. One of '{"http://schemas.unitedplanet.de/intrexx/2016/application/element/":defaultvalue, "http://schemas.unitedplanet.de/intrexx/2016/application/element/":radiocontrol}' is expected.

  2. Consequences

    If it concerns an isolated application, which has no dependencies on other applications, then portal can by all means be operable - however, this specific application cannot be published and not accessed as a result. If there are dependencies to other applications, these also cannot be published as a result and it may mean that it is not possible to use your portal at all.

  3. Measures

    If you find this kind of error in your logfile, please contact our support. We can work together to try and remove the error either directly or by creating a patch with the assistance of our Development department; this patch not only helps you but also all other potential portals that are affected by this error. Please note that this solution can typically only be implemented with a later online update.