...
Since each client can encounter one of these old objects at any time, client developers have be 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.
...
| Return code | Name | Condition |
|---|---|---|
| 201 | Created | The entity type convertion was successful |
| 412 | Precondition Failed | Returned if the passed entity.etag does not match the etag of the entity (ConflictingUpdateException) |
| 400 | Bad Request | The entity cannot be converted for any reason. The message should explain why the type change failed. |
Table 2.
The following table lists how each old type will be converted into a new type.
...
| 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
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.