@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/zoho-patterns/creator/widget-integration.md

@@ -0,0 +1,306 @@
+# Creator Widget Integration
+
+## Critical Constraints
+
+> **WARNING:** Widgets do NOT work on published pages. If you need external user interaction, use the Publish API instead (see publish-api-patterns.md).
+
+> **LIMIT:** Maximum 50 widgets per Creator application.
+
+## Widget Initialization
+
+Every widget MUST call `ZOHO.CREATOR.init()` before any other API calls:
+
+```javascript
+// Widget entry point - ALWAYS starts here
+ZOHO.CREATOR.init().then(function() {
+    console.log("Widget initialized successfully");
+    loadWidgetData();
+}).catch(function(error) {
+    console.error("Widget init failed:", error);
+    document.getElementById("app").innerHTML =
+        "<div class='error'>Widget failed to load. Please refresh.</div>";
+});
+```
+
+## JS API v1 vs v2 Differences
+
+| Feature | v1 (Legacy) | v2 (Current) |
+|---------|-------------|--------------|
+| Initialization | `ZDK.Page.getForm()` | `ZOHO.CREATOR.init()` |
+| Get record | `ZDK.Page.getRecord()` | `ZOHO.CREATOR.DATA.getRecord()` |
+| Create record | `ZDK.Apps.CRM.createRecord()` | `ZOHO.CREATOR.DATA.createRecord()` |
+| Event handling | Callback-based | Promise-based |
+| Widget context | Limited | Full form/record context |
+| SDK location | Self-hosted | `https://js.zohostatic.com/creator/widgets/version/widgetsdk-min.js` |
+
+> **WARNING:** v1 API is deprecated. All new widgets MUST use v2. Migrate existing v1 widgets when modifying them.
+
+## Widget-to-Form Communication
+
+### Reading Current Record Data
+
+```javascript
+ZOHO.CREATOR.init().then(function() {
+    // Get the current record context
+    ZOHO.CREATOR.UTIL.getInitParams().then(function(params) {
+        var recordId = params.record_id;
+        var formName = params.form_link_name;
+        var appName = params.app_link_name;
+
+        if (recordId) {
+            // Editing existing record - fetch data
+            ZOHO.CREATOR.DATA.getRecordById({
+                appName: appName,
+                formName: formName,
+                id: recordId
+            }).then(function(response) {
+                var record = response.data;
+                populateWidget(record);
+            });
+        } else {
+            // New record context
+            initNewRecordWidget();
+        }
+    });
+});
+```
+
+### Writing Data Back to Form
+
+```javascript
+// Update a field in the parent form
+function updateFormField(fieldName, value) {
+    ZOHO.CREATOR.UTIL.setFieldValue(fieldName, value)
+        .then(function(response) {
+            console.log("Field updated:", fieldName, "=", value);
+        })
+        .catch(function(error) {
+            console.error("Failed to update field:", error);
+        });
+}
+
+// Set multiple fields at once
+function updateMultipleFields(fieldMap) {
+    var promises = [];
+    for (var field in fieldMap) {
+        promises.push(
+            ZOHO.CREATOR.UTIL.setFieldValue(field, fieldMap[field])
+        );
+    }
+    Promise.all(promises).then(function() {
+        console.log("All fields updated");
+    });
+}
+```
+
+### Navigating Between Records
+
+```javascript
+// Open another record in a new tab
+function openRelatedRecord(appName, formName, recordId) {
+    ZOHO.CREATOR.UTIL.navigateTo({
+        appName: appName,
+        formName: formName,
+        recordId: recordId,
+        target: "_blank"
+    });
+}
+```
+
+## Passing Parameters to Widgets
+
+### Via URL Parameters (Widget Configuration)
+
+```javascript
+// In widget settings, set URL params: ?mode=edit&type=invoice
+ZOHO.CREATOR.init().then(function() {
+    var urlParams = new URLSearchParams(window.location.search);
+    var mode = urlParams.get("mode") || "view";
+    var type = urlParams.get("type") || "default";
+
+    initWidget(mode, type);
+});
+```
+
+### Via Form Field Values
+
+```javascript
+// Read a hidden field that stores config JSON
+ZOHO.CREATOR.init().then(function() {
+    ZOHO.CREATOR.UTIL.getFieldValue("Widget_Config")
+        .then(function(response) {
+            var config = JSON.parse(response.value || "{}");
+            applyConfiguration(config);
+        });
+});
+```
+
+## Widget Sizing and Responsive Design
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <style>
+        /* Widget container - respect Creator's iframe constraints */
+        body {
+            margin: 0;
+            padding: 8px;
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            font-size: 13px;
+            overflow-x: hidden;
+        }
+
+        .widget-container {
+            width: 100%;
+            max-width: 100%;
+            box-sizing: border-box;
+        }
+
+        /* Resize widget height dynamically */
+        .auto-height {
+            min-height: 100px;
+            max-height: 600px;
+            overflow-y: auto;
+        }
+    </style>
+</head>
+<body>
+    <div class="widget-container auto-height" id="app">
+        <!-- Widget content -->
+    </div>
+    <script src="https://js.zohostatic.com/creator/widgets/1.0/widgetsdk-min.js"></script>
+    <script src="app.js"></script>
+</body>
+</html>
+```
+
+### Resizing Widget Iframe Dynamically
+
+```javascript
+// Notify Creator to resize the widget iframe
+function resizeWidget(height) {
+    ZOHO.CREATOR.UTIL.resize({
+        height: height + "px"
+    }).then(function() {
+        console.log("Widget resized to", height);
+    });
+}
+
+// Auto-resize based on content
+function autoResize() {
+    var contentHeight = document.getElementById("app").scrollHeight;
+    resizeWidget(Math.min(contentHeight + 20, 800)); // Cap at 800px
+}
+```
+
+## CORS Handling for API Calls from Widgets
+
+> **WARNING:** Widgets run in an iframe. Direct API calls to external services will be blocked by CORS. Use one of these patterns:
+
+### Pattern 1: Catalyst Proxy (Recommended)
+
+```javascript
+// Widget calls Catalyst function which calls external API
+async function fetchExternalData(endpoint, params) {
+    try {
+        // Call your Catalyst function (same Zoho domain = no CORS issue)
+        var response = await ZOHO.CREATOR.DATA.invokeFunction({
+            appName: "my-app",
+            functionName: "proxy_external_api",
+            data: {
+                endpoint: endpoint,
+                params: JSON.stringify(params)
+            }
+        });
+        return JSON.parse(response.data);
+    } catch (error) {
+        console.error("Proxy call failed:", error);
+        throw error;
+    }
+}
+```
+
+### Pattern 2: Zoho Creator Custom Function Proxy
+
+```javascript
+// Call a Deluge custom function that makes the external call
+async function callViaDeluge(apiUrl, method, body) {
+    var response = await ZOHO.CREATOR.DATA.invokeFunction({
+        appName: "my-app",
+        functionName: "external_api_proxy",
+        data: {
+            url: apiUrl,
+            method: method,
+            body: JSON.stringify(body)
+        }
+    });
+    return response;
+}
+```
+
+### Supporting Deluge Function
+
+```deluge
+// Custom function: external_api_proxy
+// Arguments: url (TEXT), method (TEXT), body (TEXT)
+
+response = invokeUrl [
+    url: url
+    type: if(method == "POST", POST, if(method == "PUT", PUT, GET))
+    headers: {"Content-Type": "application/json"}
+    body: body
+    connection: "external-api-connection"
+];
+
+return response.toString();
+```
+
+## Debugging Widget Load Failures
+
+| Symptom | Cause | Solution |
+|---------|-------|----------|
+| Blank iframe | SDK not loaded | Verify SDK URL is accessible, check network tab |
+| "init() failed" | Wrong SDK version | Match SDK version to your Creator plan |
+| Fields not updating | Wrong field link name | Use link names (underscored), not display names |
+| Widget shows in edit but not list | Widget placement config | Reconfigure widget placement in form settings |
+| CORS errors in console | Direct external API call | Route through Catalyst proxy (see above) |
+| Widget loads slowly | Large bundle size | Code-split, lazy-load non-critical components |
+| Data not refreshing | Cached API responses | Add timestamp parameter to API calls |
+
+### Debug Mode Pattern
+
+```javascript
+var DEBUG = window.location.search.includes("debug=true");
+
+function debugLog(label, data) {
+    if (DEBUG) {
+        console.log("[Widget Debug]", label, JSON.stringify(data, null, 2));
+        // Also render to page for mobile debugging
+        var debugDiv = document.getElementById("debug-output");
+        if (debugDiv) {
+            debugDiv.innerHTML += "<pre>" + label + ": " +
+                JSON.stringify(data, null, 2) + "</pre>";
+        }
+    }
+}
+
+ZOHO.CREATOR.init().then(function() {
+    debugLog("Init", { status: "success", timestamp: new Date().toISOString() });
+
+    ZOHO.CREATOR.UTIL.getInitParams().then(function(params) {
+        debugLog("Params", params);
+    });
+});
+```
+
+## Widget Development Workflow
+
+1. **Local Development:** Use `http://localhost:3000` with mock Zoho SDK
+2. **Upload to Creator:** Settings > Widgets > Upload ZIP (index.html at root)
+3. **Test in Form:** Add widget field, open form in edit mode
+4. **Debug:** Use `?debug=true` parameter for verbose logging
+5. **Production:** Remove debug flags, minify JS, test on all target browsers
+
+> **REMINDER:** Widgets only work for logged-in Zoho users viewing forms within Creator. For external-facing functionality, use Publish API patterns.

package/skills/zoho-patterns/creator/workflow-automation.md

@@ -0,0 +1,253 @@
+# Creator Workflow Automation
+
+## Workflow Execution Order
+
+When a record is created or edited, Creator executes automation in this order:
+1. Field validation rules
+2. On-create/edit workflow (Deluge scripts)
+3. Field update rules (form rules)
+4. Blueprint transitions (if applicable)
+5. Approval processes (if triggered)
+6. Scheduled workflows (independent, time-based)
+
+> **WARNING:** If a workflow modifies a field that triggers another workflow, infinite loops are possible. Use `input.Trigger_Type` to guard against re-entry.
+
+## On-Create / On-Edit Triggers
+
+```deluge
+// Workflow: On Create of "Invoice" form
+// Trigger: Record creation
+
+// Guard against re-entry from approval/blueprint updates
+if (input.Trigger_Type == "form_submission")
+{
+    // Set audit fields
+    input.Created_By_Name = zoho.loginuserid;
+    input.Created_Date = zoho.currentdate;
+
+    // Auto-generate invoice number
+    lastRecord = zoho.creator.getRecords("billing-app", "All_Invoices", "", 1, 1, "Invoice_Number", "desc");
+    if (lastRecord.size() > 0)
+    {
+        lastNum = lastRecord.get(0).get("Invoice_Number").toLong();
+        input.Invoice_Number = lastNum + 1;
+    }
+    else
+    {
+        input.Invoice_Number = 10001;
+    }
+
+    // Cross-app notification
+    sendmail [
+        from: zoho.adminuserid
+        to: input.Account_Manager.Email
+        subject: "New Invoice Created: INV-" + input.Invoice_Number
+        message: "Invoice for " + input.Customer_Name + " - $" + input.Total_Amount
+    ];
+}
+```
+
+```deluge
+// Workflow: On Edit of "Project" form
+// Only fire when Status changes
+
+if (input.Status != input.Status_previous)
+{
+    // Log status change to audit subform
+    auditRow = Project_History();
+    auditRow.Old_Status = input.Status_previous;
+    auditRow.New_Status = input.Status;
+    auditRow.Changed_By = zoho.loginuserid;
+    auditRow.Changed_Date = zoho.currenttime;
+
+    // Insert into subform
+    input.Project_History.insert(auditRow);
+
+    // Notify team on completion
+    if (input.Status == "Completed")
+    {
+        teamMembers = zoho.creator.getRecords("pm-app", "Team_Members", "Project == " + input.ID);
+        for each member in teamMembers
+        {
+            sendmail [
+                from: zoho.adminuserid
+                to: member.get("Email")
+                subject: "Project Completed: " + input.Project_Name
+                message: "The project has been marked complete."
+            ];
+        }
+    }
+}
+```
+
+## Scheduled Workflows
+
+```deluge
+// Scheduled: Daily at 6 AM UTC
+// Purpose: Auto-close stale opportunities older than 90 days
+
+staleDate = zoho.currentdate.subDay(90);
+criteria = "Stage == \"Negotiation\" && Last_Activity_Date < \"" + staleDate.toString("dd-MMM-yyyy") + "\"";
+staleDeals = zoho.creator.getRecords("sales-app", "All_Deals", criteria, 1, 200);
+
+closedCount = 0;
+for each deal in staleDeals
+{
+    updateMap = Map();
+    updateMap.put("Stage", "Closed Lost");
+    updateMap.put("Close_Reason", "Auto-closed: No activity 90+ days");
+    zoho.creator.updateRecord("sales-app", "Deals", deal.get("ID").toLong(), updateMap);
+    closedCount = closedCount + 1;
+}
+
+// Report results
+if (closedCount > 0)
+{
+    sendmail [
+        from: zoho.adminuserid
+        to: "sales-manager@company.com"
+        subject: "Auto-Close Report: " + closedCount + " deals closed"
+        message: closedCount + " stale deals auto-closed on " + zoho.currentdate
+    ];
+}
+```
+
+## Blueprint Configuration
+
+Blueprints enforce process stages (e.g., Lead Qualification, Project Delivery):
+
+| Component | Purpose | Example |
+|-----------|---------|---------|
+| States | Allowed statuses | Draft, In Review, Approved, Rejected |
+| Transitions | Allowed movements | Draft→In Review, In Review→Approved |
+| Before Transition | Validation script | Check required fields filled |
+| During Transition | Collect input | Rejection reason, approval notes |
+| After Transition | Post-action script | Notify stakeholders, update related records |
+
+```deluge
+// Blueprint: Before Transition "Submit for Review"
+// Validate completeness before allowing transition
+
+errors = List();
+
+if (input.Description.length() < 50)
+{
+    errors.add("Description must be at least 50 characters");
+}
+if (input.Attachments.size() == 0)
+{
+    errors.add("At least one attachment is required");
+}
+if (input.Estimated_Hours == 0)
+{
+    errors.add("Estimated hours must be provided");
+}
+
+if (errors.size() > 0)
+{
+    cancel submit;
+    alert errors.toString(",");
+}
+```
+
+## Approval Processes
+
+```deluge
+// Approval: Invoice over $10,000 requires manager approval
+// Criteria: Total_Amount > 10000
+
+// On Approve action:
+input.Approval_Status = "Approved";
+input.Approved_By = zoho.loginuserid;
+input.Approved_Date = zoho.currenttime;
+
+// Trigger downstream: create Books invoice
+bookData = Map();
+bookData.put("customer_name", input.Customer_Name);
+bookData.put("line_items", input.Line_Items);
+response = zoho.books.createRecord("invoices", "YOUR_ORG_ID", bookData, "zoho-books-connection");
+
+// On Reject action:
+input.Approval_Status = "Rejected";
+input.Rejection_Reason = input.Approver_Comments;
+sendmail [
+    from: zoho.adminuserid
+    to: input.Submitted_By.Email
+    subject: "Invoice Rejected: " + input.Invoice_Number
+    message: "Reason: " + input.Approver_Comments
+];
+```
+
+## Field Update Rules
+
+Field update rules execute WITHOUT triggering on-edit workflows (avoids loops):
+
+- Use for: Auto-calculations, status derivations, default values
+- Do NOT use for: Cross-app updates, email notifications, complex logic
+
+## Custom Functions in Workflows
+
+> **WARNING:** Custom functions share the 5000-statement limit with the calling workflow. If your workflow uses 3000 statements, the custom function only has 2000 remaining.
+
+```deluge
+// Custom function: calculateProjectHealth(projectId)
+// Called from workflow after status update
+
+projectId = input.projectId;
+tasks = zoho.creator.getRecords("pm-app", "All_Tasks", "Project == " + projectId, 1, 200);
+
+totalTasks = tasks.size();
+completedTasks = 0;
+overdueTasks = 0;
+
+for each task in tasks
+{
+    if (task.get("Status") == "Completed")
+    {
+        completedTasks = completedTasks + 1;
+    }
+    if (task.get("Due_Date") < zoho.currentdate && task.get("Status") != "Completed")
+    {
+        overdueTasks = overdueTasks + 1;
+    }
+}
+
+healthScore = (completedTasks * 100) / totalTasks;
+if (overdueTasks > 3)
+{
+    healthScore = healthScore - 20;
+}
+
+updateMap = Map();
+updateMap.put("Health_Score", healthScore);
+updateMap.put("Health_Status", if(healthScore >= 80, "Green", if(healthScore >= 50, "Yellow", "Red")));
+zoho.creator.updateRecord("pm-app", "Projects", projectId, updateMap);
+```
+
+## Debugging Workflow Failures
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Workflow doesn't fire | Wrong trigger type selected | Check form settings > workflows |
+| Fires multiple times | Edit workflow + field update loop | Add `input.Trigger_Type` guard |
+| Partial execution | 5000 statement limit hit | Split into custom function + scheduled |
+| Null pointer error | Field not available in context | Check field availability per trigger type |
+| Email not sent | Org email limits exceeded | Check Admin > Email usage |
+| Cross-app call fails | Connection expired/wrong scope | Re-authorize connection in settings |
+
+### Logging Pattern for Debugging
+
+```deluge
+// Add to any workflow for troubleshooting
+logMap = Map();
+logMap.put("Workflow_Name", "Invoice_OnCreate");
+logMap.put("Record_ID", input.ID);
+logMap.put("Trigger_Type", input.Trigger_Type);
+logMap.put("Timestamp", zoho.currenttime);
+logMap.put("User", zoho.loginuserid);
+logMap.put("Details", "Invoice " + input.Invoice_Number + " created");
+
+zoho.creator.createRecord("admin-app", "Workflow_Logs", logMap);
+```
+
+> **NOTE:** Creator audit logs are only retained for 1 year. For compliance clients (HIPAA/SOC2), implement custom audit archival to a separate form or external store.