--- title: Migrate your configuration description: This chapter covers the steps required to migrate your IDM configuration to IDM 8.1. component: pingidm version: 8.1 page_id: pingidm:upgrade-guide:migrate-config canonical_url: https://docs.pingidentity.com/pingidm/8.1/upgrade-guide/migrate-config.html keywords: ["Migration", "Configuration", "Security", "Scripts", "Property Files"] section_ids: migrate-config-files: Migrate configuration files update-boot-properties: Migrate boot.properties update-security: Migrate security settings update-scripts: Migrate custom scripts migrate-bundles: Migrate custom bundles update-provisioner-files: Migrate provisioner files updating-custom-ui: Migrate UI customizations updating-logback: Migrate logging functionality updating-jetty: Migrate Jetty configuration files updating-workflow-vue3: Migrate workflows to Vue 3 --- # Migrate your configuration This chapter covers the steps required to migrate your IDM configuration to IDM 8.1. There is no automated way to migrate a customized configuration to IDM 8.1, so you must migrate customized configuration files manually. If you're upgrading from IDM 8.0.x, there are three ways to do this: * Use the new IDM 8.1 configuration files as a base, and copy any customizations you have made to the new files. This is the preferred option, particularly if you have used version control on your configuration and can determine the exact changes you have applied. * Use your existing configuration files as a base, and add any new IDM 8.1 configuration to your existing files. * Use your existing configuration as is with no IDM 8.1 changes. Usually, a customized IDM 8.0.x configuration will work without further modification on IDM 8.1. ## Migrate configuration files For customized files in your project's `conf/` directory, check that the customizations are compatible with the changes outlined in [Changed functionality](../release-notes/changed-functionality.html). If there are no incompatible changes, either copy your old configuration files to your IDM 8.1 installation, or copy any customization into the corresponding new configuration files. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If you create custom configuration files, don't use spaces or special characters in the filenames, in accordance with the [OSGi specification](https://docs.osgi.org/specification/osgi.core/8.0.0/framework.service.html#i3043166). | ## Migrate `boot.properties` On the IDM 8.1 installation, edit the `resolver/boot.properties` file to match any customizations that you made on your IDM 8.0.x server. Specifically, check the following elements: * The HTTP, HTTPS, and mutual authentication ports. If you changed the default ports in your IDM 8.0.x deployment, make those same changes in the new `boot.properties` file. * Check that the keystore and truststore passwords match the current passwords for the keystore and truststore of your existing IDM deployment. ## Migrate security settings Copy the contents of your IDM 8.0.x `security/` folder to the IDM 8.1 installation. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you don't copy your old truststore and keystore files to your new instance, you cannot decrypt anything that was encrypted by your old instance of IDM. | ## Migrate custom scripts Migrate any custom scripts or default scripts *that you have modified* to the `script` directory of your IDM 8.1 instance. In general, custom and customized scripts should be located in the `openidm/script` directory of your existing IDM deployment. For custom scripts, review [Changed functionality](../release-notes/changed-functionality.html). If you're confident that the scripts will work as intended on IDM 8.1, copy these scripts to the new instance. If you modified a default IDM script, compare the default versions of the IDM 8.0.x and IDM 8.1 scripts. If nothing has changed between the default versions, review your customizations against [Changed functionality](../release-notes/changed-functionality.html). If a default script has changed since the IDM 8.0.x release, test that your customizations work with the new default script. If you are confident that your changes will work as intended on the new version, copy the customized scripts to the new `script` directory. | | | | - | ------------------------------------------------------------------------------------------------------------------------------- | | | If you modify any shell scripts, such as `startup.sh`, you must migrate your changes manually to the new version of the script. | ## Migrate custom bundles If your existing deployment includes any custom JAR files in the `bundles` directory, migrate these to the new deployment. Pay particular attention to any files that support JDBC database drivers. ## Migrate provisioner files Change any customized provisioner configurations in your existing deployment to point to the connectors that are provided with IDM 8.1. Specifically, make sure that the `connectorRef` properties reflect the new connector versions, where applicable. For example: ```json "connectorRef" : { "bundleName": "org.forgerock.openicf.connectors.ldap-connector", "bundleVersion": "[1.4.0.0,1.6.0.0)", "connectorName": "org.identityconnectors.ldap.LdapConnector" }, ``` Alternatively, copy the connector .jar files from your existing deployment into the `openidm/connectors` directory of the new installation. ## Migrate UI customizations | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Starting with IDM 8.1, the [legacy admin UI is deprecated](../release-notes/deprecated-functionality.html#legacy-admin-ui-deprecated) and is no longer bundled with IDM. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI.Both UIs are available as separate downloads from the [Backstage download site](https://backstage.forgerock.com/downloads):- To install the Platform admin UI, follow the steps in [Install the Platform admin UI for standalone IDM](../setup-guide/platform-admin-ui.html). - To continue using the legacy admin UI, follow the steps in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). | If you have customized the admin UI, review any custom UI files from your previous IDM deployment (generally in the `openidm/ui/admin/extension` directory), and compare them against the corresponding IDM 8.1.0 files from the legacy admin UI artifact, and make changes, as needed. Learn more in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). ## Migrate logging functionality For customized logging behavior in your project, check that the customizations are compatible with the changes outlined in [Server logs](../monitoring-guide/server-logs.html). Update your `conf/logback.xml` file with any necessary changes. If you want to preserve the JUL style logs, learn more in [pattern layout encoder](../monitoring-guide/server-logs.html#pattern-layout-encoder). ## Migrate Jetty configuration files | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In IDM 8.0, `jetty.xml` is no longer supported.When serving SSL requests, Jetty 12 checks that the incoming host header matches the server certificate's subject and returns a `400 Bad Request` error on a mismatch. If you're upgrading to IDM 8.0, you must ensure your IDM server certificate subject matches the host name used by your deployment.Learn more in [Jetty 12 support](../release-notes/whats-new.html#jetty_12_support). | If you haven't modified your `jetty.xml` configuration file, you don't need to make changes for Jetty 12 because the current configuration replicates the `jetty.xml` default settings. However, if you've made changes, you might need to adjust the `webserver.listener-*json` files as needed. For example, the `webserver.listener-mutualAuth.json` file duplicates the `8444` port configuration in `jetty.xml`. You can enable mutual authentication on any listener by setting the `secure` and `mutualAuth` flags to `true`. Learn more in [Embedded Jetty configuration](../install-guide/appendix-jetty.html) and in [Secure network connections](../security-guide/chap-connections.html). ## Migrate workflows to Vue 3 If you have custom workflow form templates, review them for compatibility with Vue 3. The end-user UI no longer registers `ValidationObserver`, `ValidationProvider`, or the `$set()` reactivity API globally. You must update any templates that depend on these. Learn more in [Update custom workflow templates for Vue 3](../workflow-guide/custom-workflow-template.html#vue3-workflow-migration).