Workspaces multi-tenant architecture
Scope: New access management and permission mechanism applies only to FlowX Designer access. Runtime permissions through Keycloak roles (at process level) remain unchanged.

​
Key benefits

Faster Onboarding

Onboard new business verticals in days instead of weeks with shared platform capabilities

Data Isolation

Provide secure separation between different business contexts while allowing controlled resource sharing

Enhanced Access Control

Implement granular permissions with role-based access control (RBAC) and access control lists (ACLs)

​
Key concepts

​
Workspace

A workspace is a logical grouping of entities and assets defined in FlowX that are only available to a subset of users who are given explicit access. Each workspace operates independently, ensuring data and configuration separation between different business contexts.

​
Multi-workspace user access

Users can be granted access to multiple workspaces and can switch between them as needed. When a user has access to multiple workspaces, they can select which workspace to enter after authentication.

​
Data isolation

Workspaces provide logical data isolation, meaning that resources (projects, libraries, themes, etc.) are scoped to specific workspaces and cannot be accessed from other workspaces without explicit sharing configurations.

​
Additional terminology

  • Group: A collection of users who share common characteristics, responsibilities, or access needs within a system. Groups are used to simplify access control by managing permissions collectively rather than assigning them individually to each user.
  • Permissions: Define what actions can be performed on resources. They are fine-grained access controls that specify privileges for a resource type, such as: read process, edit process, delete process.
  • Roles: Collections of permissions grouped together based on job functions or responsibilities. They simplify permission management by assigning a set of permissions to users instead of managing them individually.
Role assignment rule: Roles are never assigned directly to users or groups. A user or group is assigned a role ONLY when given access to a workspace OR a project/library. Exception: org_admin role is the only one assigned to users directly at the organization level.
When a user has multiple roles assigned in the context of a workspace or project, their access level is the union of all permissions from all roles associated with the user.

​
Workspace use cases

​
How workspaces work

​
Authentication and access flow

1

User Authentication

User logs in using OAuth 2.0 through the configured identity provider (Keycloak or client’s existing provider). Authenticated users are saved with subject ID in FlowX database.
2

Permission Retrieval

System fetches the user’s workspace permissions and available workspaces
3

Workspace Selection

If user has access to multiple workspaces, they select which workspace to enter
4

Context Loading

FlowX Designer loads with workspace-specific content, projects, and permissions

​
Resource management

Complete Separation: Projects cannot be exported from one workspace to another on the same environmentWorkspace Scoping: Each project is tagged with its workspace ID and only accessible within that workspaceIndependent Lifecycle: Projects in different workspaces can have the same names and follow independent versioningCritical Constraint: Having the same project or library configuration in multiple workspaces on the same FlowX instance is NOT permittedImport Behavior: Projects created from version or build import are created with access only for the currently logged in user with ‘Project Owner’ role. Workspace admins are also able to view projects. Access can be extended to required users subsequently.Runtime Permissions: Permissions for Runtime section are received by users with workspace role. Users inherit runtime permissions from workspace role for ALL projects/libraries they have access to.

​
Additional workspace features

​
Command Center (AI Agents)

AI Agents permission is a project level permission starting in FlowX 5.0 release. Consequence: Command center will be available only on projects or libraries pages.

​
Audit Logs

Audit log entry in main menu for every workspace will be available only for users with Workspace Admin role. The reason for this is that global audit log includes all logs for all projects/libraries in workspace.
In FlowX 5.0 release, audit logs for Workspace management, User management at ORG level, Workspace groups are not implemented. Feature will be included in FlowX 5.1 release.

​
Out of Office

Entries will be able to be added by organization admins for all users in organization. At workspace level, Workspace Admin users can add/modify entries only for workspace users.
In FlowX 5.0 release, Out of office is not available. Feature will be included in FlowX 5.1 release.

​
Access control

​
Role-based access control (RBAC)

Predefined Roles

  • admin - Full workspace administration
  • configurator - Project and process configuration
  • ui_ux_designer - Interface design capabilities
  • project_viewer - Read-only project access

Workspace-Specific

Roles are specific to each workspace - a user can have different roles in different workspaces
In FlowX 5.0 release, only pre-defined roles will be available to use for workspace and project/library access.

​
Detailed role permissions

Workspace admin: Manages all workspace level resources including users, roles, themes. Can configure access and content, but cannot manage organization-wide settings.
Workspace admins will be able to view and edit ALL projects and libraries in workspace, regardless of project/library access settings.
Workspace user: View only access to workspace entities. Can create projects, but only sees projects they have explicit access to. Theme editor: Extends workspace user role to include permissions to manage themes and associated resources (global media files).

​
User groups

User groups simplify permission management by allowing you to assign permissions to groups rather than individual users.
  • Default Groups: Each workspace includes an “Everyone in workspace” default group
  • Custom Groups: Create groups based on teams, departments, or project requirements
  • Inherited Permissions: Users automatically inherit permissions from their group memberships

​
Access control lists (ACLs)

​
Organization administration

​
Organization admin role

The org_admin role is the only role assigned directly to users at the organization level, not workspace level.
Organization admins will be able to see all workspaces and have the same permissions as Workspace Admins inside each workspace. Multiple users can have this role assigned. Role can be assigned/revoked by other org admins.

​
User management

Users are created in FlowX only after their first login in FlowX Designer.
Organization users page lists only users created in FlowX (after first login or manually created by organization admins). User details page shows Workspace access summary.

​
Onboarding a new user in FlowX

Users synced from customer’s LDAP are not automatically created in FlowX. Steps to onboard a new team member:
  1. User logs into FlowX Designer.
  2. They are redirected to a ‘No workspace assigned’ page.
  3. User is now created in FlowX and available in the Users list in Organization Settings section.
  4. An organization admin assigns access to the user to the corresponding workspace(s) with needed role (Workspace user, Workspace Admin or Theme editor).
  5. With the next login, user will have access to selected workspaces.

​
Creating a user from FlowX Designer

Feature works only if Keycloak is the authentication provider. Helpful for internal use, but rarely used by customers. Note: might not be available in FlowX 5.0. If there is a need to create users, they need to be created directly in Keycloak.
When user is created using the + icon, the user is saved in Keycloak and FlowX designer. After successfully adding user, organization admins can immediately assign user to workspaces.

​
Additional organization settings

​
Runtime roles and groups

Legacy Roles and Groups pages (for managing roles and groups only in Keycloak) are accessible in Organization Settings section and renamed Runtime Roles and Runtime Groups. Will be used going forward to manage any roles needed for process permission configuration.
All workspaces will share the same list of runtime roles and groups.
If Keycloak is not used as authentication provider, Runtime Roles and Runtime Groups pages will return errors in FlowX 5.0.

​
Set environment info

Configuring client and environment information is available only in Organization settings section under Platform status page.

​
Workspace management

​
Creating and managing workspaces

1

Admin Access Required

Only users with organization administrator permissions can create new workspaces
2

Workspace Configuration

Set workspace name, description, and basic settings during creation
3

Automatic Setup

System automatically creates default roles and groups for the new workspace
4

User Assignment

Add initial users and assign appropriate roles to get started
Deleting a workspace is not available in FlowX 5.0.

​
User management within workspaces

  • Direct Assignment: Add users directly to workspace with specific roles
  • Group Membership: Add users to groups that inherit workspace permissions
  • Multi-Workspace Access: Users can be members of multiple workspaces

​
Migration and compatibility

​
Initial setup requirements

Critical Setup Step: Before starting any FlowX 5.0 environment, the initial organization admin must be configured.
  1. To create the first user in FlowX Designer with organization admin role, an environment variable SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME needs to be configured with the username of the user from Identity Store (Keycloak/ other Identity Store from where the users are used to login in FlowX.AI).
  2. If request to Keycloak fails, the fallback is to use SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID to create the organization admin user. Value that must be set is the subject identifier. (sub in JWT token OR user’s id in Keycloak).
This step is important for creating any environment, no matter if there’s a pre-existing env or a newly created one.
IMPORTANT: Instruct DeevOps team to set this user id BEFORE system startup. Otherwise the authorization-service startup will fail. Ensure the correct value is set. The correct value is the subject id of the user, value that will be populated by the authorization service in the access token used for FlowX login.

​
For existing FlowX customers

When upgrading to FlowX 5.0, a default workspace is automatically created containing all your existing resources.
What Happens During Migration:
  • All existing projects, libraries, and themes are moved to a default workspace
  • All existing functionality continues to work without changes
Default workspace details:
  • Name: “Default workspace” (can be changed following the migration)
  • UUID: “00000000-0000-0000-0000-000000000001”
What gets migrated:
  • All active process instances will be migrated under default workspace
  • Failed process start instances migration
  • Workflow instances migration
  • Scheduled processes migration
  • Audit logs migration
Out of office and Fonts will not be migrated under default workspace, as they are managed at organization level.
For clients who need inactive process instances migrated, we’ll provide migration script which will be run post migration.
Post-migration manual steps:
Important: Existing users will not be migrated; they will need to log into FlowX so that their user is created.
  • Organization admin will need to provide individual access to workspace for each user
  • Access to projects and libraries should be additionally configured as per workspace requirements
  • Existing admin roles and groups used for FlowX Designer access are deprecated and should be removed post-migration from Keycloak
Step is optional, but encouraged so that the role list for runtime permissions is manageable. List of deprecated roles (which can be removed) will be provided in documentation.

​
For new FlowX 5.0 installations

New FlowX 5.0 environments do not include a default workspace. Initial setup is required.
Initial Setup Process:
  1. Configure the first workspace administrator user
  2. Create the initial workspace
  3. Set up users and role assignments
  4. Begin creating projects and processes

​
Best practices

​
Workspace design

Clear Boundaries

Define workspaces based on clear business, regulatory, or organizational boundaries

Naming Conventions

Use consistent naming conventions for workspaces, roles, and resources

Documentation

Document workspace purposes, user access patterns, and governance policies

Scalability Planning

Plan workspace structure to accommodate future growth and organizational changes

​
Permission management

  • Principle of Least Privilege: Grant minimum necessary permissions
  • Group-Based Management: Use groups for permission management rather than individual assignments
  • Regular Audits: Periodically review and audit workspace permissions
  • Clear Ownership: Establish clear ownership models for workspace resources

​
Resource sharing

  • Controlled Sharing: Implement clear policies for resource sharing between workspaces
  • Dependency Management: Track and manage dependencies between shared resources
  • Version Control: Maintain version control for shared libraries and themes

​
Common use cases

​
Limitations and considerations

​
Current limitations

Cross-Workspace Project Export: Projects cannot be exported from one workspace to another on the same environment.
  • Resource Isolation: Direct access to resources from other workspaces is not possible
  • Single Environment Sharing: Library sharing only works within the same FlowX environment
  • Permission Inheritance: Workspace permissions don’t automatically inherit across workspace boundaries

​
FlowX 5.0 specific limitations

Additional limitations in FlowX 5.0 release:
  • Move projects or libraries to another workspace feature is not available. Initially (when upgrading to FlowX 5.0), all existing projects and libraries are migrated to Default Workspace.
  • Workspace import/export is out of scope; each FlowX environment will have a default workspace configured initially and workspaces are managed independently on each instance.
  • Transfer project/library ownership feature will be delivered in 5.1 release.

​
Planning considerations

  • Change Management: Organizational alignment needed for governance models
  • User Training: Users need to understand workspace selection and navigation
  • Governance Policies: Clear policies needed for resource sharing and access management
  • Migration Planning: Existing customers should plan workspace structure before creating additional workspaces