Nuclos 4.0 upgrade notes: special measures to observe when updating.

On this page

This page was machine-translated from German as a first draft and is currently under review. The authoritative source remains the German original (see the language switch above).

Database migration

Upgrading an existing Nuclos 3 instance to Nuclos 4 performs a series of automatic migration steps that may require manual follow-up work. The upgrade procedure and the required follow-up work are described in the following sections. Please note that the follow-up work can take some time. Performing a prior backup of both the Nuclos database and the Nuclos home directory <NUCLOS-HOME> is essential for easily restoring a working installation in case of error.

Prerequisites for an upgrade to Nuclos 4

The following prerequisites must be met before an upgrade can be performed.

• Every Nuclet in your instance must have a unique name and a unique package (see MIG-06).
• No old rules may exist in your instance anymore; all rules must be migrated to the Nuclos API (see Legacy rules in Nuclos 4.0).
• Your Nuclos instance must already be updated to at least Nuclos 3.12.0, and every form in it must have been opened at least once. If you have assigned workspaces to user groups, you must publish these workspaces at least once. If you already use the matrix component that has existed since Nuclos 3.15.0, your Nuclos instance must already be updated to at least Nuclos 3.15.6 (see MIG-03).

Performing the upgrade to Nuclos 4

The following steps are to be taken to perform an upgrade to Nuclos 4.

1. Run the installer, as you may be used to from previous upgrades.
2. Start the Nuclos server; this automatically starts the automatic migration. The migration logs the execution of all steps in the file <NUCLOS-HOME>/logs/migration_04_00_0022_main.log. You can tell the migration is complete by the fact that the file <NUCLOS-HOME>/logs/migration_04_00_0022_finish.log has been generated.
3. Check the file <NUCLOS-HOME>/logs/migration_04_00_0022_main.log once the migration is complete. This file provides information about any migration errors that occurred and in particular lists detected manual follow-up work, thus giving you important hints about the follow-up work still to be done.
4. Carry out the required manual follow-up work, see the following points MIG-01 to MIG-09.

To make it easier to get an overview and estimate the migration effort for your Nuclos 3 instance, a short list of the "typical" follow-up work follows. It gives you an overview and covers the follow-up work required in most cases. In any case, please read the following migration notes MIG-01 to MIG-09 carefully.

1. All data sources (menu Configuration | Data sources) and database-object source texts (menu Configuration | Database) must be checked and adjusted if necessary. In most cases no adjustment is required, but this can be the case, for example, when users, states or actions are joined in, because as of Nuclos 4 they receive a UID, i.e. the column INTID in T_MD_USER, T_MD_STATE and T_MD_PROCESS is replaced by STRUID. The corresponding join conditions must be adjusted. There can be further individual cases in which adjustments are required to restore the functionality of a data source.
2. All data sources for dynamic business objects (dynamic entities) and all data sources for charts must be opened and saved once. Afterwards they must be inserted into the corresponding layouts again, the column settings must be restored, and state-dependent permissions on dynamic business objects must be re-entered in the state model. This configuration information cannot be migrated from a Nuclos 3 instance, so it is recommended to check the affected places beforehand and note them if necessary, because the migration removes dynamic business objects from the layouts.
3. All state models must be laid out again; the layout of existing state models is lost during the migration.

System changes

System changes

• Views are no longer created for business objects, dynamic business objects and charts.

Follow-up work

• Dynamic business objects and charts must be saved again and then re-entered into the layouts and tree views (business-object wizard).
• If the migration could not find and replace something automatically, the data sources and database objects must be adjusted manually. They should therefore be checked for correct operation.
• Subform list views for dynamic business objects must be recreated.
• Read permissions on dynamic business objects in the state model must be granted again.

System changes

• The column settings in the workspaces are only supported in the new list-view format (as of Nuclos v3.12). Data of the previous column configurations is not carried over.
• The settings of a matrix are also affected.

Avoidance

• With a Nuclos v3.12+, it is enough to open a result list or an affected subform to trigger a conversion. When the client is closed, these are then saved in the database. For shared workspaces, don't forget to publish!
• A Nuclos v3.15.6+ is required for the matrix.

System changes

• Every Nuclet gets a random local identifier (4 digits). This will differ from instance to instance.
• Replaces T_EO in the table names.
• Database-object names will have to begin with this identifier.
• The automatic migration will rename tables.
• Database constraints & indexes are dropped and recreated with a new central name.
• Nuclet component assignment and a Nuclet import will exchange identifiers accordingly.

Follow-up work

• If the migration could not find and replace something automatically, the data sources and database objects must be adjusted manually. They should therefore be checked for correct operation.

User Preferences (not the workspaces) are reset. These include, among others:

• Most recently used workspace
• Order of the workspaces in the bar
• Settings for the LiveSearch
• Column settings for the personal tasks and other task lists
• Split-pane setting on the forms (not the workspace layout)

System changes

• Nuclets must have a unique package and a unique name.

Preparation

• Add missing name and package details in Nuclets.
• All Nuclets must be checked for uniqueness of package and name and changed if necessary.

Workspaces are largely migrated. Exceptions are:

• Most recently opened Explorer tabs.
• The search condition of a recently opened business-object tab.

Resource planning is largely migrated. Exceptions are:

• Certain special settings such as "Step arrangement" or "Fixed width".

The display of state models is reset

Here we describe a procedure that enables you to carry out this follow-up work in advance. This is valuable, for example, when you want to keep the downtime of your production environment as low as possible. 

1. Successfully perform the migration on a test / configuration environment.
2. Identify and handle the follow-up work using the migration log (migration_04_00_0022_main.log). You can find these fastest with the corresponding searches for the MIG-XX topics.
3. Export your Nuclet as usual using the Nuclet management. Note: the instance transfer was removed. If your system has several individual Nuclets, it is a good idea to create a new parent Nuclet and equip it with the dependencies on the other Nuclets.
4. On the production environment you then also install the new Nuclos 4.0 version and run the migration on the first start of the server. 
5. Once the migration has run successfully, you can import the Nuclet with the necessary follow-up work.