Overview

This guide explains how to control data access in Insights using teams, permissions, and row-level security

Note: Make sure you have Insights Admin role in order to configure user permissions

Insights provides three levels of access control:

1. Application-level: Role-based access (Insights Admin, Insights User)
2. Resource-level: Team-based access to data sources, tables, dashboards, charts
3. Row-level: Filter-based restrictions on table data (e.g., show only assigned customers)

Permission Hierarchy

User → Team(s) → Resources (Data Sources/Tables) → Row Filters

• Users are assigned to one or more teams
• Teams are granted access to specific resources
• Resources can have row-level filters applied

---

Enable Permissions

Step 1: Enable Team Permissions

1. Go to Settings → Permissions
2. Toggle "Enable permissions to restrict access..."
3. This activates team-based resource access control

Step 2: Enable User Permissions (Optional)

For Frappe site data sources only:

1. Toggle "Apply User Permissions"
2. This applies Frappe's role-based permissions on top of team permissions
3. Only works for site data sources (not external databases)

---

Teams

What are Teams?

Teams are groups of users who share access to the same resources. Every Insights installation has an Admin team with full access.

Creating Teams

1. Go to Settings → Permissions
2. Click "Create Team"
3. Enter team name (e.g., "Sales Team West", "Finance Team")
4. Click Create

Managing Team Members

1. Click on a team from the list
2. Go to the Members tab
3. Add/remove users using email addresses

Example:

Team: Sales Team West
Members:
  - john@company.com
  - jane@company.com
  - robert@company.com

---

Resource Permissions

What are Resources?

Resources that can be shared with teams: - Data Sources: Database connections - Tables: Individual tables within data sources - Dashboards: Dashboard access - Charts: Chart access - Workbooks: Workbook access (through sharing)

Granting Access to Data

1. Click on a team
2. Go to the Access tab
3. Select data sources and/or specific tables
4. Click Done to save

Access Patterns

Pattern 1: Full Data Source Access

Grant access to entire data source: - User can query all tables in that data source - Best for admins or broad access needs

Pattern 2: Specific Table Access

Grant access to individual tables: - User can only query selected tables - More granular control - Better for restricted access

Example:

Sales Team West has access to:
  ✓ Data Source: Production Database
    ✓ Table: customers
    ✓ Table: orders
    ✓ Table: invoices
    ✗ Table: employee_salaries (not accessible)

---

Row-Level Security (Table Restrictions)

What are Table Restrictions?

Table restrictions are filter expressions that automatically limit which rows users can see in a table. This is the key feature for implementing "users can only see their own data" scenarios.

How to Set Table Restrictions

1. Click on a team → Access tab
2. Select a data source to expand it
3. Check the tables you want to grant access to
4. Click "Set Filters" next to a table name
5. Enter a filter expression
6. Click Done to save

Filter Expression Syntax

Expressions use Python-like syntax with table column names:

# Basic equality
column_name == 'value'

# Multiple conditions
region == 'West' AND active == 1

# Comparisons
revenue > 100000

# String operations
customer_name.startswith('A')

# NULL checks
manager IS NOT NULL

---

Use Cases & Examples

Use Case 1: Sales Team - Territory-Based Access

Scenario: Sales reps should only see customers in their assigned territory.

Setup: 1. Create team: "Sales Team North" 2. Add team members: northern sales reps 3. Grant access to customers table 4. Set table restriction:

territory == 'North'
   

Result: Team members only see customers where territory = 'North'

---

Use Case 2: Sales Rep - Individual Assignment

Scenario: Each sales rep should only see their assigned customers and their sales data.

Setup: 1. Create team: "Sales Representatives" 2. Add all sales reps as members 3. Grant access to tables: - customers - sales_orders 4. Set table restrictions:

For customers table:

sales_person == frappe.session.user
   

For sales_orders table:

sales_person == frappe.session.user
   

Result: - John (john@company.com) only sees customers/orders where sales_person = 'john@company.com' - Jane (jane@company.com) only sees customers/orders where sales_person = 'jane@company.com'

---

Use Case 3: Manager - Team View

Scenario: Sales managers should see all data for their team members.

Setup: 1. Create team: "Sales Managers West" 2. Add managers as members 3. Grant access to same tables as reps 4. Set table restrictions:

For customers table:

sales_person_region == 'West'
   

Or if you have a manager column:

manager == frappe.session.user
   

Result: Managers see all their team's data, reps see only their own.

---

Use Case 4: Finance Team - AR Visibility

Scenario: AR team should see all invoices, but only for active customers.

Setup: 1. Create team: "Accounts Receivable" 2. Add AR team members 3. Grant access to: - customers - sales_invoices - payments 4. Set table restrictions:

For customers table:

status == 'Active' AND outstanding_amount > 0
   

For sales_invoices table:

status != 'Paid' AND due_date IS NOT NULL
   

Result: AR team sees all unpaid invoices for active customers.

---

Use Case 5: Multi-Company Access

Scenario: Users should only see data for their assigned company/branch.

Setup: 1. Create teams per company: "Company A Team", "Company B Team" 2. Grant access to shared tables 3. Set table restrictions:

company == 'Company A'
   

Result: Users in "Company A Team" only see Company A data across all tables.

---

Use Case 6: Time-Based Access

Scenario: Analysts should only see recent data.

Setup: 1. Create team: "Junior Analysts" 2. Grant access to transaction tables 3. Set table restrictions:

transaction_date >= '2024-01-01'
   

Result: Analysts can't see historical data older than specified date.

---

Best Practices

1. Start with Admin Team

• Keep the Admin team for system administrators
• Don't add regular users to Admin team
• Admins can see ALL data regardless of permissions

2. Use Descriptive Team Names

Bad: "Team 1", "Group A"

Good: "Sales Team West", "Finance AR Team", "Marketing Analysts"

3. Combine Resource + Row Filters

For maximum security:

1. Grant access to specific tables only (not entire data source)
2. Apply row-level filters on those tables
3. Test with a non-admin user account

4. Test Your Restrictions

1. Create a test user account
2. Add to the restricted team
3. Log in as that user
4. Verify they can only see expected data

---

Troubleshooting

Users can't see any data

Check: 1. Is permissions enabled? (Settings → Permissions) 2. Is user in a team? 3. Does team have access to the data source/table? 4. Are table restrictions too restrictive? 5. Test with admin account first

Users see wrong data

Check: 1. Review table restriction expressions 2. Verify column names match database schema exactly 3. Check for typos in filter expressions 4. Test with SQL query directly

---

Security Considerations

What Permissions DON'T Protect

• Direct database access: Permissions only apply within Insights
• API access: If users can access backend APIs directly
• Exported data: Once data is exported (CSV, Excel), filters don't apply
• Shared workbooks: Sharing bypasses team permissions

What Permissions DO Protect

• All queries created within Insights
• Dashboard and chart views
• Data exploration and query builder
• API calls through Insights frontend

Recommendations

• Implement database-level security for sensitive data
• Audit team membership regularly
• Review and test permissions after schema changes
• Use read-only database users for Insights connections