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.