Page History
When a Case-Type is created, it is often not completely finished. One of the strengths if DCM would be the ability to adjust the Case when necessary, since the environment might also be changing. Doing so, you'll have to take some things into account. Some things being highly flexible to change, and some are harder. This guide explains the considerations when changing models on live cases.
Guide Contents
| Table of Contents | ||
|---|---|---|
|
Before starting your change
There are a few things to consider before you start changing your Blueriq model.
What is the nature of the change?
What is the type of change that needs performing? There are two different types to consider:
...
When the second change type is in order, one case-type will remain as maintainable object, but you'll have to consider what to migrate to the newly changed model. The remainder of this article is aimed at the second type, where migrations might be needed
Do I have cases in production?
When I possibly have cases in production, I might have to actively migrate these cases to the new situation. It is important to know what the change is, and what the consequences are for the production cases. For example, when all cases in production passed a certain stage, you might not need to actively migrate all cases to the new situation where something is changed in the early stage. On the other hand, changing logic might also have an effect that results that were positive before, become false in the future. Please take this into account (for example, the application has been deemed "complete", is not anymore since you added an extra requirement to this derivation). You must be aware whether you want the consequences of your change to any case in progress.
When there is no case yet in production, then the strategy of clearing your database and move on to your new model might fit best.
Performing the change
What needs migrating highly depends on what the change is. Keep in mind there are different places in the Case-Engine where state is stored. All with different characteristics.
The Process module has been changed
The process is persisted in the database. Any inconsistency in the database might lead to the current cases to not being able to continue anymore. The two types of data stored in the process database is the process profile and the tasks.
Process profile
The process profile holds all user-set attributes which have been mapped to the process engine. Either by an incoming message event or a data mapping after a task execution. Adding new attributes is possible, but renaming/removing attributes might be difficult. Currently there is no way to clear attributes/entities from the process profile. So when you want to delete an attribute, you have to make sure it is not mapped anymore, and wait until all cases containing this attribute have finished.
| Info |
|---|
The user-set attributes of the process profile are stored in the database. All stored attributes must always be available in the process module in the Blueriq model. When something is missing, the process-engine cannot load the case anymore, and assumes something is wrong and throws an error. |
Since the profile is only ever updated when an action has taken place, it might be necessary to perform an active migration of all cases when something is changed in this module.
Because profile management is very limited in the process module, I would advice to only use simple model constructions, like singletons with attributes. Instances and relations are harder to maintain. User-set values are best to debug, since you can see the actual value in the database (for example by using the DCM-Maintenance-APP).
Process definition
The process definition (flows/tasks canvas) is also stored in the database in some way. All (sub) processes which are active, cancelled or completed are stored, together with all elements in the process (sub)flow. The process engine reads these from the database to determine what to do with them. Especially the open and started nodes are important to keep in mind when determining what to migrate.
Check the example given above. The DCM-Maintenance-APP shows the state in the database, where "Beoordelen" is open (so active), it is waiting on a condition node "condition" with ID 88, corresponding with the milestone in the flow. The task "Toevoegen Bewijsstukken" has already been completed once, but is open to being picked up again (ID 89 is completed and ID 93 is open again).
The process engine checks for each node with the status "open" in the database, what to do next during a process evaluation. This means that each node should exist in the process definition (model) so it can determine what to do. The process engine either uses a "persistency-id" of the given element, or the "name" within the process (sub)flow. When there is no match, it crashes.
| Info |
|---|
All process elements with the status "open" or "started" in the database should be present in the (sub) process in the model definition. Make sure it does, otherwise the process cannot continue. |
This characteristic can make process migrations quite difficult. Adding items are not, but deleting them is not always possible. When an item needs to be deleted in the process, make sure all cases contain no node with status "open" or "started" anymore. One way of doing this, is to migrate in two steps:
- set the precondition of the element-to-delete to FALSE, so during the first migration step, all instances of this element are cancelled
- check there is no case left in production relying on this element, then delete the item and migrate again.
To keep the process as flexible as possible, please make sure the actions to perform are all ad-hoc. Changing processes when a sequence of tasks is placed on a process line, may be far more complex to migrate, since you have to determine what to do with all cases in all states somewhere on this line.
| Info |
|---|
The process profile and process state is only changed after some action has been performed. So after a model change, changes are only seen after a task has been executed. Note that throwing a message event will not perform a data-mapping, so this will not update the mapped values from the case dossier. |
The dossier has been changed
The dossier is stored in aggregate format, meaning the data can only be interpreted by loading the data (user-set attributes from the database) together with a consistent model. All information will be derived again when needed in the rule-engine. When you want to change the model, it is likely you'll want to change the data that goes with the change.
Make sure the data from the database can always be loaded into the profile. Attributes that can not be loaded are ignored, with the risk of data loss. Simply renaming an attribute means that any existing data in the database might be lost, since the attribute is not longer known in the model. Make sure to deal with this possible impact, possibly by actively migrating your data.
For example, when an attribute has been renamed. Any cases where the original value was stored need migration. There needs to be a model containing the old attribute and the newly created attribute. The old value should be set in the new attribute. Only after this migration the old attribute can be deleted from the model. Now the migration is complete.
For each situation, you have to determine what to do and if a migration is needed. For some changes (for example additions to the model), it might not be necessary to actively migrate cases.
Case Migration
When your changes have been set, you could end up with either a migration flow (actively migrating data) or an empty migration flow to just update and recalculate all data based on the same data + new model. One way of triggering a migration, is to use a message event and an automatic task. The message event triggers the migration, the automatic task processes any changes and makes sure the newly derived case state is mapped back to the process profile. Any newly created tasks will become active after the process evaluation.
In the DCM Foundation there is a model pattern to do this migration. There is a migration version number added to the metadata. This way you can monitor which case is migrated to which version of the model. There is a migration endpoint triggering the migration automatic task. The task consists of "doing the migration steps" (can be empty when there is no data migration needed), and setting the migration version to the latest number after the flow. This way you could create a case-list, and check the cases that still need migration. The easiest way of migrating all cases is by throwing a message event to all cases.
A different approach could be to lazy migrate each case. So when a task is started, check whether migrations are necessary, and perform the migration steps. However, this means that you possibly need to keep older model patterns (for example legacy attributes) in your latest Blueriq case model for a longer time. The migration strategy could of course also be a combination of active and lazy migrations.
Overview
Content Tools