jomarko commented on code in PR #3587: URL: https://github.com/apache/incubator-kie-tools/pull/3587#discussion_r3280204107
########## packages/bpmn-editor/docs/MIGRATION_GUIDE.md: ########## @@ -0,0 +1,669 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +# @kie-tools/bpmn-editor :: MIGRATION GUIDE + +## Overview + +The Apache KIE BPMN Editor has been rewritten. The **Classic BPMN Editor** (Stunner/GWT-based, last available in Apache KIE 10.1) has been replaced by the **New BPMN Editor** (React/ReactFlow-based, available from Apache KIE 10.2+). + +The New BPMN Editor provides: + +- React and ReactFlow technology stack +- Grid snapping and infinite canvas +- Multi-node selection +- Best-effort backwards compatibility with Classic Editor files + +--- + +## Key UI/UX Differences + +### 1. Canvas and Navigation + +| Feature | Classic Editor | New Editor | +| --------------- | ---------------------------- | ------------------------------ | +| **Canvas Type** | Fixed canvas with scrollbars | Infinite canvas | +| **Zoom** | Toolbar buttons | Mouse wheel + toolbar controls | +| **Pan** | Scrollbars | Drag canvas background | + +--- + +### 2. Palette and Node Creation + +| Feature | Classic Editor | New Editor | +| ---------------- | ------------------------- | ------------------------------ | +| **Custom Tasks** | Mixed with standard tasks | Dedicated "Custom Tasks" panel | + +**Palette Panel Icons:** + +- Start Events +- Intermediate Catch Events +- Intermediate Throw Events +- End Events +- Tasks +- Call Activity +- Sub-processes +- Gateways +- Lanes +- Data Object +- Group +- Text Annotation +- Custom Tasks + +--- + +### 3. Properties Panel + +**Properties Panel Sections:** + +- Element Properties (Name, Documentation, ID) +- Execution Properties (Async, Multi-instance, SLA) +- Data Mapping +- Scripts (onEntry/onExit) +- Notifications +- Reassignments +- Variables +- Metadata + +--- + +### 4. Left Sidebar Panels (New) + +#### Process Variables Panel + +**Location**: Left sidebar, first icon + +Dedicated panel for managing process variables with data types and custom tags. + +**Classic Editor**: Variables managed in Properties panel +**New Editor**: Dedicated panel + +#### Correlations Panel + +**Location**: Left sidebar, second icon + +Manage message correlations: + +- Correlation Properties +- Correlation Keys +- Message Bindings +- Subscriptions + +**Classic Editor**: Correlations accessed via "Collaboration" section in Properties panel, opened through "Correlations" button in a modal dialog +**New Editor**: Dedicated left sidebar panel with tabbed interface (Properties tab and Keys tab) + +#### Properties Management Panel + +**Location**: Left sidebar, third icon + +Centralized management for: + +- Data Types +- Messages +- Signals +- Escalations +- Errors + +**Classic Editor**: Scattered across dialogs +**New Editor**: Single panel + +--- + +### 5. Selection and Multi-Selection + +| Feature | Classic Editor | New Editor | +| ------------------- | ---------------------- | ------------------------------------ | +| **Multi-Selection** | Ctrl+Click or drag box | Drag box | +| **Bulk Operations** | Limited | Delete, copy, move multiple elements | + +**Note**: Properties panel shows "Multiple nodes selected (N)" when multiple elements are selected. Cannot edit properties when both nodes and edges are selected. + +--- + +### 8. Global Properties + +| Feature | Classic Editor | New Editor | +| ---------------------- | ------------------ | --------------------------- | +| **Process Properties** | Single form | Expandable sections | +| **ID & Namespace** | Basic input fields | Copy and regenerate buttons | + +**Sections:** + +- Process (Name, Documentation, Type, Executable, Ad-hoc) +- ID & Namespace (with copy/regenerate) +- Misc (Expression language, Package name, Version, Process Instance Description) + +--- + +### 9. Keyboard Shortcuts + +Standard shortcuts remain the same (Ctrl+Z, Ctrl+C, Ctrl+V, Delete, etc.). + +**New**: + +- Mouse wheel for zoom (in addition to Ctrl+/-) +- Toggle Properties panel + +--- + +## Common Tasks + +### Creating a New Process + +**New Editor**: When opening an empty BPMN file, a "Create Your BPMN Process" dialog appears. Enter a Process ID (required, no spaces) and click "Start Modeling". + +### Working with Process Variables + +**Classic Editor**: Variables managed in Properties panel when canvas background is selected. + +**New Editor**: Click Variables icon (left sidebar, first icon) to open dedicated panel. Click "Add Variable" to create new variables with data types and tags. + +### Managing Correlations + +**New Editor**: Click Correlations icon (left sidebar, second icon). Use Properties tab for Correlation Properties and Message Bindings. Use Keys tab for Correlation Keys and Subscriptions. + +### Defining Reusable Properties + +**New Editor**: Click Properties Management icon (left sidebar, third icon). Tabs available for Data Types, Messages, Signals, Escalations, and Errors. + +--- + +## Step-by-Step Walkthrough: Recreating a BPMN Process Review Comment: sure, I am sorry I was not clear enough in previous comment. I totally agree it is not needed to add addition screenshots. <img width="1052" height="933" alt="Image" src="https://github.com/user-attachments/assets/4cf0b32a-1559-4363-a857-5aa7deeddcb0"; /> my point is in the attached, on very small area we mix 3 approaches - pink compares using text **Classic** on left side, **New** on right side - green compares using tables - blue does not compare, has only **New** I think we should compare always either by **Table** for example as we do in 1,2, 5 or 6, or by two text sections. positioned probably like ``` **Classic** lorem ipsum text **New** Lorem ipsum text ``` is my point more clean now? -- 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]
