Incompatible Changes

When you update to IDM 7.0.x from a version prior to IDM 7.0.0, the following changes may impact existing deployments. Adjust existing scripts, files, and clients, as necessary:

The Activiti workflow engine has been replaced with Flowable. Current workflow definitions will continue to work with the new engine in compatibility mode, but all new workflow definitions must be written for Flowable. For more information, see "Workflow Definition Comparison".

If you are using MySQL for the workflow database, the following apply:

  • You must use MySQL version 5.6.4 or later. If you are 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.

  • 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:

    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.

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. For more information, see "Monitoring With the Prometheus Endpoint".

Debugging Information for Groovy Scripts

In previous releases, setting javascript.exception.debug.info=true in resolver/boot.properties 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, 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

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. For more information, see Set the Log Message Format.

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. For more information, see "Authentication and Roles".

Note

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.

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. Multiple resource collections will still work with a JDBC repository, for legacy reasons.

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. For more information, see "Monitoring With the Prometheus Endpoint".

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 are migrating from a previous IDM release, you might need to adjust your scripts to take this change into account.

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.

For more information about the queued synchronization configuration, see "Configure Queued Synchronization".

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. For more information about effective roles and assignments, see "Effective Roles and Effective Assignments". For more information about queryConfig and virtual properties, see "Virtual Properties".

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.

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:

"temporalConstraints" : {
    "description" : "An array of temporal constraints for a role",
    "title" : "Temporal Constraints",
    "viewable" : false,
    "returnByDefault" : true,
    "isTemporalConstraint" : true,
    "type" : "array",
    ...
} 

For information about setting temporal constraints on roles, see "Use Temporal Constraints to Restrict Effective Roles".

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

For details on the JMS handler configuration, see "Configure the JMS Audit Event Handler".

The default configuration for audit has been changed to no longer have the recon audit topic included by default. It can be enabled 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. For more information, see Query the Reconciliation Audit Log.

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:

"userPassword" : {
    "type" : "string",
    "nativeName" : "userPassword",
    "nativeType" : "string",
    ...

to

"userPassword" : {
    "type" : "string",
    "nativeName" : "__PASSWORD__",
    "nativeType" : "JAVA_TYPE_GUARDEDSTRING",
    ...

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 for which 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 simply be ignored.

Consent is now assessed only on a per-mapping, per-object basis. For more information, see "Configure Privacy and Consent".

IDM 7 adds support for the latest version of MySQL Connector/J has been added. If you are using version 8.0 or later, make sure your datasource.jdbc-default.json file includes a setting for the time zone in your jdbcUrl property:

"jdbcUrl" : "jdbc:mysql://&{openidm.repo.host}:&{openidm.repo.port}/openidm?allowMultiQueries=true&characterEncoding=utf8&serverTimezone=UTC",

Also, note the driverClass changed in 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.

The default security protocols for inbound connections to IDM are TLSv1.2 and TLSv1.3. For information on enabling additional protocols, see "Enable and Disable Secure Protocols and Cipher Suites".

Support for the TLSv1.1 protocol has been removed by default.

The address2 attribute has been removed from the managed object schema (conf/managed.json).

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 ForgeRock BackStage 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, see "Database Table Connector".

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.

Read a different version of :