Home panel
Overview
The Home panel is the main dashboard of the OKMFlow workflow engine. It provides comprehensive workflow management capabilities, allowing users to create, configure, and monitor workflow process definitions and their active instances. The panel is organized into multiple sections for efficient workflow administration and real-time instance monitoring.
Panel Layout
The Home panel is structured with three main areas:
- Top navigation bar: Contains the main menu options (Home, Designer, Users, Tools, Admin)
- Left sidebar menu: Provides quick access to workflow creation and management actions
- Center content area: Divided into two main sections for Process Definitions and Process Instances
Left Sidebar Menu
The vertical sidebar on the left provides quick access to workflow management operations:
- Create empty workflow: Creates a new blank workflow definition
- Import workflow definition: Imports a workflow from an external file
- View workflow library: Access the library of available workflow templates
- Refresh panel: Reload the current view to reflect latest changes
Process Definitions Section
The first section displays all workflow definitions available in the system. This section provides a paginated table view with filtering and management capabilities.
Table Columns
| Column | Description |
|---|---|
| Id | Unique numeric identifier for the process definition |
| Version | Version number of the workflow definition |
| Name | Descriptive name of the workflow |
| Active | Checkbox indicating whether the workflow is currently active and can be instantiated |
| Actions | Icons for workflow management operations |
Pagination and Filtering
- Pagination: Default page size is 10 elements, which can be modified
- Name filter: Filter workflows by name using the search field
Available Actions
| Action | Description |
|---|---|
| Edit | Opens the Designer to modify the workflow definition |
| Delete | Removes the workflow definition from the system |
| Activate / Disable | Toggles the active state of the workflow. Only active workflows can be instantiated. |
| Export | Exports the workflow definition to a file for backup or transfer |
| Clone | Creates a copy of the workflow definition |
| Rename | Changes the name of the workflow definition |
| Lock | Locks the workflow to prevent modifications |
| Add to library | Adds the workflow to the workflow library for reuse |
Workflow Version Management
The OKMFlow workflow engine supports versioning of workflow definitions, allowing multiple versions of the same workflow to coexist in the system. This enables safe workflow evolution while maintaining backward compatibility with running instances.
Version Management Principles
| Concept | Description |
|---|---|
| Single Active Version | Only one version of a workflow can be active at any given time. The active version is used for all new workflow instances. |
| Version Number | Each workflow definition has a version number. When creating a new version, the version number is automatically incremented by 1. |
| Activation Control | The active version can be changed using the Activate/Disable action in the Process Definitions section menu. |
| Running Instance Continuity | Workflow instances that are already running continue to execute using their original version, even if that version is no longer active. |
Version Behavior
Active vs Inactive Versions
- Active version: The workflow version marked as "active" is used when starting new workflow instances. Only one version can be active at a time.
- Inactive versions: Previous versions remain in the system and continue to support running instances, but cannot be used to start new workflows.
- Concurrent execution: Multiple versions of the same workflow can be executing simultaneously. Running instances maintain their original version throughout their lifecycle.
When you activate a different version of a workflow, existing running instances are not affected. They continue using the version they were started with, ensuring execution stability and preventing unexpected behavior.
New Instance Behavior
When a new workflow instance is created:
- The system uses the currently active version of the workflow definition
- The instance remains bound to this version for its entire lifecycle
- If the workflow is later updated or a new version is activated, the running instance continues with its original version
Creating New Versions
To create a new version of an existing workflow, follow this process:
- Export the active workflow: Use the Export action to save the current active workflow definition to a file
- Import the workflow: Use the "Import workflow definition" option from the left sidebar to import the exported file
- Result: The system creates a new workflow definition with:
- The same workflow name
- Version number incremented by 1
- Inactive status (not automatically activated)
- Modify and activate: Edit the new version as needed using the Designer, then activate it when ready for production use
Important: When importing a workflow whose name already exists in the system, a new version is automatically created with version number +1. The imported workflow is not automatically activated. You must explicitly activate the new version if you want new instances to use it.
Version Management Workflow
A typical version management workflow follows these steps:
- Active production workflow: Version 1 is active and processing new instances
- Create new version: Export version 1 and import it to create version 2 (inactive)
- Modify version 2: Make improvements or fixes to version 2 using the Designer
- Testing: Test version 2 in a controlled environment
- Activate version 2: When ready, activate version 2 using the Activate action
- Result:
- Version 1 becomes inactive
- Existing version 1 instances continue running
- New instances start with version 2
- Both versions execute concurrently until all version 1 instances complete
Use Cases
| Use Case | Approach |
|---|---|
| Bug fixes | Create a new version with corrections, test thoroughly, then activate when ready. Old instances continue with the buggy version and complete normally. |
| Feature additions | Add new nodes or transitions to a new version. Activate when stable. Existing instances won't have the new features but will complete successfully. |
| Process improvements | Optimize workflow logic in a new version without affecting running instances. Gradually transition by activating the improved version. |
| Rollback | If a new version causes issues, reactivate the previous stable version. New instances will use the old version, while problematic instances can be handled individually. |
Best Practices for Version Management
- Version naming convention: Use descriptive workflow names that remain consistent across versions. The version number will differentiate them.
- Test before activating: Always test a new workflow version thoroughly before activating it for production use.
- Document version changes: Maintain documentation of what changed between versions to facilitate troubleshooting and rollback decisions.
- Monitor concurrent versions: When multiple versions are running, use the Process Instances section to monitor both old and new version instances.
- Clean up old versions: Once all instances of an old version have completed, consider deleting obsolete workflow definitions to reduce clutter.
- Gradual rollout: For critical workflows, consider a phased approach by activating the new version during low-traffic periods.
- Keep stable versions: Don't delete inactive versions that still have running instances, as this may cause reference issues.
The version management system ensures zero downtime workflow updates. You can safely improve and deploy new workflow versions while existing instances complete without interruption.
Process Instances Section
The second section displays active workflow instances (workflow executions). This paginated table shows all running, waiting, or completed workflow instances with detailed information and management options.
Table Columns
| Column | Description |
|---|---|
| Id | Unique identifier for the process instance |
| Status | Current state of the workflow instance (RUNNING, ERROR, WAITING, ENDED) |
| Start date | Timestamp when the workflow instance was initiated |
| End date | Timestamp when the workflow completed (if finished) |
| Last activity | Timestamp of the most recent activity in this workflow |
| Node | Description of the current node or last active node |
| OpenKM Node | UUID reference to the associated OpenKM document or folder |
| Actions | Icons for instance management and inspection |
Filtering Options
- Process Instance ID: Filter by the unique identifier of the process instance
- Status filter: Filter instances by status (running, error, waiting, ended)
Instance Actions
Each process instance provides five management and inspection options:
1. Process Variables
Displays and manages all context variables for the workflow instance. This view provides:
- Add button: Create new variables in the workflow context
- Filter field: Search variables by name
- Variable type selector: Filter variables by category
- All: Display all variables
- Internal: Show only internal system variables
- Form definition: Show only variables from form fields
- Edit action: Modify variable values
- Delete action: Remove variables from the context
The Process Variables table displays:
- Name: Variable name
- Class: Variable type (String, Document, Actor, ProcessInstance, etc.)
- Value: Current value of the variable
- Actions: Edit and delete icons for modifiable variables
2. Logs
Provides a complete audit trail of all states the workflow has passed through during execution. This chronological log helps troubleshoot workflow issues and understand execution flow.
The Logs table displays:
| Column | Description |
|---|---|
| Date | Timestamp when the state change occurred |
| Name | Name of the node that triggered the log entry |
| Node type | Type of node (start, task, action, etc.) |
| Status | State change type (enter, leave, assigned, error) |
| Data | Additional information about the state change (assigned actors, error messages, variable values) |
The logs are paginated and show the complete execution history of the workflow instance.
3. Task Instances
Displays all tasks the workflow has passed through in chronological order. The last task in the list is the one currently pending completion by a user.
The Task Instances table displays:
| Column | Description |
|---|---|
| Id | Unique identifier for the task instance |
| Process Instance | ID of the parent process instance |
| Start | Timestamp when the task was created |
| End | Timestamp when the task was completed |
| Status | Current state of the task (CLOSED, OPEN, etc.) |
| Actor | User currently assigned to complete the task |
| Pooled actors | List of users who can claim pooled tasks |
| Name | Name of the task node |
| Form definition | (Visible when "Show basic" is enabled) XML definition of the task's property group metadata |
| Actions | Management options for the task |
Task Instance Features
- Change assigned user: Reassign the task to a different user
- Goto button: Jump to a specific task in the workflow sequence
Important: The "Goto" functionality should be used with caution as it breaks the default workflow logic by skipping nodes. This can lead to unexpected behavior or incomplete workflow execution. Only use this feature for troubleshooting or emergency recovery situations.
- Show basic checkbox: When enabled, displays an additional "Form definition" column showing the property group metadata XML for each task
4. Preview
Displays a visual diagram of the workflow definition with an arrow indicator showing the current execution point. This graphical representation helps users:
- Understand the current workflow state at a glance
- Visualize the workflow path taken
- Identify the next steps in the process
- Troubleshoot workflow execution issues
The preview shows all nodes, transitions, and clearly marks the current active node with an arrow.
5. Delete
Removes the process instance from the system. This action:
- Permanently deletes the workflow instance and all associated data
- Cannot be undone
- Should be used carefully, typically for cancelled or failed workflows
- Does not affect the process definition, only the running instance
Important: Deleting a process instance permanently removes all workflow execution data including task history, variables, and logs. This action cannot be undone. Use with caution.
Best Practices
- Use descriptive workflow names: Choose clear, meaningful names for process definitions to facilitate identification and management
- Activate workflows selectively: Only activate workflows that are fully tested and ready for production use
- Monitor process instances regularly: Check the Process Instances section to identify stuck, failed, or problematic workflows
- Export workflows before modifications: Create backups by exporting workflow definitions before making significant changes
- Use filtering effectively: Take advantage of name and status filters to quickly locate specific workflows or instances
- Review logs for troubleshooting: When workflows fail or behave unexpectedly, examine the Logs view to understand the execution sequence
- Be cautious with Goto: The task instance "Goto" feature should only be used in exceptional circumstances as it bypasses normal workflow logic
- Manage variables carefully: When editing process variables, ensure changes align with the workflow's expected data structure
- Use Preview for verification: The visual preview helps verify workflow execution is following the expected path
- Clean up completed instances: Consider deleting old, completed workflow instances to maintain system performance
- Leverage the workflow library: Add well-tested, reusable workflows to the library for easy access across projects
Use the "Show basic" checkbox in Task Instances to view the complete form definition XML. This is particularly useful when troubleshooting form-related issues or understanding the metadata structure of tasks.
The Home panel integrates with the OpenKM document management system. Process instances can reference OpenKM documents through the "OpenKM Node" field, enabling workflows to operate on documents and folders stored in OpenKM.
