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:
Md Afiq Iskandar 2025-04-23 10:47:35 +08:00
parent 591f5ca4d8
commit ac76e02825
2 changed files with 518 additions and 0 deletions

View 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

View 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