PingAM

Create versioned nodes

When you want to make changes to an existing node, it’s best practice to create a new version of the node. This gives you greater control over how and when the changes are deployed to existing authentication flows. For example, you could test the changes on a subset of users first, before rolling them out more widely.

To ensure consistency, decide on a naming convention for versioned nodes before you start. For example, append Vn to node class names where n is the version.

For example, MyNodeV2 is version 2 of a node whose class name is MyNode.

To create a new versioned node:

  1. Create a Java class for your new versioned node that implements the Node interface. Find more information in Node class.

    Depending on the scale of changes, you could start with a copy of the existing class.

  2. Name the class according to your naming conventions.

  3. Add the VersionMetadata annotation to specify the name or class name of the original node, the version of the new node, and optionally, the upgrader class name.

  4. If you specify an upgrader class name, add the following:

    • The NodeVersionUpgrader.UpgraderMetadata annotation to specify the version of the new node and the name of the previous upgrader class.

      If an upgrader class name has been specified but the NodeVersionUpgrader.UpgraderMetadata annotation is missing, the new node won’t install.

    • The Upgrader class to define the upgrade logic to update the node’s configuration from one version to another.

  5. Add a Changelog to the node’s .properties file to detail the changes introduced in the new version. This step is optional, but it’s helpful to keep a record of changes for a node.