Upgrading the model refers to the act of replacing an older version of a base or mixin model with a newer version. Upgrade your model to make new features, improvements to features, and user experience and performance improvements available to users. An upgrade model is the new version of the base or mixin model, until the upgrade is complete. When the upgrade is complete, the upgrade model becomes the new base or mixin model and the original base or mixin is no longer in use.

Upgrading your model is different from updating your upgrade files. Upgrading your base or mixin models changes the composition of the working model itself, modifying the resources that your working model inherits and mixes in. Updating an upgrade file ensures that your data sources maintain the correct structure as you issue new versions and revisions of your working model. The primary upgrade file is named Main.upgrade and additional upgrade files are named based on their model namespace, for example flow:Main.upgrade.

When you upgrade a model, carry out the following set of tasks:

1. Specify the upgrade model.
2. Review the changes introduced by the upgrade model.
3. Merge changes from the upgrade into the working model and resolve any model conflicts.
4. Test the model to ensure that you have resolved the issues correctly.
5. Complete the upgrade.
6. Upgrade the model metadata.

Some of the changes introduced by an upgrade, such as the addition of new classes, can be relatively straight-forward. Others, such as the modification of complex UI forms or data mappings, may require more care.

Model types

Different terms are used to refer to models based on the role they play in their relationship to other models.

Working model
Working model refers to the overall model that you are developing. The term refers collectively to the current model, base model, and any mixin models that participate in defining the application that you will ultimately deploy.

Current model
The current model is the model that you are currently carrying out development work on. It is the only model that you are able to edit directly using NexJ Studio.

Base model
The base model is the model that forms the foundation of your working model. A base model is a JAR file to which the working model makes reference. When the working model is published, all uncustomized base-model elements are copied over and included in the published JAR file.

Mixin model
Mixins are models that provide additional functionality, but are typically not complete enough to be deployed on their own. When the working model is published, the elements of the mixin model are not included in the published JAR file. Only a reference to its mixin model is included. As a result, the mixin models must be available at the time of deployment.

Upgrade model
During the upgrade process, an upgrade model is the new base or mixin model that is replacing the existing base or mixin model. During the upgrade you can use a 3-way comparison to see how changes between the upgrading and existing models will effect your working model. At the end of the upgrade, the upgrade model becomes the new base or mixin. Upgrade models are not directly editable and are never deployed.

Before you upgrade

Before upgrading, consider planning your upgrade process. For example, consider how you will review and merge upgrade changes and test upgrades.

Reviewing and merging upgrade changes

You upgrade your model to include new features and improvements to existing features into the model. However, you may have previously customized features for your specific business needs. Your customizations may conflict with the
latest NexJ CRM functionality.

When you merge code, you resolve conflicts between custom project code, current core code, and the latest NexJ CRM code. Consider resolving minor code conflicts early in the upgrade process. Resolving large conflicts may involve coordination between business and development teams. Consider planning updated designs for large scale conflicts with your business and development teams before merging code. For example, defer large conflicts that require starting the application to a later stage in the upgrade.

A functional feature contains multiple files and file types, for example, metaclasses, UI forms and screens, integration messages, data transformations, and services. Developers may encounter issues when working in parallel because changes are visible by file type rather than feature in the Upgrade view in NexJ Studio. To avoid this issue, consider:

• Dividing work by file type, for example, one developer works on metaclasses, a second developer works on forms and screens, another works on unit tests.
• Minimizing the size of the development team early in the upgrade, for example, to 2 or 3 developers. Then, increase the team size as clearer boundaries between features and files emerge later in the upgrade process.
• Performing frequent checkins.
• Promoting clear communications between developers.

For more information on reviewing and merging upgrade changes, see Reviewing and merging upgrade changes.

Testing upgrades

Expect to encounter validation errors after merging code. Consider prioritizing which errors to resolve. For example, initially resolve only the compile-time errors that prevent deploying and launching the application. Aim to get the application running to allow testing to begin. Also consider dividing validation errors between developers.

After performing smoke tests, consider resolving only the major errors that prevent QA from performing a full regression test. Also consider assigning developers to bug fixes by workspace.

When upgrading merged features and enabling new features, perform a merge of features that were too large for the merging during the initial code merge. At this stage, also run and update unit tests, then triage and fix resulting bugs. Anticipate that this stage will be the longest phase of the upgrade process. This stage may resemble a regular development phase.

For more information on testing upgrade changes, see Testing upgrades.

Specifying upgrade models

Begin the model upgrade process by specifying the model that you want to use to replace your existing base or mixin model.

The upgrade model must be available as a published JAR file and loaded into the base models tab of the model library.

To specify an upgrade model.

1. In the toolbar, click the Set Current Model button .
   The Model Library dialog opens.
2. In the Models tab, select the model whose base model (or mixin) you want to upgrade and click Edit.
   The Properties dialog opens.
3. Specify the model you want to upgrade.
   • If you are upgrading the base model, click the Browse button next to the Upgrade Model field.
   • If you are upgrading a mixin model, click the cell in the Upgrade column next to the mixin model that you want to upgrade and then click the Browse button that appears in the cell.
     A dialog opens.
4. Browse to the upgrade model and click OK.
   The dialog closes. In the Properties dialog, the Upgrade Model field now identifies upgrade model.

5. Click OK.
   The working model information now identifies the current model, the old base model, the mixin model, and the upgrade model.

   Note

   Do not click Complete Upgrade.
   Clicking this button will complete the replacement of the base or mixin model with the upgrade model without giving you the opportunity to review the changes the upgrade introduces.

   If you do complete the upgrade prematurely, you can recover by respecifying the original base model and restarting the upgrade process.

6. Click OK.
   The Properties dialog closes.

7. Click Close to close the Model Library dialog.

The model now recognizes that it is being upgraded.

If the upgrade view does not open automatically, open it from the menu bar by clicking Window → Show View →Upgrade. You can then continue by reviewing the comparison summary and making any model changes required.

Reviewing and merging upgrade changes

After you have specified an upgrade model, you can use the Upgrade view to review the model changes introduced by the upgrade and to merge changes into the current model.

The upgrade model might add, delete, or modify base model items. These might be changes to resources that you have customized, or to resources that you have not customized. The Upgrade view allows you to view a summary of changed resources at a glance. You can also explore the details of each change and update the working model as required.

The comparison editor

The comparison editor allows you to view the detailed differences between your current and base models. During an upgrade, it allows a three-way comparison between the base, current, and upgrade models.

The comparison editor opens whenever you double-click a model element in the Upgrade view.

Two-way comparison

Two-way comparisons are launched in two cases:

• You are looking at a resource that differs between the base and current models, but is unaffected by the upgrade. These resources are marked with grey right-pointing arrow .
• You are looking at a resource that differs between the base and upgrade models, but that has not been customized. These resources are marked with a blue left-pointing arrow .

In both of these cases, only two versions of the model exist, so the only comparison available is a two-way comparison. It is also possible to force a two-way comparison between an element from the upgrade model and the current model, but this is done by explicitly telling the three-way comparison to ignore the base model.

When you open a comparison between the base and current model, the comparison editor displays source code for both models. For structured resources, a Structure Compare frame gives you an expandable view of the changes in the resource. Double-clicking the changes in the Structure Compare frame focuses the Text Compare frame on the changes to that part of the resource. The Current section of the Text Compare frame allows you to edit the model source directly.

You cannot make changes to the Base model.

The following picture shows a current model that has customized a class by doing the following:

• Deleting attribute A
• Changing the type of attribute C
• Adding attribute D

Notice that the overlay icons differ depending on the nature of the change.

Similarly, when you open a comparison between the base and upgrade models, the comparison editor displays resource source code and structure for both models. In this case, however, none of the panes are editable, because you cannot make changes to base or upgrade models. In the following image, the upgrade changes the type of attribute C and adds a new attribute D.

Three-way comparison

Three-way comparison occurs when a Main.upgrade file introduces changes to a customized resource.

Depending on your Compare/Patch preferences, you may initially only see the source for the current model and upgrade model. However, differences between these models and the base model are still highlighted. For example, in the following screen, Attribute C is highlighted because of a difference between the base model and the other two models.

Similar to the comparison between the current and base models, you can edit the Current model directly in this editor. You cannot edit the Upgrade or Base models.

If you click the Show Ancestor Pane button , the base model source code appears, as shown in the following image:

Sometimes, you may want to ignore the original base, and focus only on differences between the upgrade model and the current model. If this is the case, you can click the Two-Way Compare (Ignore Ancestor) button . This button turns the comparison editor into a two-way comparison between the Current and Upgrade models. For example, the following image shows the same upgrade, ignoring the ancestor.

Upgrade conflicts

Upgrade conflicts occur when a difference between the current model and upgrade model overlaps with a difference between the current model and the base model.

This is:

• The current model customizes a model element from the base.
• The upgrade model makes a change to the same element.
• The specific changes made by the current and upgrade models are different and overlap each other.

Example of a three-way difference without a conflict

Suppose your working model is based on a model called BaseModel, which has a revision value of 1.0. The models have the following details:

• BaseModel 1.0 includes a class, ExampleClass.
• ExampleClass has a single attribute, AttributeA, which is a tinyint.
• In your current model, you customize ExampleClass and add a second attribute, AttributeB.

Now suppose that you want to upgrade your base model to use BaseModel 2.0, and that BaseModel 2.0 includes the following model change:

• BaseModel 2.0 modified AttributeA so that it is now an integer.
• BaseModel 2.0 introduces a new attribute, AttributeC, which is a string.

When you carry out the upgrade, you will not see any conflicts. This is because the changes that the current model makes to AttributeA through customization do not overlap with the changes introduced by the upgrade. In order to pick up the changes from the upgrade, however, you still have to merge those changes into your customized model.

Example of a three-way difference with a conflict

Now suppose a small change in the example. You still begin with a model based on BaseModel 1.0:

• BaseModel 1.0 includes a class, ExampleClass.
• ExampleClass has a single attribute, AttributeA, which is a tinyint.
• In your current model, you customize ExampleClass and make the following changes:
  • You change the type of AttributeA to decimal.
  • You add a second attribute, AttributeB, as an integer.

You now upgrade your base model to use BaseModel 2.0, which includes the following model changes:

• BaseModel 2.0 modifies AttributeA so that it is now a integer type.
• BaseModel 2.0 also introduces an attribute, AttributeB, as an integer.

This situation will show as a conflict because there is an overlapping difference between the changes in AttributeA overlap between the current model and the upgrade model. Notice that AttributeB is not flagged as a conflict because
there is no difference between the value in the current and upgrade models. If, however, the current model had marked AttributeB as being of type double, then both AttributeA and AttributeB would be marked as conflicts.

Reviewing upgrade changes

Use the Upgrade view to review the changes introduced by the upgrade model.

To review the changes introduced by a model upgrade, you must have specified an upgrade model, and have opened the Upgrade view. If the Upgrade view is not open, you can open it from the menu bar by clicking Window → Show View → Upgrade.

You can use the Upgrade view at any time to view a summary of how the current model has modified and customize the base model. However, when an upgrade model is also specified, the view provides a three-way comparison between the current, base, and upgrade models.

To review model upgrade changes:

1. In the Model Library, select the model that you are upgrading.
2. In the Upgrade view, select the comparisons that you want to filter on:
   • To show only resources that differ between the current and the base models models, click the Current button .
   • To show only resources that differ between the upgrade and base models, click the Base button .
   • To show resources that differ between the upgrade and current models click the Upgrade button .

   • To show all resources without filtering, click the button corresponding to the currently applied filter.
     Each resource displayed in the Upgrade view has an overlay icon, which indicates the nature of the difference between the models. The icon meanings are summarized in the following table:

     Icon	Description
     	Indicates a difference between the resource in the current model and the resource in the base model.
     	Indicates that the resource exists in the current model, but not in the base model.
     	Indicates a difference between the resource in the upgrade model and the resource in the base model.
     	Indicates that the resource exists in the upgrade model, but not in the base model. That is, the upgrade introduces a new resource.
     	Indicates that the resource exists in the base model, but not in the upgrade model. That is, the upgrade will remove the resource if it is not customized.
     	Indicates a difference between the resource in the current model and the resource in the upgrade model. If the upgrade modifies a part of the resource that the current model also customizes, then an additional mark appears in the Conflict column.

3. If you want to review the details of an upgrade change, in the Upgrade view, double-click the resource whose changes you want to review.

Merging upgrade changes

Review and merge each change introduced by the upgrade model.

When you open a resource in the Comparison editor, the editor highlights each change. Conflicting and nonconflicting changes are identified by different highlight colours. You can review each change and decide whether to copy the change into the current model.

To merge upgrade changes:

1. In the Upgrade view, double-click the resource whose updates you want to review and merge.
   At a minimum, you should review any customized resources affected by the upgrade. These are marked with the upgrade overlay . If the element also has conflicts, a mark appears in the Has Conflict column of the Upgrade view.
   The element opens in the Comparison editor.
2. In the Structure Compare pane, double-click the part of the resource for which you want to view the upgrades.
   If the resource is unstructured, a full comparison opens automatically.
   The version of the element displays on the right side, and the current model's customized information appears on the left side.
3. Use the Next Difference and Previous Difference buttons to navigate through the modified parts of the model element.
   You can also use the Next Change and Previous Change buttons to navigate smaller increments of the file. Differences are generally larger content groups made up of one or more adjacent changes.
   As you click through the model element, the differences and changes become selected in the editor.

4. When you have selected a change that you want to merge into the current model, click the Copy Current Change button .
   The change is copied from the Upgrade pane into the Current pane. If you copy a non-conflicting change then the upgrade model content replaces the current model content. If you copy a conflicting change then the upgrade model content is pasted below the current model content.

   Tip

   You can also use the Copy All Non-Conflicting Changes button to copy all non-conflicting changes from the Upgrade model element to the Current model element.

5. In the Current pane, edit the model source as required to ensure its accuracy and completeness.
   This step is primarily required to resolve upgrade conflicts or to work with highly complex merges such as updates to the model's Main.upgrade file. You can also edit the current model element directly through the Current pane as an alternative to using the Copy Change buttons.
6. When you have completed making your changes to the element in the current model, press Ctrl+S to save your changes.

7. In the Upgrade view, right-click the element that you have been merging and select Mark as Merged.
   This puts an indicator in the Merge column of the table, allowing you to track which elements you have finished reviewing.

   Info

   As you continue to merge the upgrade changes into your model elements, elements that you have marked as merged may disappear from the list when you save other changes to your current model.

   As you continue to merge the upgrade changes into your model elements, elements that you have marked as merged may disappear from the list when you save other changes to your current model.

Continue by reviewing and merging each remaining element. When you are done, you can complete the upgrade.

Overriding upgrade changes

Override an upgrade change before completing the merge in order to stop your current model from making use of the model element changes coming from the upgrade.

Sometimes an upgrade model introduces change that you do not want to incorporate. If the incoming changes affect an element that you have customized, then you can review and reject the change when you merge the upgrade changes. However, if the changes affect an uncustomized element, then you must customize the element in order to reject the upgrade changes.

1. In the Upgrade view, double-click the element whose changes you want to review, and potentially reject. Uncustomized elements affected by the upgrade are marked with the base overlay .
   The element opens in the Comparison editor. The upgrade version of the element displays on the right side, and the base model version appears on the left side.
2. In the Structure Compare pane, review the differences between the base and upgrade models.
   At this point, you are unable to edit either model.
3. If you want to accept all of the changes, then close the editor.
4. If you want to override one or more of the incoming changes, customize the element so that you can edit it:
   1. Locate the element in the model navigator.
      To do this quickly, you can right-click the element in the Upgrade view and select Open. Then enable the Link Model Navigator to Editors button to immediately locate the element in the navigator.
   2. Right-click the element and select Customize.
      A copy of the base model version of the element is created in the current model and the overlay of the model element changes to the upgrade icon.

The incoming changes to this element are now ignored unless you explicitly merge them as part of the upgrade.

If you only want to override some, but not all, of the incoming changes to an element, you can continue by merging the changes into the customized element, following the instructions in Merging upgrade changes.

Testing upgrades

Test the upgraded working model before completing the upgrade.

To deploy your upgrade model for testing you must have a test environment set up for deployment and either have an environment file or a server and connections file for that test environment.

You are unable to publish a model while it is in the process of being upgraded. However, you can still deploy the working model directly from NexJ Studio.

If you deploy a model during the upgrade process, the deployment makes use of the upgrade model, and not the base model. This allows you to fully test your upgrades on a test server before completing the upgrade and publishing a deployable JAR for staging and validation.

To validate and test your model:

1. In the toolbar, click the Validate Model button .
2. Verify that there are no errors.
   You should not deploy models with errors.
3. In the toolbar, click the Set Current Server button. Choose the server or environment corresponding to your test environment.
4. [Optional] If you selected a server in the previous step, click the Set Current Connections button and select the corresponding connections file that you want to use for your deployment.
5. Configure the server settings for your test environment. When changes are made to settings that require server configuration, for example data sources and channels, the server must be configured before deployment. Configuring before deployment ensures that unconfigured settings do not cause errors.
   • To enable automatic configuration from the menu bar, click Project → Configure Automatically. NexJ Studio will run the configuration process each time you deploy a model.
   • To start the configuration process manually from the menu bar, click Project → Configure Server. The configuration process occurs.
6. Click the Deploy Model button to begin deploying to the application server.

After your model is deployed, run your unit tests and other software test plans against the application on the test server. When you are satisfied that your upgraded model works as expected, you can complete the upgrade and publish the upgraded model for deployment or further validation.

Completing the upgrade

Complete the upgrade to fully replace the original base or upgrade model with the newer version.

To complete the upgrading of a base or mixin model:

1. In the Upgrade view, click the Complete Upgrade button .
2. If there are any unmerged upgrade changes, confirm that you want to continue the upgrade without merging them by clicking Yes.
3. Click the Set Current Model button to open the Model Library dialog.
   Notice that the base version of the model has changed to the upgrade version.

It is recommended that you validate and publish your model from the Model Library dialog after completing the upgrade.

Upgrading model metadata

The Model XML Upgrade Tool automates the process of updating metadata files when new features have been added to the NexJ Application Framework.

Each version of NexJ Studio is associated with a core version of the framework which reads XML data files according to a structure defined in the XML Schema Definition. The Model XML Upgrade Tool revises the model's metadata files after a core framework update has modified the schema definition.

The Model XML Upgrade Tool can change, add, and remove XML elements and attributes of model resources. Existing metadata files will be overwritten and replaced when the tool is run. You are provided with the option to back up existing metadata files before the upgrade occurs.

Models are defined by a .metadata file that contains the core framework version number. It is common for the core version of a model to be specified with a plus sign afterwards. This indicates the model is compatible with the specified core version and above. In the following example, the .metadata file is meant to work with version 3.0 and higher:

.metadata (Version 3.0)
<Metadata name=”NexJ CRM" coreVersion=”3.0+”/>

When the core framework version has been upgraded, the .metadata file will notice it is using an older version. Running the Model XML Upgrade Tool will perform the provided upgrade steps to ensure that the model's metadata
files are compatible with the new XML Schema Definition and update the version number in the .metadata file:

.metadata (Version 4.0)
<Metadata name="NexJ CRM" coreVersion"4.0+"/>

In this example, version 4.0 of the framework changes the schema definition. The Model XML Upgrade Tool will identify which metadata files are incompatible and fix them. Framework version 4.0 will change both attribute names and attribute values: required="true" will now only be recognized as constraint="required".

Under framework version 3.0 the Person class contains the following:

Person.meta (Version 3.0)

<Class description="The person class">
     <Attribute name="firstName" required="true" type="string />

After upgrading to framework version 4.0, the Model XML Upgrade Tool will modify Person.meta to comply with the current XML Schema Definition. After the tool is run it will contain the following:
Person.meta (Version 4.0)

<Class description="The person class">
     <Attribute name="firstName" constraint="required" type="string />

The Person class now adheres to the XML format for core framework version 4.0 and is compatible with NexJ Studio installations using version 4.0.

Using the Model XML Upgrade Tool

Use the Model XML Upgrade Tool to update your model's metadata files to comply with the XML Schema Definition of the current NexJ Application Framework.

To run the Model XML Upgrade Tool:

1. In menu bar, click Project → Upgrade Model XML.
   The Upgrade XML Wizard dialog opens.
2. Select the required model and click Next.
3. In the Source Core Version field, select the version of the framework your metadata is currently using.
4. In the Target Core Version field, select the version of the framework you are upgrading the metadata to.
   This is typically the highest and most recent version number.
5. Click Next.

6. Select the resource files you want to upgrade by selecting the checkbox next to their file names.

   Info

   You can double-click any file to open the comparison editor to the right. This allows you to compare the differences between the current and upgraded versions.

7. [Optional] Select the Backup source files with .orig extension checkbox to create a backup of each metadata file being upgraded. If you are working with a clean checkout, this may not be needed.
8. Click Finish to run the tool and perform the upgrade.
   The Model XML Upgrade dialog closes. A dialog appears confirming the Upgrade XML Wizard has successfully run on the selected files.
9. Click the Validate Model button  to validate your model and ensure that the upgrade was completed successfully.

Your XML metadata files are now compatible with the selected target version of NexJ Studio and NexJ Application Framework.