Currently, there are eighteen entity types supported in Synapse but most of those types are old and have been unofficially deprecated for a few years now. We have not provided the means to convert these old entities to the new types so there are many of these old object in Synapse (see PLFM-1879).
Since each client can encounter one of these old objects at any time, client developers have been forced to support both the 'old' way and the 'new' way of working with entities for years now. This adds complexity and increases the support cost for each client. This document outlines a plan for migrating all old types into the types we currently support in Synapse.
...
In the past we support many types of entity containers. Each container can have one more child entity. Table 1 shows which entity types are allowed to be containers of other entities. Our users were either confused by all of these container types or wanted a new type for their special cases. We decided that the only containers we want to support all were Folders and Projects.
Locationable & Containers
...
In order to fully depreciated the unsupported types, we need to convert each old type objects into an object of the supported types (without changing the entity ID). The plan is to add a new services that will convert an old entity to a new type. This service make all changes to an old Entity in a single transaction. This means an Entity type change will either succeed (making it permanent if done on production), or the transaction will be rolled-back leaving the entity exactly as it was before the call. Many conversions will be simple. For example, it will be simple to convert a a data object with a single file. Conversion will not be simple for all cases where there is not a one-to-one relationship between the old and new.
...
| Original Entity | Converted To | Details |
|---|---|---|
| Non-container Locationable with a single LocationData of type awss3 | FileEntity | An S3FileHandle will be created for the location. The type will be changed to a FileEntity pointing to the new FileHandle |
| Non-container Locationable with a single LocationData of type external | FileEntity | An ExternalFileHandle will be created for the location. The type will be change to a FileEntity pointing to the new FilewHandle. |
| Non-container Locationable with a single LocationData of type awsebs, sage, github | Unsupported (400) | There is no way to represent these types with FileHandles. The caller will need to convert the type to either awss3 or external and then try again. |
| Non-container Locationable with more than one LocationData of any type | Unsupported (400) | There is now way to represent multiple location with a single file. the caller will need to pick a single location to keep and remove the rest and then try again. |
| Non-container Locationable that has one or more Link children | Unsupported (400) | File cannot have children. The caller must move or delete the Links and try again. |
| Container non-locationable | Folder | The container will simply be converted to folder. |
| Container locationable with n number of LocationData of type awss3 or external | Folder + n child FileEntity | The original entity will be converted to a folder, and a child FileEntity will be added for each valid LocationData. |
| Container locationable with n number of LocationData of type awsebs, sage, github | Unsupported (400) | There is no way to represent these types with FileHandles. The caller will need to convert the type to either awss3 or external and then try again. |
Table 3
Versionable
All locationable objects are also versionable. This means there can be multiple version of the same file(s). When an old entity with multiple versions is changed to a new type, each version will be converted the same way as the current version. If any version of an entity cannot be changed then the change will fail (leaving the entity in its original state). The failure report will indicate exactly what went wrong. Since versions of an entity are not editable, the only way to "fix" an old entity with in incompatible version will be to delete the incompatible version. Once all incompatible version are delete, another attempt can be made to convert the type.
Migration plan
- Once the new entity conversion service is in place, we will setup a script to to call it for every old entity on staging. The script will record all entities that file to convert for any reason. The normal migration process will "undo" all type changes on staging.
- We will need to work with the original entity owners to find fixes for all entities that cannot be changed. We will also need the original owners to review the type changes on staging and confirm the migration went as expected.
- For all successful type conversions on staging we can repeat the conversion on production (making the type change permanent).
- Repeat steps 1-3 until all old types are converted.
...