As you know (hopefully), Sitecore XC stores all its entities as Json-serialized strings in the database. This makes it really flexible, as any components and policies you add to an entity are just serialized and stored. And if you need to change the entity, you deserialize it and the entity is again available to you to work with.
That is until you introduce something breaking. For instance, you decide to change the name of a component. Now, any serialized instance using the old name, cannot be deserialized. Now you have a problem, because how do you fix this?
IEntityMigrationPipeline to the rescue!
Fortunately, there is a solution. The
FindEntityPipeline is responsible for retrieving an entity from the database. Within that pipeline, the
DeserializeEntityBlock does the deserialization of the entity. If, during deserialization, a
JsonSerializationException is thrown, the
IEntityMigrationPipeline is run. It takes a
FindEntityArgument as its input and returns the translated entity (if possible) as its output. This is what it looks like in my version of the Commerce Engine:
IEntityMigrationPipeline starts with the
FindEntityJsonBlock. This block retrieves the entity from the database and puts the Json as a string in the
SerializedEntity property of the
FindEntityArgument. Any block after the
FindEntityJsonBlock can be used to "fix" the Json so it can be deserialized and returned as the correct entity.
If you need an example on how to do this, the Commerce SDK contains a project called
Plugin.Sample.Upgrade which contains
PatchEnvironmentJsonBlock. This block patches the environment Json so that the type
Sitecore.Commerce.Plugin.Customers.Cs.ProfilesSqlPolicy is changed to