Upgrading, Migrating and Installing Fixes


Updating a Service Pack (from ApplinX Version 9.7 and above)

The upgrade process is similar to the installation process. Please refer to the SAG Installer documentation, which you can find at http://documentation.softwareag.com/. When selecting the installation directory, ensure not to select the directory where ApplinX is currently installed (the default path is C:\SoftwareAG).

In the panel including the ApplinX specific parameters, browse and select the ApplinX license file.

Post-update Results

  • When opening the Software AG Designer, the default workspace will point to a new location. If you use the new workspace location, check that the preferences suit your needs.

  • From version 8.2, the batch and shell commands used to start and stop the server, and to start the Administrator are located in the <ApplinX installation>/bin folder.

Post-update Tasks

  • When using ApplinX web applications (JSP or .NET): Upgrade the web application using the ApplinX Web Application Manager in the Designer (refer to Framework Management in the Web Application Development documentation of ApplinX).

  • You may have made changes in your previous ApplinX version, in one of the following files. Backup copies of these files can be found (unless otherwise stated) in the ApplinX installation directory with the .bak suffix. To apply these changes to your current ApplinX version, you must copy the changes from within the backup files to the relevant file.

    • GXApplinXService.ini

    • bin/startup.bat

    • bin/startup.sh

    • bin/gxadmin.bat

    • bin/gxadmin.sh

    • config/gxadmin.prp

    • config/gxstartup.prp

Migrating

ApplinX applications from previous ApplinX versions are able to run on the current ApplinX version once you have performed a number of migration activities. The migration process has been tested for supported versions. Migration can be performed when installing the new ApplinX server version or via batch files after the new server has been installed.

The following topics are covered below:

Pre-Migration Steps and Prerequisites

  • Back up the repository database.

Migration Options

Migration can be carried out as follows:

Migration of all ApplinX Applications when installing ApplinX

To migrate ApplinX applications during the installation process: In the screen where you select the ApplinX parameters, select the Migrate previous ApplinX data check box and specify the existing installation location.

graphics/wminstall4a.png

Migration of all ApplinX applications after installing ApplinX

To migrate all ApplinX applications after the installation has been completed: Run the <ApplinX root>\utilities\migrate_ApplinX_server.bat/sh file, enter the installation path of your previous installation, and then enter the new path of the current installation.

For example: migrate_ApplinX_server.bat "c:\ApplinX52" "c:\SoftwareAG\ApplinX"

Migration of a Specific Applinx Application

Start of instruction setTo migrate a Single Applinx Application

  1. Export the relevant GXAR file of the application (the GXAR file includes both the application and entities)

  2. Import the GXAR to the new version. Refer to Importing an Application's Configuration or Entities in the Designing and Developing an Application documentation.

Migration of ApplinX Applications with External Database

For ApplinX applications that use an external database (except JDBC-ODBC), the database type will be changed automatically to internal database. A message warns that there are applications containing a JDBC-ODBC database type that will not be migrated. You have two options:

  1. Choose OK to continue with the installation. ApplinX will migrate all applications except for the JDBC-ODBC types. The names of these applications will be written to a log.

  2. Choose Cancel to stop the installation, then modify those applications.

Start of instruction setTo modify JDBC-ODBC applications

  • Change the repository type to internal DB /gxz in the original ApplinX installation installed on your computer, and then restart the installation and migration.

Migration Results

The following is the outcome of the migration process and relates to migrating all ApplinX applications:

  • The entire old config folder (except for the http.xml file) is copied to the new installation location. The gxstartup.prp file from this folder is renamed to .bak, and the new gxstartup.prp file (from the new installation) is used.

  • The new config folder (from the new installation) is renamed to config.bak.

  • The entire host-applications folder is copied except for the demo applications. The demo applications from the new installation are used.

  • All database related jar/zip (classes*.zip, classes*.jar, *sql*, *db2*) are copied to the lib folder of the new installation. Note: any other DB driver should be copied manually to \ApplinX\applinx-web\WEB-INF\lib.

  • The batch and shell commands used to start and stop the server, and to start the Administrator are no longer located in the ApplinX installation folder. These files are now located in <ApplinX installation>/bin folder and are named startup.bat and shutdown.bat accordingly for the server, and gxadmin for the Administrator.

    The start-gxserver.bat/sh and gxadmin.bat/sh files from the previous ApplinX installation are copied to <ApplinX Installation>\bin and the gxstartup.prp and GXApplinXService.ini files are copied to <ApplinX Installation>. These files are renamed to *.bak.

    Notes:

    1. Any manual changes made in the previous ApplinX versions (such as language, file encoding, database jar etc.) must be backed up and copied to the new version.
    2. When migrating from APX 8.0, conf folder (internal Tomcat) is not copied from the old installation. Therefore any manual change made in this folder must be re-done again in the new conf folder.

Relevant for migrating from ApplinX versions before 8.0:

The following actions occur when the server is started for the first time after the migration process has been completed:

  • Each application (configured in config/gxconfig.xml), will be created as a separate file and copied to host-application/<application name>/gxconfig.xml. The original file config/gxconfig.xml will hold from now on only ApplinX server configuration and host definitions which are not in use by any application.

  • Replay files are copied to host-applications/<application name>/records and new recorded files are saved in this location.

  • If a file based repository (GXZ or MDB) is configured for the application, the repository is copied to host-applications/<application name>/db .

A post-migration report is written to the <ApplinX root>/log/gxlog.txt.

Note:
If the application name includes space characters, these are replaced by underscores, as space characters are not supported in versions from 8.0 and above. However, previous SOAP clients will be able to connect to old addresses which include spaces.

Post-migration Tasks

  • When opening ApplinX Designer, enter the name of a workspace directory. When upgrading from ApplinX version 8.0 and above, define a new workspace directory in order to be able to work with both versions.

Post-migration Web Application Tasks

JSP:

  1. Ensure that you have:

  2. It is recommended to import/copy the web applications from older Eclipse versions to the lastest version of the Software AG Designer, as this is the common Software AG development tool, used with other Software AG products such as ApplinX, EntireX, CentraSite and Integration Server.

  3. Upgrade the web application using the ApplinX Web Application Manager in the Designer (refer to Framework Management in the Web Application Development documentation).

  4. Compile the JSP project:

    • With IDE (from Eclipse or any other IDE)

    • Without IDE (make.bat)

Note:
When working with an application which included space characters in the application name, you are required to manually change the application name in the web application (e.g. in GXBasicWebForm.jsp file, or in the Framework Configuration Editor, in the Application name parameter).

.NET:

  1. It is recommended to convert from .NET project type "Web Project" to "Web Site" as from the current version ApplinX generates .NET web pages based on the "Web Site" format and file structure.

  2. Upgrade the web application using the ApplinX Web Application Manager in the Designer (refer to Framework Management in the Web Application Development documentation).

  3. Compile (relevant for .NET "Web Projects" type projects):

    • With IDE (from Visual studio)

    • Without IDE (make.bat)

Note:
When working with an application which included space characters in the application name, you are required to manually change the application name in the web application (e.g. in GXBasicWebForm.cs/GXBasicWebForm.vb file, or in the Framework Configuration Editor, in the Application name parameter).

Installing a Fix using Scripts

Fixes are available for Linux and Windows on the Software AG Empower website. Follow the instructions below when downloading the fix from Empower.

Note that when applying a fix, you must make sure that the installed ApplinX version is of the same service pack as the fix version, i.e. that the first three digits are the same (e.g. 10.1.0).

Start of instruction setTo install a fix

  1. The fix will install and add all the necessary new files to your existing ApplinX installation.

  2. Before starting the fix installation, shut down the ApplinX Server service and close the Software AG Designer.

  3. To start the fix installation process, extract the fix zip file to the existing ApplinX directory: For example: C:\SoftwareAG\ApplinX. A new directory is created: \hotfix-<hot fix version>.

  4. To install the fix, just run install-hotfix.bat on Windows platforms, or install-hotfix.sh on Linux platforms. On Windows platforms: Check that the ECLIPSE_PATH parameter is pointing to the desired Eclipse installation location and that you have removed the rem remark indication.

    Note:
    Installing the fix also updates the Eclipse plug-in.

  5. During the fix installation, a backup folder will be created containing the original files from before the update (backup-for-hotfix-<hot fix version>).

  6. After the fix installation, a log is created with a list of all the copied files (install.hotfix.log).

  7. Upgrade the web application using the ApplinX Web Application Manager in the Designer. Refer to Framework Management in the Web Application Development documentation.

Note:
It is possible to uninstall the fix. This will revert all updated files to their original state. To uninstall the fix, just run uninstall-hotfix.bat on Windows platforms, or uninstall-hotfix.sh on Linux platforms. After the fix uninstallation, a log is created with a list of all copied files (uninstall.hotfix.log).

Upgrading the ApplinX Server

When upgrading the ApplinX server - for example when applying a fix or during migration - you will need also to upgrade the web application as well. If the client and server versions do not match, you will get the following error message:
"Error 6002- Version mismatch.
The application version [<version>] does not match the server version [<version>]. Server version must be equal to the application version.
Action: Upgrade the web application.
"

Troubleshooting

This section covers the following topics:

Upgrading from Version 5.2

  • GXAR File
    If you had trouble migrating from 5.2 or earlier version, you can also upgrade from 5.2 version by creating a new ApplinX Application (GXAR file) in the new environment and importing the GXZ file you have exported from the 5.2 version. In this case you can import all the entities directly to the new application's repository.

  • Binary Client
    If you are using a binary client, you will need to re-generate this after migrating from version 5.2.

    Start of instruction setTo re-generate a binary client

    • From the ApplinX Designer, choose Generate Procedure Client on the relevant procedure group.

      See Generating a Procedure Client under Designing and Developing an Application.

      The newly generated class files will replace the old class files that are currently included in your web project.

Converting Old Paths

ApplinX offers a built-in utility to convert old paths, which are only supported for runtime, into the new Path Procedures. After conversion, check that all fields were mapped correctly and match the old path in the 5.2 version.

The new Path Procedures are much more powerful. We recommend you convert the old paths to Path Procedures. See Path Procedures in section Designing and Developing an Application.

Installing a Fix using Scripts (Hotfix or Fix in Hand)

Follow the instructions as described under Installing a Fix using Scripts. Make sure you unzipped the hotfix into the ApplinX installation directory, otherwise the upgrade process will not work.

Upgrading a Web Application

After applying the hotfix on the ApplinX server and Designer you must also upgrade the web application as well, otherwise if the client and the server versions do not match, you will get the following error message: "Error 6002- Version mismatch. The application version [<version>] does not match the server version [<version>]. Server version must be equal to the application version. Action: Upgrade the web application".

See Framework Management in the Web Application Development documentation.

Use New and Different Workspace for each Environment

When upgrading to a new version it is important to also create and use a different workspace. After you have created a new workspace, you can use the workspace import wizard to import the old workspace configuration to the new one.

Uninstalling the ApplinX Server and Designer

If you want to revert the changes made by the hotfix process and return to your original state, you can use the uninstall batch file utility to return to the old ApplinX server version and build; the Designer's plug-in must be uninstalled manually.

Start of instruction setTo return to original state

  1. Close the ApplinX Server and use the uninstall batch file (in Linux it the .sh file) located in the hotfix directory to remove the fix installed.

    Note:
    If the user has multiple hotfixes, you will need to downgrade the last one first and then the older one.

  2. Open the Designer and choose Help > About > Installation Details. Select the ApplinX plug-in and choose Uninstall.

  3. Reinstall the ApplinX plug-in. Open the Designer and choose Help > Install new software.

  4. Click Add and select the ApplinX plug-in installation file (located in <Installation directory>\Software\Designer\updates or <last hotfix folder>\Designer). The file naming convention is:
    com.softwareag.applinx.workbench-[version number][XX].[Y].

  5. Select the ApplinX plug-in from the list on the Main screen and click Finish.

  6. Restart the Designer and open the ApplinX perspective.

    After the fix has been uninstalled, a log is created with a list of all copied files (uninstall.hotfix.log).

You also need to unzip the old web application file located in the previous version to the location of the web application folder.