Follow these steps to install IDM:

1. Make sure you have an appropriate version of Java installed:

   $ java -version
   java version "1.8.0_121"
   Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
   Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)

   For a description of the Java requirements, see "Before You Install" in the Release Notes.

2. Download IDM from the ForgeRock BackStage site. The ForgeRock BackStage site provides access to ForgeRock releases. These releases are thoroughly validated for ForgeRock customers who run the software in production deployments, and for those who want to try or test a given release.

3. Unpack the contents of the .zip file into the install directory:

   $ unzip ~/Downloads/IDM-6.0.0.7.zip
   Archive:  IDM-6.0.0.7.zip
     inflating: openidm/.checksums.csv
      creating: openidm/bundle/
    extracting: openidm/bundle/openidm-audit-6.0.0.7.jar
   ...

4. By default, IDM listens for HTTP and HTTPS connections on ports 8080 and 8443, respectively. To change the default port, edit your resolver/boot.properties file. For more information, see "Host and Port Information" in the Integrator's Guide.

   The hostname associated with IDM by default is localhost. To change the default hostname, edit the openidm.host property in your resolver/boot.properties file.

   When you deploy IDM in production, you must set openidm.host to the URL of your deployment. If you do not do so, calls to the /admin endpoint are not redirected properly.

5. Before running IDM in production, replace the default embedded DS repository with a supported repository.

   For more information, see "Selecting a Repository".

To run IDM as a background process, see "Starting, Stopping, and Running the Server" in the Integrator's Guide.

Follow these steps to run IDM interactively:

1. Start the Felix container, load all services, and start a command shell to allow you to manage the container:

   • Start IDM (UNIX):

     $ cd /path/to/openidm
     $ ./startup.sh
     
     Using OPENIDM_HOME:   /path/to/openidm
     Using PROJECT_HOME:   /path/to/openidm
     Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
     Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
     -> OpenIDM version "6.0.0.7"
     OpenIDM ready

   • Start IDM (Windows):

     C:\> cd \path\to\openidm
     C:\> startup.bat
     
     "Using OPENIDM_HOME:   \path\to\openidm"
     "Using PROJECT_HOME:   \path\to\openidm"
     "Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m -Dfile.encoding=UTF-8"
     "Using LOGGING_CONFIG: -Djava.util.logging.config.file=\path\to\openidm\conf\logging.properties"
     -> OpenIDM version "6.0.0.7"
     OpenIDM ready
     -> 

   At the OSGi console -> prompt, you can enter commands such as help for usage, or ps to view the bundles installed. For a list of the core services and their states, run the following command:

   -> scr list
   BundleId Component Name Default State
       Component Id State      PIDs (Factory PID)
   [   5]   org.forgerock.openidm.config.enhanced.starter  enabled
       [   1] [active      ] org.forgerock.openidm.config.enhanced.starter
   [   5]   org.forgerock.openidm.config.manage  enabled
       [   0] [active      ] org.forgerock.openidm.config.manage
   [  10]   org.forgerock.openidm.datasource.jdbc  enabled
   [  10]   org.forgerock.openidm.repo.jdbc  enabled
   [  11]   org.forgerock.openidm.repo.ds  enabled
       [  48] [active      ] org.forgerock.openidm.repo.ds
   ...
   -> 

   A default startup does not include certain configurable services, which will indicate an unsatisfied state until they are included in the configuration. As you work through the sample configurations described later in this guide, you will notice that these services are active.

   Startup errors and messages are logged to the console by default. You can also view these messages in the log files at /path/to/openidm/logs.

2. Alternatively, you can manage the container and services from the Apache Felix Web Console.

   Use these hints to connect to the Apache Felix Web Console:

   • Default URL: https://localhost:8443/system/console

   • Default user name: admin

   • Default password: admin

   Select Main > Components to see core services and their respective states.

You can stop IDM from the -> prompt in the OSGi console, or through the Apache Felix Web Console. Both of these options stop the Felix container.

1. In the OSGi console, enter the shutdown command at the -> prompt:

   -> shutdown
   ...
   $

2. In the Apache Felix Web Console, select Web Console > System Information to stop the container.

3. On Unix systems, you can stop IDM by using the shutdown.sh script, located in the /path/to/openidm directory:

   $ ./shutdown.sh
   ./shutdown.sh
   Stopping OpenIDM (31391)

1. Access the following URL to obtain the JSON representation of all users in the IDM repository:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    http://localhost:8080/openidm/managed/user/?_queryId=query-all-ids

   When you first install IDM with an empty repository, no users exist.

2. Create a user joe by sending a RESTful POST.

   The following curl commands create the user joe in the repository.

   • Create joe (UNIX):

     $ curl \
      --header "Content-Type: application/json" \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request POST \
      --data '{
      "userName":"joe",
      "givenName":"joe",
      "sn":"smith",
      "mail":"joe@example.com",
      "telephoneNumber":"555-123-1234",
      "password":"TestPassw0rd",
      "description":"My first user",
      "_id":"joe"
      }' \
      http://localhost:8080/openidm/managed/user?_action=create
     {
       "_id": "joe",
       "_rev": "00000000c03fd7aa",
       "userName": "joe",
       "givenName": "joe",
       "sn": "smith",
       "mail": "joe@example.com",
       "telephoneNumber": "555-123-1234",
       "description": "My first user",
       "accountStatus": "active",
       "effectiveRoles": [],
       "effectiveAssignments": []
     }

   • Create joe (Windows):

     C:\> curl ^
      --header "Content-Type: application/json" ^
      --header "X-OpenIDM-Username: openidm-admin" ^
      --header "X-OpenIDM-Password: openidm-admin" ^
      --request POST ^
      --data "{
      \"userName\":\"joe\",
      \"givenName\":\"joe\",
      \"sn\":\"smith\",
      \"mail\":\"joe@example.com\",
      \"telephoneNumber\":\"555-123-1234\",
      \"password\":\"TestPassw0rd\",
      \"description\":\"My first user\",
      \"_id\":\"joe\"
      }" ^
      http://localhost:8080/openidm/managed/user?_action=create

3. Fetch the newly created user from the repository with a RESTful GET:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    http://localhost:8080/openidm/managed/user/joe
   {
     "_id": "joe",
     "_rev": "00000000c03fd7aa",
     "userName": "joe",
     "givenName": "joe",
     "sn": "smith",
     "mail": "joe@example.com",
     "telephoneNumber": "555-123-1234",
     "description": "My first user",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

Set up a new project as follows:

1. Create a directory for your new project:

   $ mkdir /path/to/my-project

   Note that the automated update process does not work for projects that are subdirectories of the default project. You should therefore create your new project directory somewhere outside of /path/to/openidm/.

2. Set up a minimal configuration:

   • If your project will be similar to any of the sample configurations (described in the Samples Guide) copy the contents of the sample to your new project.

     For example:

     $ cp -r /path/to/openidm/samples/sync-with-ldap/* /path/to/my-project/

     You can then customize the sample configuration according to your requirements.

   • If you do not want to start with one of the sample configurations, copy the conf/ and script/ directories from the default project to your new project directory:

     $ cd /path/to/openidm
     $ cp -pr conf /path/to/my-project/
     $ cp -pr script /path/to/my-project/

     You can then customize the basic configuration according to your requirements.

3. Start your new project as follows:

   $ cd /path/to/openidm
   $ ./startup.sh -p /path/to/my-project

To configure a new or existing DS instance as an external repository, follow these steps:

1. If you have not yet installed DS, download it from ForgeRock's BackStage site and extract the zip archive.

2. Set up DS with a base DN entry of dc=openidm,dc=forgerock,dc=com.

   $ cd /path/to/opendj
   $ ./setup directory-server \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPassword password \
    --hostname localhost \
    --ldapPort 31389 \
    --adminConnectorPort 34444 \
    --baseDN dc=openidm,dc=forgerock,dc=com \
    --acceptLicense
   Validating parameters..... Done
   Configuring certificates..... Done
   Configuring server..... Done
   
   To see basic server status and configuration, you can launch
   /path/to/opendj/bin/status

   This command configures DS on the localhost, listening on ports 31389 and 34444 so that it does not conflict with the default ports used in the LDAP samples. You can use any available ports in the setup. If you use a different host and an LDAP port other than 31389, change the primaryLdapServers property in your repo.ds-external.json file accordingly.

3. Create the matching rules required to set up indexes for the default IDM data:

   $ ./bin/dsconfig \
    create-schema-provider \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "IDM managed/user Json Schema" \
    --type json-query-equality-matching-rule \
    --set enabled:true \
    --set case-sensitive-strings:false \
    --set ignore-white-space:true \
    --set matching-rule-name:caseIgnoreJsonQueryMatchManagedUser \
    --set matching-rule-oid:1.3.6.1.4.1.36733.2.3.4.1  \
    --set indexed-field:userName \
    --set indexed-field:givenName \
    --set indexed-field:sn \
    --set indexed-field:mail \
    --set indexed-field:accountStatus \
    --trustAll \
    --no-prompt
   The JSON Query Equality Matching Rule was created successfully
   
   $ ./bin/dsconfig \
    create-schema-provider \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "IDM managed/role Json Schema" \
    --type json-query-equality-matching-rule \
    --set enabled:true \
    --set case-sensitive-strings:false \
    --set ignore-white-space:true \
    --set matching-rule-name:caseIgnoreJsonQueryMatchManagedRole \
    --set matching-rule-oid:1.3.6.1.4.1.36733.2.3.4.2  \
    --set indexed-field:"condition/**" \
    --set indexed-field:"temporalConstraints/**" \
    --trustAll \
    --no-prompt
   The JSON Query Equality Matching Rule was created successfully
   
   $ ./bin/dsconfig \
    create-schema-provider \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "IDM Relationship Json Schema" \
    --type json-query-equality-matching-rule \
    --set enabled:true \
    --set case-sensitive-strings:false \
    --set ignore-white-space:true \
    --set matching-rule-name:caseIgnoreJsonQueryMatchRelationship \
    --set matching-rule-oid:1.3.6.1.4.1.36733.2.3.4.3  \
    --set indexed-field:firstResourceCollection \
    --set indexed-field:firstResourceId \
    --set indexed-field:firstPropertyName \
    --set indexed-field:secondResourceCollection \
    --set indexed-field:secondResourceId \
    --set indexed-field:secondPropertyName \
    --trustAll \
    --no-prompt
   The JSON Query Equality Matching Rule was created successfully
   
   $ ./bin/dsconfig \
    create-schema-provider \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "IDM Cluster Object Json Schema" \
    --type json-query-equality-matching-rule \
    --set enabled:true \
    --set case-sensitive-strings:false \
    --set ignore-white-space:true \
    --set matching-rule-name:caseIgnoreJsonQueryMatchClusterObject \
    --set matching-rule-oid:1.3.6.1.4.1.36733.2.3.4.4  \
    --set indexed-field:"timestamp" \
    --set indexed-field:"state" \
    --trustAll \
    --no-prompt
   The JSON Query Equality Matching Rule was created successfully

4. Copy the IDM LDIF schema to the DS schema folder. To ensure that the schema definitions for IDM load only after all of the DS schema files installed by default, rename the file with a number higher than the default DS schema files. This example renames the file to 99-openidm.ldif:

   $ cp /path/to/openidm/db/ds/schema/openidm.ldif db/schema/99-openidm.ldif

5. Restart DS to load the new schema:

   $ bin/stop-ds --restart
   Stopping Server...
   [02/Mar/2018:15:14:53 -0800] category=BACKEND severity=NOTICE msgID=370 msg=The backend userRoot is now taken offline
   ...
   [02/Mar/2018:15:15:12 -0800] category=CORE severity=NOTICE msgID=139 ... The Directory Server has started successfully

6. Create the required indexes:

   $ bin/dsconfig \
    create-backend-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name fr-idm-managed-user-json \
    --set index-type:equality \
    --trustAll \
    --no-prompt
   The Backend Index was created successfully
   
   $ bin/dsconfig \
    create-backend-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name fr-idm-managed-role-json \
    --set index-type:equality \
    --trustAll \
    --no-prompt
   The Backend Index was created successfully
   
   $ bin/dsconfig \
    create-backend-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name fr-idm-relationship-json \
    --set index-type:equality \
    --trustAll \
    --no-prompt
   The Backend Index was created successfully
   
   $ bin/dsconfig \
    create-backend-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name fr-idm-cluster-json \
    --set index-type:equality \
    --trustAll \
    --no-prompt
   The Backend Index was created successfully
   
   $ bin/dsconfig \
    create-backend-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name fr-idm-json \
    --set index-type:equality \
    --trustAll \
    --no-prompt
   The Backend Index was created successfully
   
   $ bin/dsconfig \
    create-backend-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name fr-idm-link-type \
    --set index-type:equality \
    --trustAll \
    --no-prompt
   The Backend Index was created successfully
   
   $ bin/dsconfig \
    create-backend-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name fr-idm-link-firstid \
    --set index-type:equality \
    --trustAll \
    --no-prompt
   The Backend Index was created successfully
   
   $ bin/dsconfig \
    create-backend-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name fr-idm-link-secondid \
    --set index-type:equality \
    --trustAll \
    --no-prompt
   The Backend Index was created successfully
   
   $ bin/dsconfig \
    create-backend-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backend-name userRoot \
    --index-name fr-idm-link-qualifier \
    --set index-type:equality \
    --trustAll \
    --no-prompt
   The Backend Index was created successfully

   Finally, rebuild the indexes:

   $ bin/rebuild-index \
    --hostname localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --baseDN dc=openidm,dc=forgerock,dc=com \
    --rebuildAll \
    --start 0 \
    --trustAll
   Rebuild Index task 20180302154417277 scheduled to start 02 Mar 2018 3:44:17 PM

7. Import the populate_users.ldif file into DS to set up the default entries required by IDM:

   $ bin/import-ldif \
    --ldifFile /path/to/openidm/db/ds/scripts/populate_users.ldif \
    --backendID userRoot \
    --hostName localhost \
    --port 34444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --trustAll \
    --noPropertiesFile
   Import task 20180302154533707 scheduled to start immediately
   ...
   Import task 20180302154533707 has been successfully completed

   Your DS instance is now ready to be used as an external repository.

8. In your IDM installation, remove the default DS repository configuration file (repo.ds.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.ds.json

9. Copy the external DS repository configuration file (repo.ds-external.json) to your project's conf directory and rename it repo.ds.json:

   $ cd /path/to/openidm/
   $ cp db/ds/conf/repo.ds-external.json my-project/conf/repo.ds.json

10. If your DS instance is not running on the localhost and listening for LDAP connections on port 31389, adjust the primaryLdapServers property in that file to match your DS setup.

11. Start IDM with the configuration for your project. For example:

    $ cd /path/to/openidm
     $ ./startup.sh -p my-project
     Executing ./startup.sh...
     Using OPENIDM_HOME:   /path/to/openidm
     Using PROJECT_HOME:   /path/to/my-project
     Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
     Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/my-project/conf/logging.properties
     -> OpenIDM version "6.0.0.7"
     OpenIDM ready

After you have installed MySQL on the local host and before starting IDM for the first time, configure the server to use the new repository, as described in the following sections.

This procedure assumes that a password has already been set for the MySQL root user:

1. Download MySQL Connector/J, version 5.1 or later from the MySQL website. Unpack the delivery, and copy the .jar into the openidm/bundle directory:

   $ cp mysql-connector-java-version-bin.jar /path/to/openidm/bundle/

2. Make sure that IDM is stopped:

   $ cd /path/to/openidm/
   $ ./shutdown.sh
   OpenIDM is not running, not stopping.

3. Remove the default DS repository configuration file (repo.ds.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.ds.json

4. Copy the MySQL database connection configuration file (datasource.jdbc-default.json) and the database table configuration file (repo.jdbc.json) to your project's conf directory:

   $ cd /path/to/openidm/
   $ cp db/mysql/conf/datasource.jdbc-default.json my-project/conf/
   $ cp db/mysql/conf/repo.jdbc.json my-project/conf/

5. If you have previously set up a MySQL repository for IDM, you must drop the openidm database and users before you continue:

   mysql> drop database openidm;
   Query OK, 21 rows affected (0.63 sec)
   mysql> drop user openidm;
   Query OK, 0 rows affected (0.02 sec)
   mysql> drop user openidm@localhost;
   Query OK, 0 rows affected (0.00 sec)

6. Import the IDM data definition language script into MySQL:

   $ cd /path/to/mysql
   $ mysql -u root -p < /path/to/openidm/db/mysql/scripts/openidm.sql
   Enter password:
   $ 

   Note

   If you see errors like Access denied for user 'root'@'localhost', and are deploying on a new installation of Ubuntu 16.04 and above, the UNIX_SOCKET plugin may be installed, which applies Linux root credentials to MySQL. In that case, substitute sudo mysql -u root for mysql -u root -p in the commands in this section.

   This step creates an openidm database for use as the internal repository, and a user openidm with password openidm who has all the required privileges to update the database:

   $ mysql -u root -p
   Enter password:
   Welcome to the MySQL monitor.  Commands end with ; or \g.
   Your MySQL connection id is 18
   Server version: 5.5.19 MySQL Community Server (GPL)
   ...
   mysql> use openidm;
   Reading table information for completion of table and column names
   You can turn off this feature to get a quicker startup with -A
   
   Database changed
   mysql> show tables;
   
   +---------------------------+
   | Tables_in_openidm         |
   +---------------------------+
   | clusteredrecontargetids   |
   | clusterobjectproperties   |
   | clusterobjects            |
   | configobjectproperties    |
   | configobjects             |
   | genericobjectproperties   |
   | genericobjects            |
   | ...                       |
   | schedulerobjects          |
   | schedulerobjectproperties |
   | uinotification            |
   | updateobjectproperties    |
   | updateobjects             |
   +---------------------------+
   

   Exit the mysql console.

   mysql> exit
   Bye

7. Create the IDM database user.

   If you are running MySQL 5.7 or higher, run the following script:

   $ cd /path/to/mysql
   $ mysql -u root -p < /path/to/openidm/db/mysql/scripts/createuser.sql
   Enter password: 

   If you are running a MySQL version prior to 5.7, run the following script:

   $ cd /path/to/mysql
   $ mysql -u root -p < /path/to/openidm/db/mysql/scripts/createuser.mysql56.sql
   Enter password: 

8. Run the three scripts that set up the tables required by the Activiti workflow engine.

   If you are running MySQL 5.6.4 or higher, run the following scripts:

   $ cd /path/to/mysql
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql.create.engine.sql
   Enter password: 
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql.create.history.sql
   Enter password: 
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql.create.identity.sql
   Enter password: 
      

   If you are running a MySQL version prior to 5.6.4, run the following scripts:

   $ cd /path/to/mysql
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql55.create.engine.sql
   Enter password: 
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql55.create.history.sql
   Enter password: 
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql.create.identity.sql
   Enter password: 
      

9. If you are planning to direct audit logs to this repository, run the script that sets up the audit tables:

   $ mysql -D openidm -u root -p < openidm/db/mysql/scripts/audit.sql
   Enter password: 

10. Update the connection configuration to reflect your MySQL deployment. The default connection configuration in the datasource.jdbc-default.json file is as follows:

    {
        "driverClass" : "com.mysql.jdbc.Driver",
        "jdbcUrl" : "jdbc:mysql://&{openidm.repo.host}:&{openidm.repo.port}/openidm?allowMultiQueries=true&characterEncoding=utf8",
        "databaseName" : "openidm",
        "username" : "openidm",
        "password" : "openidm",
        "connectionTimeout" : 30000,
        "connectionPool" : {
            "type" : "hikari",
            "minimumIdle" : 20,
            "maximumPoolSize" : 50
        }
    }

    Specify the values for openidm.repo.host and openidm.repo.port in one of the following ways:

    • Set the values in resolver/boot.properties or your project's conf/system.properties file, for example:

      openidm.repo.host = localhost
      openidm.repo.port = 3306

    • Set the properties in the OPENIDM_OPTS environment variable and export that variable before startup. You must include the JVM memory options when you set this variable. For example:

      $ export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=3306"
      $ ./startup.sh -p /path/to/openidm/my-project
      Executing ./startup.sh...
      Using OPENIDM_HOME:   /path/to/openidm
      Using PROJECT_HOME:   /path/to/openidm
      Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=3306
      Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
      Using boot properties at /path/to/openidm/resolver/boot.properties
      -> OpenIDM version "6.0.0.7"
      OpenIDM ready

These instructions are specific to MS SQL Server 2012 R2 Standard Edition, running on a Windows Server 2012 R2 system. Adapt the instructions for your environment.

After you have installed MS SQL on the local host, install IDM, if you have not already done so, but do not start the instance. Import the data definition and configure IDM to use the MS SQL repository, as described in the following steps:

1. Use SQL Management Studio to import the IDM data definition language script into MS SQL:

   1. Navigate to SQL Server Management Studio.

   2. On the Connect to Server panel, select Windows Authentication and click Connect.

   3. Select File > Open > File and navigate to the data definition language script (path\to\openidm\db\mssql\scripts\openidm.sql). Click Open to open the file.

   4. Click Execute to run the script.

2. This step creates an openidm database for use as the internal repository, and a user openidm with password openidm who has all the required privileges to update the database. You might need to refresh the view in SQL Server Management Studio to see the openidm database in the Object Explorer.

   Expand Databases > openidm > Tables. You should see the IDM tables in the openidm database, as shown in the following example.

   

3. Execute the three scripts that set up the tables required by the Activiti workflow engine:

   You can use the sqlcmd command to execute the scripts, for example:

   PS C:\Users\Administrator> sqlcmd -S localhost -d openidm ^
       -i C:\path\to\openidm\db\mssql\scripts\activiti.mssql.create.engine.sql
   PS C:\Users\Administrator> sqlcmd -S localhost -d openidm ^
       -i C:\path\to\openidm\db\mssql\scripts\activiti.mssql.create.history.sql
   PS C:\Users\Administrator> sqlcmd -S localhost -d openidm ^
       -i C:\path\to\openidm\db\mssql\scripts\activiti.mssql.create.identity.sql

   Note

   When you run the activiti.mssql.create.engine.sql script, you might see the following warning in the log:

   Warning! The maximum key length is 900 bytes. The index 'ACT_UNIQ_PROCDEF' has maximum
   length of 1024 bytes. For some combination of large values, the insert/update operation will fail.

   It is very unlikely that the key length will be an issue in your deployment, and you can safely ignore this warning.

4. If you are going to direct audit logs to this repository, run the script that sets up the audit tables:

   PS C:\Users\Administrator> sqlcmd -S localhost -d openidm ^
    -i C:\path\to\openidm\db\mssql\scripts\audit.sql

5. IDM requires an MS SQL driver that must be created from two separate JAR files. Create the driver as follows:

   1. Download the JDBC Driver for SQL Server from Microsoft's download site. IDM requires at least version 4.2 of the driver (sqljdbc_4.2.8112.100_enu.tar.gz). The precise download URL might vary, depending on your location.

      Extract the JAR file (sqljdbc42.jar), using 7-zip or an equivalent file management application and copy the file to the openidm\db\mssql\scripts directory.

   2. Download the bnd JAR file (bnd-2.4.0.jar) that enables you to create OSGi bundles. For more information about bnd, see http://bnd.bndtools.org/.

      Copy this JAR file to openidm\db\mssql\scripts.

   3. Your openidm\db\mssql\scripts directory should now include the following files:

      bnd-2.4.0.jar  sqljdbc4.bnd  sqljdbc42.jar

   4. Create an OSGi bundle from the driver JAR with the following command:

      C:\> cd \path\to\openidm\db\mssql\scripts
      ./> java -jar bnd-2.4.0.jar wrap --properties sqljdbc4.bnd --output sqljdbc42-osgi.jar sqljdbc42.jar

      This step creates the OSGi bundle named sqljdbc42-osgi.jar.

   5. Copy the sqljdbc42-osgi.jar file to the openidm\bundle directory:

      ./> copy sqljdbc42-osgi.jar \path\to\openidm\bundle

6. Remove the default DS repository configuration file (repo.ds.json) from your project's conf/ directory. For example:

   C:\> cd \path\to\openidm\my-project\conf\
   .\> del repo.ds.json

7. Copy the database connection configuration file for MS SQL (datasource.jdbc-default.json) and the database table configuration file (repo.jdbc.json) to your project's configuration directory. For example:

   C:\> cd \path\to\openidm
   .\> copy db\mssql\conf\datasource.jdbc-default.json my-project\conf\
   .\> copy db\mssql\conf\repo.jdbc.json my-project\conf\

8. Update the connection configuration to reflect your MS SQL deployment. The default connection configuration in the datasource.jdbc-default.json file is as follows:

   {
       "driverClass" : "com.microsoft.sqlserver.jdbc.SQLServerDriver",
       "jdbcUrl" : "jdbc:sqlserver://&{openidm.repo.host}:&{openidm.repo.port};instanceName=default;databaseName=openidm;applicationName=OpenIDM",
       "databaseName" : "openidm",
       "username" : "openidm",
       "password" : "openidm",
       "connectionTimeout" : 30000,
       "connectionPool" : {
           "type" : "hikari",
           "minimumIdle" : 20,
           "maximumPoolSize" : 50
       }
   }

   Specify the values for openidm.repo.host and openidm.repo.port in one of the following ways:

   • Set the values in resolver/boot.properties or your project's conf/system.properties file, for example:

     openidm.repo.host = localhost
     openidm.repo.port = 1433

   • Set the properties in the OPENIDM_OPTS environment variable and export that variable before startup. You must include the JVM memory options when you set this variable. For example:

     $ export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=1433"
     $ cd /path/to/openidm
     $ ./startup.sh -p my-project
     Executing ./startup.sh...
     Using OPENIDM_HOME:   /path/to/openidm
     Using PROJECT_HOME:   /path/to/openidm
     Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=1433
     Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
     Using boot properties at /path/to/openidm/resolver/boot.properties
     -> OpenIDM version "6.0.0.7"
     OpenIDM ready

1. Import the IDM schema using the data definition language script (/path/to/openidm/db/oracle/scripts/openidm.sql), as the appropriate schema owner user.

   When you have run the script, you should be able to query the internaluser table. The query should return two records (openidm-admin and anonymous). The output here has been formatted for legibility:

   SQL> select * from internaluser;
   
   OBJECTID     openidm-admin
   -----------------------------------------------------------------------------
   REV          0
   -----------------------------------------------------------------------------
   PWD          openidm-admin
   -----------------------------------------------------------------------------
   ROLES        [ { "_ref" : "repo/internal/role/openidm-admin" },
                  { "_ref" : "repo/internal/role/openidm-authorized" } ]
   -----------------------------------------------------------------------------
   
   OBJECTID     anonymous
   -----------------------------------------------------------------------------
   REV          0
   -----------------------------------------------------------------------------
   PWD          anonymous
   -----------------------------------------------------------------------------
   ROLES        [ { "_ref" : "repo/internal/role/openidm-reg" } ]
   -----------------------------------------------------------------------------

2. Run the three scripts that set up the tables required by the Activiti workflow engine.

   You can use the Oracle SQL Developer Data Modeler to run the scripts, as described in the corresponding Oracle documentation.

   You must run the following scripts:

   /path/to/openidm/db/oracle/scripts/activiti.oracle.create.engine.sql
   /path/to/openidm/db/oracle/scripts/activiti.oracle.create.history.sql
   /path/to/openidm/db/oracle/scripts/activiti.oracle.create.identity.sql

3. If you plan to direct audit logs to this repository, run the script that sets up the audit tables:

   You can use the Oracle SQL Developer Data Modeler to run the scripts, as described in the previous step.

   You must run the following script:

   /path/to/openidm/db/oracle/scripts/audit.sql

4. Create an Oracle DB driver from two separate jar files and set up the repository configuration for Oracle DB, as follows:

   1. Download the Oracle JDBC driver for your Oracle DB version from Oracle Technology Network and place it in the openidm/db/oracle/scripts directory:

      $ ls /path/to/openidm/db/oracle/scripts
      ojdbc7_g.jar    openidm.sql

   2. Create a bnd file and edit it to match the version information for your JDBC driver.

      You can use the sample bnd file located in openidm/db/mssql/scripts. Copy the bnd file to the same location as the JDBC driver:

      $ cd /path/to/openidm/db
      $ cp mssql/scripts/sqljdbc4.bnd oracle/scripts
      $ ls oracle/scripts
      ojdbc7_g.jar    openidm.sql    sqljdbc4.bnd

      The JDBC driver version information for your driver is located in the Specification-Version property in the MANIFEST file of the driver:

      $ cd /path/to/openidm/db/oracle/scripts
      $ unzip -q -c ojdbc7_g.jar META-INF/MANIFEST.MF
      ...
      Specification-Vendor: Sun Microsystems Inc.
      Specification-Title: JDBC
      Specification-Version: 4.0
      ...

      Edit the bnd file to match the JDBC driver version:

      $ more sqljdbc4.bnd
      ...
      version=4.0
      Export-Package: *;version=${version}
      Bundle-Name: Oracle JDBC Driver 4.0 for SQL Server
      Bundle-SymbolicName: Oracle JDBC Driver 4.0 for SQL Server
      Bundle-Version: ${version}
      Import-Package: *;resolution:=optional

   3. Download the bnd JAR file (bnd-2.4.0.jar) that enables you to create OSGi bundles. For more information about bnd, see http://bnd.bndtools.org/.

      Place the bnd JAR file in the same directory as the JDBC driver, and the bnd file:

      $ ls /path/to/openidm/db/oracle/scripts
      bnd-2.4.0.jar    ojdbc7_g.jar    openidm.sql    sqljdbc4.bnd

   4. Change to the directory in which the script files are located and run the following command to create the OSGi bundle:

      $ cd /path/to/openidm/db/oracle/scripts
      $ java -jar bnd-2.4.0.jar wrap -properties sqljdbc4.bnd ojdbc7_g.jar
      Dec 10, 2013 9:53:28 AM java.util.prefs.FileSystemPreferences$1 run
      INFO: Created user preferences directory.
      ojdbc7_g.jar 984 0

      A new .bar file has now been created:

      $ ls
      bnd-2.4.0.jar  ojdbc7_g.bar  ojdbc7_g.jar  openidm.sql  sqljdbc4.bnd

   5. Move the .bar file to the openidm/bundle directory and rename it with a .jar extension. It does not matter what you name the file:

      $ mv ojdbc7_g.bar /path/to/openidm/bundle/ojdbc7_g-osgi.jar

5. Remove the default DS repository configuration file (repo.ds.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.ds.json

6. Copy the database connection configuration file for Oracle (datasource.jdbc-default.json) and the database table configuration file (repo.jdbc.json) to your project's configuration directory. For example:

   $ cd /path/to/openidm/
   $ cp db/oracle/conf/datasource.jdbc-default.json my-project/conf/
   $ cp db/oracle/conf/repo.jdbc.json my-project/conf/

7. Update the connection configuration to reflect your Oracle database deployment. The default connection configuration in the datasource.jdbc-default.json file is as follows:

   {
       "driverClass" : "oracle.jdbc.OracleDriver",
       "jdbcUrl" : "jdbc:oracle:thin:@//&{openidm.repo.host}:&{openidm.repo.port}/DEFAULTCATALOG",
       "databaseName" : "openidm",
       "username" : "openidm",
       "password" : "openidm",
       "connectionTimeout" : 30000,
       "connectionPool" : {
           "type" : "hikari",
           "minimumIdle" : 20,
           "maximumPoolSize" : 50
       }
   }

   Specify the values for openidm.repo.host and openidm.repo.port in one of the following ways:

   • Set the values in resolver/boot.properties or your project's conf/system.properties file, for example:

     openidm.repo.host = localhost
     openidm.repo.port = 1525

   • Set the properties in the OPENIDM_OPTS environment variable and export that variable before startup. You must include the JVM memory options when you set this variable. For example:

     $ export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=1525"
     $ cd /path/to/openidm
     $ ./startup.sh -p my-project
     Executing ./startup.sh...
     Using OPENIDM_HOME:   /path/to/openidm
     Using PROJECT_HOME:   /path/to/openidm
     Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=1525
     Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
     Using boot properties at /path/to/openidm/resolver/boot.properties
     -> OpenIDM version "6.0.0.7"
     OpenIDM ready

   The jdbcUrl corresponds to the URL of the Oracle DB listener, including the service name, based on your configured Local Naming Parameters (tnsnames.ora). It should be whatever is appropriate for your environment.

   The DEFAULTCATALOG refers to the SID (system identifier), for example, orcl.

   The username and password correspond to the credentials of the service user that connects from IDM.

1. The path/to/openidm/db/postgresql/scripts/createuser.pgsql script sets up an openidm database and user, with a default password of openidm. The script also grants the appropriate permissions.

   Edit this script if you want to change the password of the openidm user, for example:

   $ more /path/to/openidm/db/postgresql/scripts/createuser.pgsql
   create user openidm with password 'mypassword';
   create database openidm encoding 'utf8' owner openidm;
   grant all privileges on database openidm to openidm;

2. Edit the Postgres client authentication configuration file, pg_hba.conf. Add the following entries for the following users: postgres and openidm:

   local   all   openidm      trust
   local   all   postgres      trust

3. As the postgres user, execute the createuser.pgsql script as follows:

   $ psql -U postgres < /path/to/openidm/db/postgresql/scripts/createuser.pgsql
   CREATE ROLE
   CREATE DATABASE
   GRANT

4. Execute the openidm.pgsql script as the new openidm user that you created in the first step:

   $ psql -U openidm < /path/to/openidm/db/postgresql/scripts/openidm.pgsql
   
   CREATE SCHEMA
   CREATE TABLE
   CREATE TABLE
   CREATE TABLE
   CREATE INDEX
   CREATE INDEX
   ...
   START TRANSACTION
   INSERT 0 1
   INSERT 0 1
   COMMIT
   CREATE INDEX
   CREATE INDEX

   Your database has now been initialized.

5. Run the three scripts that set up the tables required by the Activiti workflow engine:

   $ psql -d openidm -U openidm < /path/to/openidm/db/postgresql/scripts/activiti.postgres.create.engine.sql
   $ psql -d openidm -U openidm < /path/to/openidm/db/postgresql/scripts/activiti.postgres.create.history.sql
   $ psql -d openidm -U openidm < /path/to/openidm/db/postgresql/scripts/activiti.postgres.create.identity.sql

6. If you are going to direct audit logs to this repository, run the script that sets up the audit tables:

   $ psql -d openidm -U openidm < /path/to/openidm/db/postgresql/scripts/audit.pgsql

7. Remove the default DS repository configuration file (repo.ds.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.ds.json

8. Copy the database connection configuration file for PostgreSQL (datasource.jdbc-default.json) and the database table file (repo.jdbc.json) to your project's configuration directory. For example:

   $ cd /path/to/openidm
   $ cp db/postgresql/conf/datasource.jdbc-default.json my-project/conf/
   $ cp db/postgresql/conf/repo.jdbc.json my-project/conf/

9. Update the connection configuration to reflect your PostgreSQL deployment. The default connection configuration in the datasource.jdbc-default.json file is as follows:

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

   If you changed the password in step 1 of this procedure, edit the datasource.jdbc-default.json file to set the value for the password field to whatever password you set for the openidm user.

   Specify the values for openidm.repo.host and openidm.repo.port in one of the following ways:

   • Set the values in your resolver/boot.properties file:

     openidm.repo.host = localhost
     openidm.repo.port = 5432

   • Set the properties in the OPENIDM_OPTS environment variable and export that variable before startup. You must include the JVM memory options when you set this variable. For example:

     $ export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=5432"
     $ cd /path/to/openidm
     $ ./startup.sh -p my-project
     Executing ./startup.sh...
     Using OPENIDM_HOME:   /path/to/openidm
     Using PROJECT_HOME:   /path/to/openidm
     Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=5432
     Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
     Using boot properties at /path/to/openidm/resolver/boot.properties
     -> OpenIDM version "6.0.0.7"
     OpenIDM ready

10. PostgreSQL is now set up for use as the internal repository.

    Start IDM with the configuration for your project. Monitor the console for the success of your setup. After startup, run a scr list command. In the output, you should see that repo.jdbc is active, whereas repo.ds is enabled but not active:

    $ cd /path/to/openidm
    $ ./startup.sh -p my-project
    Using OPENIDM_HOME:   /path/to/openidm
    Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
    Using LOGGING_CONFIG:
    -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
    Using boot properties at /path/to/openidm/resolver/boot.properties
    -> scr list
    BundleId Component Name Default State
        Component Id State      PIDs (Factory PID)
     [   5]   org.forgerock.openidm.config.enhanced.starter  enabled
        [   1] [active      ] org.forgerock.openidm.config.enhanced.starter
     [   5]   org.forgerock.openidm.config.manage  enabled
        [   0] [active      ] org.forgerock.openidm.config.manage
     [  10]   org.forgerock.openidm.datasource.jdbc  enabled
     [  10]   org.forgerock.openidm.repo.jdbc  enabled
        [  48] [active      ] org.forgerock.openidm.repo.jdbc
     [  11]   org.forgerock.openidm.repo.ds  enabled
    ...

11. Set up indexes to tune the PostgreSQL repository according to your specific deployment.

    Important

    No indexes are set by default. If you do not tune the repository correctly by creating the required indexes, the performance of your service can be severely impacted. For example, setting too many indexes can have an adverse effect on performance during managed object creation. Conversely, not indexing fields that are searched will severely impact search performance.

    IDM includes a /path/to/openidm/db/postgresql/scripts/default_schema_optimization.pgsql script that sets up a number of indexes. This script includes extensive comments on the indexes that are being created. Review the script before you run it to ensure that all the indexes are suitable for your deployment.

    When you have refined the script for your deployment, execute the script as a user with superuser privileges, so that the required extensions can be created. By default, this is the postgres user:

    $ psql -U postgres openidm < /path/to/openidm/db/postgresql/scripts/default_schema_optimization.pgsql
    CREATE INDEX
    CREATE INDEX
    CREATE INDEX
    CREATE INDEX
    CREATE INDEX
    CREATE INDEX

Before you start, make sure that the server is stopped.

$ cd /path/to/openidm/
$ ./shutdown.sh
OpenIDM is not running, not stopping.

Configure IDM to use the DB2 repository, as described in the following steps:

1. Create an OSGi bundle for the DB2 JDBC driver, as follows:

   1. Download the DB2 JDBC driver for your database version from the IBM download site and place it in the openidm/db/db2/scripts directory.

      Use either the db2jcc.jar or db2jcc4.jar, depending on your DB2 version. For more information, see the DB2 JDBC Driver Versions.

      $ ls /path/to/db/db2/scripts/
      db2jcc.jar  openidm.sql

   2. Create a bnd file and edit it to match the version information for your JDBC driver.

      You can use the sample bnd file located in openidm/db/mssql/scripts. Copy the bnd file to the same location as the JDBC driver.

      $ cd /path/to/openidm/db
      $ cp mssql/scripts/sqljdbc4.bnd db2/scripts/
      $ ls db2/scripts
      db2jcc.jar  openidm.sql  sqljdbc4.bnd

      The JDBC driver version information for your driver is located in the Specification-Version property in the MANIFEST file of the driver.

      $ cd /path/to/openidm/db/db2/scripts
      $ unzip -q -c db2jcc.jar META-INF/MANIFEST.MF
      Manifest-Version: 1.0
      Created-By: 1.4.2 (IBM Corporation)

      Edit the bnd file to match the JDBC driver version.

      $ more sqljdbc4.bnd
      ...
      version=1.0
      Export-Package: *;version=${version}
      Bundle-Name: IBM JDBC DB2 Driver
      Bundle-SymbolicName: com.ibm.db2.jcc.db2driver
      Bundle-Version: ${version}

   3. Download the bnd JAR file (bnd-2.4.0.jar) that enables you to create OSGi bundles. For more information about bnd, see http://bnd.bndtools.org/.

      Place the bnd JAR file in the same directory as the JDBC driver, and the bnd file.

      $ ls /path/to/openidm/db/db2/scripts
      bnd-2.4.0.jar  db2jcc.jar  openidm.sql  sqljdbc4.bnd

   4. Change to the directory in which the script files are located and run the following command to create the OSGi bundle:

      $ cd /path/to/openidm/db/db2/scripts

      $ java -jar bnd-2.4.0.jar wrap --properties sqljdbc4.bnd --output db2jcc-osgi.jar db2jcc.jar

      This command creates an OSGi bundle, as defined by the --output option: db2jcc-osgi.jar:

      $ ls
      bnd-2.4.0.jar  db2jcc.bar  db2jcc.jar  openidm.sql  sqljdbc4.bnd

   5. Move the OSGi bundle fle to the openidm/bundle directory:

      $ mv db2jcc-osgi.jar /path/to/openidm/bundle/

2. Remove the default DS repository configuration file (repo.ds.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.ds.json

3. Copy the database connection configuration file for DB2 (datasource.jdbc-default.json) and the database table configuration file (repo.jdbc.json) to your project's configuration directory. For example:

   $ cd /path/to/openidm/
   $ cp db/db2/conf/datasource.jdbc-default.json my-project/conf/
   $ cp db/db2/conf/repo.jdbc.json my-project/conf/

4. Update the connection configuration to reflect your DB2 deployment. The default connection configuration in the datasource.jdbc-default.json file is as follows:

   {
       "driverClass" : "com.ibm.db2.jcc.DB2Driver",
       "jdbcUrl" : "jdbc:db2://&{openidm.repo.host}:&{openidm.repo.port}/dopenidm:retrieveMessagesFromServerOnGetMessage=true;",
       "databaseName" : "sopenidm",
       "username" : "openidm",
       "password" : "openidm",
       "connectionTimeout" : 30000,
       "connectionPool" : {
           "type" : "hikari",
           "minimumIdle" : 20,
           "maximumPoolSize" : 50
       }
   }

   Specify the values for openidm.repo.host and openidm.repo.port in one of the following ways:

   • Set the values in resolver/boot.properties or your project's conf/system.properties file, for example:

     openidm.repo.host = localhost
     openidm.repo.port = 50000

   • Set the properties in the OPENIDM_OPTS environment variable and export that variable before startup. You must include the JVM memory options when you set this variable. For example:

     $ export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=50000"
     $ cd /path/to/openidm
     $ ./startup.sh -p my-project
     Executing ./startup.sh...
     Using OPENIDM_HOME:   /path/to/openidm
     Using PROJECT_HOME:   /path/to/openidm
     Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=50000
     Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
     Using boot properties at /path/to/openidm/resolver/boot.properties
     -> OpenIDM version "6.0.0.7"
     OpenIDM ready

5. Create a user database for IDM (dopenidm).

   $ db2 create database dopenidm

6. Import the IDM data definition language script into your DB2 instance.

   $ cd /path/to/openidm
   $ db2 -i -tf db/db2/scripts/openidm.sql

   The database schema is defined in the SOPENIDM database.

7. You can show the list of tables in the repository, using the db2 list command, as follows:

   $ db2 LIST TABLES for all
   
    Table/View                      Schema          Type  Creation time
   ------------------------------- --------------- ----- --------------------------
   CLUSTEROBJECTPROPERTIES         SOPENIDM        T     2015-10-01-11.58.05.968933
   CLUSTEROBJECTS                  SOPENIDM        T     2015-10-01-11.58.05.607075
   CONFIGOBJECTPROPERTIES          SOPENIDM        T     2015-10-01-11.58.01.039999
   CONFIGOBJECTS                   SOPENIDM        T     2015-10-01-11.58.00.570231
   GENERICOBJECTPROPERTIES         SOPENIDM        T     2015-10-01-11.57.59.583530
   GENERICOBJECTS                  SOPENIDM        T     2015-10-01-11.57.59.152221
   INTERNALUSER                    SOPENIDM        T     2015-10-01-11.58.04.060990
   LINKS                           SOPENIDM        T     2015-10-01-11.58.01.349194
   MANAGEDOBJECTPROPERTIES         SOPENIDM        T     2015-10-01-11.58.00.261556
   MANAGEDOBJECTS                  SOPENIDM        T     2015-10-01-11.57.59.890152
   ...

8. Connect to the openidm database, then run the three scripts that set up the tables required by the Activiti workflow engine:

   $ db2 connect to dopenidm
   $ db2 -i -tf /path/to/openidm/db/db2/scripts/activiti.db2.create.engine.sql
   $ db2 -i -tf /path/to/openidm/db/db2/scripts/activiti.db2.create.history.sql
   $ db2 -i -tf /path/to/openidm/db/db2/scripts/activiti.db2.create.identity.sql

9. If you plan to direct audit logs to this repository, run the script that sets up the audit tables:

   $ db2 -i -tf /path/to/openidm/db/db2/scripts/audit.sql

The following procedure depends on the IDM version that you are updating from:

1. If you are currently on IDM 6.0 - 6.0.0.4, download the pre-patch file from ForgeRock's BackStage site.

   • For IDM 6.0.0, 6.0.0.1, or 6.0.0.2, download IDM-6.0.0.5-pre-patch-from-6.0.0-6.0.0.2.zip.

   • For IDM 6.0.0.3 or 6.0.0.4, download IDM-6.0.0.5-pre-patch-from-6.0.0.3-6.0.0.4.zip.

2. Copy the pre-patch file to /path/to/openidm/bin/update.

3. Download the IDM-6.0.0.7.zip from ForgeRock's BackStage site.

4. Copy IDM-6.0.0.7.zip to /path/to/openidm/bin/update.

5. Back up your 6.0.0.x deployment. Save any customized *.json configuration files, located in your project's /conf directory. Save your custom directories.

6. If you have a read-only deployment, mount the directory in read-write mode before starting the update.

7. If you integrated IDM with AM, disable any authentication modules that are in use.

8. If you have a custom resolver/boot.properties file in your IDM 6.0.0.x deployment, you will need to copy the file to your 6.0.0.7 deployment.

   For example, if you have an IDM 6.0 deployment, extract IDM-6.0.0.7.zip to a temporary directory. Then, copy the custom IDM 6.0 resolver/boot.properties file to your 6.0.0.7 resolver directory.

   If you have not customized the default resolver/boot.properties file in your deployment, you can simply overwrite it with version 6.0.0.7 of this file.

9. Start IDM. IDM must be running when you launch an update.

   Note

   You must use the CLI to update your system. As of IDM 6.0, the facility to update servers through the Admin UI has been removed.

10. Disable and re-enable connections to AM.

1. Go to your IDM installation:

   $ cd /path/to/openidm

2. Run the cli.sh command to apply the pre-patch zip:

   $ ./cli.sh update \
     --acceptLicense \
     --user openidm-admin:openidm-admin \
     --url http://localhost:8080/openidm \
     --skipRepoUpdatePreview \
     IDM-6.0.0.5-pre-patch-from-6.0.0.3-6.0.0.4.zip

   Note

   If you are updating from IDM 6.0.0, 6.0.0.1, or 6.0.0.2, use IDM-6.0.0.5-pre-patch-from-6.0.0-6.0.0.2.zip.

   The update process continues and completes with "Scheduler has been resumed."

   Executing ./cli.sh...
   Starting shell in /openidm
   License was accepted via command line argument.
   Repository update preview was skipped.
   Pausing the Scheduler
   Scheduler has been paused.
   Waiting for running jobs to finish.
   All running jobs have finished.
   Entering into maintenance mode...
   Now in maintenance mode.
   Installing the update archive IDM-6.0.0.5-pre-patch-from-6.0.0.3-6.0.0.4.zip
   Update procedure is still processing...
   The update process is complete.
   Exiting maintenance mode...
   No longer in maintenance mode.
   Resuming the job scheduler.
   Scheduler has been resumed..

3. Restart IDM.

4. Run the cli.sh command to apply the IDM-6.0.0.7.zip:

   $ ./cli.sh update \
     --acceptLicense \
     --user openidm-admin:openidm-admin \
     --url http://localhost:8080/openidm \
     --skipRepoUpdatePreview \
     IDM-6.0.0.7.zip

   The update process continues and completes with "Scheduler has been resumed."

   Executing ./cli.sh...
   Starting shell in /openidm
   License was accepted via command line argument.
   Repository update preview was skipped.
   Pausing the Scheduler
   Scheduler has been paused.
   Waiting for running jobs to finish.
   All running jobs have finished.
   Entering into maintenance mode...
   Now in maintenance mode.
   Installing the update archive IDM-6.0.0.7.zip
   Update procedure is still processing...
   Update procedure is still processing...
   Update procedure is still processing...
   Update procedure is still processing...
   Update procedure is still processing...
   Update procedure is still processing...
   The update process is complete.
   Exiting maintenance mode...
   No longer in maintenance mode.
   Resuming the job scheduler.
   Scheduler has been resumed..

   Note

   You may see the following intermittent error during the update process, which you can ignore:

   Error encountered while checking status of install.  Retrying 8 more times

   The error occurs when attempting to get the update status but does not interrupt the process.

5. Shutdown IDM.

6. Manually remove the oldest version of bundle/openidm-repo-opendj-<version>, which was generated from the release prior to the 6.0.0.5 update.

   For example, bundle/openidm-repo-opendj-6.0.0.4.jar.old-1557935520313.

7. If you are updating from versions IDM 6.0.0 through IDM 6.0.0.3 to this release, you must clear the reconprogressstate data from your repository by running a Groovy script.

   Note

   This step is not necessary when updating from IDM 6.0.0.4 or 6.0.0.5.

   Run the following Groovy script to clear the reconprogressstate data in your repository:

   def result = openidm.query(
     "repo/reconprogressstate", [ "_queryFilter" : "true", "_fields" : "_id" ]).result;
   for ( item in result ) {
     openidm.delete("repo/reconprogressstate/" + item["_id"], null);
   }
   return result.size() + " reconprogressstate records deleted";

   This script will work regardless of the type of repository, and can be sent as a REST call. For example:

   curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
      "type":"groovy",
      "source":"def result = openidm.query(\"repo/reconprogressstate\", [ \"_queryFilter\" : \"true\", \"_fields\" : \"_id\" ]).result; for ( item in result ) { openidm.delete(\"repo/reconprogressstate/\" + item[\"_id\"], null); }; return result.size() + \" reconprogressstate records deleted\";"
    }' \
    "http://localhost:8080/openidm/script?_action=eval"
   "1 reconprogressstate records deleted"

8. Manually update the conf/ui-themeconfig.json. Change the Bootstrap version to css/bootstrap-3.4.1-custom.css from the previous 3.3.7 version.

   The update does not touch this file, to avoid overwriting possible customization of the UI theme.

9. Restart your server.

   Your update has successfully completed.

   Note

   There is a known issue that could arise when running your update. When running a pause scheduler job using a REST call (scheduler/job?_action=pauseJobs), the update can possibly end up in an infinite loop (see OPENIDM-11265: Unable to pause scheduler jobs with REST call).

   The workaround is to clear out the schedulerobjects and schedulerobjectproperties tables before the update and later recreate all scheduler jobs.

   Note

   During the upgrade to version 6.0.0.7, you may see an exception for registerFilter from org.forgerock.openidm.jetty.LargePayloadServletFilter in the IDM logs. You can ignore this message, as it is a harmless exception.