Role selection & management guide

Documentation Navigation:

Workspaces Access Rights - Role overview and concepts
Complete Permissions Matrix - Detailed permission specifications
Permission Reference Guide - Technical implementation details
Role Selection Guide (Current) - Practical scenarios and best practices

This guide helps you choose the appropriate roles for different users based on their responsibilities, expertise, and access requirements.

Role selection decision tree

Use this decision tree to quickly identify the appropriate role:

Role selection by persona

Platform administrators

Organization Administrator

Role: org_adminTypical Responsibilities:

Managing the entire FlowX platform
Creating and organizing workspaces
Managing organization-wide users and groups
Overseeing system health and configurations
Implementing organization-wide policies

Example Users:

Platform administrators
IT managers
System architects

Key Considerations:

Assign sparingly - only to users needing cross-workspace access
Has access to ALL projects across ALL workspaces
Should be limited to 2-3 trusted individuals

Business unit managers

Workspace Administrator

Role: workspace_adminTypical Responsibilities:

Managing workspace users and access
Overseeing all workspace projects
Managing workspace themes and branding
Configuring workspace-level settings
Handling workspace resource allocation

Example Users:

Department heads
Business unit managers
Team leads with administrative duties

Key Considerations:

Has admin access to all projects in their workspace
Cannot access other workspaces without explicit assignment
Should be assigned to responsible leaders only

Developers and configurators

Project Owner

Role: project_ownerAssignment: Automatic (assigned to project creator)Typical Responsibilities:

Complete project governance
Managing project team access
Final approval on project changes
Project lifecycle management

Example Users:

Project leads
Technical architects
Product owners

Key Considerations:

Automatically assigned at project creation
Can transfer ownership to another user
Only one owner per project

Project Editor

Role: project_editorTypical Responsibilities:

Building and configuring processes
Designing workflows
Creating UI configurations
Managing integrations
Creating builds and deployments

Example Users:

Senior developers
Business analysts
Technical configurators

Key Considerations:

Full configuration access without ownership
Cannot grant/revoke project access
Standard role for project team members

Runtime Policy Access:

Configurators who need to change active policy should be assigned workspace_runtime_editor role in their workspace
Even if they only have project_viewer access on specific projects, the workspace-level runtime role allows policy changes

Specialized roles

UI/UX Designer

Role: theme_editorTypical Responsibilities:

Designing application themes
Managing brand assets
Creating and organizing fonts
Managing media library
Ensuring visual consistency

Example Users:

UI/UX designers
Brand managers
Visual designers
Marketing team members

Key Considerations:

Extends workspace_user with design permissions
Can create projects but focused on visual aspects
Read-only for projects without explicit access

DevOps Engineer

Role: workspace_runtime_editorTypical Responsibilities:

Creating and managing builds
Configuring runtime environments
Managing deployment policies
Overriding configuration parameters
Monitoring process instances

Example Users:

DevOps engineers
Release managers
Technical operations staff
System administrators

Key Considerations:

Extends workspace_user with runtime permissions
Can manage deployments across workspace
Does not grant automatic project configuration access

Operations Engineer

Role: workspace_operations_editorTypical Responsibilities:

Managing process instance operations (migration & move token)
Editing process variables on active instances
Managing operational tasks across the workspace
Supporting process migrations and token movements

Example Users:

Support engineers
Operations team members
Technical support staff
Process operations managers

Key Considerations:

Extends workspace_user with operations permissions
Can manage operations across workspace
Does not include broader runtime capabilities (builds, policies)
Available starting in FlowX 5.3

Stakeholders and reviewers

General Workspace User

Role: workspace_userTypical Responsibilities:

Creating new projects
Working on assigned projects
Viewing workspace resources
Basic workspace participation

Example Users:

Junior developers
Business analysts
Process designers
General team members

Key Considerations:

Default role for most workspace members
Can create projects (becomes owner automatically)
Needs explicit project access to work on others’ projects

Viewer / Auditor

Role: project_viewerTypical Responsibilities:

Reviewing project configurations
Auditing processes and workflows
Compliance checking
Documentation and training

Example Users:

Business stakeholders
Quality assurance personnel
Compliance officers
External consultants
New team members (onboarding)

Key Considerations:

Completely read-only access
Can test processes through interface
Safe for sensitive stakeholders

Common role assignment scenarios

Scenario 1: New employee onboarding

Day 1: View-only access

Assign workspace_user role at workspace levelGrant project_viewer role for relevant projectsRationale: Allow new employee to explore and learn without risk

Week 2-4: Limited editing

Grant project_editor role for specific training projectsKeep viewer access for production projectsRationale: Hands-on learning in safe environment

After onboarding: Full access

Grant project_editor role for assigned projectsRemove training project accessRationale: Ready for production work with appropriate permissions

Scenario 2: External consultant engagement

Short-term review (1-2 weeks)

Recommended Role: project_viewerAccess Pattern:

Grant access only to specific projects under review
No workspace-level role assignment
Time-bound access (remove after engagement)

Benefits:

Complete visibility for review purposes
No risk of accidental modifications
Easy to audit consultant’s activities

Implementation project (3-6 months)

Recommended Roles:

Workspace level: workspace_user
Project level: project_editor for specific projects

Access Pattern:

Create dedicated workspace for consultant projects
Grant editor access only to contracted projects
Regular access reviews during engagement

Benefits:

Consultant can work independently
Clear boundaries on accessible projects
Easy cleanup after engagement ends

Long-term partnership (6+ months)

Recommended Roles:

Workspace level: workspace_user or specialized role
Project level: project_editor or project_owner as needed

Access Pattern:

Treat similar to internal team member
Consider dedicated workspace for partner projects
Quarterly access reviews and adjustments

Benefits:

Full integration with team workflows
Appropriate access for extended engagement
Maintains security through regular reviews

Scenario 3: Cross-functional team project

Small Project (2-5 people)
Medium Project (5-15 people)
Large Project (15+ people)

Team Composition:

1 Project Owner (automatically assigned to creator)
2-3 Project Editors (developers/analysts)
1 Project Viewer (stakeholder)

Access Setup:

Creator starts project → becomes project_owner
Grant project_editor to development team
Grant project_viewer to business stakeholder
Use "Everyone in workspace" group if all team members need access

Best Practices:

Keep team small and roles simple
Regular sync meetings reduce need for complex permissions
Document decisions in project comments

Team Composition:

1 Project Owner (technical lead)
5-8 Project Editors (developers, analysts, designers)
1 Theme Editor (UI/UX specialist)
2-3 Project Viewers (stakeholders, QA)
1 Runtime Editor (DevOps)

Access Setup:

1. Create workspace groups:
   - "ProjectName_Developers" → project_editor
   - "ProjectName_Stakeholders" → project_viewer
2. Assign specialized workspace roles as needed
3. Use groups for bulk permission management

Best Practices:

Use groups instead of individual assignments
Regular access reviews (monthly)
Document group purposes clearly

Team Composition:

1 Project Owner (product owner/architect)
10-15 Project Editors (multiple teams)
2-3 Theme Editors (design team)
1-2 Runtime Editors (DevOps team)
5-8 Project Viewers (stakeholders, compliance, QA)

Access Setup:

1. Create hierarchical groups:
   - "ProjectName_Core_Team" → project_editor
   - "ProjectName_Design_Team" → theme_editor + project_editor
   - "ProjectName_DevOps_Team" → runtime_editor + project_editor
   - "ProjectName_Stakeholders" → project_viewer
2. Use workspace admin to manage groups centrally
3. Implement approval workflow for access requests

Best Practices:

Dedicated workspace admin for project
Automated access reviews (bi-weekly)
Clear escalation path for access issues
Document architecture decisions and ownership

Scenario 4: Multi-workspace organization

Enterprise Organization Structure

Organizational Setup:Organization Level:

2-3 org_admin (Platform administrators)

Workspace Level (per business unit):

1 workspace_admin (Business unit manager)
15-30 workspace_user (Standard members)
2-3 theme_editor (Design team)
1-2 workspace_runtime_editor (DevOps team)
1-2 workspace_operations_editor (Operations/Support team)

Project Level (varies by project):

Projects follow patterns from Scenario 3

Access Patterns:

Each business unit has dedicated workspace
Cross-workspace collaboration via library sharing
Central DevOps team has runtime_editor in all workspaces
Central design team has theme_editor in relevant workspaces
Central operations team has operations_editor for process management

Governance:

Monthly access reviews by workspace_admin
Quarterly organization-wide audit by org_admin
Automated alerts for inactive users
Clear documentation of cross-workspace access

Role escalation matrix

When should you upgrade a user’s role?

Current Role	Escalate To	Trigger Conditions	Approval Required
`project_viewer`	`project_editor`	User needs to make configuration changes Completed onboarding period	Project Owner
`workspace_user`	`theme_editor`	User assigned to design responsibilities Demonstrated design skills	Workspace Admin
`workspace_user`	`runtime_editor`	User assigned to DevOps responsibilities Deployment management needed	Workspace Admin
`workspace_user`	`operations_editor`	User assigned to operations responsibilities Process migration needs	Workspace Admin
`project_editor`	`project_owner`	Original owner leaving User taking over project leadership	Current Owner or Workspace Admin
`workspace_user`	`workspace_admin`	User promoted to management Administrative duties assigned	Organization Admin
`workspace_admin`	`org_admin`	User taking platform-wide responsibilities Multi-workspace management	Existing Org Admin + Management

Always follow the principle of least privilege. Escalate roles only when necessary and document the business justification.

Role de-escalation and removal

When to downgrade roles

Project Completion

Scenario: Project is completed and moved to maintenanceAction:

Downgrade most project_editor to project_viewer
Keep 1-2 editors for maintenance
Keep project_owner for governance

Timing: At project completion milestone

Role Change

Scenario: User moves to different team or responsibilitiesAction:

Remove access to old projects
Assign appropriate role for new responsibilities
Transfer project_owner if applicable

Timing: During role transition period

Contractor End

Scenario: Contractor engagement endsAction:

Remove all workspace access
Document contractor’s contributions
Archive or transfer project ownership if needed

Timing: On contractor’s last day

Security Incident

Scenario: Suspicious activity or policy violationAction:

Immediate suspension of access
Investigation by security/admin team
Appropriate remediation based on findings

Timing: Immediately upon detection

Access removal checklist

Identify all access points

List all workspaces user has access to
Identify all projects with direct access
Check group memberships
Review project ownership assignments

Transfer ownership

Transfer project_owner role if user owns projects
Update project documentation with new owner
Notify project stakeholders of change

Remove access

Remove from workspace-level roles
Remove from project-level access
Remove from all groups
Verify removal in system

Document and communicate

Document reason for removal
Update team rosters and directories
Communicate changes to affected teams
Archive for compliance if needed

Role assignment anti-patterns

Avoid these common mistakes when assigning roles:

Anti-pattern 1: Everyone is an admin

Problem:

Assigning workspace_admin or org_admin to too many users
“Just in case” administrative access

Impact:

Reduced security and accountability
Increased risk of accidental changes
Difficult to audit who made changes

Solution:

Limit admin roles to actual administrators
Use project_editor or project_owner for project-level needs
Implement proper access request workflow

Anti-pattern 2: Never updating roles

Problem:

Roles assigned during onboarding never reviewed
Users retain access after role changes
Inactive users still have full access

Impact:

Security vulnerabilities accumulate
Compliance issues with access audits
Potential data breaches

Solution:

Quarterly access reviews
Automated inactive user detection
Role-based access recertification

Anti-pattern 3: Individual assignments instead of groups

Problem:

Assigning roles to individual users instead of groups
Not using the “Everyone in workspace” group
Managing access one user at a time

Impact:

High administrative overhead
Inconsistent access patterns
Difficult to scale

Solution:

Create groups for teams and functions
Use groups for project access
Individual assignments only for exceptions

Anti-pattern 4: Too granular or too broad

Problem:

Creating overly complex permission structures
OR giving everyone the same high-level access

Impact:

Confusion about who can do what
Either too restrictive or too permissive
Difficult to maintain

Solution:

Start with predefined roles
Use workspace/project boundaries naturally
Add granularity only when truly needed

Anti-pattern 5: No documentation

Problem:

Access decisions not documented
No record of why users have certain roles
No clear ownership of access management

Impact:

Cannot audit access decisions
Difficult to troubleshoot access issues
Compliance problems

Solution:

Document all non-standard role assignments
Maintain role assignment justifications
Clear ownership of access management process

Groups and access management

FlowX uses groups to simplify access management across users. Understanding built-in groups and creating custom groups efficiently manages permissions at scale.

Built-in workspace groups

Everyone in workspace group

Every workspace automatically includes a special system-managed group for all workspace members:

all_users_[workspace_name]

Display Name in UI: Everyone from <workspace name>Purpose: Provides convenient access management for all users associated with a workspace.Automatic Behavior:

Created automatically during workspace provisioning
Cannot be edited, deleted, or duplicated
Users automatically added when granted workspace access (direct or through another group)
Users automatically removed when workspace access is revoked
Pre-selected by default when creating new projects/libraries
Appears in user/group search results when granting project access

Common Use Cases:

Grant all workspace members read access to reference projects
Provide baseline visibility across all workspace projects
Simplify onboarding by giving new users automatic access to shared resources
Create workspace-wide announcements or shared libraries

Example:

Workspace: "Product Development"
Auto-created group: "all_users_product_development"
Display name: "Everyone from Product Development"

When creating a new project in “Product Development” workspace, the group “Everyone from Product Development” appears pre-selected, allowing immediate assignment of a role (viewer, editor, etc.) to all workspace members.

Cannot Exclude Individual MembersThe “Everyone in workspace” group includes ALL workspace members without exception. You cannot:

Remove specific users from this group
Create exceptions or exclusions
Modify group membership manually

If you need selective access, create custom groups for specific teams or roles.

Custom groups

Creating Groups
Managing Groups
Group Strategies

When to create custom groups

Create custom groups when you need:

Team-based access (e.g., “Development Team”, “QA Team”)
Role-based access (e.g., “Senior Developers”, “Stakeholders”)
Project-specific access (e.g., “Project Alpha Team”)
Cross-functional teams (e.g., “Release Management”, “Architecture Board”)

Group creation best practices

Plan group structure

Identify natural team boundaries and access patterns before creating groups.Good Examples:

dev_team_frontend
stakeholders_finance_dept
project_phoenix_core_team

Poor Examples:

random_users
temp_group_1
johns_team (too specific, not transferable)

Use descriptive names

Group names should clearly indicate purpose and membership.Naming Convention: [function]_[department/project]_[sub-group]Examples:

developers_mobile_ios
viewers_executive_leadership
editors_project_migration

Document group purpose

Add clear descriptions explaining:

Who should be members
What access the group provides
When to use the group for access grants

Assign appropriate permissions

Grant groups workspace-level roles, then use groups when assigning project access:

Create group: "Mobile Development Team"
Add members: All mobile developers
Grant workspace role: workspace_user
Use group for project access: Grant project_editor to "Mobile Development Team" on mobile projects

Access patterns using groups

Pattern 1: Hierarchical Teams

all_users_product_development (workspace)
├── team_backend_developers
├── team_frontend_developers
├── team_qa_engineers
└── team_product_owners

Each sub-group receives different project roles based on responsibilities.Pattern 2: Project-Based Groups

project_alpha_core_team → project_editor
project_alpha_stakeholders → project_viewer
project_alpha_devops → project_editor + workspace_runtime_editor
project_alpha_operations → project_viewer + workspace_operations_editor

Groups organized around specific projects for clear access boundaries.Pattern 3: Cross-Functional Groups

architecture_review_board → project_viewer on all projects
release_management_team → workspace_runtime_editor
security_team → project_viewer + audit access

Groups that span multiple projects with specialized access needs.Pattern 4: External Collaboration

external_consultants_acme → project_editor on assigned projects only
external_auditors_bigfour → project_viewer on compliance projects
partners_vendor_xyz → project_viewer on integration projects

Separate groups for external parties with time-bound access.

Group vs. individual assignment decision matrix

Scenario	Use Group	Use Individual Assignment
5+ users need same access	✅ Yes	❌ No
Access pattern is temporary (< 1 month)	❌ No	✅ Yes
Access follows team structure	✅ Yes	❌ No
One-off exception for specific user	❌ No	✅ Yes
Access will change frequently	❌ No	✅ Yes
Multiple projects need same team access	✅ Yes	❌ No
Executive/stakeholder with unique access	❌ No	✅ Yes
New team being formed	✅ Yes	❌ No

Troubleshooting permission issues

Common permission-related issues and their solutions. Use this guide to quickly diagnose and resolve access problems.

Common error scenarios

Error: "Cannot see Projects menu"

Symptoms:

Projects menu entry not visible
Workspace appears empty
Cannot navigate to any projects

Possible Causes:

No workspace access granted
Missing workspace_read permission
Not a member of any workspace

Solutions:

Verify workspace membership

Check if user has been granted access to the workspace:

Contact workspace administrator
Verify user appears in workspace Users list
Check group membership if access is group-based

Confirm workspace role

User needs at minimum workspace_user role:

Review user’s assigned roles in workspace
Verify workspace_read permission is included
If missing, workspace admin should assign appropriate role

Clear cache and re-login

Sometimes permissions don’t update immediately:

Log out of FlowX Designer
Clear browser cache
Log back in
Check if Projects menu now appears

Error: "Can see project but cannot edit"

Symptoms:

Project appears in list
Can open project but all controls disabled
Configure shows as “View” instead
No Save buttons visible

Possible Causes:

Have project_viewer role instead of project_editor
Have read-only permissions on project
Project is locked or archived

Solutions:

Check project role

Verify assigned project role:

Open project
Look for edit controls (should be hidden if viewer)
Check contextual menu (Configure vs View)

Request role upgrade

Contact project owner to grant edit access:

Identify project owner (automatic creator or transferred owner)
Request project_editor role
Provide business justification for edit access

Verify project status

Ensure project is active:

Check if project is archived
Verify project version is editable
Confirm no system locks in place

Error: "Cannot create builds"

Symptoms:

No “Create build” button visible
Import build action missing
Runtime menu entries not accessible

Possible Causes:

Missing wks_builds_create permission
Don’t have workspace_runtime_editor role
Workspace-level runtime access not granted

Solutions:

Request runtime access

Contact workspace administrator:

Explain need for build creation
Request workspace_runtime_editor role
Alternative: Request specific wks_builds_create permission

Understand scope change

Note that runtime permissions moved to workspace level in v5.0:

Old: Per-project runtime access
New: Workspace-wide runtime access
May need different permission strategy

Error: "User added to group but still no access"

Symptoms:

User appears in group membership list
User still cannot access expected resources
Group-based permissions not applying

Possible Causes:

Group not assigned to project
Group has insufficient permissions
Permission cache not refreshed
Individual permission overrides group

Solutions:

Verify group assignments

Check where group is used:

Check project-level access for group
Verify group has appropriate roles assigned

Check permission hierarchy

Understand permission precedence:

Individual permissions may override group
Multiple groups combine permissions
A user’s permissions in the context of a project is the reunion of their permissions given though groups or individual assignments

Force refresh

Clear permission cache:

User logs out completely
Clear browser cache and cookies
User logs back in
Permissions should refresh from backend

Review group role

Ensure group has correct role:

Check group’s workspace-level role
Verify group’s project-level role
Confirm role includes needed permissions

Error: "Project owner left, cannot manage access"

Symptoms:

Original project owner no longer with organization
Cannot grant/revoke project access
Project governance blocked

Possible Causes:

Project ownership not transferred
No other users have admin rights on project
Workspace admin access not configured

Solutions:

Contact workspace administrator

Workspace admin can help:

Has projects_admin permission
Can grant access to projects
Can help identify new owner

Transfer project ownership

Workspace admin or org admin can:

Assign new project owner
Transfer governance rights
Update project documentation

Prevent future issues

Implement ownership best practices:

Always have 2+ users with project_editor minimum
Document ownership succession plan
Review project ownership quarterly
Assign workspace admin as backup owner for critical projects

Best practices summary

Start Conservative

Begin with project_viewer or workspace_user and escalate as needed based on demonstrated needs

Use Groups

Create and use groups for teams and functions rather than managing individual user access

Regular Reviews

Quarterly access reviews, remove inactive users, validate permissions match responsibilities

Document Decisions

Maintain records of role assignments, especially for elevated privileges and exceptions

Use Automation

Use group memberships and role inheritance to reduce manual access management

Plan for Transitions

Have clear processes for role changes, project ownership transfers, and access removal

Keycloak roles vs Designer roles

FlowX uses two separate role systems. Understanding the difference prevents common confusion:

Aspect	Keycloak realm roles	FlowX Designer roles
Managed in	Keycloak Admin Console	FlowX Designer (Workspaces)
Purpose	Service authentication, runtime process access	Designer UI access, project permissions
Assigned to	Users and service accounts	Users and groups within workspaces
Examples	`SA_FLOWX`, `default-roles-flowx`	`org_admin`, `workspace_admin`, `project_editor`

Keycloak realm roles quick reference

Role	Purpose	Who needs it
`SA_FLOWX`	Service account role. Identifies FlowX platform services for inter-service communication.	Service accounts only, not human users
`default-roles-flowx`	Default realm role automatically assigned to new users in the FlowX Keycloak realm.	All users (assigned automatically)

In FlowX 4.x, roles like FLOWX_ADMIN, FLOWX_CONFIGURATOR, and FLOWX_VIEWER were Keycloak realm roles that controlled Designer access. In FlowX 5.0+, these have been replaced by the Designer role system (workspace_admin, project_editor, etc.). See the migration mapping for the full conversion table.

Do not confuse Keycloak realm roles with FlowX Designer roles. Assigning a user workspace_admin in Keycloak has no effect — it must be assigned through the FlowX Designer interface. Keycloak only handles authentication (login), while Designer handles authorization (what you can access).

Workspaces Access Rights

Overview of FlowX workspace access rights and role hierarchy

Complete Permissions Matrix

Detailed permission matrices for all FlowX roles

Permission Reference Guide

Technical implementation details, UI mappings, and naming conventions

Access Management Overview

Overview of FlowX access management system

Configuring IAM Solution

Setting up identity and access management

Workspaces

Understanding workspaces and organizing projects

Microservices

Plugins

Observability

Access management

​Role selection decision tree

​Role selection by persona

​Platform administrators

Organization Administrator

​Business unit managers

Workspace Administrator

​Developers and configurators

Project Owner

Project Editor

​Specialized roles

UI/UX Designer

DevOps Engineer

Operations Engineer

​Stakeholders and reviewers

General Workspace User

Viewer / Auditor

​Common role assignment scenarios

​Scenario 1: New employee onboarding

​Scenario 2: External consultant engagement

​Scenario 3: Cross-functional team project

​Scenario 4: Multi-workspace organization

Enterprise Organization Structure

​Role escalation matrix

​Role de-escalation and removal

​When to downgrade roles

​Access removal checklist

​Role assignment anti-patterns

​Anti-pattern 1: Everyone is an admin

​Anti-pattern 2: Never updating roles

​Anti-pattern 3: Individual assignments instead of groups

​Anti-pattern 4: Too granular or too broad

​Anti-pattern 5: No documentation

​Groups and access management

​Built-in workspace groups

​Everyone in workspace group

all_users_[workspace_name]

​Custom groups

​When to create custom groups

​Group creation best practices

​Group lifecycle management

​Access patterns using groups

​Group vs. individual assignment decision matrix

​Troubleshooting permission issues

​Common error scenarios

​Best practices summary

Start Conservative

Use Groups

Regular Reviews

Document Decisions

Use Automation

Plan for Transitions

​Keycloak roles vs Designer roles

​Keycloak realm roles quick reference

​Related documentation

Workspaces Access Rights

Complete Permissions Matrix

Permission Reference Guide

Access Management Overview

Configuring IAM Solution

Workspaces

Role selection decision tree

Role selection by persona

Platform administrators

Business unit managers

Developers and configurators

Specialized roles

Stakeholders and reviewers

Common role assignment scenarios

Scenario 1: New employee onboarding

Scenario 2: External consultant engagement

Scenario 3: Cross-functional team project

Scenario 4: Multi-workspace organization

Role escalation matrix

Role de-escalation and removal

When to downgrade roles

Access removal checklist

Role assignment anti-patterns

Anti-pattern 1: Everyone is an admin

Anti-pattern 2: Never updating roles

Anti-pattern 3: Individual assignments instead of groups

Anti-pattern 4: Too granular or too broad

Anti-pattern 5: No documentation

Groups and access management

Built-in workspace groups

Everyone in workspace group

Custom groups

When to create custom groups

Group creation best practices

Group lifecycle management

Access patterns using groups

Group vs. individual assignment decision matrix

Troubleshooting permission issues

Common error scenarios

Best practices summary

Keycloak roles vs Designer roles

Keycloak realm roles quick reference

Related documentation