Best Practices for Upgrading from v4 to v5

Upgrading from v4 to version v5 is a major process that requires careful preparation, client communication (including their active participation), testing, and technical adjustments. Below are the key best practices to ensure a smooth migration.

Effort and Preparation

Pre-production environment – The key first step is to compare tests against production or to create a pre-prod environment, so testing is performed on real templates and upgrade issues are not mixed with historical errors from the test environment.

Thorough preparation is essential – It is necessary to actively communicate with the client and present the new TAS design in advance, especially the layout of attributes on forms and the visual details of cases, to align expectations. Form and case details should be reviewed due to differences in UI/UX between version 4 and 5.

Testing with all stakeholders – Since the user interface changes significantly, it is recommended to include as many stakeholders and users as possible in testing, so they do not see the new GUI for the first time in production.

Client involvement – The client must clearly define what they need to display and what adjustments are critical for them.

Dockerization – If the upgrade also involves migration to a dockerized environment, it is best to perform the dockerization first, verify functionality, and only then carry out the upgrade. This helps separate infrastructure issues from upgrade-related issues.

Key Areas Requiring Significant Adjustments

Form Variables

• Variable assignments must be restructured into well-defined sections due to new design rules.
• The new layout requires structured adjustments; existing settings cannot simply be reused.
• To transfer variable assignment settings from test to production, use the Export/Import variable assignments feature.

Case Overview (CO)

• If the new design is used, the entire CO must be rewritten using React components.
• The original HTML markup remains backward compatible and can be retained.
• It is necessary to reconsider how data is structured and displayed.

Dynamic Conditions and WatchVars

• Mandatory use of WatchVars – In v5, dynamic conditions are evaluated differently due to loading speed optimizations.
• What worked quickly without WatchVars in v4 now requires explicit WatchVars to avoid performance issues.
• Example: Repeated evaluation of varReadOn can significantly slow down form performance.

Dynamic Rows

• Behavior review and optimization are crucial, especially for runCondOnChange.
• Mandatory use of WatchVars – In v5, dynamic rows are also evaluated differently due to performance optimizations.
• In v4, dynamic rows were evaluated similarly to v5 with the parameter runAfterConds: true. It is recommended to add this parameter by default in all dynamic rows.
• Scrollbars – For larger data volumes, it is necessary to allow smooth scrolling and navigation.

Integrations via curl

• All curl-based integrations must be retested individually and in parallel.
• In case of SSL errors, curl must now be replaced by Axios (see Axios).
• Switching to Axios requires a complete redesign of error handling.

Performance of Overviews with Large Data Volumes

• v5 optimizes overviews and data handling differently.
• It is very useful to prepare test data that approximately matches production volumes, so potential performance bottlenecks can be identified before go-live.

Key Adjustments

Global Scripts

• Be cautious with duplicate global scripts (e.g., the commafy function may appear multiple times).
• v5 combines React scripts with traditional scripts, which can lead to unexpected conflicts.

Language Mutations

• Verify the availability of language mutations – some languages may not be fully supported in new React scripts and may need to be added manually by consultants.

Previously Hidden Issues

• Users pay more attention to the system after an upgrade, which may reveal older hidden issues.
• v5 is stricter – some elements that worked in v4 may fail validation in the new version.
• Pay attention to necessary changes in lodash functions used in calculations and other unsupported functions (see Upgrade guide).

Improvements and Recommendations

Design Consistency

• The new CO design is well received, but it is important to align its appearance with task views.
• Clients often request that task layouts match the CO.

Client Involvement

• Clients will not identify all issues on their own – they must be actively guided to define their requirements.
• CO looks best with four columns.

Approach to Redesign

• It is not possible to simply copy the v4 design – changes must be accepted, and the new concept adopted.
• Early client involvement ensures aligned expectations.
• Recommended approach: prepare a draft concept by the consultant first and then review it with the client.

Client Expectations

• Clients often assume the upgrade will happen automatically without their involvement.
• They must be clearly informed that they need to actively participate in configuring the new setup.

Managing Perception of Issues

• It is important to communicate changes effectively – issues that would have occurred in TAS 4 must not be mistakenly attributed to v5.
• Problems such as organizational structure changes may be incorrectly linked to the upgrade.
• Managing client expectations is critical to avoid misunderstandings. Clients often do not fully understand what to expect.

Final Recommendations

✅ Thorough preparation and communication are key to a successful migration.

✅ Following the official technical documentation helps prevent problems.

✅ Redesign must be anticipated, especially for variables, CO, and dynamic conditions.

✅ Clients must be informed from the start about changes and their impact.

By following these recommendations, it is possible to minimize problems, optimize performance, and ensure a smooth transition to v5.