Skip to main content
Version: 1.6.x

Generic Roles

Regular roles are permission management components based on the RBAC model, providing a complete solution for role definition, permission assignment, and member binding. They handle user permission control, API access authorization, and portal access management, supporting role inheritance, permission composition, and hierarchical authorization mechanisms, with deep integration with organizational architecture to achieve enterprise-level permission control.

The hierarchical structure of regular role elements is Meta (roles.Meta) → Type (roles.NormalType) → Instance. Developers can quickly create regular role instance elements through JitAI's visual development tools.

Of course, developers can also create their own Type elements or modify the official roles.NormalType element provided by JitAI in their own App to implement their own encapsulation.

Quick Start​

Creating Instance Elements​

Directory Structure​

Recommended Directory Structure
roles/
├── developer/              # Role instance directory (path customizable)
│   ├── e.json              # Element definition file (required)
│   └── developer.json      # Role configuration file (required)

e.json File​

e.json Configuration Example
{
  "backendBundleEntry": ".",
  "frontBundleEntry": "./developer.json",
  "title": "Developer",
  "type": "roles.NormalType"
}

Business Configuration File​

developer.json Configuration Example
{
  "apiPerm": {
    "services.UserService.createUser": "allow",
    "services.ProjectService.*": "deny"
  },
  "apiPermSwitch": 1,
  "shellPerm": {
    "shells.Admin": "all",
    "shells.Portal": "read"
  }
}

Usage Example​

Getting Role Information
# Get role instance
role = app.getElement("roles.developer")

# Get role basic information
role_info = role.info
print(f"Role Name: {role_info['roleTitle']}")
print(f"Role ID: {role_info['roleName']}")

# Get permission configuration
api_perms = role_info.get('apiPerm', {})
shell_perms = role_info.get('shellPerm', {})

Element Configuration​

e.json Configuration​

Configuration ItemTypeRequiredDescription
titlestringYesRole display name
typestringYesFixed value: roles.NormalType
backendBundleEntrystringYesBackend entry, usually "."
frontBundleEntrystringYesFrontend entry, points to configuration file

Business Configuration File​

Configuration ItemTypeRequiredDescription
apiPermobjectNoAPI permission configuration, key is API path, value is permission type
apiPermSwitchnumberNoAPI permission switch, 0 off/1 on
shellPermobjectNoPortal permission configuration, key is portal fullName, value is permission type

API Permission Configuration​

API Permission Configuration Example
{
  "apiPerm": {
    "services.UserService.createUser": "allow",      // Explicitly allow
    "services.UserService.deleteUser": "deny",       // Explicitly deny
    "services.ProjectService.*": "allow",             // Wildcard matching
    "models.UserModel.save": "allow"                  // Model method permission
  },
  "apiPermSwitch": 1
}

Portal Permission Configuration​

Portal Permission Configuration Example
{
  "shellPerm": {
    "shells.Admin": "all",        // Full access
    "shells.Portal": "read",      // Read-only access
    "shells.Api": "none"          // No access
  }
}

Properties​

info​

Gets the complete information of the role, including basic configuration and permission data.

Usage Example
role = app.getElement("roles.developer")
role_data = role.info

# Access role information
print(role_data['roleName'])    # Role fullName
print(role_data['roleTitle'])   # Role display name
print(role_data['apiPerm'])     # API permission configuration
print(role_data['shellPerm'])   # Portal permission configuration

Methods​

getRoleData​

Gets the complete configuration data of the role, supporting data merging from application inheritance.

Return Value​

  • Type: dict
  • Description: Dictionary containing complete role configuration

Usage Example​

Getting Role Data
role = app.getElement("roles.developer")
data = role.getRoleData()

# Check role permissions
def check_api_permission(api_path):
    api_perms = data.get('apiPerm', {})
    
    # Exact match
    if api_path in api_perms:
        return api_perms[api_path] == 'allow'
    
    # Wildcard matching
    for perm_path, permission in api_perms.items():
        if perm_path.endswith('*'):
            prefix = perm_path[:-1]
            if api_path.startswith(prefix):
                return permission == 'allow'
    
    return False

# Usage example
has_permission = check_api_permission("services.UserService.createUser")

Advanced Features​

Role Inheritance​

Regular roles support application-level inheritance, where child applications can inherit parent application role configurations and override or extend them.

Child Application Role Configuration
{
  "apiPerm": {
    "services.NewService.*": "allow"
  },
  "apiPermSwitch": 1,
  "shellPerm": {
    "shells.NewPortal": "all"
  }
}

Permission Check Integration​

Integrate permission check logic in business code:

Permission Check Implementation
def check_user_role_permission(user_id, api_path):
    # Get user's role list
    member_model = app.getElement("roles.models.AppRoleMemberModel")
    user_roles = member_model.query(
        filter=f"Q(authId='{user_id}')",
        fieldList=['roleName']
    )
    
    # Check each role's permissions
    for role_data in user_roles['rowDatas']:
        role = app.getElement(role_data['roleName'])
        role_info = role.info
        
        api_perms = role_info.get('apiPerm', {})
        if api_perms.get(api_path) == 'allow':
            return True
    
    return False

Dynamic Permission Management​

Implement dynamic permission adjustments by modifying role configuration files:

Dynamic Permission Update
import json

def update_role_permissions(role_name, new_permissions):
    # Get role node
    role_element = app.getElement(role_name)
    config_file = f"{role_element._nodes[0].name}.json"
    
    # Read current configuration
    current_config = json.loads(role_element._nodes[0].getFile(config_file))
    
    # Update permissions
    current_config['apiPerm'].update(new_permissions)
    
    # Save configuration (in actual projects, this needs to be done through management interface)
    print(f"New permission configuration: {current_config}")