Skip to main content

Upgrading the iGrafx platform

Upgrade the on-premises iGrafx platform by replacing the application server with the new version while keeping your igrafxdata base directory and databases. Plan the version path first — old versions must pass through intermediate "stepping-stone" releases.

Prerequisites​

  • Your current platform version. Check it before planning the path.
  • Access to the stepping-stone installers — provide your order number and date at the iGrafx licensed-software page.

Stepping-stone versions​

When upgrading from an old version, upgrade through these intermediate versions in order before going further:

Coming fromUpgrade to
15.x16.1.0
16.0 – 16.216.3.4
16.3 – 17.217.3.3
17.3 – 17.517.7.0.758
17.6 – 18.218.3.7.941 (⚠️ not 18.3.8)
18.3 and laterlatest

For example, from 16.4 to 18.3 you upgrade to 17.3, then 17.7, then 18.3.

Migrating from Process Central / Web Central 15.x is a different process — see Migrating to the iGrafx platform.

note

Java: The required JRE depends on the release — Java 11 for 17.7–19.4, Java 21 for 19.5–19.24, and Java 25 for 20.0 and later. If you use a WAR deployment rather than the pre-deployed package, you upgrade the JRE yourself; see WAR file deployments. The pre-deployed packages ship with Tomcat 11 (16.3.x–17.2.x shipped Tomcat 8; 17.3.x–17.4.x shipped Tomcat 8.5, 17.4.x-19.24.x shipped Tomcat 9).

Backup requirements​

Before any upgrade, back up all databases — the administration database and every repository database (they may be combined or separate, and you may have several repositories). Also back up your igrafxdata base directory (for example C:\iGrafx\iGrafxPlatform\igrafxdata).

Maintenance window / downtime​

The service is removed and reinstalled, so the platform is down during the upgrade. Also:

  • ⚠️ In a cluster, stop all nodes before upgrading — data can be corrupted if a node accesses the database during the upgrade.
  • ⚠️ If the admin or a repository database is actively mirrored, disable mirroring for the duration.
  • Never connect two platform servers to the same administration or repository databases at the same time (except in a cluster).
note

If you customized the platform service — a non-default security scheme, Java memory settings, extra startup variables — note the existing service settings before you remove the service, and reapply them afterward. Gathering this can depend on your environment; if in doubt, check with iGrafx Professional Services first. Settings to capture include JVM memory, the security scheme, SAML2 configuration, and any other customizations.

Steps​

Choose the procedure that matches your deployment.

Pre-deployed Tomcat on Windows (current installation 16.3 or later)​

  1. Confirm your database and igrafxdata backups (above).

  2. Open a command line, go to your existing installation directory (for example C:\iGrafx\iGrafxPlatform), and open the windows subfolder.

  3. If you customized the service (or aren't sure): run manage_service.bat iGrafxPlatform (replace iGrafxPlatform with your service name). On the Java tab, copy the memory, security-scheme, and port settings into a text file for later, then close the dialog.

  4. Run remove_service.bat iGrafxPlatform.

  5. Rename the existing installation directory so you can identify it as the previous version — for example C:\iGrafx\iGrafxPlatform_w.x.y.z.

  6. Extract the new iGrafxPlatform*-Predeployed.zip into the location you want the server to run from (for example C:\iGrafx\iGrafxPlatform). Don't ignore decompression warnings — if one appears, try a location nearer the drive root.

  7. Copy the igrafxdata folder from the renamed previous base directory into the new one (for example from …_w.x.y.z\igrafxdata to …\igrafxdata).

  8. As a best practice, archive your log files, then empty the \igrafxdata\logs folder.

  9. If you modified server.xml or context.xml in the previous Tomcat (for example for SSL behind a proxy or a JNDI database connection), reapply those changes to the new files in apache-tomcat-9.x.xx/conf. Don't overwrite the new files with the old ones.

  10. From the windows subfolder, run install_service.bat 8080. To use different ports, a different service name, or a different authentication scheme, adjust the command — run install_service.bat with no port to see the format and defaults. Confirm the UAC prompt if asked. The service starts automatically and shows a confirmation.

    The command-line confirmation that the platform service installed and started.

  11. If you did step 3: run manage_service.bat iGrafxPlatform again, reapply the memory settings and any custom system properties from your notes, then save with OK and restart the service from the Windows Services dialog. (A -XX:MaxPermSize parameter is ignored on Tomcat 8 and 9 — don't set it.)

  12. Open the application in a browser from a different machine to confirm it's reachable.

  13. Apply any database adjustments relevant to your environment.

  14. If the platform connects over TLS to a server with a self-signed certificate or one from a non-standard CA — a mail server, an LDAP or Active Directory server, or an iGrafx Process AutomationProcess Automation Executing a modeled process directly via a workflow engine, with human tasks, system calls, and decision logic orchestrated from the model. server — re-import those certificates into the new installation's Java keystore. See Trust an external server's certificate.

info

If the browser shows a setup page asking for database details, you most likely skipped copying igrafxdata (step 7). Stop the service, redo that step, and restart.

Pre-deployed Tomcat on Windows (current installation 16.2 or older)​

The procedure is the same as above, with these differences:

  • In steps 3–4, the default service name before 16.3 was Tomcat7, not iGrafxPlatform (it changed in 16.3). Use manage_service.bat Tomcat7 and remove_service.bat Tomcat7.
  • The previous Tomcat is version 7 — find server.xml and context.xml in apache-tomcat-7.x.xx/conf. The format of these files changed in 16.3, so reapplying your changes by hand is required; overwriting the new files with the old ones prevents the server from starting.

WAR file deployments​

  1. Back up all databases and your igrafxdata folder.

  2. Upgrade the deployed JRE before you deploy the new WAR. The version depends on the release you're upgrading to:

    • 17.7 – 19.4 — Java 11
    • 19.5 – 19.24 — Java 21
    • 20.0 and later — Java 25

    You can keep your own application server as long as it's compatible with that JRE.

  3. Deploy the new WAR (or EAR) file using your usual deployment mechanism.

Administration changes after upgrade​

  • New permissions — upgrading from 16.2 or earlier can introduce permissions that aren't granted to security roles by default. Enable them where you want them in Administration → Security Roles (Server, Repository, or Item Roles). Treat all but Use repository and Edit Performance Indicator Data as administration permissions, and grant them with care.

    The Security Roles configuration showing per-role permission settings.

  • Logging — from 16.2 on, configure logging in Administration → Support → Logging Settings. File-based logging still works but must use the log4j2.xml format, not the older log4j.properties.

Database adjustments​

  • Full-text engine — from 16.2 on, the application server does full-text indexing, not SQL Server. After upgrading, consider removing Full-Text and Semantic Extractions for Search from the database instance (make sure nothing else needs it first). The application reindexes after the upgrade, which can make it slower than usual for a while.

  • SQL Server statistics — after upgrading a repository database, refresh its statistics so the query optimizer performs well:

    USE dbNameHere;
    GO
    EXEC sp_updatestats;

Verify​

  • Open the application in a browser from a machine other than the server.
  • In a cluster, bring all nodes back to the same version, then restart them.
  • Confirm the database adjustments above where applicable.

Rollback / backout​

The renamed previous installation directory and your backups are your fallback. If an upgrade fails, restore the database backups and revert to the previous installation. When moving the platform to new hardware, copy the igrafxdata folder across, and never restart the service on the old hardware after starting it on the new one. These articles can help: