MohammadMu99 commented on issue #2421:
URL: 
https://github.com/apache/incubator-kie-issues/issues/2421#issuecomment-6623467616

   Hi all 👋
   
   ### ✅ Done so far
   
   The linked PR (apache/incubator-kie#7259) adds an optional 
`variableMigrationPlan` list inside `processMigrationPlan`, with three actions:
   
   ```json
   "variableMigrationPlan": [
     { "action": "rename",  "from": "custName", "to": "customerName" },
     { "action": "default", "name": "riskLevel", "value": "LOW" },
     { "action": "remove",  "name": "tempFlag" }
   ]
   ```
   
   - `rename`: copies `from` into `to`, then clears `from` (does nothing if 
`from` is empty).
   - `default`: sets `name` to `value` only if it is empty.
   - `remove`: clears `name`.
   
   > **Why it helps:** today, when a new process version renames, adds or drops 
a variable, migrated instances keep the value under the old name and the new 
variable stays empty. These rules keep the data in line with the new version, 
with no custom code or manual database fixes.
   
   ### 🔜 Planned follow-up PRs
   
   I've already built a few more extensions to migration plans in my own 
project. I'd like to contribute them **one at a time, each in its own PR**, so 
they stay small and easy to review.
   
   | PR | Extension | What it does | Why it helps |
   |----|-----------|--------------|--------------|
   | 1 | **Variable type conversion** | Changes a variable's type during 
migration. | Instances keep working when the new version expects a different 
type, instead of failing at runtime. |
   | 2 | **Completed node migration** | Marks new nodes as completed when they 
were added *before* the point an instance has reached. | History and progress 
stay correct; the new steps don't look skipped or pending. |
   | 3 | **Node restart** | Cancels an active node and starts the target node 
fresh on the new version. | Running instances pick up the changed node 
definition (e.g. a fixed on-entry script) instead of continuing with the old 
one. |
   | 4 | **Conditional rules** | Applies any plan entry only to instances whose 
variables match. | One plan can handle different instances differently, instead 
of writing several plans or migrating by hand. |
   
   Each PR will build on the previous ones and include its own tests.
   
   <details>
   <summary>JSON shape I use today, with examples (click to expand)</summary>
   
   #### 1. Variable type conversion
   
   ```json
   { "action": "convert", "name": "amount", "toType": "Integer" }
   ```
   
   - A new action inside `variableMigrationPlan`.
   - Reads the current value of `amount` as text and converts it to `toType`.
   - Supported types: `String`, `Integer`, `Long`, `Double`, `BigDecimal`, 
`Boolean` (case-insensitive).
   - An empty variable stays empty. A value that can't be converted (e.g. 
`"abc"` to `Integer`) fails the migration.
   
   > **Why it helps:** if `amount` was a `String` in v1 and is an `Integer` in 
v2, gateways, scripts and rules in v2 would hit a type error on old instances. 
Converting during migration fixes the data once, at the safest point, and a bad 
value stops the migration instead of breaking the instance later.
   
   #### 2. Completed node migration
   
   ```json
   "completedNodeMigrationPlan": [
     { "reachedNodeId": "_REVIEW", "completedNodeId": "_NEW_CHECK", 
"reachedState": "completed" }
   ]
   ```
   
   - `reachedNodeId`: a node from the **old** version. The rule applies only if 
the instance has already reached it.
   - `completedNodeId`: a **new** node in the target version that the instance 
has logically passed. It is added to the instance's completed nodes, just 
before `reachedNodeId`, so the order stays correct.
   - `reachedState` (optional):
     - `"completed"`: the rule applies only if `reachedNodeId` is already 
**completed**.
     - Omitted: the rule also applies if `reachedNodeId` is still **active**.
   - If `completedNodeId` doesn't exist in the target version, the migration 
fails. If it's already completed, nothing changes.
   
   > **Why it helps:** when v2 adds a step *before* where an instance already 
is, the instance never ran that step. Without this, the process diagram and 
history show a gap. Marking it completed keeps the instance's progress 
consistent with the new definition, for monitoring, audit and any logic that 
checks completed nodes.
   
   #### 3. Node restart
   
   ```json
   { "sourceNodeId": "_REVIEW_V1", "targetNodeId": "_REVIEW_V2", "restart": 
true }
   ```
   
   - A new optional flag on a normal `nodeInstanceMigrationPlan` entry.
   - Without `restart`: the active node's ID is simply remapped, and the node 
keeps its current state.
   - With `"restart": true`: after the instance is moved to the new version, 
the active `sourceNodeId` is **cancelled** and `targetNodeId` is **triggered 
fresh**.
   - The rule is skipped if `sourceNodeId` isn't active. The migration fails if 
`targetNodeId` doesn't exist in the target version.
   
   > **Why it helps:** a plain remap keeps the old node instance as it was, so 
a user task keeps its old inputs, form and assignment even after migration. 
Restarting makes the instance use the **new** definition right away (new 
inputs, new actors, new on-entry logic) without cancelling and recreating the 
whole process instance.
   
   > 📝 **Example: changed on-entry script**
   >
   > In v1, the `Review` task's on-entry script sets `approvalLimit = 5000`.
   > In v2, the script is fixed to compute `approvalLimit` from the customer's 
segment, and the task now uses that value.
   >
   > - **Remap only:** instances already waiting at `Review` were entered under 
v1, so the new script **never runs** for them. They keep the old 
`approvalLimit` and behave differently from new instances.
   > - **With `restart`:** the task is re-entered on v2, so the **new on-entry 
script runs**. Old instances end up in the same state as instances started on 
v2 and continue as v2 expects.
   >
   > The same applies to anything that runs when a node is entered: on-entry 
scripts, input data mappings, actor/group assignment and task deadlines.
   
   #### 4. Conditional rules
   
   ```json
   {
     "action": "default", "name": "riskLevel", "value": "HIGH",
     "when": { "variable": "amount", "operator": ">", "value": "1000" }
   }
   ```
   
   - An optional `when` block on **any** entry: a node mapping, a variable rule 
or a completed-node rule.
   - No `when`: the entry always applies. With `when`: it applies only to 
instances whose variable matches.
   - Operators: `=`, `!=`, `>`, `>=`, `<`, `<=`, `empty`, `not empty`.
   - Numbers are compared as numbers (`"900" < "1000"`), anything else as text.
   - If the variable is empty, only `!=` and `empty` match.
   - Here: instances with `amount > 1000` get `riskLevel = HIGH`. Other 
instances are left alone.
   
   > **Why it helps:** real instances aren't all the same. Big loans may need a 
different default, or a restart only for one branch. With `when`, one plan file 
covers all cases, instead of splitting instances by hand and keeping several 
plans in sync.
   
   </details>
   
   ### 💬 Open question: JSON format
   
   All of these already work in my project, but the JSON shapes above are my 
own design so far.
   
   If anyone would like to discuss the JSON format (naming, structure, or how 
these fit with the existing `nodeInstanceMigrationPlan`), I'd be happy to agree 
on whatever standard fits the project best **before** opening the PRs.
   
   Thanks!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to