Registry v5.0.0 is a significant rewrite due to the retirement of the older version of the underlying framework (CakePHP v2). The project leveraged this opportunity to clean up a number of long standing issues, some dating back to v0.1. As a result, upgrading may be fairly disruptive.
Approaches to Upgrading
Existing Registry installations cannot be upgraded in place. Data must be migrated to a new v5.0.0 based installation. As such, the recommended approach is to first stand up a new Registry v5 test instance, and then perform a test migration.
Performing Data Migration
Registry v5 uses a process called Transmogrification to migrate data from a v4 instance. More information is available here.
What Changed
Database Tables
The Registry database should ordinarily be treated as a "black box", and code or interfaces should not be designed around direct table access. Registry v5.0.0 changes the name of all tables (mostly to drop the cm_
prefix) and restructures various tables. For full details, review the documentation for tables of interest.
Enrollment Flow Identifier Collection
As part of the transition to Registry v5.0.0, support for legacy configurations for collecting external identifiers is being removed. See Migrating to EnvSource to for more information.
Extended Attributes No Longer Supported
Extended Attributes were deprecated in Registry v3.3.0, and are removed entirely as of Registry v5.0.0. Transmogrification will convert Extended Attributes to Ad Hoc Attributes using the Extended Attribute name
field as the Ad Hoc Attribute tag
. The Extended Attribute display_name
field is discarded.
External Identities (formerly Organizational Identities) Require Affiliations
In Registry v4.x and earlier, affiliation
was not a required field for OrgIdentities. However, in Registry v5, affiliation
for ExternalIdentityRole is required. Prior to Trnsmogrification, affiliations should be assigned to any OrgIdentities that don't have them, or the OrgIdentity will not transmogrify.
Login Identifiers Move to Person
Login to Registry v4.x and earlier was controlled by Identifiers attached to the Org Identity associated with the CO Person. In Registry v5.0.0 and later, login is controlled by Identifiers directly attached to the Person. Transmogrification can migrate existing data, but ongoing enrollment and data loading processes (including via External Identity Sources and the API) may need to be reviewed.
Organizational Identity Pooling No Longer Supported
Organizational Identity Pooling was deprecated in Registry v3.1.0, and since then certain functions were not available to pooled deployments. The capability is entirely removed as of Registry v5.0.0. Deployments still using Org Identity Pooling should "unpool" their identities prior to Transmogrification. There is no tooling available for unpooling at the moment. Deployments using a pooled configuration should contact the developers for assistance.
Parallel Job Runners
Registry Job Command now supports running in parallel, and from multiple nodes. The command syntax has changed slightly, and cron jobs may need to be updated.
REST API
Registry v5 introduces API v2. Although similar, it is not the same as the previous v1, and so existing code may not work without modification. Of note:
- Responses now include metadata.
- Support for pagination has been added.
- Multiple records can be provided in a single add request.
- XML payloads are no longer supported.
- The VOOT API is no longer supported.
- "Translated" enumerations are no longer supported. Where v1 used (eg) the string
Active
, v2 simply usesA
.
REST API Users
API Users created in Registry v5 use API Keys that are randomly generated, and hashed using a different method than earlier versions. API Keys (formerly called "passwords") will continue to work, and they will be rehashed automatically when the API User authenticates. However, it may be desirable to generate new API Keys for existing API Users after upgrading, since the newer hashing mechanism is stronger.
URL Formats
CakePHP has changed its URL format, so pretty much all bookmarks will need to be changed. In general, controller names now use hyphens instead of underscores, and named parameters now use standard query args. So, for example
https://my.server/registry/co_enrollment_flows/start/coef:10
becomes
https://my.server/registry/co-enrollment-flows/start?coef=10
It's possible to set up Apache rewrite rules to accept the old format and translate it to the new format, however Registry v5 does not include this sort of configuration out of the box.
Plugins
XXX