3.2 Installing Patches and Performing Upgrades
Key Takeaways
Back up the database and every customization and stop all running tasks before patching or upgrading.
A patch archive is expanded into the existing installation directory, then the patch DDL script and iiq patch <version> are run.
A new version must be expanded into an empty directory, because expanding over an old version leaves obsolete files that cause failures.
iiq upgrade runs once per installation, not once per application server, after upgrade_identityiq_tables has been applied.
E-fixes match one patch level and must not be carried into an upgraded installation, and the IQService version must match the IdentityIQ version.
Installing Patches and Performing Upgrades
Objective 1.5, understand the process of installing patches and upgrades, is about two procedures that look alike but are not interchangeable. The exam often describes one step and asks whether it belongs to a patch, an upgrade, or neither.
Vocabulary
| Term | Meaning | Example |
|---|---|---|
| Release (GA) | A full product version | IdentityIQ 8.4 |
| Patch | A cumulative maintenance release for one version | 8.4p2 |
| E-fix | A narrow fix delivered for one specific patch level | An e-fix built for 8.4p2 |
| Upgrade | Moving to a new version | 8.3 → 8.4 |
Read the release notes (for an upgrade) or the patch README (for a patch) first. They list supported platforms, required actions, and behavior changes. SailPoint's upgrade chapter opens with "Do not perform the upgrade until you have completely read the Release Notes."
Preparing: Identical for Both
- Check what is running. On the Task Results and Report Results pages, confirm that no task-generated processes are running, and terminate any that are before shutting down. Workflow approvals also appear on Task Results. They are not running processes, so do not terminate them.
- Back up the database and customizations. Any customization inside the installation directory can be overwritten. This includes
.hbm.xmlextended-attribute files inWEB-INF/classes/sailpoint/objectand web content such as XHTML, JavaScript, and images. SailPoint recommends keeping customized files in a separate custom directory so that you can copy them back. - Stop the application servers on every host.
Installing a Patch
The patch archive is designed to go over the current installation:
- Expand the patch archive into
identityiq_home, for examplejar -xvf identityiq-8.4p2.jar. - Run the patch database script from
WEB-INF/databasefor your database type, for exampleupgrade_identityiq_tables-8.4p2.mysql. - From
WEB-INF/bin, run the patch command with the patch version:./iiq patch 8.4p2. - Reapply any overwritten customizations, restart the application servers, and verify the version on the Debug About page.
Every host must run the same patch level. An SSB-based build (section 3.1) handles this by putting the patch archive in base/patch and rebuilding the WAR.
Performing a Version Upgrade
SailPoint's installation guide sets the upgrade order:
- Confirm the starting version. The guide says you can upgrade only from the latest released version, at any patch level.
- Delete old installation files and download the new release.
- Expand the new
identityiq.warinto a clean directory. The guide warns that unlike a patch release, a new version cannot be expanded into the same directory as the old one, because obsolete files would remain and cause unexpected failures. - Do not add previously used e-fixes. They are compatible only with the patch level they were built for.
- Reapply file customizations. Copy your customized
IdentityExtended.hbm.xml,LinkExtended.hbm.xml, andCertificationItemExtended.hbm.xmlinto the new installation. Account attribute changes must also be made to certification item attributes. - Upgrade the database. Edit
upgrade_identityiq_tables.<db>the same way you edited the original creation script (names, schema), then run it with the client set to continue on error. If patches were applied to the old version, errors such as Duplicate column iiqlock are expected, because the patch already made those changes. If you need a plugin database that does not exist yet, run the plugin creation script separately. - Run
iiq upgradefromWEB-INF/bin. It updates configuration and managed data in the database and runs once per installation, no matter how many application servers you have. - Upgrade external components together. Upgrade the IQService (stop with
IQService.exe -k, uninstall with-u, extract the new version, install with-i, start with-s) and any Connector Gateway, keeping the gateway'sinit.xml. - Start and verify, then run the post-upgrade steps:
post_upgrade_identityiq_tables.<db>removes tables, columns, and indexes that were needed only during the upgrade. The Data Export tables have their own upgrade script. - Reapply database-side customizations. Out-of-the-box task definitions, reports, rules, and workflows are overwritten by the upgrade. Reapply any edits you made to them. Also refresh any externally saved XML copies by exporting them again, because objects from the old version may no longer match.
Patch vs. Upgrade Side by Side
| Question | Patch | Upgrade |
|---|---|---|
| Where are the files expanded? | Over the existing identityiq_home | Into an empty directory |
| Database script | upgrade_identityiq_tables-<patch>.<db> | upgrade_identityiq_tables.<db>, then post_upgrade_... |
| Command | iiq patch <patch-version> | iiq upgrade (once per installation) |
| E-fixes | Check the README for which e-fixes the patch includes | Never carry old e-fixes forward |
| External components | Keep IQService at the matching version | Upgrade IQService and Connector Gateway at the same time |
| Customized product objects | Review the README | Reapply modifications to OOTB rules, workflows, tasks, and reports |
Exam Traps
- Running
iiq upgradeseparately on every host is unnecessary, because the command changes shared database content. - Terminating pending workflow approvals from Task Results before an upgrade is wrong. They are not running processes.
- Expanding a new major version over the old directory is the classic upgrade failure.
- An IQService left at the old version after an upgrade breaks Active Directory provisioning.
During an upgrade from IdentityIQ 8.3 to 8.4, an engineer expands the new identityiq.war on top of the existing 8.3 directory. Why does SailPoint's installation guide prohibit this?
The WAR file cannot be read by the jar command in an existing directory.
It would overwrite the database connection settings in the keystore.
Files that no longer exist in the new version would remain and could cause unexpected failures.
It would immediately run iiq upgrade before the database script is applied.
A production installation has four IdentityIQ application servers sharing one database. How many times should iiq upgrade be run during the version upgrade?
Once for the installation
Once on each of the four servers
Once per application server plus once on the database server
It is not run; the upgrade DDL script replaces it
Which sequence matches a typical IdentityIQ patch installation after backups are taken and the application servers are stopped?
Expand the patch into a new empty directory, run iiq upgrade, then run the post-upgrade script.
Run iiq patch, then expand the patch archive, then import init.xml.
Import the patch jar through Global Settings > Import from File, then restart.
Expand the patch archive into identityiq_home, run the patch database script, then run iiq patch with the patch version.
Before shutting down for an upgrade, an administrator sees several workflow approval items on the Task Results page. What should the administrator do with them?
Terminate them so the upgrade database script does not fail.
Leave them alone, because they are approvals managed by IdentityIQ rather than running processes.
Export them with checkout -clean and delete them.
Convert them to e-fixes so they can be reapplied after the upgrade.
Sections you finish are checked off in the contents.