@hailer/mcp 0.0.1

package/.claude/skills/hailer-api/references/workflows.md

@@ -0,0 +1,720 @@
+# Hailer Workflows API
+
+## Overview
+
+Workflows automate business processes by defining a series of steps, transitions, and actions that activities follow. Workflows can include conditional logic, automatic assignments, notifications, and integrations.
+
+## Workflow Concepts
+
+- **Workflow** - A defined process with steps and transitions
+- **Step** - A stage in the workflow (maps to activity status)
+- **Transition** - Movement from one step to another
+- **Trigger** - Event that starts or advances a workflow
+- **Action** - Automated task performed during workflow execution
+- **Condition** - Logic that determines workflow behavior
+
+## Endpoints
+
+### List Workflows
+
+```http
+GET /v3/workflows?workspace_id=ws_123
+```
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "id": "wf_123",
+      "name": "Invoice Approval Process",
+      "description": "Multi-step invoice approval workflow",
+      "workspace_id": "ws_456",
+      "active": true,
+      "steps": [
+        {
+          "id": "step_1",
+          "name": "Submitted",
+          "status": "submitted"
+        },
+        {
+          "id": "step_2",
+          "name": "Manager Review",
+          "status": "manager_review"
+        },
+        {
+          "id": "step_3",
+          "name": "Finance Approval",
+          "status": "finance_approval"
+        },
+        {
+          "id": "step_4",
+          "name": "Approved",
+          "status": "approved"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Get Workflow
+
+```http
+GET /v3/workflows/{workflow_id}
+```
+
+Returns complete workflow definition including steps, transitions, actions, and conditions.
+
+### Create Workflow
+
+```http
+POST /v3/workflows
+Content-Type: application/json
+
+{
+  "name": "Bug Fix Workflow",
+  "workspace_id": "ws_123",
+  "description": "Standard process for bug fixes",
+  "steps": [
+    {
+      "name": "Reported",
+      "status": "reported"
+    },
+    {
+      "name": "Triaged",
+      "status": "triaged"
+    },
+    {
+      "name": "In Progress",
+      "status": "in_progress"
+    },
+    {
+      "name": "Testing",
+      "status": "testing"
+    },
+    {
+      "name": "Resolved",
+      "status": "resolved"
+    }
+  ],
+  "transitions": [
+    {
+      "from": "reported",
+      "to": "triaged",
+      "name": "Triage",
+      "conditions": []
+    },
+    {
+      "from": "triaged",
+      "to": "in_progress",
+      "name": "Start Work",
+      "actions": [
+        {
+          "type": "assign",
+          "user_id": ":current_user"
+        },
+        {
+          "type": "notify",
+          "recipients": ["manager"]
+        }
+      ]
+    }
+  ],
+  "triggers": [
+    {
+      "event": "activity.created",
+      "conditions": [
+        {
+          "field": "tags",
+          "operator": "contains",
+          "value": "bug"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Update Workflow
+
+```http
+PATCH /v3/workflows/{workflow_id}
+{
+  "active": true,
+  "description": "Updated description"
+}
+```
+
+### Delete Workflow
+
+```http
+DELETE /v3/workflows/{workflow_id}
+```
+
+## Workflow Steps
+
+### Step Object
+
+```json
+{
+  "id": "step_123",
+  "name": "In Review",
+  "status": "review",
+  "order": 2,
+  "color": "#FF9800",
+  "actions": [
+    {
+      "type": "assign",
+      "role": "reviewer"
+    },
+    {
+      "type": "notify",
+      "template": "review_requested"
+    }
+  ]
+}
+```
+
+### Add Step
+
+```http
+POST /v3/workflows/{workflow_id}/steps
+{
+  "name": "Quality Assurance",
+  "status": "qa",
+  "order": 3
+}
+```
+
+### Update Step
+
+```http
+PATCH /v3/workflows/{workflow_id}/steps/{step_id}
+{
+  "name": "QA Testing",
+  "color": "#9C27B0"
+}
+```
+
+### Delete Step
+
+```http
+DELETE /v3/workflows/{workflow_id}/steps/{step_id}
+```
+
+## Workflow Transitions
+
+### Transition Object
+
+```json
+{
+  "id": "trans_123",
+  "from": "in_progress",
+  "to": "review",
+  "name": "Submit for Review",
+  "conditions": [
+    {
+      "field": "custom_fields.test_coverage",
+      "operator": ">=",
+      "value": 80
+    }
+  ],
+  "actions": [
+    {
+      "type": "comment",
+      "text": "Submitted for review"
+    },
+    {
+      "type": "assign",
+      "role": "reviewer"
+    }
+  ]
+}
+```
+
+### Available Operators
+
+- `=` / `!=` - Equals / Not equals
+- `>` / `<` / `>=` / `<=` - Comparisons
+- `contains` - String contains
+- `in` - Value in list
+- `is_empty` / `is_not_empty` - Empty checks
+
+### Add Transition
+
+```http
+POST /v3/workflows/{workflow_id}/transitions
+{
+  "from": "review",
+  "to": "approved",
+  "name": "Approve",
+  "conditions": [
+    {
+      "field": "assigned_to",
+      "operator": "=",
+      "value": ":current_user"
+    }
+  ]
+}
+```
+
+## Workflow Actions
+
+Actions are automated tasks performed when transitions occur or steps are entered.
+
+### Available Action Types
+
+#### Assign Activity
+
+```json
+{
+  "type": "assign",
+  "user_id": "user_123"
+}
+```
+
+Or use role-based assignment:
+```json
+{
+  "type": "assign",
+  "role": "manager"
+}
+```
+
+#### Send Notification
+
+```json
+{
+  "type": "notify",
+  "recipients": ["assigned_to", "creator"],
+  "template": "status_changed",
+  "custom_message": "Activity moved to {{status}}"
+}
+```
+
+#### Add Comment
+
+```json
+{
+  "type": "comment",
+  "text": "Automatically moved to {{step_name}} on {{date}}"
+}
+```
+
+#### Update Field
+
+```json
+{
+  "type": "update_field",
+  "field": "priority",
+  "value": "high"
+}
+```
+
+#### Create Subtask
+
+```json
+{
+  "type": "create_activity",
+  "title": "Code Review for {{parent_title}}",
+  "template_id": "tmpl_review"
+}
+```
+
+#### Trigger Webhook
+
+```json
+{
+  "type": "webhook",
+  "url": "https://your-server.com/webhook",
+  "method": "POST",
+  "payload": {
+    "activity_id": "{{activity_id}}",
+    "status": "{{status}}"
+  }
+}
+```
+
+#### Send Email
+
+```json
+{
+  "type": "email",
+  "to": ["{{assigned_to}}"],
+  "subject": "Activity {{title}} needs your attention",
+  "template": "activity_assigned"
+}
+```
+
+## Workflow Triggers
+
+Triggers start or advance workflows based on events.
+
+### Trigger Types
+
+#### Activity Created
+
+```json
+{
+  "event": "activity.created",
+  "conditions": [
+    {
+      "field": "priority",
+      "operator": "=",
+      "value": "critical"
+    }
+  ],
+  "workflow_id": "wf_123"
+}
+```
+
+#### Activity Updated
+
+```json
+{
+  "event": "activity.updated",
+  "conditions": [
+    {
+      "field": "status",
+      "operator": "=",
+      "value": "completed"
+    }
+  ],
+  "actions": [
+    {
+      "type": "notify",
+      "recipients": ["creator"]
+    }
+  ]
+}
+```
+
+#### Time-Based
+
+```json
+{
+  "event": "scheduled",
+  "schedule": "0 9 * * 1",
+  "conditions": [
+    {
+      "field": "status",
+      "operator": "in",
+      "value": ["open", "in_progress"]
+    }
+  ]
+}
+```
+
+Schedule uses cron syntax:
+- `* * * * *` - Every minute
+- `0 9 * * 1` - Every Monday at 9:00 AM
+- `0 0 1 * *` - First day of each month
+
+#### Field Changed
+
+```json
+{
+  "event": "activity.field_changed",
+  "field": "assigned_to",
+  "workflow_id": "wf_123"
+}
+```
+
+## Workflow Execution
+
+### Trigger Workflow
+
+```http
+POST /v3/workflows/{workflow_id}/trigger
+{
+  "activity_id": "act_123",
+  "input": {
+    "priority": "high",
+    "requester": "Johan Rekna"
+  }
+}
+```
+
+### Advance Activity in Workflow
+
+```http
+POST /v3/workflows/{workflow_id}/advance
+{
+  "activity_id": "act_123",
+  "to_step": "step_456"
+}
+```
+
+### Get Workflow State
+
+```http
+GET /v3/activities/{activity_id}/workflow
+```
+
+**Response:**
+```json
+{
+  "workflow_id": "wf_123",
+  "current_step": {
+    "id": "step_2",
+    "name": "In Review",
+    "status": "review"
+  },
+  "available_transitions": [
+    {
+      "id": "trans_3",
+      "name": "Approve",
+      "to": "step_3"
+    },
+    {
+      "id": "trans_4",
+      "name": "Reject",
+      "to": "step_1"
+    }
+  ],
+  "history": [
+    {
+      "from": "step_1",
+      "to": "step_2",
+      "timestamp": "2025-01-15T10:30:00Z",
+      "user_id": "user_123"
+    }
+  ]
+}
+```
+
+## Conditional Logic
+
+### Condition Object
+
+```json
+{
+  "field": "custom_fields.budget",
+  "operator": ">",
+  "value": 10000
+}
+```
+
+### Complex Conditions
+
+Use `AND` / `OR` logic:
+
+```json
+{
+  "operator": "AND",
+  "conditions": [
+    {
+      "field": "priority",
+      "operator": "=",
+      "value": "high"
+    },
+    {
+      "field": "assigned_to",
+      "operator": "is_not_empty"
+    }
+  ]
+}
+```
+
+```json
+{
+  "operator": "OR",
+  "conditions": [
+    {
+      "field": "status",
+      "operator": "=",
+      "value": "completed"
+    },
+    {
+      "field": "status",
+      "operator": "=",
+      "value": "cancelled"
+    }
+  ]
+}
+```
+
+## Workflow Templates
+
+### Create from Template
+
+```http
+POST /v3/workflows/from-template
+{
+  "template_id": "tmpl_invoice_approval",
+  "workspace_id": "ws_123",
+  "customizations": {
+    "approval_threshold": 5000,
+    "approver_role": "finance_manager"
+  }
+}
+```
+
+### Available Templates
+
+- Invoice Approval
+- Bug Tracking
+- Change Request
+- Customer Support Ticket
+- Project Management
+- HR Onboarding
+
+## Workflow Analytics
+
+### Get Workflow Statistics
+
+```http
+GET /v3/workflows/{workflow_id}/stats
+```
+
+**Response:**
+```json
+{
+  "total_activities": 523,
+  "active_activities": 89,
+  "completed_activities": 434,
+  "average_completion_time_days": 5.3,
+  "step_statistics": [
+    {
+      "step": "submitted",
+      "count": 89,
+      "average_time_in_step_days": 0.5
+    },
+    {
+      "step": "review",
+      "count": 45,
+      "average_time_in_step_days": 2.1
+    }
+  ]
+}
+```
+
+## Best Practices
+
+1. **Keep workflows simple** - Complex workflows are hard to maintain
+2. **Use clear step names** - Self-explanatory names improve usability
+3. **Add conditions to transitions** - Prevent invalid state changes
+4. **Automate notifications** - Keep stakeholders informed
+5. **Test workflows thoroughly** - Test all paths before deployment
+6. **Monitor workflow performance** - Track bottlenecks and delays
+7. **Document workflow purpose** - Add descriptions for team understanding
+8. **Use templates** - Start with proven workflow patterns
+9. **Version workflows** - Track changes over time
+10. **Limit workflow complexity** - Maximum 10-15 steps for maintainability
+
+## Example Workflows
+
+### Simple Approval Workflow
+
+```json
+{
+  "name": "Simple Approval",
+  "steps": [
+    {"name": "Submitted", "status": "submitted"},
+    {"name": "Approved", "status": "approved"},
+    {"name": "Rejected", "status": "rejected"}
+  ],
+  "transitions": [
+    {
+      "from": "submitted",
+      "to": "approved",
+      "name": "Approve",
+      "actions": [
+        {"type": "comment", "text": "Approved by {{current_user}}"},
+        {"type": "notify", "recipients": ["creator"]}
+      ]
+    },
+    {
+      "from": "submitted",
+      "to": "rejected",
+      "name": "Reject",
+      "actions": [
+        {"type": "comment", "text": "Rejected by {{current_user}}"},
+        {"type": "notify", "recipients": ["creator"]}
+      ]
+    }
+  ]
+}
+```
+
+### Multi-Stage Review Workflow
+
+```json
+{
+  "name": "Multi-Stage Review",
+  "steps": [
+    {"name": "Draft", "status": "draft"},
+    {"name": "Peer Review", "status": "peer_review"},
+    {"name": "Manager Review", "status": "manager_review"},
+    {"name": "Final Approval", "status": "final_approval"},
+    {"name": "Published", "status": "published"}
+  ],
+  "transitions": [
+    {
+      "from": "draft",
+      "to": "peer_review",
+      "name": "Submit for Peer Review",
+      "actions": [
+        {"type": "assign", "role": "peer_reviewer"},
+        {"type": "notify", "recipients": ["assigned_to"]}
+      ]
+    },
+    {
+      "from": "peer_review",
+      "to": "manager_review",
+      "name": "Escalate to Manager",
+      "conditions": [
+        {"field": "custom_fields.peer_approved", "operator": "=", "value": true}
+      ],
+      "actions": [
+        {"type": "assign", "role": "manager"},
+        {"type": "update_field", "field": "priority", "value": "high"}
+      ]
+    }
+  ]
+}
+```
+
+## Workflow Variables
+
+Use variables in action templates:
+
+- `{{activity_id}}` - Activity ID
+- `{{activity_title}}` - Activity title
+- `{{status}}` - Current status
+- `{{assigned_to}}` - Assigned user
+- `{{creator}}` - Activity creator
+- `{{current_user}}` - User performing action
+- `{{step_name}}` - Current step name
+- `{{date}}` - Current date
+- `{{custom_fields.field_name}}` - Custom field value
+
+## Error Handling
+
+Workflows can fail due to:
+- Invalid conditions
+- Missing required fields
+- Permission errors
+- Action execution failures
+
+Get workflow errors:
+
+```http
+GET /v3/workflows/{workflow_id}/errors?activity_id=act_123
+```
+
+**Response:**
+```json
+{
+  "errors": [
+    {
+      "timestamp": "2025-01-15T10:30:00Z",
+      "step": "review",
+      "action": "assign",
+      "error": "User not found",
+      "details": "Attempted to assign to user_999 which does not exist"
+    }
+  ]
+}
+```