@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/zoho-patterns/integration/zoho-flow-patterns.md

@@ -0,0 +1,334 @@
+# Zoho Flow Patterns
+
+## Flow vs Deluge Decision Framework
+
+| Criteria | Use Flow | Use Deluge |
+|----------|----------|-----------|
+| Non-developer can maintain | Yes | No |
+| Complex conditional logic | No | Yes |
+| Multi-step with branching | Limited | Yes |
+| Third-party app integration | Yes (800+ connectors) | Requires invokeUrl |
+| Real-time event triggers | Yes | Yes |
+| Batch processing > 100 records | No | Yes (scheduled) |
+| Custom data transformation | Limited | Yes |
+| Statement limit concerns | N/A (no limit) | Yes (5000 limit) |
+| Error handling granularity | Basic | Full try-catch |
+| Audit/compliance logging | Limited | Full control |
+| Cost | Per-task pricing | Included in plan |
+| Execution timeout | 10 min per flow | 40s (invokeUrl), varies |
+
+### When to Use Flow
+
+1. Simple trigger → action patterns (e.g., new CRM lead → send Slack message)
+2. Connecting Zoho apps to third-party services (Slack, Teams, Stripe)
+3. Non-technical team needs to modify automation
+4. Rapid prototyping of integration workflows
+5. Scheduled data pulls from external APIs (no Deluge needed)
+
+### When to Use Deluge
+
+1. Complex business logic with multiple conditionals
+2. Batch processing hundreds of records
+3. Custom error handling and retry logic
+4. Performance-critical operations
+5. Operations requiring transaction-like behavior
+6. Tight integration within a single Zoho app
+
+## Flow Triggers
+
+### App Triggers (Event-Based)
+
+```
+Zoho CRM:
+  - New record created (Contact, Deal, Lead, etc.)
+  - Record updated (specific field changes)
+  - Record deleted
+  - Stage change (Blueprint transitions)
+
+Zoho Books:
+  - Invoice created/updated
+  - Payment received
+  - Expense created
+
+Zoho Creator:
+  - Form submission
+  - Record update via workflow
+
+External:
+  - Webhook received (custom payload)
+  - Schedule (cron-like)
+  - Email received (Zoho Mail)
+```
+
+### Schedule Triggers
+
+```
+Every 15 minutes (minimum)
+Every hour
+Daily at specific time
+Weekly on specific day
+Monthly on specific date
+Custom cron expression
+```
+
+### Webhook Triggers
+
+```
+Flow provides a unique webhook URL:
+https://flow.zoho.com/webhook/catch/<flow-id>/<token>
+
+Send POST request with JSON body to trigger flow.
+```
+
+## Flow Actions
+
+### Data Operations
+
+```
+Get Record       → Fetch single record by ID
+Get Records      → Fetch multiple with criteria
+Create Record    → Insert new record
+Update Record    → Modify existing record
+Delete Record    → Remove record
+Search Records   → Find by criteria/keyword
+```
+
+### Logic Operations
+
+```
+If/Else          → Conditional branching
+Switch           → Multi-path routing
+Loop             → Iterate over list (max 500 items)
+Delay            → Wait before next action (min 1 minute)
+Stop             → End flow execution
+```
+
+### Data Manipulation
+
+```
+Format Date      → Convert date formats
+Math             → Calculations
+Text             → String operations
+JSON Parse       → Extract from JSON
+List Operations  → Filter, map, sort
+```
+
+## Custom Connections in Flow
+
+For APIs not in Flow's built-in connector list:
+
+### Creating Custom Connection
+
+1. Go to Flow > Settings > Connections > Custom
+2. Define:
+   - Base URL: `https://api.example.com`
+   - Authentication: OAuth2 / API Key / Basic Auth
+   - Default headers
+
+### Using Custom Connection
+
+```
+Action: Custom API Call
+Method: POST
+URL: /v1/orders
+Headers:
+  Content-Type: application/json
+Body:
+  {
+    "customer_id": "${crm.contact.id}",
+    "amount": "${crm.deal.amount}",
+    "description": "${crm.deal.deal_name}"
+  }
+```
+
+### OAuth2 Custom Connection Setup
+
+```
+Authorization URL: https://api.example.com/oauth/authorize
+Token URL: https://api.example.com/oauth/token
+Client ID: [from API provider]
+Client Secret: [from API provider]
+Scopes: read write
+```
+
+## Error Handling in Flow
+
+### Built-in Error Handling
+
+Flow provides:
+- **Retry on failure:** 1, 2, or 3 retries with exponential backoff
+- **Error branch:** Route to alternate path on failure
+- **Error notification:** Email alert on flow failure
+
+### Error Branch Pattern
+
+```
+[Trigger: CRM Deal Won]
+    ↓
+[Action: Create Invoice in Books]
+    ├── Success → [Send confirmation email]
+    └── Error → [Log error to Creator]
+                    ↓
+                [Send alert to Slack channel]
+                    ↓
+                [Create follow-up task in CRM]
+```
+
+### Error Logging via Flow
+
+```
+On Error:
+  1. Create record in Creator "Flow_Error_Log" form:
+     - Flow_Name: "CRM to Books Invoice"
+     - Error_Message: ${error.message}
+     - Error_Step: ${error.step_name}
+     - Trigger_Record: ${trigger.record_id}
+     - Timestamp: ${system.current_time}
+
+  2. Post to Cliq:
+     - Channel: #flow-errors
+     - Message: "Flow failed: ${flow.name} at step ${error.step_name}"
+```
+
+## Flow Limitations vs Deluge
+
+| Limitation | Flow | Deluge Alternative |
+|-----------|------|-------------------|
+| Loop iterations | Max 500 per loop | 5000 statement limit (but flexible) |
+| Execution time | 10 min per flow | Scheduled: 5 min, Cron: 15 min |
+| Data size | 10MB per execution | Limited by API response size |
+| Nested conditions | 5 levels deep | Unlimited nesting |
+| API calls per flow | 25 actions | Limited by statement count |
+| Custom functions | Not available | Full Deluge functions |
+| File operations | Limited | Full file manipulation |
+| Database queries | Via app connectors | Direct ZCQL, criteria |
+| String manipulation | Basic formatters | Full string operations |
+| Error detail | Step-level only | Line-level with stack trace |
+
+## Multi-Step Workflow Examples
+
+### Lead Qualification Pipeline
+
+```
+Trigger: New Lead in CRM
+
+Step 1: [Get] Fetch lead details
+Step 2: [If] Check lead score
+  ├── Score >= 80:
+  │   Step 3a: [Update] Set status to "Hot Lead"
+  │   Step 4a: [Create] Task for sales rep
+  │   Step 5a: [Send] Slack notification to #hot-leads
+  ├── Score >= 50:
+  │   Step 3b: [Update] Set status to "Warm Lead"
+  │   Step 4b: [Create] Scheduled follow-up
+  └── Score < 50:
+      Step 3c: [Update] Set status to "Nurture"
+      Step 4c: [Add] to email campaign
+```
+
+### Invoice Reminder Automation
+
+```
+Trigger: Schedule (Daily at 9 AM)
+
+Step 1: [Get Records] Overdue invoices from Books
+Step 2: [Loop] For each overdue invoice:
+  Step 3: [If] Days overdue check
+    ├── 7+ days:
+    │   [Send] Reminder email to customer
+    │   [Update] Reminder_Sent_Count + 1
+    ├── 30+ days:
+    │   [Send] Urgent reminder
+    │   [Create] Task for collections team
+    └── 60+ days:
+        [Send] Final notice
+        [Update] Status to "Collections"
+        [Notify] Finance manager via Cliq
+```
+
+### Cross-Platform Data Sync
+
+```
+Trigger: Webhook from external system
+
+Step 1: [Parse] JSON payload
+Step 2: [Search] CRM for matching contact by email
+Step 3: [If] Contact exists?
+  ├── Yes:
+  │   [Update] CRM contact with new data
+  │   [Get] Associated Books contact
+  │   [Update] Books contact (custom fields)
+  └── No:
+      [Create] New CRM contact
+      [Wait] 2 hours (for native Books sync)
+      [Verify] Books contact created
+      [If] Not created → [Create] manually in Books
+```
+
+## Conditional Logic
+
+### If/Else Conditions
+
+```
+Conditions available:
+- Equals / Not equals
+- Contains / Does not contain
+- Starts with / Ends with
+- Greater than / Less than
+- Is empty / Is not empty
+- Is true / Is false
+- Matches regex (limited)
+```
+
+### Switch (Multi-Branch)
+
+```
+Switch on: ${crm.deal.stage}
+  Case "Qualification":     → [Action A]
+  Case "Proposal":          → [Action B]
+  Case "Negotiation":       → [Action C]
+  Case "Closed Won":        → [Action D]
+  Case "Closed Lost":       → [Action E]
+  Default:                  → [Log unexpected stage]
+```
+
+## Best Practices
+
+1. **Name flows descriptively:** "CRM-Deal-Won-to-Books-Invoice" not "Flow 1"
+2. **Add descriptions to each step** for team maintainability
+3. **Use error branches** on every external API call
+4. **Set up failure notifications** to a monitored channel
+5. **Test with edge cases** before enabling (null values, special characters)
+6. **Monitor task usage** - Flow charges per task execution
+7. **Version control:** Export flow JSON for backup (Settings > Export)
+8. **Avoid infinite loops:** Ensure update triggers don't re-trigger the same flow
+
+## Flow + Deluge Hybrid Pattern
+
+Sometimes the best solution uses both:
+
+```
+Flow handles:
+  - Triggering on external events
+  - Routing to appropriate handler
+  - Notifications and simple updates
+
+Deluge handles:
+  - Complex business logic
+  - Batch operations
+  - Data transformation
+  - Error handling with retry
+
+Example:
+  [Flow Trigger: Webhook from Stripe]
+      ↓
+  [Flow: Parse payload, extract customer_id]
+      ↓
+  [Flow: Call Creator custom function via API]
+      ↓
+  [Deluge: Complex invoice reconciliation logic]
+      ↓
+  [Deluge: Update multiple records, handle errors]
+      ↓
+  [Flow: Send success/failure notification]
+```