shortcutxl 0.2.0

package/skills/integrations/sage-intacct.md

@@ -0,0 +1,401 @@
+**Sage Intacct Excel Formula Guide**
+
+**Intro**
+You have full access to Sage Intacct data through the CData Excel Add-in for Sage Intacct, but you should only pull Sage Intacct data **when the user explicitly tells you to**. The CData connector enables SQL-style queries against Sage Intacct's cloud ERP, including general ledger, accounts payable, accounts receivable, projects, and dimensional reporting. You can retrieve any data point by writing CDATAQUERY formulas directly in Excel cells.
+
+**IMPORTANT:** Before completing a task involving Sage Intacct, you must verify:
+1. Your CDATAQUERY formulas do not return errors.
+2. All values should seem reasonable and make intuitive sense based on your general knowledge of accounting.
+3. Use cell references for dynamic values when possible as opposed to hardcoded values.
+4. Be aware that Sage Intacct uses dimensional accounting; include dimension filters when needed.
+5. Date formats in queries should use ISO format (YYYY-MM-DD).
+6. Entity/company context may affect results in multi-entity environments.
+
+You should essentially gut check every value that shows up. If there are any errors or the values seem wrong, you likely wrote the SQL syntax incorrectly or are referencing invalid object/field names. Please correct the formula until it outputs the proper value.
+
+---
+
+**CData Excel Functions Overview**
+
+CData provides one main Excel function for Sage Intacct:
+
+| Function | Purpose | Use Case |
+|----------|---------|----------|
+| CDATAQUERY | Execute SQL query | Retrieve any Sage Intacct data via SQL SELECT statements |
+
+---
+
+**1. CDATAQUERY - SQL Query Function**
+
+Returns data from Sage Intacct using SQL syntax. Results spill into adjacent cells.
+
+**Syntax:** =CDATAQUERY("SQL Query")
+
+**Basic Examples:**
+=CDATAQUERY("SELECT * FROM GLAccount LIMIT 10")
+-> First 10 GL accounts.
+
+=CDATAQUERY("SELECT CustomerID, Name, TotalDue FROM Customer WHERE Status = 'active'")
+-> Active customers with balances.
+
+=CDATAQUERY("SELECT * FROM APBill WHERE State = 'A' ORDER BY WhenDue")
+-> Approved AP bills by due date.
+
+**Using Cell References:**
+=CDATAQUERY("SELECT * FROM ARInvoice WHERE CustomerID = '" & A1 & "'")
+-> Invoices for customer ID in cell A1.
+
+=CDATAQUERY("SELECT * FROM GLEntry WHERE Amount > " & B1)
+-> GL entries exceeding amount in cell B1.
+
+---
+
+**2. Connection Setup**
+
+Before using CDATAQUERY, the CData Excel Add-in must be configured:
+
+1. Install CData Excel Add-in for Sage Intacct (~$500-1000/year license)
+2. Open Excel and go to CData ribbon tab
+3. Click "Get Data" or "Connect"
+4. Select Sage Intacct as data source
+5. Enter connection details:
+   - Company ID (required)
+   - User ID (required)
+   - Password (required)
+   - Sender ID (Web Services credential)
+   - Sender Password (Web Services credential)
+6. Optionally specify Entity ID for multi-entity access
+7. Connection persists for session
+
+**Connection Properties:**
+| Property | Description |
+|----------|-------------|
+| CompanyId | Sage Intacct company identifier |
+| UserId | Web Services user ID |
+| Password | Web Services password |
+| SenderId | Partner/developer sender ID |
+| SenderPassword | Sender password |
+| EntityId | Optional: specific entity for multi-entity |
+| LocationId | Optional: location filter |
+
+---
+
+**3. Sage Intacct Objects Reference**
+
+**General Ledger:**
+| Object | Description | Key Fields |
+|--------|-------------|------------|
+| GLAccount | Chart of accounts | AccountNo, Title, AccountType, NormalBalance, Status |
+| GLEntry | GL transaction lines | RecordNo, AccountNo, Amount, TrxAmount, WhenCreated |
+| GLBatch | GL journal batches | RecordNo, BatchNo, State, WhenCreated |
+| GLDetail | GL detail by period | AccountNo, Amount, DepartmentID, LocationID |
+| StatisticalJournalEntry | Statistical journals | RecordNo, AccountNo, Amount |
+
+**Accounts Payable:**
+| Object | Description | Key Fields |
+|--------|-------------|------------|
+| Vendor | Vendor master | VendorID, Name, TotalDue, Status, PaymentTerm |
+| APBill | AP bills/invoices | RecordNo, VendorID, TotalEntered, TotalDue, State |
+| APBillItem | AP bill line items | RecordNo, BillKey, Amount, AccountNo, DepartmentID |
+| APPayment | AP payments | RecordNo, VendorID, TotalPaid, WhenCreated |
+| APAdjustment | AP adjustments | RecordNo, VendorID, TrxTotalEntered |
+
+**Accounts Receivable:**
+| Object | Description | Key Fields |
+|--------|-------------|------------|
+| Customer | Customer master | CustomerID, Name, TotalDue, Status, PaymentTerm |
+| ARInvoice | AR invoices | RecordNo, CustomerID, TotalEntered, TotalDue, State |
+| ARInvoiceItem | AR invoice lines | RecordNo, InvoiceKey, Amount, AccountNo |
+| ARPayment | AR receipts | RecordNo, CustomerID, TotalReceived, WhenCreated |
+| ARAdjustment | AR adjustments | RecordNo, CustomerID, TrxTotalEntered |
+
+**Order Entry / Purchasing:**
+| Object | Description | Key Fields |
+|--------|-------------|------------|
+| SODocument | Sales orders | RecordNo, CustomerID, TotalEntered, State |
+| PODocument | Purchase orders | RecordNo, VendorID, TotalEntered, State |
+| SODocumentEntry | SO line items | RecordNo, ItemID, Quantity, Price |
+| PODocumentEntry | PO line items | RecordNo, ItemID, Quantity, Price |
+
+**Projects:**
+| Object | Description | Key Fields |
+|--------|-------------|------------|
+| Project | Projects | ProjectID, Name, Status, CustomerID, TotalBudget |
+| Task | Project tasks | TaskID, ProjectID, Name, Status |
+| Timesheet | Timesheets | RecordNo, EmployeeID, ProjectID, Hours |
+| ExpenseReport | Expense reports | RecordNo, EmployeeID, TotalEntered, State |
+
+**Dimensions:**
+| Object | Description | Key Fields |
+|--------|-------------|------------|
+| Department | Departments | DepartmentID, Title, Status |
+| Location | Locations | LocationID, Name, Status |
+| Class | Classes | ClassID, Name, Status |
+| Employee | Employees | EmployeeID, Name, Status, DepartmentID |
+| Item | Items/products | ItemID, Name, ItemType, Status |
+
+---
+
+**4. Common Field Reference**
+
+**GLAccount Fields:**
+| Field | Description |
+|-------|-------------|
+| RecordNo | System record number |
+| AccountNo | Account number |
+| Title | Account name/title |
+| AccountType | Type: balancesheet, incomestatement |
+| NormalBalance | Debit or Credit |
+| Status | active or inactive |
+| Category | Account category |
+| ClosingType | Closing account type |
+| ClosingAccountNo | Closing account number |
+| WhenCreated | Creation date |
+| WhenModified | Last modified date |
+
+**Vendor Fields:**
+| Field | Description |
+|-------|-------------|
+| RecordNo | System record number |
+| VendorID | Vendor identifier |
+| Name | Vendor name |
+| Status | active or inactive |
+| TotalDue | Outstanding balance |
+| PaymentTerm | Payment terms |
+| PrimaryEmailAddress | Primary email |
+| PrimaryPhone | Primary phone |
+| PayToName | Pay to contact |
+| DefaultGLAccount | Default expense account |
+| Form1099Type | 1099 type |
+| Form1099Name | 1099 name |
+| TaxID | Tax ID number |
+
+**Customer Fields:**
+| Field | Description |
+|-------|-------------|
+| RecordNo | System record number |
+| CustomerID | Customer identifier |
+| Name | Customer name |
+| Status | active or inactive |
+| TotalDue | Outstanding balance |
+| PaymentTerm | Payment terms |
+| PrimaryEmailAddress | Primary email |
+| PrimaryPhone | Primary phone |
+| CreditLimit | Credit limit |
+| DefaultRevenueAccount | Default revenue account |
+| ShipToName | Ship to contact |
+| BillToName | Bill to contact |
+
+**APBill Fields:**
+| Field | Description |
+|-------|-------------|
+| RecordNo | System record number |
+| BillNo | Bill number |
+| VendorID | Vendor identifier |
+| VendorName | Vendor name |
+| WhenCreated | Bill date |
+| WhenDue | Due date |
+| WhenPaid | Payment date |
+| TotalEntered | Bill total |
+| TotalDue | Amount due |
+| TotalPaid | Amount paid |
+| State | A=Approved, D=Draft, P=Pending, V=Void |
+| Description | Description |
+| ReferenceNo | Reference/PO number |
+| BaseCurrency | Transaction currency |
+
+**ARInvoice Fields:**
+| Field | Description |
+|-------|-------------|
+| RecordNo | System record number |
+| InvoiceNo | Invoice number |
+| CustomerID | Customer identifier |
+| CustomerName | Customer name |
+| WhenCreated | Invoice date |
+| WhenDue | Due date |
+| WhenPaid | Payment date |
+| TotalEntered | Invoice total |
+| TotalDue | Amount due |
+| TotalPaid | Amount paid |
+| State | A=Approved, D=Draft, P=Pending, V=Void |
+| Description | Description |
+| ReferenceNo | Reference/SO number |
+
+---
+
+**5. State/Status Codes**
+
+**Document States:**
+| Code | Meaning |
+|------|---------|
+| A | Approved/Active |
+| D | Draft |
+| P | Pending Approval |
+| V | Void |
+| C | Closed |
+| S | Submitted |
+| I | In Progress |
+
+**Entity Status:**
+| Status | Description |
+|--------|-------------|
+| active | Active record |
+| inactive | Inactive/archived |
+
+---
+
+**6. SQL Syntax Reference**
+
+**SELECT Statement:**
+```sql
+SELECT column1, column2 FROM ObjectName WHERE condition ORDER BY column LIMIT n
+```
+
+**Operators:**
+| Operator | Description | Example |
+|----------|-------------|---------|
+| = | Equals | `WHERE Status = 'active'` |
+| <> | Not equals | `WHERE State <> 'V'` |
+| > | Greater than | `WHERE TotalDue > 1000` |
+| < | Less than | `WHERE TotalDue < 500` |
+| >= | Greater or equal | `WHERE WhenCreated >= '2024-01-01'` |
+| <= | Less or equal | `WHERE WhenDue <= '2024-12-31'` |
+| LIKE | Pattern match | `WHERE Name LIKE 'Acme%'` |
+| IN | In list | `WHERE State IN ('A','P')` |
+| IS NULL | Null check | `WHERE WhenPaid IS NULL` |
+| AND | Logical AND | `WHERE TotalDue > 0 AND State = 'A'` |
+| OR | Logical OR | `WHERE State = 'D' OR State = 'P'` |
+
+**Aggregate Functions:**
+| Function | Description | Example |
+|----------|-------------|---------|
+| SUM() | Sum values | `SELECT SUM(TotalDue) FROM APBill` |
+| COUNT() | Count rows | `SELECT COUNT(*) FROM Customer` |
+| AVG() | Average | `SELECT AVG(TotalDue) FROM Vendor` |
+| MIN() | Minimum | `SELECT MIN(WhenCreated) FROM ARInvoice` |
+| MAX() | Maximum | `SELECT MAX(TotalEntered) FROM APBill` |
+
+**GROUP BY:**
+```sql
+SELECT VendorID, SUM(TotalDue) as Outstanding FROM APBill WHERE State = 'A' GROUP BY VendorID
+```
+
+---
+
+**7. Example Formulas by Use Case**
+
+**Chart of Accounts:**
+=CDATAQUERY("SELECT AccountNo, Title, AccountType, NormalBalance FROM GLAccount WHERE Status = 'active' ORDER BY AccountNo")
+-> Active GL accounts.
+
+=CDATAQUERY("SELECT AccountNo, Title FROM GLAccount WHERE AccountType = 'incomestatement' AND Status = 'active'")
+-> Income statement accounts.
+
+**Accounts Payable:**
+=CDATAQUERY("SELECT VendorID, Name, TotalDue FROM Vendor WHERE TotalDue > 0 AND Status = 'active' ORDER BY TotalDue DESC")
+-> Vendors with outstanding balances.
+
+=CDATAQUERY("SELECT BillNo, VendorName, WhenDue, TotalDue FROM APBill WHERE State = 'A' AND TotalDue > 0 ORDER BY WhenDue")
+-> Approved unpaid bills by due date.
+
+=CDATAQUERY("SELECT VendorID, SUM(TotalDue) as Outstanding FROM APBill WHERE State = 'A' AND TotalDue > 0 GROUP BY VendorID ORDER BY Outstanding DESC")
+-> AP aging by vendor.
+
+=CDATAQUERY("SELECT * FROM APBill WHERE WhenDue < '2024-02-01' AND TotalDue > 0 AND State = 'A'")
+-> Overdue AP bills.
+
+**Accounts Receivable:**
+=CDATAQUERY("SELECT CustomerID, Name, TotalDue FROM Customer WHERE TotalDue > 0 AND Status = 'active' ORDER BY TotalDue DESC")
+-> Customers with outstanding balances.
+
+=CDATAQUERY("SELECT InvoiceNo, CustomerName, WhenDue, TotalDue FROM ARInvoice WHERE State = 'A' AND TotalDue > 0 ORDER BY WhenDue")
+-> Approved unpaid invoices by due date.
+
+=CDATAQUERY("SELECT CustomerID, SUM(TotalDue) as Outstanding FROM ARInvoice WHERE State = 'A' AND TotalDue > 0 GROUP BY CustomerID ORDER BY Outstanding DESC")
+-> AR aging by customer.
+
+**General Ledger:**
+=CDATAQUERY("SELECT AccountNo, SUM(Amount) as Balance FROM GLEntry WHERE AccountNo = '1000' GROUP BY AccountNo")
+-> GL balance for account 1000.
+
+=CDATAQUERY("SELECT AccountNo, TrxAmount, WhenCreated FROM GLEntry WHERE WhenCreated >= '2024-01-01' ORDER BY WhenCreated")
+-> GL entries for current year.
+
+**Dimensional Reporting:**
+=CDATAQUERY("SELECT DepartmentID, SUM(Amount) as Total FROM GLEntry WHERE AccountNo LIKE '6%' GROUP BY DepartmentID")
+-> Expenses by department.
+
+=CDATAQUERY("SELECT LocationID, SUM(Amount) as Total FROM GLEntry WHERE AccountNo LIKE '4%' GROUP BY LocationID")
+-> Revenue by location.
+
+**Projects:**
+=CDATAQUERY("SELECT ProjectID, Name, Status, TotalBudget FROM Project WHERE Status = 'active'")
+-> Active projects with budgets.
+
+=CDATAQUERY("SELECT ProjectID, SUM(Amount) as ActualCost FROM GLEntry WHERE ProjectID IS NOT NULL GROUP BY ProjectID")
+-> Project actual costs.
+
+**Vendor/Customer Lookup:**
+=CDATAQUERY("SELECT VendorID, Name, PrimaryEmailAddress, PrimaryPhone, TotalDue FROM Vendor WHERE Name LIKE '%" & A1 & "%'")
+-> Search vendors by name.
+
+=CDATAQUERY("SELECT CustomerID, Name, PrimaryEmailAddress, CreditLimit, TotalDue FROM Customer WHERE Name LIKE '%" & A1 & "%'")
+-> Search customers by name.
+
+---
+
+**8. Multi-Entity Considerations**
+
+Sage Intacct supports multi-entity consolidation. When working with multi-entity:
+
+1. **Entity Context:** Queries return data for the connected entity by default
+2. **Cross-Entity:** Use EntityID field if available to filter by entity
+3. **Consolidated:** Some objects support consolidated views across entities
+
+**Example:**
+=CDATAQUERY("SELECT EntityID, VendorID, TotalDue FROM Vendor WHERE TotalDue > 0")
+-> AP by entity (if multi-entity enabled).
+
+---
+
+**9. Error Handling**
+
+**Common Errors:**
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Connection failed | Invalid credentials | Verify CompanyId, UserId, SenderId |
+| Invalid object | Object name wrong | Check object names in section 3 |
+| Invalid field | Field doesn't exist | Verify field names for that object |
+| Syntax error | SQL syntax issue | Check quotes, operators, parentheses |
+| No data returned | Query too restrictive | Broaden WHERE conditions |
+| Permission denied | Insufficient access | Check Web Services user permissions |
+| Rate limit | Too many requests | Add delays, use LIMIT clauses |
+
+**Debugging Tips:**
+1. Start with simple query: `SELECT * FROM ObjectName LIMIT 5`
+2. Add WHERE clauses incrementally
+3. Verify date format: use 'YYYY-MM-DD'
+4. String values need single quotes: `WHERE VendorID = 'V001'`
+5. Check object names are correct (case-sensitive)
+6. Verify Web Services user has access to the object
+
+---
+
+**Final Checklist:**
+- What Sage Intacct data is needed? (GL? AP? AR? Projects? Dimensions?)
+- What time frame is required? (Use WhenCreated, WhenDue filters)
+- What dimensions are needed? (Department, Location, Class, Project)
+- What state/status filter applies? (A=Approved, D=Draft, etc.)
+- Are object and field names correct? (Case-sensitive)
+- Are string values in single quotes?
+- Are dates in YYYY-MM-DD format?
+- Is LIMIT clause needed for large datasets?
+- Is multi-entity context correct?
+
+---
+
+**Additional Resources:**
+- CData Sage Intacct Driver: https://www.cdata.com/drivers/sageintacct/
+- CData Excel Add-in Help: https://cdn.cdata.com/help/DSE/excel/
+- Sage Intacct Web Services Guide: https://developer.intacct.com/web-services/
+- Sage Intacct Object Reference: https://developer.intacct.com/api/