Skip to end of metadata
Go to start of metadata

This article will describe the steps that you need to take when making a change to the service schema and how to upgrade the SMS Configuration. As part of this guide we will explain which upgrade rules need to be created and how to write them.

Note: This is a working document which will continue to evolve as as fill in more detail. If you have comments or suggestions, please feel free to make them.

Kinds of schema changes

Currently there are two ways to change the service schema in AM:

  1. In the xml schema files that use the sms.dtd
  2. Through annotations on POJO's in the AM codebase

When a change is made to the schema of AM, there needs to be a corresponding change to AM's configuration. New installations of AM will will produce the latest configuration, however existing installations of AM will have configuration that is out of date. The role of an upgrade rule in this case is to upgrade the existing configuration so that it matches the latest schema of AM.

Currently there are 3 ways a customer might upgrade AM's configuration depending on the deployment model they are using:

  1. LDAP SMS: These customers have a deployment based on storing their configuration in an LDAP database. They will upgrade their configuration using the AM upgrader. Developers creating these rules will implement org.forgerock.openam.upgrade.steps.UpgradeStep
  2. Amster based Deployments: These customers have their configuration as exported Amster files. These configuration files will need to be upgraded using the openam-config-upgrader. Developers implementing these rules will need to write new Amster rules to perform this upgrade.

  3. File-based Configuration Deployments: Starting with AM 7.0.0, customers will be able to store their configuration in file-based configuration files on disk. Similar to Amster files in some ways, these new files will also be upgraded using the openam-config-upgrader.

When upgrade rules need writing

For both Amster and FBC, upgrade rules only need to be written for changes to the existing configuration files i.e. not when additions are made. This is because for both Amster (via a new AM install) and FBC (via a set of base configuration files shipped it the AM docker image) any new configuration files will automatically be included.

To summarise when changes are needed:

Change OperationAmsterFBC

Checklist of required actions

As part of a schema change the following tasks need to be completed

Directly Related

The openam-config-upgrader is released with AM and is the tool for upgrading both Amster-export and FBC AM configuration.

Child Pages


  1. Beware

    AME-19231 - Getting issue details... STATUS

  2. A very useful talk by Peter Major covering upgrade.  (Link to recording can be found on the title page.)

  3. If the upgrade rules check will fail for the duration of the PR unless any schema change is removed from the PR

    This tool is somewhat a blunt instrument but does serve the purpose to inform the developer that they have changed the schema and may need to take steps for upgrade e.g. write upgrade rules for file based configuration.

    Currently, the upgrade-rules-check will fail for any schema change and will not go green (unless that schema change is removed from the PR).  Note, the stage is not mandatory.

    Here is an example of the test output from Jenkins, which is saying that the hash on the original schema is different from the changes in this PR

    Jenkins output - upgrade rules check detects schema change
    [36mmaven_1  |[0m ++ cat service-schema-branch_point_commit.hash
    [36mmaven_1  |[0m + echo '  service schema at branch point # DO NOT EDIT THIS FILE BY HAND. Run the maven command to generate it.
    [36mmaven_1  |[0m 7a30070f177cc5a343444c68d35593c0b7dfa294ddd331693da07db66f9a7a69'
    [36mmaven_1  |[0m   service schema at branch point # DO NOT EDIT THIS FILE BY HAND. Run the maven command to generate it.
    [36mmaven_1  |[0m 7a30070f177cc5a343444c68d35593c0b7dfa294ddd331693da07db66f9a7a69
    [36mmaven_1  |[0m ++ cat service-schema-branch_head_commit.hash
    [36mmaven_1  |[0m + echo '  service schema at branch head # DO NOT EDIT THIS FILE BY HAND. Run the maven command to generate it.
    [36mmaven_1  |[0m fc6a410aec90d3f79b1bb2cd7ff0db3c765a3b7408b8fb0a32c8c667cf9ca8fa'
    [36mmaven_1  |[0m + diff --brief service-schema-branch_point_commit.hash service-schema-branch_head_commit.hash
    [36mmaven_1  |[0m   service schema at branch head # DO NOT EDIT THIS FILE BY HAND. Run the maven command to generate it.
    [36mmaven_1  |[0m fc6a410aec90d3f79b1bb2cd7ff0db3c765a3b7408b8fb0a32c8c667cf9ca8fa
    [36mmaven_1  |[0m Files service-schema-branch_point_commit.hash and service-schema-branch_head_commit.hash differ
    [36mmaven_1  |[0m + exit 2
    [36mpr-12479-5-6-upgrade-rules-check-1600911120207-maven_maven_1 exited with code 2

    The test failure results in the message in the PR pointing to this wiki page