26. Administration & RBAC

Workingflow uses a dynamic, database-driven Role-Based Access Control (RBAC) system. Unlike hardcoded role checks, all authorization rules are stored in the database and can be modified at runtime through admin screens — no application restart required.

This guide will help you understand the security model, establish best practices, and troubleshoot common administrative issues.

Security Architecture Overview

Workingflow evaluates security in five distinct layers. A request must pass all applicable layers to succeed.

┌──────────────────────────────────────────────┐
│ Layer 1: Authentication                      │
│ - Spring Security form login                 │
│ - CSRF, XSS, Clickjacking protection         │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│ Layer 2: Page Authorization (Role-Page)      │
│ - URL-based: can this role access /path?     │
│ - Configured via Role-Page Management screen │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│ Layer 3: UI Element Authorization            │
│ - PageObject-based: can this role see button?│
│ - Configured via Role-PageObject screen      │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│ Layer 4: Workflow Start Authorization        │
│ - Process-Role: can this role start workflow?│
│ - Configured via Process Roles screen        │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│ Layer 5: Task Authorization                  │
│ - Assignee/candidate group validation        │
│ - Driven by BPMN assignment rules            │
└──────────────────────────────────────────────┘

Best Practices for Administrators

1. Design Roles by Business Function: Do not create a role for every individual user. Create roles like ROLE_HR_MANAGER, ROLE_IT_SUPPORT, or ROLE_FINANCE_CLERK. Roles are just arbitrary text labels—they have no hardcoded meaning until you map them to pages and processes.
2. Page Protection is the First Line of Defense: Use Role-Page Management to block URL access entirely. If a user doesn't have access to the /workflows/list page, they will receive a 403 Forbidden error even if they try to guess the URL.
3. Use Page Objects for Granular UI Control: Use Role-PageObject Management to hide specific buttons on a page. For example, give all managers access to the process instances page, but use the instance.stop Page Object to ensure only Senior Managers see the "Stop Instance" button.

Common Administrative Workflows

1. Onboarding a New Department

When a new team (e.g., Marketing) starts using Workingflow, follow this sequence:

1. Go to Role Management and create ROLE_MARKETING.
2. Go to Role-Page Management and grant ROLE_MARKETING access to the core pages (/workflows/list, /tasks/my, /instances/my-active).
3. Go to User Management and map ROLE_MARKETING to the new employees.
4. Go to Process Roles and give ROLE_MARKETING permission to start the "Marketing Campaign Approval" workflow.

2. Troubleshooting: "I can't see the workflow!"

If a user complains that they cannot see a specific workflow in their "Start Workflow" list, check these three things:

• Check 1: Do they actually have the correct role? (Verify in User-Role Management)
• Check 2: Does their role have access to the /workflows/list and /workflows/{id}/start pages? (Verify in Role-Page Management)
• Check 3: Is the workflow explicitly mapped to their role? (Verify in Process Roles). Note: If a workflow has zero roles assigned to it, nobody can start it!

3. Monitoring System Health

As an administrator, your daily/weekly routine should involve checking the health of the engine:

• Engine Admin (/admin/engine): Check for Stuck Tasks. If a Script Task failed because of a typo in your Javascript, the task will pause and appear here. You can fix the BPMN script and click "Retry" directly from this console. You should also monitor Deadletter Jobs for permanently failed background tasks.
• Error Logs (/admin/error-logs): Review unhandled Java exceptions. The Smart Summary feature will automatically scan the StackTrace and attempt to pinpoint the exact line of code or missing BPMN variable that caused the crash, saving you hours of debugging.

Admin Screens Reference

• User Management (/admin/users): Search, enable, disable, or delete user accounts. (Disabled users cannot log in).
• Role Management (/admin/roles): Create and delete arbitrary role labels.
• User-Role Assignment (/admin/user-role): Assign roles to users. A user's effective permissions are the union of all their assigned roles.
• Role-Page Management (/admin/role-page): Map roles to specific URL endpoints.
• Role-PageObject Management (/admin/role-pageobject): Map roles to specific UI elements (like buttons).
• Process Roles (/admin/process-roles): Control which roles are allowed to start specific workflows.
• System Settings (/admin/settings): Configure email language (en or tr) and email sender display names.
• HTTP Connectors (/admin/connectors): Manage external API integrations for Service Tasks.
• Tag Management (/admin/tags): Create colored badges to categorize workflows.
• API Keys (/admin/api-keys): Generate and revoke wf_ prefixed tokens for REST API access.
• Scheduled Workflows (/admin/schedules): Manage background cron jobs that automatically trigger workflows.