@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/zoho-patterns/deluge/cross-app-integration.md

@@ -0,0 +1,356 @@
+# Deluge Cross-App Integration
+
+## Zoho Ecosystem Data Flow
+
+```
+CRM (Sales) ──→ Books (Finance) ──→ Analytics (Reporting)
+    ↕                 ↕                     ↑
+Creator (Ops) ──→ Inventory ──────────────→┘
+```
+
+> **CRITICAL:** CRM-to-Books has a native 2-hour sync cycle. Do NOT rebuild this. See integration/crm-books-native-sync.md for details on when to extend vs replace.
+
+## CRM Operations
+
+### Get Record by ID
+
+```deluge
+// zoho.crm.getRecordById(module, recordId)
+try
+{
+    deal = zoho.crm.getRecordById("Deals", dealId);
+
+    if (deal != null)
+    {
+        dealName = deal.get("Deal_Name");
+        amount = deal.get("Amount");
+        stage = deal.get("Stage");
+        contactId = deal.get("Contact_Name").get("id");
+
+        info "Deal: " + dealName + " - $" + amount + " (" + stage + ")";
+    }
+    else
+    {
+        info "Deal not found: " + dealId;
+    }
+}
+catch (e)
+{
+    info "CRM getRecord failed: " + e.toString();
+}
+```
+
+### Search Records
+
+```deluge
+// Search CRM with criteria
+criteria = "(Email:equals:" + customerEmail + ")";
+contacts = zoho.crm.searchRecords("Contacts", criteria);
+
+if (contacts.size() > 0)
+{
+    contact = contacts.get(0);
+    contactId = contact.get("id");
+    contactName = contact.get("Full_Name");
+}
+else
+{
+    info "No contact found for: " + customerEmail;
+}
+```
+
+### Create CRM Record
+
+```deluge
+// Create a new Deal in CRM
+dealMap = Map();
+dealMap.put("Deal_Name", input.Project_Name + " - " + input.Customer_Name);
+dealMap.put("Amount", input.Estimated_Value);
+dealMap.put("Stage", "Qualification");
+dealMap.put("Closing_Date", zoho.currentdate.addMonth(2).toString("yyyy-MM-dd"));
+dealMap.put("Contact_Name", contactId); // Lookup by ID
+
+try
+{
+    newDeal = zoho.crm.createRecord("Deals", dealMap);
+    dealId = newDeal.get("id");
+    info "Created CRM Deal: " + dealId;
+
+    // Store reference back in Creator
+    input.CRM_Deal_ID = dealId;
+}
+catch (e)
+{
+    info "CRM Deal creation failed: " + e.toString();
+}
+```
+
+### Update CRM Record
+
+```deluge
+updateMap = Map();
+updateMap.put("Stage", "Closed Won");
+updateMap.put("Amount", input.Final_Amount);
+updateMap.put("Closing_Date", zoho.currentdate.toString("yyyy-MM-dd"));
+
+try
+{
+    response = zoho.crm.updateRecord("Deals", dealId, updateMap);
+    info "Deal updated: " + response;
+}
+catch (e)
+{
+    info "CRM update failed: " + e.toString();
+}
+```
+
+## Books Operations
+
+### Create Invoice in Books
+
+```deluge
+// Create Zoho Books invoice from Creator data
+lineItems = List();
+
+for each item in input.Line_Items
+{
+    line = Map();
+    line.put("name", item.Description);
+    line.put("quantity", item.Quantity);
+    line.put("rate", item.Rate);
+    line.put("tax_id", item.Tax_ID);
+    lineItems.add(line);
+}
+
+invoiceData = Map();
+invoiceData.put("customer_id", input.Books_Customer_ID);
+invoiceData.put("date", zoho.currentdate.toString("yyyy-MM-dd"));
+invoiceData.put("due_date", zoho.currentdate.addDay(30).toString("yyyy-MM-dd"));
+invoiceData.put("line_items", lineItems);
+invoiceData.put("reference_number", input.Invoice_Number);
+invoiceData.put("notes", "Created from Creator project: " + input.Project_Name);
+
+try
+{
+    orgId = "YOUR_BOOKS_ORG_ID";
+    response = zoho.books.createRecord("invoices", orgId, invoiceData, "zoho-books-connection");
+
+    if (response.get("code") == 0)
+    {
+        booksInvoiceId = response.get("invoice").get("invoice_id");
+        input.Books_Invoice_ID = booksInvoiceId;
+        info "Books Invoice created: " + booksInvoiceId;
+    }
+    else
+    {
+        info "Books error: " + response.get("message");
+    }
+}
+catch (e)
+{
+    info "Books invoice creation failed: " + e.toString();
+}
+```
+
+### Get Books Records
+
+```deluge
+// Get customer from Books
+try
+{
+    orgId = "YOUR_BOOKS_ORG_ID";
+    customer = zoho.books.getRecordsByID("contacts", orgId, booksCustomerId, "zoho-books-connection");
+
+    customerName = customer.get("contact").get("contact_name");
+    outstandingBalance = customer.get("contact").get("outstanding_receivable_amount");
+    info customerName + " owes: $" + outstandingBalance;
+}
+catch (e)
+{
+    info "Books lookup failed: " + e.toString();
+}
+```
+
+## Cross-Application Triggers
+
+### CRM Deal Won → Create Books Invoice
+
+```deluge
+// Workflow: On Edit of CRM Deal, when Stage = "Closed Won"
+if (input.Stage == "Closed Won" && input.Stage_previous != "Closed Won")
+{
+    // Step 1: Get contact details from CRM
+    contact = zoho.crm.getRecordById("Contacts", input.Contact_Name.get("id"));
+    email = contact.get("Email");
+
+    // Step 2: Find or create Books customer
+    orgId = "YOUR_BOOKS_ORG_ID";
+    searchResult = zoho.books.getRecords("contacts", orgId, {
+        "email": email
+    }, "zoho-books-connection");
+
+    booksCustomerId = "";
+    if (searchResult.get("contacts").size() > 0)
+    {
+        booksCustomerId = searchResult.get("contacts").get(0).get("contact_id");
+    }
+    else
+    {
+        // Create new customer in Books
+        newCustomer = Map();
+        newCustomer.put("contact_name", contact.get("Full_Name"));
+        newCustomer.put("email", email);
+        newCustomer.put("company_name", contact.get("Account_Name").get("name"));
+        createResp = zoho.books.createRecord("contacts", orgId, newCustomer, "zoho-books-connection");
+        booksCustomerId = createResp.get("contact").get("contact_id");
+    }
+
+    // Step 3: Create invoice
+    invoiceData = Map();
+    invoiceData.put("customer_id", booksCustomerId);
+    invoiceData.put("line_items", [{
+        "name": input.Deal_Name,
+        "quantity": 1,
+        "rate": input.Amount
+    }]);
+
+    zoho.books.createRecord("invoices", orgId, invoiceData, "zoho-books-connection");
+}
+```
+
+## Data Mapping Between Apps
+
+### Field Mapping Reference
+
+| CRM Field | Books Field | Creator Field | Notes |
+|-----------|-------------|---------------|-------|
+| Contact_Name | contact_name | Customer_Name | Text match |
+| Email | email | Email | Unique identifier |
+| Account_Name | company_name | Company | May differ |
+| Amount | total | Total_Amount | Numeric |
+| Phone | phone | Phone | Format varies |
+| Owner | - | Assigned_To | CRM-only concept |
+
+### Mapping Function
+
+```deluge
+// Reusable mapping function
+// Custom Function: mapCRMToBooks(crmRecord)
+crmRecord = input.crmRecord.toJSON();
+
+booksData = Map();
+booksData.put("contact_name", crmRecord.get("Full_Name"));
+booksData.put("email", crmRecord.get("Email"));
+booksData.put("phone", crmRecord.get("Phone"));
+
+// Handle company name differences
+if (crmRecord.containsKey("Account_Name") && crmRecord.get("Account_Name") != null)
+{
+    booksData.put("company_name", crmRecord.get("Account_Name").get("name"));
+}
+
+// Address mapping (CRM uses components, Books uses concatenated)
+address = "";
+if (crmRecord.get("Mailing_Street") != null) { address = address + crmRecord.get("Mailing_Street") + "\n"; }
+if (crmRecord.get("Mailing_City") != null) { address = address + crmRecord.get("Mailing_City") + ", "; }
+if (crmRecord.get("Mailing_State") != null) { address = address + crmRecord.get("Mailing_State") + " "; }
+if (crmRecord.get("Mailing_Zip") != null) { address = address + crmRecord.get("Mailing_Zip"); }
+booksData.put("billing_address", {"address": address});
+
+return booksData;
+```
+
+## Handling Sync Conflicts
+
+### Last-Write-Wins (Simple)
+
+```deluge
+// Compare timestamps to determine which system has latest data
+crmModified = deal.get("Modified_Time");
+creatorModified = creatorRecord.get("Modified_Time");
+
+if (crmModified > creatorModified)
+{
+    // CRM is authoritative - update Creator
+    updateCreatorFromCRM(deal, creatorRecord.get("ID"));
+}
+else
+{
+    // Creator is authoritative - update CRM
+    updateCRMFromCreator(creatorRecord, deal.get("id"));
+}
+```
+
+### Source-of-Truth Pattern (Recommended)
+
+```deluge
+// Define which system owns which fields
+// CRM owns: Contact info, deal stage, pipeline
+// Books owns: Payment status, invoice amounts, tax
+// Creator owns: Project details, tasks, timesheets
+
+// Only sync fields owned by the source system
+// Never overwrite a field from a non-authoritative system
+```
+
+## Native Sync vs Custom Sync Decision Framework
+
+| Factor | Use Native Sync | Build Custom |
+|--------|----------------|-------------|
+| Standard entities (Contacts, Invoices) | Yes | No |
+| 2-hour delay acceptable | Yes | No |
+| Custom fields need syncing | Extend native | Yes |
+| Real-time needed (< 5 min) | No | Yes |
+| Complex transformations | No | Yes |
+| Multi-org sync | No | Yes |
+| Conditional sync (only some records) | No | Yes |
+
+> **WARNING:** Before building custom sync, verify the native CRM→Books sync doesn't already handle your use case. Duplicating native sync creates data conflicts and maintenance burden.
+
+## Cross-App Error Handling
+
+```deluge
+// Robust cross-app operation with rollback tracking
+syncErrors = List();
+syncedRecords = List();
+
+records = zoho.creator.getRecords("app", "Pending_Sync_Report", "", 1, 50);
+
+for each record in records
+{
+    try
+    {
+        // Attempt CRM update
+        crmResult = zoho.crm.updateRecord("Deals", record.get("CRM_ID"), {
+            "Stage": record.get("New_Stage")
+        });
+        syncedRecords.add(record.get("ID"));
+    }
+    catch (e)
+    {
+        syncErrors.add({
+            "record_id": record.get("ID"),
+            "crm_id": record.get("CRM_ID"),
+            "error": e.toString(),
+            "timestamp": zoho.currenttime
+        });
+    }
+}
+
+// Mark synced records
+for each syncedId in syncedRecords
+{
+    zoho.creator.updateRecord("app", "Sync_Queue", syncedId, {"Sync_Status": "Completed"});
+}
+
+// Report errors
+if (syncErrors.size() > 0)
+{
+    sendmail [
+        from: zoho.adminuserid
+        to: "admin@company.com"
+        subject: "Cross-App Sync Errors: " + syncErrors.size() + " failures"
+        message: syncErrors.toString()
+    ];
+}
+```