# SheetRocks for Salesforce

## Overview

SheetRocks for Salesforce is a native managed package that brings powerful spreadsheet capabilities directly into your Salesforce org. This guide covers Salesforce-specific installation, configuration, and integration details.

## Installation

### Prerequisites

- Salesforce Enterprise or Unlimited Edition
- System Administrator profile
- Lightning Experience enabled

### Install from AppExchange

1. Visit the [SheetRocks listing on AppExchange](https://appexchange.salesforce.com/)
2. Click "Get It Now"
3. Choose your org (production or sandbox)
4. Approve third-party access (required for managed packages)
5. Select installation for "All Users" or specific profiles
6. Wait for installation to complete (typically 5-10 minutes)

### Post-Installation Setup

After installation, configure SheetRocks:

1. **Enable Lightning Web Security (Highly Recommended)**
   - Lightning Web Security is highly recommended. The older Lightning Locker mode is being deprecated by Salesforce, and SheetRocks will not support it in future releases.
   - Navigate to Setup → Session Settings
   - Check "Use Lightning Web Security for Lightning web components and Aura components"
   - Save, then hard reload your browser (Ctrl+Shift+R or Cmd+Shift+R)
2. **Assign Permission Sets**
   - Navigate to Setup → Permission Sets
   - Assign "SheetRocks User" permission set to users
3. **Warm Up the Component**
   - Open the SheetRocks App from the App Launcher (waffle icon)
   - Wait 1–2 minutes for the component to load
   - Salesforce runs post-installation steps on first load; this is required and expected
   - Repeat after every installation or component update

## Salesforce Architecture

### Custom Objects

SheetRocks uses the following custom objects:

**Workbook__c**
- Stores workbook metadata and serialized data
- Fields: Name, Description, IsTemplate__c, OwnerId
- Sharing: Private by default, templates are shared org-wide

### Lightning Web Components

**sheetrocksElement**
- Main spreadsheet interface component
- Embeddable on any Lightning page
- Supports record context for linked sheets

### Apex Classes

All Apex classes use `with sharing` to enforce Salesforce security:
- **WorkbookController** \- CRUD operations for workbooks
- **LinkedSheetController** \- Query and sync Salesforce data
- **TemplateController** \- Template management

### Security Model

SheetRocks respects Salesforce security at multiple levels:

1. **Object-Level Security**
   - CRUD permissions on Workbook__c object
   - Enforced through permission sets
2. **Field-Level Security**
   - All field access respects FLS settings
   - Queries include `WITH SECURITY_ENFORCED`
3. **Record-Level Security**
   - Private sharing model for workbooks
   - Templates use controlled sharing
   - Owner-based access control

## Key Features in Salesforce

### Linked Sheets

Connect spreadsheets to Salesforce objects with bidirectional syncing:

**Creating a Linked Sheet:**
1. Click "Linked Sheets" in the toolbar
2. Select a Salesforce object (Account, Opportunity, etc.)
3. Choose fields to include
4. Apply filters if needed
5. Click "Create"

**Syncing Data:**
- **Pull Changes**: Refresh data from Salesforce
- **Push Changes**: Save modifications back to Salesforce
- **Auto-sync**: Configure automatic refresh intervals

**Supported Objects:**
- Standard objects (Account, Contact, Opportunity, etc.)
- Custom objects (with appropriate permissions)
- Related records via lookup/master-detail relationships
- **Special Query**: Picklist metadata (see below)

### Picklist Metadata Query

SheetRocks provides a special query for retrieving picklist values from your org:

**Query Syntax:**
```sql
SELECT * FROM Picklist
```

**How It Works:**
When you create a linked sheet with this query and sync it, SheetRocks automatically:
1. Scans all other linked sheets in your workbook
2. Identifies which Salesforce objects they reference
3. Returns picklist metadata only for those objects (read-only, no sync columns)

**Example:**
If your workbook has linked sheets for Accounts and Contacts, the picklist query returns all active picklist values for those two objects:

| ObjectName | FieldName | PicklistValue |
| --- | --- | --- |
| Account | Industry | Technology |
| Account | Industry | Finance |
| Account | Rating | Hot |
| Contact | LeadSource | Web |
| Contact | LeadSource | Phone |

**Use Cases:**
- Build dynamic dropdown menus based on org picklist values
- Create data validation formulas
- Document available picklist options
- Build data migration mapping sheets

**Note:** Picklist sheets are read-only and don't include the standard sync columns (Id, LastModifiedDate, SyncState, Delete?).
**Security Note:** Only returns picklists for objects and fields you have access to.

### Record Page Integration

Launch SheetRocks directly from Salesforce records:
1. Add SheetRocks component to Lightning page
2. Component automatically detects record context
3. Create linked sheets with record filters pre-applied
4. Quick access to record-specific templates

### Templates

Create and share standardized workflows:

**Creating Templates:**
1. Build a workbook with formulas and formatting
2. Click "Save As Template"
3. Enter template name and description
4. Template becomes available org-wide

**Using Templates:**
1. Click "New from Template"
2. Browse available templates
3. Select and launch
4. Work with a copy (template remains unchanged)

**Template Use Cases:**
- Commission calculators
- Budget planning sheets
- Sales forecasting models
- Data validation workflows

### Formulas with Salesforce Data

SheetRocks formulas work seamlessly with Salesforce data:

**Reference Linked Sheet Data:**
```
=FILTER(AccountSheet!A:F, COL[4] = "Active")
=SUMIF(OpportunitySheet!COL[Amount], OpportunitySheet!COL[Stage] = "Closed Won")
```

**Dynamic Calculations:**
```
=IF(AccountSheet!A2 = "", "No Data", AccountSheet!A2)
=VLOOKUP(B2, ContactSheet!A:C, 2, FALSE)
```

**TAGS for Lookups:**
```
=TAGS(PICK(ContactSheet!A:F, "Id", "Name", "Email"))
```
This creates interactive contact tags with Id, Name, and Email fields.

## Permissions and Access

### Permission Sets

**SheetRocks User**
- Read/Write access to Workbook__c
- Access to Apex classes
- Use Lightning components

**SheetRocks Admin** (optional)
- All User permissions
- Manage templates
- View all workbooks

### Sharing Rules

**Private Workbooks:**
- Only owner can access
- Can be manually shared with specific users

**Templates:**
- Org-wide read-only access
- Only template creators can modify

### Data Access

SheetRocks enforces Salesforce security:
- Users can only query objects they have access to
- Field-level security is respected
- Record sharing rules apply to linked sheets

## Limits and Considerations

### Salesforce Governor Limits

Be aware of platform limits:
- **SOQL Queries**: Linked sheets count toward SOQL limits
- **Heap Size**: Large workbooks may approach heap limits
- **CPU Time**: Complex formulas consume CPU time
- **DML Operations**: Batch updates count toward DML limits

### Best Practices

**Performance:**
- Limit linked sheet row counts (use filters)
- Avoid deeply nested formulas
- Use ONCE() for expensive calculations
- Batch updates when possible

**Data Management:**
- Regular cleanup of old workbooks
- Archive completed workbooks
- Use templates instead of copying workbooks

**Security:**
- Review sharing rules regularly
- Audit permission set assignments
- Monitor API usage in linked sheets

## Troubleshooting

### Common Issues

**"Insufficient Privileges" Error**
- Check permission set assignments
- Verify object and field-level security
- Ensure sharing rules allow access

**Linked Sheet Not Loading**
- Verify object permissions
- Check SOQL query limits
- Review field-level security settings

**Formula Errors**
- Check syntax and function names
- Verify cell references
- Review linked sheet names

**Performance Issues**
- Reduce linked sheet row counts
- Simplify complex formulas
- Check governor limit usage

### Getting Help

**Support Resources:**
- Email: [support@sheet.rocks](mailto:support@sheet.rocks)
- Documentation: [SheetRocks Docs](/content/docs/index.html)
- In-App Help: Click help icon in toolbar

## Release Notes

SheetRocks for Salesforce is actively maintained with regular updates:
- **Version Updates**: Announced via AppExchange
- **Bug Fixes**: Delivered through patch releases
- **New Features**: Added in major releases

Check AppExchange for the latest version and release notes.

## Advanced Topics

### Custom Integrations

Extend SheetRocks with custom code:

**Lightning Web Component Integration:**
```javascript
// Embed SheetRocks in custom component
import { LightningElement } from 'lwc';

export default class CustomSheet extends LightningElement {
  // Your custom logic
}
```

**Apex Integration:**
```apex
// Programmatic workbook creation
Workbook__c wb = new Workbook__c(
  Name = 'Auto-generated',
  Data__c = '{"sheets":[]}'
);
insert wb;
```

### API Access

Access workbooks via Salesforce APIs:
- **REST API**: Standard Salesforce REST endpoints
- **Bulk API**: For large data operations
- **Metadata API**: For deployment

## Compliance and Security

### Security Review

SheetRocks has undergone Salesforce Security Review:
- No external API calls
- All Apex uses `with sharing`
- Field-level security enforced
- CRUD and FLS checks in place

### Compliance

SheetRocks complies with:
- Salesforce security best practices
- Data residency requirements (data stays in org)
- Audit and logging standards

* * *

Ready to get started? Check out the [Getting Started Guide](/content/docs/getting-started.html) for next steps.