Child pages
  • OpenIDM v4 Patch Generation
Skip to end of metadata
Go to start of metadata

OpenIDM Patch Generation

Overview

OpenIDM, as of v4.0.0, has a facility to install patches and even full OpenIDM zip distributions.  To function in this context a patch must conform to a specific set of requirements:

  • Patches are zip files that contain a subset of the files found in an OpenIDM zip. They must contain a directory tree that mirrors a standard OpenIDM installation zip but need not contain empty directories. 
  • A patch must also contain a package.properties file that describes the content of the patch. 
  • There is no need for a patch to contain a .checksums.csv file as an OpenIDM zip contains.
  • For consistency in the UI patches should be named "patch.<subject>.zip" where subject describes the purpose of the patch with a Jira or ZenDesk ID.

A simple patch meant to update a single bundle, e.g. a fix for OPENIDM-1000 which requires an update to openidm-maintenance-4.0.0.zip, should be named patch.OPENIDM-1000.zip and look like the following when unpacked:

openidm/
package.properties
  bundle/
openidm-maintenance-4.0.0.zip
 

The package.properties files must contain the following:

  • product=
    • 'product' is the product delivered by the patch, e.g. OpenIDM
  • version=
    • 'version' is the version delivered by the patch, e.g. 4.0.0
  • upgradesProduct=
    • 'upgradesProduct' is the product to which this patch may be applied, e.g. OpenIDM
  • upgradesVersion=
    • 'upgradesVersion' is the version to which this patch may be applied, e.g. 4.0.0
  • description=
    • 'description' is a short description of what this patch is meant to do, e.g. Fixes: OPENIDM-1000
  • resource=
    • 'resource' is an URL pointing to an online resource applicable to this patch such as release notes
  • restartRequired=
    • 'restartRequired' is either true of false indicating whether IDM should restart itself after installing the patch

If a patch contains files in the conf/, bin/ or bundle/ directories then those files will always be written to the
IDM deployment. If doing so would overwrite a file the user has modified from original then their modified copy
will be backed up with a ".old-<timestamp>" extension.

If a file in the patch would overwrite a user-modified file found anywhere else in IDM then the user-modified copy
is left alone and the new copy is placed in the same directory with a ".old-<timestamp>" extension.

Note on configuration (.json) changes

Configuration changes cannot be made via updated json files.  Instead they must be made via .patch files named after the config they wish to patch and be placed in the same directory as the config file.  For example, to patch conf/policy.json you create a patch file named policy.json.patch and place it in the conf directory next to policy.json.  The patch file should conform to ForgeRock JsonPatch which includes the ability to deeply transform the config document using javascript.

Config patch files, when discovered by the update utility, will be passed to the ConfigObjectService's handlePatch() method which then updates the configuration in the repo and subsequently writes those changes to disk as the config json file.

 

Generating a Patch
 

  1. Build and test changes as normal in a branch of OpenIDM
    1. Copy the openidm ZIP file elsewhere if you wish to keep it
  2. Modify the assembly XML for openidm-zip found at
    1. /openidm/openidm-zip/src/main/assembly/zip.xml
    2. See below for an example of a modified zip.xml
  3. Modify the package.properties found at
    1. /openidm/openidm-zip/src/main/resources/package.properties
    2. See below for an example of a modified package.properties
  4. Rebuild OpenIDM
    1. Copy the new openidm ZIP file elsewhere
    2. Rename it to: patch.<subject>.zip

  5. Commit the changes if process requires it

You can test the patch by running an unmodified OpenIDM and applying the patch to it.

 

Example package.properties

An example package.properties file following the example above assuming OPENIDM-1000 required a change to openidm-maintenance:

product=OpenIDM
version=4.0.0
upgradesProduct=OpenIDM
upgradesVersion=4.0.0
description=Fixes: OPENIDM-1000
resource=http://openidm.forgerock.org/doc/bootstrap/release-notes/
restartRequired=true

 

Example zip.xml

An example zip.xml file, following the example above of distributing a patch containing the maintenance bundle:

<?xml version="1.0" encoding="UTF-8"?>
<!--
The contents of this file are subject to the terms of the Common Development and
Distribution License (the License). You may not use this file except in compliance with the
License.
You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
specific language governing permission and limitations under the License.
When distributing Covered Software, include this CDDL Header Notice in each file and include
the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
Header, with the fields enclosed by brackets [] replaced by your own identifying
information: "Portions Copyrighted [year] [name of copyright owner]".
Copyright (c) 2011-2014 ForgeRock AS. All rights reserved.
-->
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
<id>bin</id>
<baseDirectory>/</baseDirectory>
<formats>
<format>zip</format>
</formats>
<fileSets>
<fileSet>
<directory>${basedir}/src/main/resources</directory>
<outputDirectory>/openidm</outputDirectory>
<fileMode>444</fileMode>
<includes>
<include>**/package.properties</include>
</includes>
<filtered>true</filtered>
</fileSet>
</fileSets>
<dependencySets>
<dependencySet>
<useProjectArtifact>false</useProjectArtifact>
<outputDirectory>/openidm/bundle</outputDirectory>
<scope>runtime</scope>
<includes>
<include>org.forgerock.openidm:openidm-maintenance:*</include>
</includes>
</dependencySet>
</dependencySets>
</assembly>

 

 

  • No labels

1 Comment

  1. Unknown User (mike2)

    The update process reads a license.txt file in the openidm/legal-notices directory.

     

    IMO, this is a good subject for a KB article, to help support engineers create patches for their customers. cc @dom