PingAM

Upgrader class

The upgrader class defines the upgrade logic to update the node’s configuration from one version to the next.

The upgrader class must implement the NodeVersionUpgrader interface.

The upgrader class provides the upgrade method, which takes the configuration to upgrade and returns the updated configuration as JSON.

For example, the following is an upgrader class for a Custom node called CustomAuthNodeV2Upgrader:

public static class CustomAuthNodeV2Upgrader implements NodeVersionUpgrader {
  @Override
  public JsonValue upgrade(JsonValue config) throws NodeUpgradeException {
    if (!config.isDefined("secretValue") || !config.isDefined("secretHeader")) {
      throw new InvalidUpgradeConfigException();
    }
    config.remove("secretValue");
    config.put("secretLabelIdentifier", "");
    return config;
  }
}

This class removes the secretValue attribute from the configuration and replaces it with the secretLabelIdentifier attribute. If configuration values are missing, the upgrader throws an exception.

Preview configuration updates

To verify the configuration will update as expected, send a POST request to the realm-config/authentication/authenticationtrees/nodes/node-name/n.0?_action=getUpgradedConfig&targetVersion=n endpoint with the current node configuration in the request body. The targetVersion must be greater than the current version.

This request returns a preview of the updated configuration but doesn’t change the node configuration.

Example

To preview the updated configuration for version 1 of the Custom node going to version 2 (using the example CustomAuthNodeV2Upgrader class), send the following POST request:

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5wM…​TU3OQ*" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=2.1,resource=3.0" \
--data '{
   "secretHeader":"X-Secret-Header",
   "secretValue":"test"
}' \
"https://am.example.com:8443/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/nodes/CustomAuthNode/1.0?_action=getUpgradedConfig&targetVersion=2"
{
  "secretHeader":"X-Secret-Header",
  "secretLabelIdentifier":""
}