Upgrade Guide

This guide provides instructions for upgrading Wren:IDM to the new version.

Wren:IDM 7

If you are upgrading to the Wren:IDM 7, please follow the steps below.

Migrate Wren:ICF connector bundle names

The connector bundle naming has changed from the OpenICF namespace to the Wren:ICF namespace. Update the bundleName field in all provisioner configuration files (conf/provisioner.openicf-*.json).

Example 1. Provisioner bundle name migration

{
  "connectorRef" : {
-   "bundleName" : "org.forgerock.openicf.connectors.ldap-connector",
+   "bundleName" : "org.wrensecurity.wrenicf.connectors.ldap-connector",
    "bundleVersion" : "...",
    "connectorName" : "org.identityconnectors.ldap.LdapConnector"
  },
  ...
}

Migrate launcher configuration

Some changes were introduced to the conf/launcher.json file, so you must update your existing launcher configuration before starting the new version. Review the reference launcher.json from the GitHub repository and apply the following changes to your configuration:

Update the OSGi bundle list to reflect renamed or newly required bundles.

The easiest approach is to start from the reference launcher.json and re-apply any project-specific customizations on top of it.

Migrate to Felix HTTP Jetty service

PAX Web has been removed in favor of standard OSGi Http Whiteboard. The following changes to the config.properties` file are required for migration to the Felix HTTP Jetty service:

Example 2. Felix HTTP Jetty service migration

- # Configures the web embedded Web server via the following file
- org.ops4j.pax.web.config.file=&{launcher.project.location}/conf/jetty.xml
-
- # Enable pax web http/https services to enable jetty
- org.osgi.service.http.enabled=true
- org.osgi.service.http.secure.enabled=true
+ # Enable Felix HTTP Jetty service
+ org.apache.felix.http.enable=true

Migrate to HikariCP JDBC connection pool

Support for the deprecated BoneCP JDBC connection pool has been completely removed. If your project is still using BoneCP, please migrate to HikariCP.

Example 3. HikariCP JDBC connection pool configuration

{
  "driverClass" : "org.postgresql.Driver",
  "jdbcUrl" : "jdbc:postgresql://&{openidm.repo.host}:&{openidm.repo.port}/idmdb",
  "username" : "wrenidm",
  "password" : "wrenidm",
  "connectionTimeout" : 30000,
  "connectionPool" : {
    "type" : "hikari",
    "minimumIdle" : 20,
    "maximumPoolSize" : 50
  }
}

Migrate configuration property (conf/config.properties) to enable JDBC health monitoring:

- # enables the statistics MBean for BoneCP. Enabling this will have a performance impact on BoneCP.
- openidm.bonecp.statistics.enabled=false

+ # Enables HikariCP MBean (JMX) monitoring
+ wrenidm.hikaricp.statistics.enabled=false

Migrate Workflows

The workflow engine was migrated from Activiti to Flowable, so the process definitions also needed to be migrated. Follow these steps to migrate your workflows:

Perform database backup

Dump all tables with the prefix act_ from the Wren:IDM database. Refer to your database documentation for information on dumping database data.

Migrate process definitions

Update your BPMN process definitions and all associated files (such as HTML forms) to use Flowable annotations. See Flowable documentation for more information.

Example 4. Process execution listener migration

<!-- Before -->
<definitions xmlns:activiti="http://activiti.org/bpmn" targetNamespace="http://www.activiti.org/test">
  <process id="userRole" name="User Role Assignment" isExecutable="true">
    <extensionElements>
      <activiti:executionListener event="start" class="org.activiti.engine.impl.bpmn.listener.ScriptExecutionListener">
        <activiti:field name="script">
          <activiti:string>
            execution.setVariable('status', 'RUNNING')
          </activiti:string>
        </activiti:field>
        <activiti:field name="language" stringValue="groovy" />
      </activiti:executionListener>
...
<!-- After -->
<definitions xmlns:flowable="http://flowable.org/bpmn" targetNamespace="http://www.flowable.org/processdef">
  <process id="userRole" name="User Role Assignment" isExecutable="true">
    <extensionElements>
      <flowable:executionListener event="start" class="org.flowable.engine.impl.bpmn.listener.ScriptExecutionListener">
        <flowable:field name="script">
          <flowable:string>
            execution.setVariable('status', 'RUNNING')
          </flowable:string>
        </flowable:field>
        <flowable:field name="language" stringValue="groovy" />
      </flowable:executionListener>
...

Migrate running process instances

Get identifiers of all running process instances:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/workflow/processinstance?_queryId=query-all-ids&_fields=id,processDefinitionId&_prettyPrint=true"
{
  "result" : [{
    "_id" : "1",
    "processDefinitionId" : "userRole:1:50"
  }, {
    "_id" : "2",
    "processDefinitionId" : "userRole:2:100"
  } ],
  ...
}

Migrate all process instances to the latest process definitions:

curl \
  --header "X-OpenIDM-Username: openidm-admin" \
  --header "X-OpenIDM-Password: openidm-admin" \
  --request POST \
  "http://localhost:8080/openidm/workflow/processinstance/1?_action=migrate"
{"Successfully migrated process instance":"1"}

curl \
  --header "X-OpenIDM-Username: openidm-admin" \
  --header "X-OpenIDM-Password: openidm-admin" \
  --request POST \
  "http://localhost:8080/openidm/workflow/processinstance/2?_action=migrate"
{"Successfully migrated process instance":"2"}
...