Skip to main content

Upgrading to Central 4

This release delivers a major step forward for Jadu Central, combining new form capabilities, modern platform compatibility, and a series of other enhancements. It also removes legacy components to simplify long-term maintenance and support.

Compatibility information​

Jadu Central 2 and above can be upgraded to Jadu Central 4.

Changes have been made to our system requirements from our Jadu Central 3 release.

Minimum supported versions:

  • PHP 8.1
  • MariaDB 10.5

Recommended versions:

  • PHP 8.3
  • MariaDB 10.11 (CentOS 7 only)
note

Customers of Jadu's managed service on CentOS 7 systems will be upgraded to MariaDB 10.11 due to support for 10.5 coming to an end.

Rocky 9 systems will remain on 10.5 as the package provider will continue support for this version for the lifetime of the operating system.

For caching on Windows, support has been added for MS Garnet. This is the recommended caching solution for Windows for Central 4 onwards.

This release has also been tested on Microsoft Windows Server 2025.

All other platform and stack components remain the same as Central 3.

Prerequisites​

Before attempting to upgrade a Jadu Central instance to Jadu Central 4.0.0, please confirm the following prerequisites are in place:

  • The system should be running Central 2.x or Central 3.x and the minimum supported PHP and database versions.
  • PHP zip extension has to be explicitly enabled if you are using PHP 8.2 or above: PHP Zip installation
  • A snapshot of the server has been taken, as encryption changes are a destructive process and any associated data will be lost if the patch is rolled back
  • If applicable, forms have been taken offline
  • We recommend the patch process is followed on your UAT environment, before application to a production environment.
note

We have identified a bug in Microsoft SQL driver 5.12 when using PHP 8.3, previously documented in the Central 2 upgrade guidance: SQL Server Driver 5.10 column type issue. A workaround has been introduced into Jadu Central to resolve this issue.

Step-by-step upgrade instructions​

Prepare the server(s)

  1. Check that the pre-requisites are met (see above)

Prepare the package

  1. If a client project exists and contains bespoke extensions, update these to be compatible with Central 4.0 by following the guidance in this document.
  2. Update the Meteor version to 4.1.x
  3. Migration for widget names (optional but recommended)
  4. Create package with any client extension as required, via Jadu Deployer or directly using Meteor

Upgrade PHP

  1. Upgrade PHP to 8.3 (optional but recommended)

Deploy the package

  1. Deploy package using the standard process via Jadu Deployer or directly using Meteor

Convert encrypted data

  1. Take a database backup - either a full backup or just the following tables:
    • JaduUsers
    • JaduAdministrators
    • JaduIntegrationDetails
  2. From the terminal on the server, execute the encryption conversion command:
php cli.php cms:upgrade:convert-encryption-to-aes --dry-run
php cli.php cms:upgrade:convert-encryption-to-aes
note

The command may take 30-45 minutes to run with larger tables. Once complete, verify that the system is stable.

Change to configuration files​

No changes have been made to configuration files in this release.

API/Code breaking changes​

Deprecated​

  • Jadu_DataMapper::getEncryptedColumns() @deprecated use Jadu_DataMapper::getAESEncryptedColumns() instead
  • Jadu_Router::add(RouteInterface $route) @deprecated use Symfony native routing instead. Klein remains currently for backwards compatibility but will be eventually removed.
  • Jadu\Service\Container::getRouter() @deprecated use Symfony native routing instead.

Breaking changes​

Encrypted data​

Several changes have been made to database tables that store encrypted values. The encryption algorithm has been changed and the values moved to new columns.

The following tables are affected:

  • JaduAdministrators
  • JaduIntegrationDetails
  • JaduUsers

DataMappers, Repository classes and other functions interacting with these tables have been updated to make these changes backwards-compatible.

Any custom code directly accessing the old columns will need to be updated.

User value hashing​

Due to the change in encryption, many columns in the JaduUsers table can no longer support value lookup. To work around this limitation, many values are now hashed and stored in a new column on the JaduUsers table. The new columns have the suffix “_hash”.

Any custom code attempting to retrieve a user record using SQL to, for example, fetch a user by email address will need to be updated. This only applies where direct SQL is used, DataMappers, Repository classes and functions have been updated to retain backwards compatibility as much as possible.

Wildcard matching against these new columns is no longer possible.

All Questions and Answers variable in forms​

To ensure correct formatting of component answers within the All Questions and Answers variable, Central 4.0 now provides three methods supported by the new variable picker.

  • getResponseTwigParameters
  • getResponseTwigTemplate
  • getResponseTextOutput

The first two methods were previously defined but not utilised. They support HTML formatting when the mapping transform is set to HTML. The third method, getResponseTextOutput, is used when the Text Output transform is selected.

Summary Table in Repeatable​

getResponseTextOutput: For repeatable components, the same method used for All Questions and Answers variable when the format is text will be applied to display the answer in the Summary table.

However, since the answer may not be saved at this point, accessing UserAnswer Metadata fields might not be possible.

It is recommended to include a fallback in this method to appropriately display or reformat the answer in the Summary rows.

If a component lacks getResponseTextOutput, the raw answer will be used in the summary table.

QuestionService- getRepeatableQuestionsForForm​

Parameter type has been changed to accept a Form object instead of formID.

AbstractRuleClauseType - getTwigParameters​

Similar change as to above, accepts a Form object instead of formID.

Other form breaking changes​

  • Any existing questions mappings within the repeatable acting as a source in the prefills page are no longer supported. They might still work on website, but opening them in Control Center will show a banner “This variable is broken”.
  • Support for answer variables within Integrated Components (ICs) will be discontinued in Central 4.0. Existing mappings will still be editable post-patch and will output a JSON structure on the website. It is strongly advised to replace these with the appropriate IC variables.
  • The new variable picker transformation will not be applied to conditional section mappings belonging to past versions of the page template.

Other Changes​

Widget Machine Name​

Widgets will no longer require hard-coded ID numbers. Instead a machineName can be set as the unique identifier for each widget.

In Photon, service definitions can be tagged with the machine name. This will take precedence over the ID to map widgets to services.

Widget files can be placed in var/widgets/{machineName}. A basePath property allows the files to be located outside of the installation home directory (e.g. vendor…).

Widgets created via the Control Centre will be stored in var/widgets/cc.

Visible Column​

The visible column is a new addition to the JaduXFormsCalculations table, used in Predefined logics. A migration script can be implemented to update this column, rendering the logic invisible on the "Create logic" page.

"Repeatable Question Row" logic​

The predefined "Repeatable Question Row" logic is now hidden. In forms, existing uses of this logic with hardcoded static row number mappings will automatically convert to Literal logic, preserving the Repeatable mapping and the correct row selection.

Instances with dynamic "Row Number" mappings will remain unchanged. However, since "Repeatable question row" logic is considered legacy, its use is discouraged.

Variable Service​

A new variable service is available for components. This service allows for the application of built-in or custom transformers, as well as custom manipulation during answer evaluation. If no variable service is added, SecondaryFieldAwareVariableService will be used as default.

validateQuestionResponse method​

The BaseComponentService (the base class for form components) now includes a new method called validateQuestionResponse. This method takes over the validation logic previously found in saveAnswer. Additionally, validateQuestionResponse is triggered when a row in a repeatable section is added or updated.

note

If a custom component does not define its own validateQuestionResponse method, it may bypass validation that was previously implemented within the saveAnswer method for that specific custom component.

All Questions & Answers Data Handling:​

Empty answers, excluding '0' or empty JSON string arrays, will be disregarded.

For integrated components, if retraced with empty answer values, the answer will be hidden.

We recommend that you use NULL or empty string values instead of default empty answer values to prevent issues.

Post-upgrade steps​

A new cli command has been added to migrate Triple des encrypted data to AES encryption:


php cli.php cms:upgrade:convert-encryption-to-aes --dry-run // To identify the no. of records that would be migrated for each site.

php cli.php cms:upgrade:convert-encryption-to-aes siteUrl // (eg:- localhost/galaxy3) - This is to run migration for the given microsite (galaxy).

php cli.php cms:upgrade:convert-encryption-to-aes // Full run for all migrations which is admin authenticatorKey, Users and Integrations for main site and across all galaxy sites.

Any cache clearing, re-indexing, link checks etc. that need to be done after the upgrade.

Following the upgrade, confirm that the website is responsive and that you can successfully log into the Control Center.

Troubleshooting tips​

Refer to our online troubleshooting guidance for tips.

Rollback instructions​

We recommend that rollback of the upgrade is undertaken if:

  • The site is down and can not be brought up
  • A critical issue is present on the site that will affect the organisation in a business critical way and does not have an immediate or imminent resolution
  • Forms have not been returned online

Once forms are online any rollback activities will affect data integrity and are to be avoided.

Should you ever need to revert from the patch, from inside the patch directory run the following command and then clear the system cache:

php -d memory_limit=512M meteor.phar patch:rollback

Further information on rolling back the patch is available in our manual.

danger

There is no command available to revert the encryption conversion for Users, Admin and Integration Settings. The command is destructive and will remove the old values.

To rollback following execution of this command, a backup of the affected database tables will be required.

Where to get help​

Testing information​

The following test cases are recommended to be executed in your UAT or Dev environment before applying this upgrade to your production environment:

  • Check correct version of Jadu Central is installed
  • Check homepage content can be created (Publishing > Homepages)
  • Check homepage created can be submitted, previewed and viewed live
  • Check preview matches live view
  • Check a form can be imported
  • Check imported form can be made live and submitted
  • Check navigation through form operates correctly (next, previous)
  • Review the submitted form in the Control Center
  • Generate a PDF from the submitted form
  • Check PDF link is present on the completed page if added and generated
  • Create a form and check page templates and can be created and added
  • Check actions which reference a “user” variable in their template can be re-run successfully
  • Export the created form
  • Confirm the availability and behaviour of any customisations
  • Log into the website using a user account and confirm the behaviour of your MyAccount portal
  • Confirm the presentation of any blogs