Assessment of Version Changes
When moving a new project version from one execution mode to another, unfinished process requests and web interface instances of a predecessor project version running in the target mode need to be considered. The execution of these instances can be continued with their current project version or with the new project version being pushed.
The decision depends on the changes made for the new project version compared to the current one:
- If only minor changes were made, existing instances can be migrated to continue their execution with the new project version. Alternatively, they can, of course, be finished with their current project version.
- If any major changes were made, it is essential to continue the execution with the current project version. A migration may lead to unintended results or break the application, for example, because the execution path of process requests becomes incoherent or newly defined variables are not available.
The tables in the following sections provide an overview of which changes in project versions are considered major and minor, as well as additional issues and warnings to consider.
Web Interfaces
Minor Changes | Major Changes |
---|---|
Renaming a label | Adding a variable |
Changing a CSS | Changing a variable name |
Changing a widget's position | Changing a script: adding/listening to a new variable |
Adding a screen for a new validation step in the process |
Processes
Minor Changes | Major Changes |
---|---|
Renaming an activity label | Adding/deleting an activity |
Renaming a row or gateway label | Changing the type of an activity |
Adding a comment | Adding/deleting branches on a gateway |
Changing a FreeMarker script without using new variables | |
Adding a measure (always manage default values using ?default("mydefaultvalue") ) |
|
Changing a measure formula not used as a filter |
**Other Issues / Warnings **
Measures are not versioned. Never delete a measure, because this will destroy reports using it (columns and filters).
Providers and Connectors
The best practice is to have separate projects for providers and connectors with a version that keeps all resources updated.
Never modify a connector as this will have an immediate effect in all execution modes, including Live. If changes are required, a new connector should be used instead.
The only situation in which it is acceptable to change a provider is when the update of obsolete credentials is required.
Custom Lists
Minor Changes |
---|
Adding a label/value pair |
Changing a label |
**Other Issues / Warnings **
Never change a value or delete an item because information in existing processes will be lost.
Collections
Minor Changes | Major Changes |
---|---|
Adding items with new keys, e.g., adding a new field "phone":xxx to {"firstname":xxx,"lastname":xxx,"address":xxx} |
Changing/deleting a key. Never do this because it is similar to changing a column name in a database. Since keys are used in patterns and to parse results, this may lead to many errors in JavaScript and Freemarker scripts. |
**Other Issues / Warnings **
The best practice is to have homogeneous objects in a collection. When adding a new field in new items, existing objects should be updated to pass a default value for the new field. For example, when adding a field for a phone number, set "phone":""
for existing items.
Never change the name of a collection, because it is its unique identifier. Changing the name will break links with other resources, and FreeMarker functions will not work anymore.
Before deleting a collection, make sure that it is not used anywhere. When a collection is deleted, it is unrecoverable.
Web Interface and Process Reports
Minor Changes | Major Changes |
---|---|
Changing/deleting a filter on a measure, screen, or status | Deleting a column As the JavaScript filter methods use measure IDs, removing a column makes it impossible to filter on the corresponding measure using JavaScript. |
**Other Issues / Warnings **
When adding a column relying on a newly created measure, make sure to set a default value to handle existing instances (?default("mydefaultvalue")
) .
Projects
Minor Changes |
---|
Renaming the title |
**Other Issues / Warnings **
Never detach a resource that is used in Live from a project. If this happens by mistake, the resource should be reattached to the project as soon as possible.
Please give details of the problem