There are several possible cases when upgrading midPoint. Please refer to release documentation or use your support channel to determine which one is your case specific.
Each new version of midPoint brings in new features. Although we try to maintain compatibility as hard as is practical some changes to the database or XML schemas are inevitable. Otherwise the new features cannot be efficiently implemented, the system will rot and become unusable. We do not want this to happen. Therefore there needs to be a reasonable balance between clean system architecture and the difficulty of upgrades. Therefore please bear with us. Even though the upgrade process may be sometimes slightly more difficult it allows us to keep the product in a great shape.
Type 0: Upgrade without any schema change
When to do? If there was no schema change between your existing midPoint version and your desired version.
What to do? Just redeploy midpoint.war. There is no need to adjust configuration or database content.
- Just redeploy the WAR
Type 1: Upgrade with database schema upgrade
When to do? If there was a compatible database schema change and an upgrade script is available.
What to do? Apply database upgrade script while midpoint is down. Redeploy midpoint.war.
- Shutdown midPoint
- Apply database upgrade script (SQL). This script is either part of a new midPoint release or use your support channel to obtain it. (see Database Schema Upgrade)
- Redeploy midpoint.war
- Start midPoint
Type 2: Upgrade with database schema change
When to do? If there was an incompatible database schema change while the XML schema is still compatible.
XML schema compatibility is indicated by namespace URL: if the namespace URL is the same then the XML schema is compatible. If it is changed then it is not.
What to do? Export all data, reconstruct database schema, upgrade WAR, import all data, clean-up.
- Export all data in XML form using midPoint GUI. The export functionality is available in a form of Export all button in the Configuration page. Please make sure that you select Object as object type in the left side bar. The XML export file with all the objects is generated when the Export all button is present. Save the file in a safe place. Visually inspect the file that it contains the exported data (users, resources, accounts, etc.).
- Shutdown midpoint.
- Clean up midpoint database schema. Use tools appropriate for your database to do it. This means removing all tables, indexes, etc. and therefore also removing all data.
- Re-create the database schema using database creation script from the new midPoint release.
- Redeploy midpoint.war.
- Start midpoint.
- Use the GUI to import the data (you will need to use the default username/password for the first login). Navigate to the Configuration page and use ordinary Import object functionality to import the XML file that was exported in the step 1. Make sure to check overwrite and keep OID options for the import and uncheck validate dynamic schema and referential integrity. This will import all the objects.
- MidPoint has created some of the objects during its startup with empty database. Some of them will be overwritten by the import, some of them will not. Therefore there is a need to clean up the extra objects. Currently this effect is limited to connectors that are automatically discovered during midpoint startup. Therefore after the import the connector objects are doubled. Navigate to the Configuration menu and list all objects of type Connector. Delete the extra objects so only one of each type remains. Warning: make sure not to break connectors that are already in use by resources. Resources link to the connectors by OID in their
<connectorRef>element. Have a look at the resource XML structure definition and determine the OID of the connector that is being referenced from the
<connectorRef>XML element. Then list the connectors and delete all the other connectors of the same type leaving only the one that is used.
- The imported objects may slightly differ when compared to their original XML version. Migration of data model is an automatic part of the import process. It means that if the original XML was using a deprecated part of the data model and there is a one-to-one equivalent then the data will be automatically converted to the supported equivalent.
- We are aware of the drawbacks and we are working hard to improve them. Later versions will most likely streamline the upgrade process.
Type 3: Upgrade after incompatible schema change
When to do? If there was an incompatible change to both database schema and XML schema. The incompatible change to XML schema is indicated by changed namespace URL. This is a very rare event.
What to do? There is no general procedure. Have a look at release notes for the new version for instructions or use your support channel. Generally speaking, a complex migration script will be needed to migrate the data.
MidPoint is a stable software, but its development pace is still considerably rapid. Therefore almost every release brings a features that require schema changes. However, starting from midPoint 3.0 the schema is strictly backwards compatible and vast majority of upgrades should be of type 1 or type 2.