How to upgrade AM SMS configuration after a Service Schema change

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.

Schema Change Detected

The role of this notification on your PR is to remind you that you are making a schema change and to direct you to this page. There is also a corresponding report which is generated which provides visual feedback on the change that has been detected. The notification is present on any PR that makes a schema change and is intended to act as a signpost for the developer rather than as a flag that needs to be cleared by action. In the future we might be able to implement detection that the appropriate configuration upgrades have been implemented and then clear the notification, however that is not possible with the present implementation.

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 which extend the org.forgerock.am.config.ServiceComponentConfig interface.

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

All three upgrade approaches are able to handle the addition and deletion of new attributes and services automatically. Understanding the way this works will help explain how the upgrade mechanisms work in general.

AM Upgrade (LDAP)
In the case of the LDAP upgrade, the UpgradeServiceSchemaStep will determine whether there are additions or deletions automatically during update. These are processed during the online upgrade and so the server has both the old and new schema representations in memory to perform the comparison.

Amster
With Amster this process changes. The Amster deployment process requires that configuration from a previous version is exported to Amster export files, upgraded offline, and then imported into a clean installation of the new server. This means that any new attributes or services will be automatically present in the new server as part of its clean installation.

File-Based Configuration
The FBC storage mechanism is only intended for use with Docker images in an automated cloud deployment. The base AM Docker image uses a base configuration which represents the default AM configuration. Like the other approaches this means attribute and service addition/deletion is handled automatically by the base configuration. The customer is expected to only maintain their custom configuration overlays which are to be layered ontop of the base configuration.

The following table summarises whether an upgrade rule is required in the above cases:

Checklist of required actions

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

• Create an upgrade step for: AM Upgrader
• Create upgrade rules for: Amster
• Create upgrade rules for: File Based Config

Directly Related

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

• openam-config-upgrader
• Questions with the tag upgrade

Areas of Upgrade Contention

Scripting Whitelist

The scripting whitelist schema file is a particular hotspot for configuration changes. This class also has a direct effect on customer scripts that might be depending on the whitelisted classes.

When making changes to this schema file, we need to be aware that we should not remove classes from the whitelists. Once a class has been whitelisted and that code has been released either on-prem or to the ID Cloud, it should be considered in-use by customers. There are exceptions to this idea however.

Firstly, if the classes were added but have not yet been released to ID Cloud customers, then we should be safe to remove the upgrade rule that added the classes. This is because customer deployments would not have been upgraded with the changes and as such they are safe to remove.

The second would be when we are deleting deprecated code. In this case we would want to make a release notes entry to inform customers that the class has been removed and provide recommendation on the alternatives they can use to help with their migration away from the deleted code.

Child Pages

• Create an upgrade step for: AM Upgrader
• Create upgrade rules for: Amster
• Create upgrade rules for: File Based Config
• How the Amster upgrade process works
• How the FBC upgrade process works
• openam-config-upgrader