General considerations

For Docker installations, the upgrade process involves downloading and deploying the latest containers.

For manual installations, the upgrade process involves downloading and extracting a new version of the PingDataGovernance Server .zip file on the server and running the update utility with the --serverRoot or -R option value from the new root server pointing to the installation.

Consider the following when upgrading:
  • The update affects only the server being upgraded. The process does not alter the configuration of other servers, so you must update those servers separately.
  • The update tool verifies that the installed version of Java meets the new server requirements. To simplify the process, install the version of Java that is supported by the new server before running the tool.
  • Upgrades for PingDataGovernance Server are only supported from versions or later. If upgrading from a version of PingDataGovernance prior to, configuration loss will occur. The update tool has a warning message about this.
Tip: For additional considerations, see Planning your upgrade.
Note: For information about important fixes made over several releases, see Critical fixes.

Considerations when upgrading to

Keep in mind the following important considerations for upgrading to this version of PingDataGovernance Server.

  • If you are upgrading to PingDataGovernance, you must also upgrade to Policy Administration GUI
  • Changes to SpEL expressions using collection projection might cause policy errors with the following form.

    EL1004E: Method call: Method <Symphonic Value method>() cannot be found on type <native Java type>

    If your policies rely on SpEL collection projection and methods like intValue(), stringValue(), jsonRepresentation(), or pojoRepresentation(), you must update these expressions. It is recommended that you update the policies to use collection transforms instead of SpEL collection projection. For information about collection transforms, see the PingDataGovernance Policy Administration Guide.

  • This upgrade moves to Jetty 9.4. As a result, the HTTPS connection handler will no longer support TLS_RSA ciphers by default. If you use any legacy HTTPS clients that still require TLS_RSA ciphers, modify the ssl-cipher-suite property of the HTTPS Connection Handler to include them.
Gateway API Endpoint and Sideband API Endpoint configurations
  • PingDataGovernance now strictly validates path parameters used in Gateway API Endpoint and Sideband API Endpoint configurations. The inbound-base-path value (for Gateway API Endpoints) and the base-path value (for Sideband API Endpoints) no longer allow duplicate path parameters. For example, "/Users/{userId}/Manager/{userId}" defines the "userId" path parameter twice and is invalid. In addition, other configuration properties cannot refer to a path parameter that is not defined by inbound-base-path or base-path.

    Previously, the server would allow such invalid configuration changes to be saved, but now the server rejects them. Upgrades or server profile deployments including invalid configuration of this kind will now fail. If this happens, correct the invalid configuration values.

Considerations when upgrading to

  • PingDataGovernance uses a new policy request format that requires changes to the Trust Framework.

    If you are using policies intended for a previous release, you can continue to use your existing policies by setting the trust-framework-version property of the Policy Decision Service to v1. If you upgrade your server using the update tool, this property is set for you automatically.

    The v1 format is deprecated, however, and you are strongly encouraged to update your Trust Framework as soon as possible. To do this, load your existing policies in the Policy Administration GUI and apply the Trust Framework changes by going to Branch Manager > Merge Snapshot and selecting the resource/policies/upgrade-snapshots/ file included with the server. Then, configure PingDataGovernance Server to issue policy requests using the new Trust Framework by setting the trust-framework-version property of the Policy Decision Service to v2.

  • If you are upgrading to PingDataGovernance, an updated version of the Policy Administration GUI is required.
  • The PingDataGovernance Policy Administration GUI no longer uses the UNIX environment variable PING_HOSTNAME. Instead, server administrators should use PING_EXTERNAL_BASE_URL to specify both the domain and the port. For more information, see the PingDataGovernance Server Administration Guide.
Policy processing and advice
  • The Allow Attributes advice and the Prohibit Attributes advice have been removed and can no longer be used. Requests involving policies that refer to these advice types will fail.
  • The HttpRequest.Headers policy request attribute is not available starting with Trust Framework version v2. It has been replaced by the HttpRequest.RequestHeaders and HttpRequest.ResponseHeaders policy request attributes. Update existing policies or Trust Framework entities that refer to HttpRequest.Headers to refer to HttpRequest.RequestHeaders.
  • SCIM 2 requests now include the resource type in the service value during policy processing. For example, for a SCIM 2 request that affects the "Users" resource type, the service value will now be "SCIM2.Users" instead of "SCIM2". Existing policy rules or targets that rely on an exact equality match for "SCIM2" must be updated. For example, a condition of "Service Equals SCIM2" would need to be updated to "Service Matches SCIM2".
  • For security, by default, the policy engine's SpEL processor now invokes Java classes only in the allow-list presented in the PingDataGovernance Server Administration Guide. To use other classes, add a key to the core section of the Policy Administration GUI's configuration called AttributeProcessing.SpEL.AllowedClasses with a list of the classes to include. If you are using embedded PDP mode, add a policy configuration key of the same name to the PingDataGovernance Server configuration.
  • The XACML-JSON PDP API now requires a different request format. With this new format, you can make multiple decisions using a single HTTP request. In addition, the response format is now compliant with the XACML-JSON specification. The 8.0 PDP API request format is no longer supported. For more information, see the PingDataGovernance Server Administration Guide.
Peer setup and clustered configuration
  • Peer setup and clustered configuration are deprecated and will be removed in PingDataGovernance 9.0. We encourage deployers to manage server configuration using server profiles, which support deployment best practices such as automation and Infrastructure-as-Code (IaC). For more information about server profiles, see the PingDataGovernance Server Administration Guide.
  • If you have upgraded a server that is in a cluster (that is, has a cluster name set in the Server Instance configuration object) to version 8.1, you will not be able to make cluster configuration changes until all servers with the same cluster name have been upgraded to version 8.1. If needed, you could create temporary clusters based on server versions and modify each server's cluster name appropriately to minimize the impact while you are upgrading.