Skip to main content

Backward compatibility

In a VIKTOR application, a lot of valuable data and knowledge is gathered over time. It is very important that, even after numerous updated to the application logic, data that is saved years ago can still successfully be processed by the application logic today, and that it results in the same output. This ensurance is called backward compatibility.

Backward incompatible changes​

The five most common cases for applications to become backward incompatible are:

  • An entity type is removed or the entity type has been renamed
  • An entity type is moved to a different parent entity type (i.e. the hierarchy is changed)
  • A parameter in the parametrization has been moved to a different path (e.g. tab1.parameter -> tab2.parameter)
  • A parameter in the parametrization has been renamed (e.g. tab.section.parameter1 -> tab.section.parameter2)
  • A parameter is used in a different way (e.g. units are now in "m" instead of "mm")

Testing backward compatibility​

The following manual steps can be performed to test compatibility of your code changes:

  1. Install and start the app on the current deployed version
  2. Start the app, create a few entities and make sure to save the input data
  3. Stop the app and switch to the to-be-deployed version
  4. Start the app (do not clear the database!)
  5. Check if there are no unexpected errors or incorrect calculation results

Best practices to avoid compatibility issues​

Most of the backward compatibility issues can be avoided with some careful planning. Always keep backward compatibility in mind when setting up a new architecture or updating your current architecture:

  • When adding a new entity type, take some extra time to think about a proper name
  • When adding a new parameter to the Parametrization, take some extra time to think about a proper name
  • When defining a unit for a parameter, try to be consistent with the rest of the parameters in the app