--- title: Changed functionality description: When you update to IDM 8.1.0 from the last major version, the following changes could affect existing deployments. Adjust existing scripts, files, clients, and so on, as necessary. You should also review Deprecation notices. component: pingidm version: 8.1 page_id: pingidm:release-notes:changed-functionality canonical_url: https://docs.pingidentity.com/pingidm/8.1/release-notes/changed-functionality.html keywords: ["Deployment", "Identities", "Compatibility", "Security", "JSON"] section_ids: changes_between_idm_8_0_x_and_8_1_0: Changes between IDM 8.0.x and 8.1.0 changed-admin-ui-removed-from-zip-810: Legacy admin UI and API Explorer removed changed-workflow-vue3-810: Custom workflow templates require Vue 3 updates changed-oracle-ucp-template-810: Oracle UCP datasource changes changed-workflow-upgrade-720-810: Workflow engine upgrade java_21_support: Java 21 support queued_synchronization_property_changes: Queued synchronization property changes default_api_version_for_unversioned_requests: Default API version for unversioned requests deprecated_metric_collection: Deprecated metric collection router_filter_metric_names: Router filter metric names jetty_metrics_for_number_of_queued_requests: Jetty metrics for number of queued requests scripted_endpoint_metric_names: Scripted endpoint metric names livesync_metric_tag_and_naming_updates: liveSync metric tag and naming updates managed_object_script_hook_naming_updates: Managed object script hook naming updates changes_between_idm_8_0_0_and_8_0_1: Changes between IDM 8.0.0 and 8.0.1 default_api_version_for_unversioned_requests_2: Default API version for unversioned requests changes_between_idm_7_5_x_and_8_0_0: Changes between IDM 7.5.x and 8.0.0 launcher_json_configuration: launcher.json configuration embedded_jetty_web_server_upgrade: Embedded Jetty web server upgrade felix_http_jetty_upgrade: Felix HTTP Jetty upgrade servlet_specification_upgrade: Servlet Specification upgrade jetty_thread_pool_settings: Jetty thread pool settings gzip_compression_settings: Gzip compression settings secure_protocol_configuration: Secure protocol configuration embedded_ds_repository: Embedded DS repository logback: Logback standalone_end_user_ui_not_bundled_with_pingidm: Standalone end-user UI not bundled with PingIDM changed-parameter-authorization-80: _api parameter requires authorization changed-array-comparison-80: Array comparison java_21_support_2: Java 21 support changes_between_idm_7_5_1_and_7_5_2: Changes between IDM 7.5.1 and 7.5.2 default_api_version_for_unversioned_requests_3: Default API version for unversioned requests changes_between_idm_7_5_0_and_7_5_1: Changes between IDM 7.5.0 and 7.5.1 changed-parameter-authorization-751: _api parameter requires authorization changed-array-comparison-751: Array comparison changes_between_idm_7_4_x_and_7_5_0: Changes between IDM 7.4.x and 7.5.0 changed-fx-flowable-upgrade-680-75: Workflow engine upgrade array_schema_fields_default_to_item_type_string: Array schema fields default to item type string populatedefaults_flag_removed_from_secrets_configuration: populateDefaults flag removed from secrets configuration java_17_required: Java 17 required legacy_hashing_algorithms_removed_from_the_admin_ui: Legacy hashing algorithms removed from the Admin UI secret_store_class_renamed: Secret store class renamed changes_between_idm_7_4_2_and_7_4_3: Changes between IDM 7.4.2 and 7.4.3 default_api_version_for_unversioned_requests_4: Default API version for unversioned requests changes_between_idm_7_4_1_and_7_4_2: Changes between IDM 7.4.1 and 7.4.2 changed-parameter-authorization-74: _api parameter requires authorization changed-array-comparison-742: Array comparison changed-java-support: Java upgrade changes_between_idm_7_4_0_and_7_4_1: Changes between IDM 7.4.0 and 7.4.1 changed-fx-flowable-upgrade-680-74: Workflow engine upgrade changes_between_idm_7_3_x_and_7_4_0: Changes between IDM 7.3.x and 7.4.0 jdk-keystore-creation: IDM requires JDK 11.0.20 or higher db2-driver-osgi: The DB2 driver is now OSGi-compliant changes_between_idm_7_3_2_and_7_3_3: Changes between IDM 7.3.2 and 7.3.3 default_api_version_for_unversioned_requests_5: Default API version for unversioned requests changes_between_idm_7_3_1_and_7_3_2: Changes between IDM 7.3.1 and 7.3.2 changed-parameter-authorization-73: _api parameter requires authorization changed-array-comparison-732: Array comparison changed-java-upgrade-732: Java upgrade changes_between_idm_7_3_0_and_7_3_1: Changes between IDM 7.3.0 and 7.3.1 changed-fx-flowable-upgrade-680-73: Workflow engine upgrade changes_between_idm_7_2_x_and_7_3_0: Changes between IDM 7.2.x and 7.3.0 array-order-agnostic-sync: Synchronization JSON array comparison is order-agnostic attribute_encryption_on_assignments: Attribute encryption on assignments changes_between_idm_7_1_x_and_7_2_0: Changes between IDM 7.1.x and 7.2.0 onDelete-default-bahavior: Default onDelete behavior felix-osgi-upgrade: Felix and OSGi upgrades jms-20-upgrade: JMS 2.0 upgrade json-patch-exceptions: PATCH request exceptions policy-enforcement-on-role-name: Policy enforcement on role name preferredLocales-precedence: Precedence in locales in the self-registration email template paused-queued-sync-changed: Paused queued synchronization for unavailable routes embedded_workflow_database: Embedded workflow database default_mysql_connection_driver: Default MySQL connection driver changes_between_idm_7_1_4_and_7_1_6: Changes between IDM 7.1.4 and 7.1.6 changes_between_idm_7_1_2_and_7_1_4: Changes between IDM 7.1.2 and 7.1.4 changes_between_idm_7_1_0_and_7_1_2: Changes between IDM 7.1.0 and 7.1.2 embedded_workflow_database_2: Embedded workflow database workflow_version_update: Workflow version update changes_between_idm_7_0_x_and_7_1_0: Changes between IDM 7.0.x and 7.1.0 data_format_change_for_external_ds_repositories: Data format change for external DS repositories audit_handler_changes: Audit handler changes parameterized_http_and_https_enablement: Parameterized HTTP and HTTPS enablement parameterized_felix_web_console_credentials: Parameterized Felix web console credentials notification_changes: Notification changes moved_configuration_files: Moved configuration files improved_validateproperty_error_handling: Improved validateProperty error handling changes_to_router_json: Changes to router.json changes_between_idm_6_5_x_and_7_0_0: Changes between IDM 6.5.x and 7.0.0 embedded_workflow_database_3: Embedded workflow database new_workflow_engine: New workflow engine changes_to_boot_properties: Changes to boot.properties changes_to_logging_properties: Changes to logging.properties change_to_how_authorization_roles_are_assigned: Change to how authorization roles are assigned schema_change_to_authzroles: Schema change to authzRoles change_to_the_internal_user_authentication_module: Change to the INTERNAL_USER authentication module change_to_prometheus_monitoring: Change to Prometheus monitoring change_in_how_boolean_values_are_assessed: Change in how boolean values are assessed queued_sync_changes: Queued sync changes virtual_property_calculation_for_effectiveroles_and_effectiveassignments: Virtual property calculation for effectiveRoles and effectiveAssignments gzip_compression_for_http_responses: Gzip compression for HTTP responses configurable_hashing: Configurable hashing temporal_constraint_enforcement_on_roles: Temporal constraint enforcement on roles change_to_jms_audit_handler: Change to JMS audit handler change_to_default_audit_configuration: Change to default audit configuration datatype_of_userpassword_property_in_provisioner_files: Datatype of userPassword property in provisioner files removal_of_the_global_consent_setting: Removal of the global consent setting support_for_mysql_connectorj_version_8_0: Support for MySQL Connector/J version 8.0 default_security_protocols_for_inbound_connections: Default security protocols for inbound connections removal_of_address2_from_the_managed_object_schema: Removal of address2 from the managed object schema icf_and_connector_changes: ICF and connector changes archive: Archive --- # Changed functionality When you update to IDM 8.1.0 from the last major version, the following changes could affect existing deployments. Adjust existing scripts, files, clients, and so on, as necessary. You should also review [Deprecation](deprecated-functionality.html) notices. If you're upgrading from an older release, review the changed functionality from all releases after your current version of IDM. For previous releases, the information could be outdated or superseded. ## Changes between IDM 8.0.x and 8.1.0 ### Legacy admin UI and API Explorer removed The legacy admin UI (`/admin`) and API Explorer (`/api`) are no longer included in the IDM `.zip` distribution. Requests to the `/admin` or `/api` endpoints on the IDM server return a `404` response. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI. Although the legacy admin UI and API Explorer are [deprecated](deprecated-functionality.html#legacy-admin-ui-deprecated), you can still download and install the artifact separately. Learn more in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). ### Custom workflow templates require Vue 3 updates The end-user UI has been upgraded from Vue 2 to Vue 3. If you have custom workflow form templates, they might require changes to work correctly. The `ValidationObserver` and `ValidationProvider` components from `vee-validate`, which the previous UI registered globally, are no longer available. Replace them with component-local validation. The `$set()` reactivity API has also been removed in Vue 3. Use direct property assignment instead. The sample workflow template has been updated as a reference. Learn more in [Update custom workflow templates for Vue 3](../workflow-guide/custom-workflow-template.html#vue3-workflow-migration). ### Oracle UCP datasource changes The default Oracle UCP datasource template (`datasource.jdbc-ucp-oracle.json`) has changed: * The JDBC URL format changed from the deprecated SID format (`@host:port:SID`) to the service name format (`@//host:port/service_name`). * The `connectionTimeout` (in milliseconds) property is replaced with `connectionWaitTimeout` (in seconds). The old property was silently ignored by UCP. Update your existing `conf/datasource.jdbc-ucp-oracle.json` file for these changes. Learn more in [Set up Oracle as an IDM repository](../install-guide/repository-oracledb.html#oracle-ucp-datasource). ### Workflow engine upgrade The Flowable embedded workflow engine has been upgraded to [version 7.2.0](https://github.com/flowable/flowable-engine/releases/tag/flowable-7.2.0). If you're upgrading from a previous version of IDM and use workflow, this upgrade requires one or more incremental [upgrade scripts](../upgrade-guide/update-repo.html#upgrade-existing-repository). ### Java 21 support Previously, IDM supported Java 17 and Java 21. Now, running IDM requires Java 21. Learn more in [Java requirements](before-you-install.html#prerequisites-java). ### Queued synchronization property changes The `maxQueueSize` for [queued synchronization](../synchronization-guide/chap-implicit-live-sync.html#configure-queued-sync) now defaults to `1000` and can't be configured to a value higher than `1000` or lower than `100`. The previous default was `20000`. The `pageSize` defaults to `100` (unchanged) and can't be configured to a value higher than `100` or lower than `10`. If the configured `pageSize` is greater than `maxQueueSize / 10`, IDM uses `maxQueueSize / 10` for the page size. If you have any configuration outside of these bounds, IDM automatically adjusts the values to the nearest bound. ### Default API version for unversioned requests Previously, REST API requests without an `Accept-API-Version` header used the latest available API version for the resource. These requests now default to API version `1.0`. The `consent`, `scheduler/job`, `scheduler/trigger`, and `schema` endpoints default to API version `2.0`. ### Deprecated metric collection Deprecated metric names are now generated along with the replacement metric names only when the `deprecatedMetricsEnabled` property is set to `true` (default) in `conf/metrics.json`. To generate only the replacement metric names, set the property to `false`. Learn more in [Deprecated metric collection](../monitoring-guide/monitoring.html#deprecated-metric-collection). ### Router filter metric names Router filter metrics now use the `router-filter` ([API](../monitoring-guide/api-metrics.html#api-metric-names)) and `idm_router_filter_seconds` ([Prometheus](../monitoring-guide/prometheus-metrics.html#prometheus-metric-names)) metric names that replace the `filter` (API) and `idm_filter_seconds` (Prometheus) metric names. This metric also specifies a `name` and `system` label. If no name label is specified, it defaults to "unknown". The `system` label is always `system="false"`. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The deprecated metric names are still available and are generated along with the new metric names unless `deprecatedMetricsEnabled` is set to `false` in `conf/metrics.json`. Learn more in [Deprecated metric collection](../monitoring-guide/monitoring.html#deprecated-metric-collection). | ### Jetty metrics for number of queued requests The [Jetty QoSHandler](../install-guide/idm-config-properties-jetty.html#config-jetty-qos-handler) metrics, `jetty.qos.queue.count` (API) and `idm_jetty_qos_queue_count` (Prometheus), now contain an accurate count of queued requests and replace `jetty.thread.queue` (API) and `idm_jetty_thread_queue` (Prometheus). ### Scripted endpoint metric names Scripted endpoint metric names are more consistent and no longer use randomly generated GUIDs for inline scripts. * API metrics: The metric `script.{script-name}.{request-type}` is now `custom-endpoint.{endpoint-name}.{request-type}`. * Prometheus metrics: The metric `idm_script_{script-name}_{request-type}` is now `idm_custom_endpoint_seconds{name="{endpoint-name}",request_type="{request-type}"}`. For both metric types, `{endpoint-name}` is determined by the endpoint's configuration file name. For example, `endpoint-myendpoint.json` results in the name `myendpoint`. | | | | - | --------------------------------------------------------------------------------------------------------------------- | | | If you have monitoring dashboards or other tools that rely on the old metric names, update them to use the new names. | ### liveSync metric tag and naming updates The liveSync metric includes updated tag and naming conventions. * [API metric](../monitoring-guide/api-metrics.html#new-livesync-metric): The metric `live-sync.{system-name}.{object-type}` is now `icf.{connector-type}.{system-identifier}.{bundle-version}.{location}.{object-class}.liveSync`. * [Prometheus metric](../monitoring-guide/prometheus-metrics.html#new-live-sync-prom-metric): The metric `idm_live_sync_seconds{object_type="{object_type}",system_name="{system_name}",quantile="{quantile}"` is now `idm_icf_seconds{action="liveSync",bundle_version="{bundle_version}",connector="{connector}",connector_type="{connector_type}",location="{location}",object_class="{object_class}",operation="action",system_identifier="{system_identifier}",quantile="{quantile}"}`. ### Managed object script hook naming updates The managed object script hook metrics include an updated naming convention and optional "object" and "script hook" tags. * [API metric](../monitoring-guide/api-metrics.html#changed-managed-object-script-hook-metric): []()The metric `managed.{managed-object}.script.{script-name}` is now `managed-script-hook.{object}.{script-hook}`. * [Prometheus metric](../monitoring-guide/prometheus-metrics.html#changed-managed-object-script-hook-metric-prom): []()The metric `idm_managed_seconds{managed_object="managed_object",operation="operation_name",script="script_name"}` is now `idm_managed_script_hook_seconds{object="object",script_hook="script_hook"}`. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The deprecated metric names are still available and are generated along with the new metric names unless `deprecatedMetricsEnabled` is set to `false` in `conf/metrics.json`. Learn more in [Deprecated metric collection](../monitoring-guide/monitoring.html#deprecated-metric-collection). | ## Changes between IDM 8.0.0 and 8.0.1 ### Default API version for unversioned requests Previously, REST API requests without an `Accept-API-Version` header used the latest available API version for the resource. These requests now default to API version `1.0`. The `consent`, `scheduler/job`, `scheduler/trigger`, and `schema` endpoints default to API version `2.0`. ## Changes between IDM 7.5.x and 8.0.0 ### `launcher.json` configuration Logging changes require new bundles and a specific `start-level` order. If you're copying `launcher.json` from a previous version of IDM, review the 8.0.0 version of `launcher.json` and integrate the changes and additions: ```json { "bundle": { "containers": [ { "location": "bundle", "includes": [ "*.jar" ], "start-level": 1, "action": "install" }, { "location": "bundle", "includes": [ "**/org.apache.aries.spifly.dynamic.bundle*.jar", "**/asm-*.jar", "**/slf4j-*.jar" ], "start-level": 2, "action": "start" }, { "location": "bundle", "includes": [ "**/openidm-system-*.jar", "**/org.apache.felix.log*.jar" ], "start-level": 3, "action": "start" }, { "location": "bundle", "includes": [ "**/openidm-infoservice-*.jar", "**/openidm-datasource*.jar", "**/openidm-scr-starter-*.jar" ], "start-level": 4, "action": "start" }, ... ] } } ``` | | | | - | --------------------------------------------- | | | Logging won't function without these changes. | ### Embedded Jetty web server upgrade The embedded Jetty web server has been upgraded to Jetty 12, and `jetty.xml` is no longer supported in this IDM release. Learn more in [Embedded Jetty configuration](../install-guide/appendix-jetty.html) and in [Migrate Jetty configuration files](../upgrade-guide/migrate-config.html#updating-jetty). | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. | ### Felix HTTP Jetty upgrade Felix HTTP Jetty has been upgraded to Jetty 12. ### Servlet Specification upgrade Servlet Specification has been upgraded to 6.0. ### Jetty thread pool settings You can now configure [Jetty thread pool settings](../install-guide/idm-config-properties-jetty.html#config-jetty-thread-settings-gzip-compression) in `conf/webserver.json`. ### Gzip compression settings You can now configure [Gzip compression for HTTP responses](../install-guide/idm-config-properties-jetty.html#config-jetty-thread-settings-gzip-compression) in `conf/webserver.json`. ### Secure protocol configuration You can now configure [Secure protocol settings](../install-guide/idm-config-properties-jetty.html#jetty-property-reference) in `conf/webserver.listener-*json`. ### Embedded DS repository The embedded DS repository is no longer included with IDM. Before you can use IDM, you must [select and configure a repository](../install-guide/chap-repository.html). ### Logback PingIDM now uses Logback to generate its server logs. You will need to add `logback.xml` to your configuration when updating. Learn more in [Server logs](../monitoring-guide/server-logs.html). ### Standalone end-user UI not bundled with PingIDM The end-user UI is no longer bundled with PingIDM. You can download and install the end-user UI separately from the GitHub repository: [ForgeRock/end-user-ui](http://github.com/ForgeRock/end-user-ui). Learn more in the [setup-guide:end-user-ui.adoc](#setup-guide:end-user-ui.adoc). ### `_api` parameter requires authorization Requests passing the `_api` parameter now require authorization. Learn more in [Common REST](../crest/about-crest.html#api-authorize-example). ### Array comparison Starting with IDM 7.3, unordered array comparison became the default behavior. For this release of IDM, ordered array comparison is the default behavior, restoring the default behavior prior to IDM 7.3. You can now use the `comparison` managed object schema configuration property to choose how JSON array comparisons are made with regard to array order. Learn more about [managed object schema properties](../objects-guide/appendix-managed-objects.html#managed-object-property-config-properties) and [array comparison](../synchronization-guide/chap-implicit-live-sync.html#array-comparison). ### Java 21 support Previously, running IDM required Java 17. You can now use Java 17 or Java 21. Learn more in [Java requirements](before-you-install.html#prerequisites-java). ## Changes between IDM 7.5.1 and 7.5.2 ### Default API version for unversioned requests Previously, REST API requests without an `Accept-API-Version` header used the latest available API version for the resource. These requests now default to API version `1.0`. The `consent`, `scheduler/job`, `scheduler/trigger`, and `schema` endpoints default to API version `2.0`. ## Changes between IDM 7.5.0 and 7.5.1 ### `_api` parameter requires authorization Requests passing the `_api` parameter now require authorization. Learn more in [Common REST](../crest/about-crest.html#api-authorize-example). ### Array comparison Starting with IDM 7.3.0, unordered array comparison became the default behavior. For this release of IDM, ordered array comparison is the default behavior, restoring the default behavior from prior to IDM 7.3.0. You can now use the `comparison` managed object schema configuration property to choose how JSON array comparisons are made with regard to array order. Learn more about [managed object schema properties](../objects-guide/appendix-managed-objects.html#managed-object-property-config-properties) and [array comparison](../synchronization-guide/chap-implicit-live-sync.html#array-comparison). ## Changes between IDM 7.4.x and 7.5.0 ### Workflow engine upgrade The Flowable embedded workflow engine has been upgraded to [version 6.8.0](https://github.com/flowable/flowable-engine/releases/tag/flowable-6.8.0). If you are upgrading from a previous version of IDM and use workflow, this upgrade requires one or more incremental upgrade scripts. For more information, refer to [Upgrade an existing repository](../upgrade-guide/update-repo.html#upgrade-existing-repository). ### Array schema fields default to item type `string` Schema fields defined as type *array* are required to have an item type defined as of IDM 7.4.0. IDM 7.5.0 defaults the item type to `string` to avoid startup issues if the type is not defined. ### `populateDefaults` flag removed from secrets configuration The sample secrets configuration (`secrets.json`) no longer includes the `populateDefaults` flag. It is safe to remove this from your secrets configuration. ### Java 17 required Running IDM requires Java 17. For more information, refer to [Java requirements](before-you-install.html#prerequisites-java). ### Legacy hashing algorithms removed from the Admin UI MD5 and SHA-1 are supported for legacy reasons, but should not be used in production environments and have been removed from the Admin UI. For more information, refer to [Salted hash algorithms](../security-guide/encoding-attribute-values.html#encoding-salted-hash). ### Secret store class renamed The `org.forgerock.openidm.secrets.config.FileBasedStore` class has been deprecated and replaced by `org.forgerock.openidm.secrets.config.KeyStoreSecretStore`. The old class is currently an alias. ## Changes between IDM 7.4.2 and 7.4.3 ### Default API version for unversioned requests Previously, REST API requests without an `Accept-API-Version` header used the latest available API version for the resource. These requests now default to API version `1.0`. The `consent`, `scheduler/job`, `scheduler/trigger`, and `schema` endpoints default to API version `2.0`. ## Changes between IDM 7.4.1 and 7.4.2 ### `_api` parameter requires authorization Requests passing the `_api` parameter now require authorization. Learn more in [Common REST](../crest/about-crest.html#api-authorize-example). ### Array comparison Starting with IDM 7.3.0, unordered array comparison became the default behavior. For this release of IDM, ordered array comparison is the default behavior, restoring the default behavior from prior to IDM 7.3.0. You can now use the `comparison` managed object schema configuration property to choose how JSON array comparisons are made with regard to array order. Learn more about [managed object schema properties](../objects-guide/appendix-managed-objects.html#managed-object-property-config-properties) and [array comparison](../synchronization-guide/chap-implicit-live-sync.html#array-comparison). ### Java upgrade You must upgrade to Java 17, which is required by Jetty 12, to run IDM 7.4.2. Learn more in [Embedded Jetty configuration](../install-guide/appendix-jetty.html). ## Changes between IDM 7.4.0 and 7.4.1 ### Workflow engine upgrade The Flowable embedded workflow engine has been upgraded to [version 6.8.0](https://github.com/flowable/flowable-engine/releases/tag/flowable-6.8.0). If you're upgrading from a previous version of IDM and use workflow, this upgrade requires one or more incremental upgrade scripts. For more information, refer to [Upgrade an existing repository](../upgrade-guide/update-repo.html#upgrade-existing-repository). ## Changes between IDM 7.3.x and 7.4.0 ### IDM requires JDK 11.0.20 or higher If you try to run this version of IDM using an older release of JDK, the following error displays: ```console SEVERE: Error loading keystore java.io.IOException: Invalid keystore format at java.base/sun.security.provider.JavaKeyStore.engineLoad(JavaKeyStore.java:667) at java.base/sun.security.util.KeyStoreDelegator.engineLoad(KeyStoreDelegator.java:222) at java.base/java.security.KeyStore.load(KeyStore.java:1479) at org.forgerock.security.keystore.KeyStoreBuilder.build(KeyStoreBuilder.java:228) at org.forgerock.openidm.secrets.keystore.KeyStoreRepository.load(KeyStoreRepository.java:59) at org.forgerock.openidm.secrets.config.ConfigSupport.asKeyStoreHolder(ConfigSupport.java:95) at org.forgerock.openidm.secrets.config.StoreSupport.asKeyStoreHolder(StoreSupport.java:61) at org.forgerock.openidm.secrets.config.FileBasedStore.asKeyStoreHolder(FileBasedStore.java:18) ... ``` For a complete list of supported Java versions, refer to [Java requirements](before-you-install.html#prerequisites-java). ### The DB2 driver is now OSGi-compliant When using IDM with a DB2 database, you previously had to create an OSGi-compliant driver. The driver included with DB2 is now compliant. For more information, refer to: * [IBM DB2 repository](../install-guide/repository-db2.html) * [Supported repositories](before-you-install.html#prerequisites-repositories) ## Changes between IDM 7.3.2 and 7.3.3 ### Default API version for unversioned requests Previously, REST API requests without an `Accept-API-Version` header used the latest available API version for the resource. These requests now default to API version `1.0`. The `consent`, `scheduler/job`, `scheduler/trigger`, and `schema` endpoints default to API version `2.0`. ## Changes between IDM 7.3.1 and 7.3.2 ### `_api` parameter requires authorization Requests passing the `_api` parameter now require authorization. Learn more in [Common REST](../crest/about-crest.html#api-authorize-example). ### Array comparison Starting with IDM 7.3.0, unordered array comparison became the default behavior. For this release of IDM, ordered array comparison is the default behavior, restoring the default behavior from prior to IDM 7.3.0. You can now use the `comparison` managed object schema configuration property to choose how JSON array comparisons are made with regard to array order. Learn more about [managed object schema properties](../objects-guide/appendix-managed-objects.html#managed-object-property-config-properties) and [array comparison](../synchronization-guide/chap-implicit-live-sync.html#array-comparison). ### Java upgrade You must upgrade to Java 17, which is required by Jetty 12, to run IDM 7.3.2. Learn more in [Embedded Jetty configuration](../install-guide/appendix-jetty.html). ## Changes between IDM 7.3.0 and 7.3.1 ### Workflow engine upgrade The Flowable embedded workflow engine has been upgraded to [version 6.8.0](https://github.com/flowable/flowable-engine/releases/tag/flowable-6.8.0). If you're upgrading from a previous version of IDM and use workflow, this upgrade requires one or more incremental upgrade scripts. For more information, refer to [Upgrade an existing repository](../upgrade-guide/update-repo.html#upgrade-existing-repository). ## Changes between IDM 7.2.x and 7.3.0 ### Synchronization JSON array comparison is order-agnostic JSON array comparison during sync is now *order-agnostic*. This change may negate the need for certain custom scripts within mappings. For example, scripts that were previously required to sort `ldapGroups` values to avoid unnecessary target object updates. ### Attribute encryption on assignments Assignment attributes are now encrypted if the corresponding connector attribute indicates confidentiality, based on the attribute's `nativeType` (such as `JAVA_TYPE_GUARDEDSTRING` or `JAVA_TYPE_GUARDED_BYTE_ARRAY`). As part of this change, the managed assignment object now includes the following property: ```json "attributeEncryption" : { } ``` If `attributeEncryption` is not present, the assignment attributes are not encrypted. If the property is present but empty, it will default to IDM's default [encryption cipher](../security-guide/encoding-attribute-values.html). To specify a different cipher, add the `cipher` property. For example: ```json "attributeEncryption" : { "cipher" : "AES/CBC/PKCS5Padding" } ``` Additionally, `secrets.json` has a new secret: `idm.assignment.attribute.encryption`. ## Changes between IDM 7.1.x and 7.2.0 ### Default `onDelete` behavior The default `onDelete` behavior previously called a file-based script, `onDelete-roles.js`. This has been removed from the managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*. ### Felix and OSGi upgrades IDM has upgraded to OSGi Core 8.0 and Felix Framework 7.0.0. ### JMS 2.0 upgrade The samples that use the Java Message Service (JMS) have been upgraded to use the 2.0 API and Apache ActiveMQ Artemis: * [Subscribe to JMS messages](../samples-guide/scripted-jms-subscriber.html) * [Direct audit information to a JMS broker](../samples-guide/audit-jms.html) ### PATCH request exceptions Previously, illegal PATCH requests could return a `400` *or* `500` exception. In such cases, IDM now returns a `400` status. ### Policy enforcement on role name The `name` property of a [managed role](../objects-guide/managed-roles.html) is now subject to the uniqueness policy by default. This means that you cannot create multiple roles with the same `name`. To change this behavior, adjust the policy validation on the `role` property in your managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*. ### Precedence in locales in the self-registration email template Previously, the `defaultLocale` specified in the Self-Registration Email Template configuration took precedence. As of IDM 7.2, locales specified as `preferredLocales` in the `Accept-Language` header take precedence over the `defaultLocale`. ### Paused queued synchronization for unavailable routes Synchronization queue processing for a mapping is now *paused* if either the source or target system route are *unregistered*. For more information, see [Configure queued synchronization](../synchronization-guide/chap-implicit-live-sync.html#configure-queued-sync). ### Embedded workflow database Previously, you could use the Flowable workflow engine's embedded H2 database for demo and testing purposes. IDM no longer includes this database. Before you use workflow, you must [install a JDBC repository](../install-guide/chap-repository.html). Learn more in [Enable workflows](../workflow-guide/enable-workflows.html). ### Default MySQL connection driver The default [JDBC Connection Configuration](../objects-guide/repo-config.html#datasource-jdbc-json) now uses the connection driver from MySQL 8.1 (`com.mysql.cj.jdbc.Driver`). ## Changes between IDM 7.1.4 and 7.1.6 No additional incompatible changes were made between 7.1.4 and 7.1.6. ## Changes between IDM 7.1.2 and 7.1.4 No additional incompatible changes were made between 7.1.2 and 7.1.4. ## Changes between IDM 7.1.0 and 7.1.2 ### Embedded workflow database Previously, you could use the Flowable workflow engine's embedded H2 database for demo and testing purposes. IDM no longer includes this database. Before you use workflow, you must [install a JDBC repository](../install-guide/chap-repository.html). Learn more in [Enable workflows](../workflow-guide/enable-workflows.html). ### Workflow version update Previously, workflows would break when upgrading from version 7.0.2 to 7.1.0 of IDM, because of out-of-sync versions of the Flowable workflow engine. This is fixed in version 7.1.2 of IDM. If you're upgrading IDM from version 7.0, please use IDM version 7.1.2 or higher. ## Changes between IDM 7.0.x and 7.1.0 ### Data format change for external DS repositories For external DS repositories with explicitly mapped managed objects, the stored data format has changed for certain data types. In IDM versions prior to 7.1, certain property values were always considered as strings, so the returned JSON format of a managed object would look something like this: ```json { "boolean": "true", "integer": "12345", "timestamp": "20210315010101Z", "json": "{\"key\":\"value\"}" } ``` In IDM 7.1, these properties are returned with the correct data type, so a similar object in IDM 7.1 looks something like this: ```json { "boolean": true, "integer": 12345, "timestamp": "2021-03-15T01:01:01Z", "json": { "key": "value" } } ``` This change doesn't affect new deployments. If you're upgrading an existing deployment with an external DS repository with explicit object mappings, you should test this change and adapt your scripts and REST API calls, as necessary. This change affects the following data types: * Booleans: from string to JSON boolean Affected OIDs: `1.3.6.1.4.1.1466.115.121.1.7` and `1.3.6.1.4.1.36733.2.1.3.3.7` * Integers: from string to JSON integer Affected OIDs: `1.3.6.1.4.1.1466.115.121.1.27` and `1.3.6.1.4.1.36733.2.1.3.3.27` * Generalized time: from string in LDAP generalized time format, to string in ISO 8601 format Affected OIDs: `1.3.6.1.4.1.1466.115.121.1.24` and `1.3.6.1.4.1.36733.2.1.3.3.24` * JSON: from JSON embedded in a string to structured JSON Affected OIDs: `1.3.6.1.4.1.36733.2.1.3.1` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If you want to retain the legacy behavior, set the following property in `conf/system.properties`:```properties openidm.ds.rest2ldap.ignoreSchema.enabled=true ```This is not recommended in a production deployment and should be used only temporarily, as part of a plan to adapt to these changes. | ### Audit handler changes The `JsonStdoutAuditEventHandler` is now pre-configured in the standard audit configuration, but is disabled by default. Previously, to enable or disable audit handlers, you needed to modify `conf/audit.json` directly. Now, you can set the following properties in the `resolver/boot.properties` file to `true` or `false`: * `openidm.audit.handler.json.enabled` * `openidm.audit.handler.stdout.enabled` * `openidm.audit.handler.repo.enabled` Learn more in: * [Choose audit event handlers](../audit-guide/configuring-topic-handlers.html) * [Property value substitution](../setup-guide/using-property-substitution.html) ### Parameterized HTTP and HTTPS enablement Previously, to enable or disable HTTP or HTTPS, you could modify `conf/config.properties` directly. Now, you can set the following properties in the `resolver/boot.properties` file to `true` or `false`: * `openidm.https.enabled` * `openidm.http.enabled` Learn more in [Property value substitution](../setup-guide/using-property-substitution.html). ### Parameterized Felix web console credentials Previously, to change the Felix web console credentials, you could modify the `conf/felix.webconsole.json` file directly. Now, you can set the following properties in the `resolver/boot.properties` file: * `openidm.felix.webconsole.username` * `openidm.felix.webconsole.password` ### Notification changes Notifications are now disabled by default. Previously, to enable or disable notifications, you could modify the applicable `conf/notificationType.json` file directly. Now, you can set the following properties in the `resolver/boot.properties` file to `true` or `false`: * `openidm.notifications.passwordUpdate` * `openidm.notifications.profileUpdate` * `openidm.notifications` Learn more in [Configure notifications](../audit-guide/notification-config.html). ### Moved configuration files The following files have been moved from the `/path/to/openidm/conf/` directory: * `auth.profile.json` moved to `/path/to/openidm/samples/example-configurations/self-service/`. * `jsonstore.json` moved to `/path/to/openidm/samples/example-configurations/self-service/`. * `identityProviders.json` moved to `/path/to/openidm/samples/example-configurations/self-service/`. ### Improved `validateProperty` error handling Previously, API requests containing the `validateProperty` action to unknown resources or those with invalid POST body content could result in an invalid `true` response, or a generic *500 Internal Server Error*. Both of these situations now return a *400 Bad Request Error* with an explanation. Error comparison * BEFORE * AFTER ```json { "code": 500, "reason": "Internal Server Error", "message": "TypeError: Cannot call method "hasOwnProperty" of null", "detail": {} } ``` ```json { "code": 400, "reason": "Bad Request", "message": "object and properties were not provided in request content, and they are unable to be retrieved.", "detail": {} } ``` ### Changes to `router.json` The default `router.json` file no longer includes `system` in the matching pattern. ## Changes between IDM 6.5.x and 7.0.0 ### Embedded workflow database Previously, you could use the Flowable workflow engine's embedded H2 database for demo and testing purposes. IDM no longer includes this database. Before you use workflow, you must [install a JDBC repository](../install-guide/chap-repository.html). Learn more in [Enable workflows](../workflow-guide/enable-workflows.html). ### New workflow engine The Activiti workflow engine has been replaced with [Flowable](https://www.flowable.com/open-source/docs/). Current workflow definitions will continue to work with the new engine in compatibility mode, but all new workflow definitions must be written for Flowable. Learn more in [Workflow definition comparison^](../../8/workflow-guide/workflow-def-comp.html). If you're using MySQL for the workflow database, the following apply: * You must use MySQL version 5.6.4 or later. If you're using an older version, perform the MySQL upgrade before upgrading to IDM 7 or later. For additional information, see the [Flowable Note for MySQL users](https://flowable.com/open-source/docs/bpmn/ch03-Configuration/#creating-the-database-tables). * Flowable automatically upgrades the database schema and can encounter non-recoverable errors related to date settings. Before you start IDM 7 or later for the first time, remove the `SQL_MODE` settings `NO_ZERO_IN_DATE` and `NO_ZERO_DATE`. Example SQL command: ```sql mysql -uroot -ppassword set GLOBAL SQL_MODE=''; use openidm; set SQL_MODE=''; ``` After you complete the upgrade process, you can restart MySQL and your original settings should be restored. ### Changes to `boot.properties` * Prometheus monitoring Monitoring using Prometheus is no longer achieved with a specific access role. The `openidm/metrics/prometheus` endpoint is now protected by a basic authentication filter, using credentials set in the `resolver/boot.properties` file. Learn more in [Prometheus endpoint](../monitoring-guide/monitoring.html#prometheus). * Debugging information for Groovy scripts In previous releases, setting `javascript.exception.debug.info=true` in the `boot.properties` file enabled additional debug information, including line numbers and file names for JavaScript exceptions. In this release, setting `groovy.exception.debug.info=true` lets you gather comparable debug information for Groovy scripts. * Added properties These properties have been added to `resolver/boot.properties`: * `openidm.servlet.upload.alias=/upload` and `openidm.servlet.export.alias=/export`: Sets the REST endpoints for the bulk import feature. * `openidm.admin.password=openidm-admin`: Lets you change the password of the administrative user before startup. * Removed properties These properties have been removed from `resolver/boot.properties`: * openidm.script.javascript.debug * openidm.script.javascript.sources * openidm.ssl.host.aliases * com.iplanet.am.cookie.name * com.sun.identity.auth.cookieName ### Changes to `logging.properties` The default log message formatter has changed from `ThreadIdLogFormatter` to `SanitizedThreadIdLogFormatter`. The new default encodes control characters (such as newline characters) using URL-encoding, to protect against log forgery. Control characters in stack traces are not encoded. Learn more in [Log message format](../monitoring-guide/server-logs.html#log-message-format). ### Change to how authorization roles are assigned In previous IDM releases, managed users were granted the `openidm-authorized` role as a relationship during user creation as part of the `onCreateUser.js` script. In IDM 7, users are granted the `openidm-authorized` role statically when they authenticate. Learn more in [Authentication and roles](../auth-guide/authentication-and-roles.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This way of granting internal authentication roles is considered a best practice and is recommended for performance reasons. However, if your deployment relies on the old way of granting the `openidm-authorized` role, that configuration is still supported, and you can use your existing `onCreateUser.js` script to grant the role on creation. | ### Schema change to `authzRoles` The default relationship model for `authzRoles` and `authzMembers` has changed in this release. In the default configuration, a user's `authzRoles` now references only the `internal/role` resource collection and not the `managed/role`. Conversely, an internal role's `authzMembers` property now references only the `managed/user` resource collection. The default schema configuration files have been amended to support this change. The `managed/role` collection has been removed from the `authzRoles` property on a managed user object and the `internal/user` collection has been removed from the `authzMembers` property on an internal role object. Multiple resource collections for a single relationship field are not currently supported with a DS repository. For legacy reasons, Multiple resource collections will still work with a JDBC repository. ### Change to the `INTERNAL_USER` authentication module The INTERNAL\_USER authentication module is no longer provided in the default authentication configuration. This change means that any scripts you used previously to update internal user passwords in the IDM repository will need to be modified. ### Change to Prometheus monitoring Monitoring using Prometheus is no longer achieved with a specific access role. The `openidm/metrics/prometheus` endpoint is now protected by a basic authentication filter, using credentials set in the `resolver/boot.properties` file. Learn more in [Prometheus endpoint](../monitoring-guide/monitoring.html#prometheus). ### Change in how boolean values are assessed Properties stored in the repository with boolean (`true/false`) values are processed differently from this release. A property value is now considered `false` if its value is `false` or `null`. The value is considered `true` only if it is `true`, not if it is `null`. If you're migrating from a previous IDM release, you might need to adjust your scripts to take this change into account. ### Queued sync changes * Processing order of queued synchronization mappings In previous IDM releases, mappings for which queued synchronization was enabled were processed first. The synchronization engine would then process the non-queued mappings in order. In IDM 7, all mappings are processed in the order in which they are listed, regardless of whether queued synchronization is enabled. If you want to retain the pre-7.0 behavior, place your queued synchronization mappings first in your list of mappings. * Removal of `remainingRetries` from queued synchronization This release lets you configure an infinite number of queued synchronization retries. As part of this change, the `remainingRetries` property has been removed from the queued synchronization object. Learn more in [Configure queued synchronization](../synchronization-guide/chap-implicit-live-sync.html#configure-queued-sync). ### Virtual property calculation for `effectiveRoles` and `effectiveAssignments` `effectiveRoles` and `effectiveAssignments` are now calculated in IDM by default, using the new `queryConfig` property. The old method of using `onRetrieve` scripts will still work. The new `queryConfig` property is also available for use with other virtual properties. Learn more in [Effective roles and effective assignments](../objects-guide/effective-roles-and-assignments.html) and [Virtual properties](../objects-guide/managed-object-virtual-properties.html). ### Gzip compression for HTTP responses You can now configure Gzip compression for HTTP responses in `conf/jetty.xml`. In previous IDM releases, compression was configured in `conf/servletfilter-gzip.json`. This file has been removed. ### Configurable hashing IDM 7 supports [configurable hashing algorithms](../security-guide/encoding-attribute-values.html#encoding-salted-hash). ### Temporal constraint enforcement on roles Enforcing temporal constraints on roles is now achieved through Java, rather than through the `onSync-roles.js` and `postOperation-roles.js` scripts. These scripts are still provided in `openidm/bin/defaults/script/roles` for backward compatibility. To use the new Java-based functionality in existing deployments, change the `role` object in your managed object schema (`conf/managed.json`) by adding `"isTemporalConstraint" : true` to the `"temporalConstraints"` object. For example: ```json "temporalConstraints" : { "description" : "An array of temporal constraints for a role", "title" : "Temporal Constraints", "viewable" : false, "returnByDefault" : true, "isTemporalConstraint" : true, "type" : "array", ... } ``` Learn more in [Use temporal constraints to restrict effective roles](../objects-guide/roles-temporal-constraints.html). ### Change to JMS audit handler The `batch` configuration for the JMS common audit handler for access logs has changed to support reconnection if the broker becomes unavailable. This change adds a `batch.writeInterval` setting. It removes the following settings: * `batch.batchEnabled` * `batch.insertTimeoutSec` * `batch.pollTimeoutSec` * `batch.shutdownTimeoutSec` * `batch.threadCount` Learn more in [Configure the JMS audit event handler](../audit-guide/configuring-topic-handlers.html#audit-jms-config). ### Change to default audit configuration The default audit configuration no longer includes the `recon` audit topic. You can enable it by adding the `recon` audit topic to the `topics` list in `conf/audit.json` for the event handlers you choose. This change does not affect how auditing reconciliations works, just what the default configuration includes. No action is necessary unless you wish to have auditing on reconciliations enabled on a new installation. Learn more in [Query the reconciliation audit log](../audit-guide/querying-audit-over-rest.html#querying-recon-logs). ### Datatype of `userPassword` property in provisioner files As a security precaution, the `nativeType` for `userPassword` properties has been changed to `JAVA_TYPE_GUARDEDSTRING` in all sample provisioner files for the LDAP connector. If you have customized provisioner files, you should change this property. For example, change: Example provisioner update * BEFORE * AFTER ```json "userPassword" : { "type" : "string", "nativeName" : "userPassword", "nativeType" : "string", ... ``` ```json "userPassword" : { "type" : "string", "nativeName" : "__PASSWORD__", "nativeType" : "JAVA_TYPE_GUARDEDSTRING", ... ``` ### Removal of the global consent setting Previous IDM versions included a global consent setting in `conf/consent.json`. This file included a single configuration property, `enabled`, which determined whether IDM should check any mappings where consent was enabled and prompt end users for consent. This global consent setting and the corresponding `consent.json file` have been removed. If you have an existing `consent.json` file in your configuration, it will be ignored. Consent is now assessed only on a per-mapping, per-object basis. ### Support for MySQL Connector/J version 8.0 IDM 7 adds support for the latest version of MySQL Connector/J. If you're using MySQL Connector/J version 8.0 or later, make sure your `datasource.jdbc-default.json` file includes a setting for the time zone in your `jdbcUrl` property: ```json "jdbcUrl" : "jdbc:mysql://&{openidm.repo.host}:&{openidm.repo.port}/openidm?allowMultiQueries=true&characterEncoding=utf8&serverTimezone=UTC", ``` Also, note the `driverClass` changed in MySQL Connector/J version 8.0, from `com.mysql.jdbc.Driver` to `com.mysql.cj.jdbc.Driver`. The previous `driverClass` name will still work for now, but should be updated to avoid it displaying a warning when starting up IDM. ### Default security protocols for inbound connections The default security protocols for inbound connections to IDM are `TLSv1.2` and `TLSv1.3`. Learn more in [Jetty property reference](../install-guide/idm-config-properties-jetty.html#jetty-property-reference). Support for the `TLSv1.1` protocol has been removed by default. ### Removal of `address2` from the managed object schema The `address2` attribute has been removed from the managed object schema (`conf/managed.json`). ### ICF and connector changes The following ICF and connector changes will have an impact on existing IDM deployments that use those connectors: * Workday connector The Workday connector is no longer bundled with IDM. Download the connector and its dependencies from the [Backstage](https://backstage.forgerock.com/downloads/) download site. * Database Table connector The configuration requirements for the Database Table connector have changed: * The `jdbcDriver` and `jdbcUrlTemplate` properties have been removed. Use `driverClassName` and `url` instead. * The `database` property has been removed. The database should now be specified in the JDBC address in `url`. * Additional (optional) configuration properties are now available. For a full list, refer to [Database table connector](https://docs.pingidentity.com/openicf/connector-reference/dbtable.html). Additionally, the Database Table connector example configurations have changed: * samples/example-configurations/provisioners/provisioner.openicf-contractordb.json * Removed `required : true` from the `__NAME__` property. * Added `required : true` to the `EMAIL` property. * Removed `"keyColumn" : "UNIQUE_ID"`. * samples/example-configurations/provisioners/provisioner.openicf-contractordb.sql Set `EMAIL` as the `PRIMARY KEY`. ## Archive For documentation and release information prior to IDM 7.0, check out the [Documentation Archive](https://docs.pingidentity.com/archive/).