Add Process Builder Documentation and Technical Appendix
- Created comprehensive documentation for the Process Builder, detailing its features, usage, and components. - Included a user-friendly overview, quick start guide, and best practices for designing workflows. - Developed a technical appendix outlining the architecture, technology stack, project structure, and component architecture. - Documented state management and connection handling within the Process Builder for developers. - Enhanced troubleshooting and error handling sections to assist users in resolving common issues.
This commit is contained in:
parent
591f5ca4d8
commit
ac76e02825
174
doc/PROCESS_BUILDER_DOCUMENTATION.md
Normal file
174
doc/PROCESS_BUILDER_DOCUMENTATION.md
Normal file
@ -0,0 +1,174 @@
|
||||
# Process Builder Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The Process Builder is a visual workflow designer that allows you to create, edit, and manage business processes using the BPMN (Business Process Model and Notation) standard. With an intuitive drag-and-drop interface, you can design complex workflows that model your organization's business processes.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Accessing the Process Builder
|
||||
1. Navigate to `/process-builder` in your browser
|
||||
2. You'll see a three-panel interface:
|
||||
- Left: Component Palette
|
||||
- Middle: Process Canvas
|
||||
- Right: Properties Panel
|
||||
|
||||
### Quick Start Guide
|
||||
1. **Create a New Process**
|
||||
- Click "New Process" in the header
|
||||
- Enter a process name and description
|
||||
- Start adding components
|
||||
|
||||
2. **Add Process Elements**
|
||||
- Drag components from the left panel onto the canvas
|
||||
- Components include Start/End events, Tasks, Gateways, etc.
|
||||
- Connect elements by dragging from one node's handle to another
|
||||
- Handles appear when hovering over nodes:
|
||||
- Top handle: Input connection point
|
||||
- Bottom handle: Output connection point
|
||||
|
||||
3. **Configure Elements**
|
||||
- Click any element in the canvas to select it
|
||||
- Use the right panel to configure its properties
|
||||
- Changes are previewed in real-time
|
||||
|
||||
4. **Save and Deploy**
|
||||
- Click "Save Process" to store your changes
|
||||
- Once ready, you can deploy the process for execution
|
||||
|
||||
## Process Components
|
||||
|
||||
### Events
|
||||
Events represent something that happens during the course of a process:
|
||||
|
||||
- **Start Event** (Green Icon)
|
||||
- Indicates where a process begins
|
||||
- Only has output handle (bottom)
|
||||
- Properties: Description, triggers
|
||||
|
||||
- **End Event** (Red Icon)
|
||||
- Indicates where a process path ends
|
||||
- Only has input handle (top)
|
||||
- Properties: Description, result types
|
||||
|
||||
### Activities
|
||||
Activities represent work performed in a process:
|
||||
|
||||
- **Task** (Blue Icon)
|
||||
- A simple atomic activity within the process
|
||||
- Has both input and output handles
|
||||
- Properties: Assignee, description
|
||||
|
||||
- **Form Task** (Purple Icon)
|
||||
- A task that requires form data
|
||||
- Has both input and output handles
|
||||
- Properties: Form name, description
|
||||
|
||||
- **Script Task** (Grey Icon)
|
||||
- Automated task that executes code
|
||||
- Has both input and output handles
|
||||
- Properties: Language, description
|
||||
|
||||
### Gateways
|
||||
Gateways control flow divergence and convergence:
|
||||
|
||||
- **Gateway** (Orange Icon)
|
||||
- Creates alternative paths based on conditions
|
||||
- Has both input and output handles
|
||||
- Properties: Conditions, description
|
||||
|
||||
## Working with the Process Canvas
|
||||
|
||||
### Navigation
|
||||
- **Pan**: Click and drag the canvas background or use middle mouse button
|
||||
- **Zoom**: Use mouse wheel or zoom controls in top-right
|
||||
- **Reset View**: Use the fit-view button in controls
|
||||
|
||||
### Element Manipulation
|
||||
- **Select**: Click on an element
|
||||
- **Multi-select**: Hold Shift while clicking elements
|
||||
- **Move**: Drag selected elements
|
||||
- **Delete**: Press Delete key or double-click element
|
||||
- **Connect**: Drag from one node's handle to another's
|
||||
|
||||
### Keyboard Shortcuts
|
||||
- **Delete**: Remove selected elements
|
||||
- **Shift**: Enable node selection
|
||||
- **Control**: Multi-select nodes
|
||||
|
||||
### Connection Points
|
||||
- **Input Handle**: Located at the top of nodes (except Start)
|
||||
- **Output Handle**: Located at the bottom of nodes (except End)
|
||||
- **Creating Connections**:
|
||||
1. Hover over a node to see handles
|
||||
2. Click and drag from a handle
|
||||
3. Drop on another node's handle
|
||||
4. Connection automatically styles based on type
|
||||
|
||||
## Process Properties
|
||||
|
||||
### Basic Settings
|
||||
- Process name and description
|
||||
- Version information
|
||||
- Start conditions
|
||||
- Process timeouts
|
||||
|
||||
### Variables
|
||||
- Process data variables
|
||||
- Input and output parameters
|
||||
- Data types and validation
|
||||
|
||||
### Participants
|
||||
- User assignments
|
||||
- Role-based assignments
|
||||
- Group assignments
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Process Design
|
||||
1. Start with a Start event and end with End event(s)
|
||||
2. Use clear, descriptive labels for all elements
|
||||
3. Connect nodes in a logical flow
|
||||
4. Use gateways to manage decision points
|
||||
5. Keep the process layout organized and clear
|
||||
|
||||
### Flow Control
|
||||
1. Ensure all paths lead to an End event
|
||||
2. Validate connections make logical sense
|
||||
3. Use appropriate node types for each step
|
||||
4. Consider the process flow direction (typically top to bottom)
|
||||
|
||||
### Visual Organization
|
||||
1. Maintain consistent spacing between nodes
|
||||
2. Align nodes for better readability
|
||||
3. Use the auto-arrange feature when available
|
||||
4. Keep related elements grouped together
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
1. **Can't Create Connection**
|
||||
- Verify you're dragging from a handle
|
||||
- Check that source and target are compatible
|
||||
- Ensure you're connecting to a handle, not the node body
|
||||
|
||||
2. **Node Won't Delete**
|
||||
- Make sure the node is selected
|
||||
- Try using the Delete key
|
||||
- Alternative: double-click the node
|
||||
|
||||
3. **Connection Looks Wrong**
|
||||
- Try repositioning nodes for better flow
|
||||
- Check that connections are made to correct handles
|
||||
- Consider using different connection types
|
||||
|
||||
### Getting Help
|
||||
- Use the control panel hints in top-right
|
||||
- Review this documentation
|
||||
- Contact support team for additional assistance
|
||||
|
||||
---
|
||||
|
||||
For technical details about implementation and integration, please refer to the [Process Builder Technical Documentation](PROCESS_BUILDER_TECHNICAL_APPENDIX.md).
|
||||
|
||||
Last updated: May 15, 2024
|
344
doc/PROCESS_BUILDER_TECHNICAL_APPENDIX.md
Normal file
344
doc/PROCESS_BUILDER_TECHNICAL_APPENDIX.md
Normal file
@ -0,0 +1,344 @@
|
||||
# Process Builder Technical Appendix
|
||||
|
||||
This document provides technical implementation details for developers working with the Process Builder system.
|
||||
|
||||
> For user documentation and usage guidelines, please refer to [Process Builder Documentation](PROCESS_BUILDER_DOCUMENTATION.md)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Technology Stack
|
||||
- **Frontend Framework**: Nuxt 3 / Vue 3
|
||||
- **State Management**: Pinia
|
||||
- **Flow Visualization**: Vue Flow
|
||||
- **UI Framework**: Tailwind CSS
|
||||
- **Icons**: Material Design Icons
|
||||
- **Validation**: Zod
|
||||
|
||||
### Key Dependencies
|
||||
```json
|
||||
{
|
||||
"@vue-flow/core": "^1.42.5",
|
||||
"@vue-flow/background": "^1.3.2",
|
||||
"@vue-flow/controls": "^1.1.2",
|
||||
"@vue-flow/minimap": "^1.5.3",
|
||||
"@pinia/nuxt": "^0.4.11",
|
||||
"uuid": "^10.0.0",
|
||||
"zod": "^3.22.2"
|
||||
}
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
pages/
|
||||
├── process-builder/
|
||||
│ ├── index.vue # Main builder interface
|
||||
│ └── manage.vue # Process management
|
||||
components/
|
||||
├── process-flow/
|
||||
│ ├── ProcessFlowCanvas.vue # Flow canvas
|
||||
│ └── ProcessFlowNodes.js # Custom node types
|
||||
stores/
|
||||
└── processBuilder.js # State management
|
||||
composables/
|
||||
└── useProcessValidation.js # Process validation
|
||||
types/
|
||||
└── process-builder.d.ts # TypeScript definitions
|
||||
```
|
||||
|
||||
## Component Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
1. **ProcessFlowCanvas.vue**
|
||||
```vue
|
||||
<script setup>
|
||||
import { ref, onMounted } from 'vue';
|
||||
import { VueFlow, useVueFlow, Panel } from '@vue-flow/core';
|
||||
import { Background } from '@vue-flow/background';
|
||||
import { Controls } from '@vue-flow/controls';
|
||||
import { MiniMap } from '@vue-flow/minimap';
|
||||
import { nodeTypes } from './ProcessFlowNodes';
|
||||
|
||||
// Initialize Vue Flow with options
|
||||
const {
|
||||
nodes,
|
||||
edges,
|
||||
addNodes,
|
||||
addEdges,
|
||||
removeNodes,
|
||||
removeEdges,
|
||||
onNodesChange,
|
||||
onEdgesChange,
|
||||
onConnect,
|
||||
fitView,
|
||||
project
|
||||
} = useVueFlow({
|
||||
defaultEdgeOptions: {
|
||||
animated: true,
|
||||
type: 'smoothstep'
|
||||
},
|
||||
deleteKeyCode: 'Delete',
|
||||
selectionKeyCode: 'Shift',
|
||||
multiSelectionKeyCode: 'Control',
|
||||
connectionMode: 'loose'
|
||||
});
|
||||
|
||||
// Flow configuration
|
||||
const flowOptions = {
|
||||
defaultZoom: 1,
|
||||
minZoom: 0.2,
|
||||
maxZoom: 4,
|
||||
fitViewOnInit: true,
|
||||
snapToGrid: true,
|
||||
snapGrid: [15, 15],
|
||||
connectionMode: 'loose',
|
||||
elementsSelectable: true,
|
||||
nodesDraggable: true,
|
||||
nodesConnectable: true
|
||||
};
|
||||
|
||||
// Event handlers for node/edge changes
|
||||
onNodesChange((changes) => {
|
||||
emit('nodesChange', changes, nodes.value);
|
||||
});
|
||||
|
||||
onEdgesChange((changes) => {
|
||||
emit('edgesChange', changes, edges.value);
|
||||
});
|
||||
|
||||
// Handle new connections
|
||||
const handleConnect = (connection) => {
|
||||
if (!connection.source || !connection.target) return;
|
||||
|
||||
const newEdge = {
|
||||
id: `${connection.source}-${connection.target}`,
|
||||
source: connection.source,
|
||||
target: connection.target,
|
||||
type: 'smoothstep',
|
||||
animated: true
|
||||
};
|
||||
|
||||
addEdges([newEdge]);
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
||||
2. **ProcessFlowNodes.js**
|
||||
```javascript
|
||||
import { h, markRaw } from 'vue';
|
||||
import { Handle, Position } from '@vue-flow/core';
|
||||
|
||||
// Custom node renderer with handles
|
||||
const CustomNode = markRaw({
|
||||
template: `
|
||||
<div :class="['custom-node', 'node-' + type]">
|
||||
<Handle
|
||||
v-if="type !== 'start'"
|
||||
type="target"
|
||||
position="top"
|
||||
/>
|
||||
|
||||
<div class="custom-node-header">
|
||||
<div class="custom-node-icon">
|
||||
<slot name="icon"></slot>
|
||||
</div>
|
||||
<div class="custom-node-title">{{ label }}</div>
|
||||
</div>
|
||||
|
||||
<div class="custom-node-content">
|
||||
<slot></slot>
|
||||
</div>
|
||||
|
||||
<Handle
|
||||
v-if="type !== 'end'"
|
||||
type="source"
|
||||
position="bottom"
|
||||
/>
|
||||
</div>
|
||||
`,
|
||||
props: ['id', 'type', 'label', 'data'],
|
||||
components: { Handle }
|
||||
});
|
||||
|
||||
// Node type definitions
|
||||
export const nodeTypes = markRaw({
|
||||
task: TaskNode,
|
||||
start: StartNode,
|
||||
end: EndNode,
|
||||
gateway: GatewayNode,
|
||||
form: FormNode,
|
||||
script: ScriptNode
|
||||
});
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
### Process Builder Store
|
||||
```typescript
|
||||
export const useProcessBuilderStore = defineStore('processBuilder', {
|
||||
state: () => ({
|
||||
processes: [],
|
||||
currentProcess: null,
|
||||
selectedNodeId: null,
|
||||
selectedEdgeId: null,
|
||||
unsavedChanges: false
|
||||
}),
|
||||
|
||||
actions: {
|
||||
createProcess(name, description) {
|
||||
const process = {
|
||||
id: uuidv4(),
|
||||
name,
|
||||
description,
|
||||
nodes: [],
|
||||
edges: [],
|
||||
createdAt: new Date().toISOString()
|
||||
};
|
||||
this.processes.push(process);
|
||||
this.currentProcess = process;
|
||||
},
|
||||
|
||||
updateNode(nodeData) {
|
||||
if (!this.currentProcess || !nodeData.id) return;
|
||||
|
||||
const nodeIndex = this.currentProcess.nodes.findIndex(
|
||||
node => node.id === nodeData.id
|
||||
);
|
||||
|
||||
if (nodeIndex > -1) {
|
||||
this.currentProcess.nodes[nodeIndex] = {
|
||||
...this.currentProcess.nodes[nodeIndex],
|
||||
...nodeData
|
||||
};
|
||||
this.unsavedChanges = true;
|
||||
}
|
||||
},
|
||||
|
||||
// Additional actions...
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Node Types and Styles
|
||||
|
||||
### Node Configuration
|
||||
```typescript
|
||||
interface NodeConfig {
|
||||
type: 'start' | 'end' | 'task' | 'form' | 'script' | 'gateway';
|
||||
label: string;
|
||||
icon: string;
|
||||
iconColor: string;
|
||||
data: {
|
||||
description?: string;
|
||||
assignee?: string;
|
||||
formName?: string;
|
||||
language?: string;
|
||||
conditions?: string[];
|
||||
};
|
||||
}
|
||||
|
||||
const nodeConfigs: Record<string, NodeConfig> = {
|
||||
start: {
|
||||
type: 'start',
|
||||
label: 'Start',
|
||||
icon: 'play_circle_filled',
|
||||
iconColor: 'text-green-500',
|
||||
data: { description: 'Process starts here' }
|
||||
},
|
||||
task: {
|
||||
type: 'task',
|
||||
label: 'Task',
|
||||
icon: 'assignment',
|
||||
iconColor: 'text-blue-500',
|
||||
data: { description: 'Task node', assignee: '' }
|
||||
},
|
||||
// Additional node configurations...
|
||||
};
|
||||
```
|
||||
|
||||
## Connection Handling
|
||||
|
||||
### Connection Logic
|
||||
```typescript
|
||||
// Connection validation
|
||||
function validateConnection(connection: Connection): boolean {
|
||||
if (!connection.source || !connection.target) return false;
|
||||
if (connection.source === connection.target) return false;
|
||||
|
||||
const sourceNode = nodes.value.find(n => n.id === connection.source);
|
||||
const targetNode = nodes.value.find(n => n.id === connection.target);
|
||||
|
||||
if (!sourceNode || !targetNode) return false;
|
||||
|
||||
// Prevent connecting to start node's input or from end node's output
|
||||
if (targetNode.type === 'start') return false;
|
||||
if (sourceNode.type === 'end') return false;
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
// Create new connection
|
||||
function createConnection(connection: Connection): Edge {
|
||||
return {
|
||||
id: `${connection.source}-${connection.target}`,
|
||||
source: connection.source,
|
||||
target: connection.target,
|
||||
type: 'smoothstep',
|
||||
animated: true,
|
||||
style: { stroke: '#555' }
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Event Handling
|
||||
|
||||
### Node Events
|
||||
```typescript
|
||||
// Node selection
|
||||
function onNodeClick(node: Node): void {
|
||||
selectedNode.value = node;
|
||||
emit('nodeSelected', node);
|
||||
}
|
||||
|
||||
// Node deletion
|
||||
function onNodeDelete(nodes: Node[]): void {
|
||||
removeNodes(nodes);
|
||||
emit('nodesChange', nodes.value);
|
||||
}
|
||||
|
||||
// Node dragging
|
||||
function onNodeDragStop(node: Node): void {
|
||||
updateNodePosition(node);
|
||||
emit('nodePositionChange', node);
|
||||
}
|
||||
```
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Best Practices
|
||||
1. Use Vue Flow's built-in features instead of custom implementations
|
||||
2. Handle all node/edge updates through the store
|
||||
3. Maintain proper typings for all components
|
||||
4. Follow Vue 3 Composition API patterns
|
||||
5. Implement proper validation for all process changes
|
||||
|
||||
### Performance Considerations
|
||||
1. Use `markRaw` for node components
|
||||
2. Minimize reactive wrapping of node data
|
||||
3. Use proper key bindings for lists
|
||||
4. Implement efficient node filtering
|
||||
5. Optimize canvas rendering
|
||||
|
||||
### Error Handling
|
||||
1. Validate all connections before creation
|
||||
2. Handle edge cases in node operations
|
||||
3. Provide meaningful error messages
|
||||
4. Implement proper error boundaries
|
||||
5. Log errors appropriately
|
||||
|
||||
---
|
||||
|
||||
For user documentation and usage guidelines, please refer to [Process Builder Documentation](PROCESS_BUILDER_DOCUMENTATION.md).
|
||||
|
||||
Last updated: May 15, 2024
|
Loading…
x
Reference in New Issue
Block a user