wulf-pulse/docs/workflow-editor-guide.md

Workflow Editor User Guide

Overview

The Workflow Editor lets you visually design and configure ticket workflows with a step-by-step approach.

---

Understanding the Steps

Step 1-5: Classification (Purple)

What they do: Match keywords in ticket title/description to classify the ticket

Step 1: Branch Routing

• Determines which team handles the ticket (NOC, SOC, Service Desk)
• Uses classification rules with keywords like "backup", "phishing", "password reset"
• Config: {"rule_type": "branch_routing", "result_field": "branch", "default_value": "service_desk"}

Step 2: Ticket Type

• Classifies as Incident (2) or Service Request (1)
• Keywords: "not working", "stopped working" → Incident
• Keywords: "how do i", "please set up" → Service Request
• Config: {"rule_type": "ticket_type", "result_field": "ticket_type"}

Step 3: Issue Classification

• Determines issue type (Email, AD, Network, Hardware, etc.) and sub-issue type
• Uses 50+ classification rules with specific keywords
• Config: {"rule_type": "issue_classification", "result_field": "issue_type", "result_field_2": "sub_issue_type"}

Step 4: Priority

• Sets ticket priority based on keywords and impact
• Security keywords → Security Event priority
• "multiple users" → Critical priority
• Config: {"rule_type": "priority", "result_field": "priority"}

Step 5: Queue Routing

• Routes to correct queue based on device patterns, priority, etc.
• Critical priority → Level 2 queue
• Workstation devices → Level 1 queue
• Config: {"rule_type": "queue_routing", "result_field": "queue_id"}

Step 6: Validation (Yellow)

What it does: Checks if all classifications are valid against database picklists

• Validates issue_type exists
• Validates sub_issue_type is a child of issue_type
• Validates priority exists
• Validates queue exists
• Config: {"required_fields": []}
• Output: Sets context.validation.is_valid (true/false)

Step 7: AI Classification (Blue) - Conditional

What it does: Uses AI to classify fields that robotic classification missed

• Only runs if: Validation failed (condition: context.validation.is_valid === false)
• Sends ticket to AI with available picklist options
• AI selects the correct issue type, sub-issue type, etc.
• Config: {"template_purpose": "ambiguous_classification", "skip_if_valid": true}

Step 8: AI Title Cleanup (Blue) - Conditional

What it does: Cleans up messy ticket titles

• Only runs if: Classification indicates title needs cleanup
• Removes email prefixes (Re:, Fw:), ticket numbers, excessive punctuation
• Condenses long titles to max 80 characters
• Config: {"template_purpose": "title_cleanup"}

Step 9: Delay (Gray)

What it does: Waits before updating Autotask

• Configurable delay (default: 30 seconds)
• Allows time for user to cancel if needed
• Uses template variable for setting: {{settings.autotask_update_delay_ms}}
• Config: {"duration_ms": "{{settings.autotask_update_delay_ms}}"}

Step 10: Update Ticket (Green)

What it does: Writes all accumulated field changes to Autotask

• Takes all changes from previous steps (stored in context.field_changes)
• Updates ticket in Autotask via API
• Updates local database copy
• Config: {"use_field_changes": true}
• Important: If this step fails, workflow stops (on_failure: 'stop')

Step 11: AI Troubleshooting (Blue) - Conditional

What it does: Generates troubleshooting steps for incidents

• Only runs if: Ticket type is Incident (ticket_type === 2)
• AI generates 3-5 troubleshooting steps
• Creates a ticket note with the steps (TODO: not implemented yet)
• Config: {"template_purpose": "troubleshooting_steps", "create_note": true}

---

How to Use the Editor

Viewing Steps

1. Go to /admin/workflow/1 (or click Edit on a workflow)
2. Steps tab shows all steps in order
3. Each step shows:
   • Step number (e.g., #1)
   • Step name (e.g., "Branch Routing")
   • Step type badge (e.g., "classify")
   • Active/Inactive toggle

Expanding a Step

1. Click "Expand" button on any step
2. You'll see:
   • Blue help box explaining what the step does
   • Configuration fields list
   • Example JSON
   • Step Name input
   • On Failure dropdown
   • Configuration JSON textarea

Editing Configuration

The JSON config defines step behavior:

Example for "Branch Routing":

{
  "rule_type": "branch_routing",
  "result_field": "branch",
  "default_value": "service_desk"
}

• rule_type: Which classification rules to use
• result_field: Where to store the result in context
• default_value: What to use if no rules match

Reordering Steps

• Use ↑ ↓ arrows on the left side of each step
• Steps execute in numerical order (1, 2, 3...)
• Reordering updates the step_order automatically

Toggling Steps

• Toggle switch on each step to enable/disable
• Disabled steps are skipped during execution
• Useful for debugging (e.g., disable AI steps to test faster)

Saving Changes

• Click "Save Changes" button at the top
• Saves both workflow metadata and all steps
• Green toast notification on success

---

Other Tabs

Trigger Tab

• Workflow Name: Display name
• Description: What this workflow does
• Trigger Event: ticket.created or ticket.updated
• Trigger Conditions: JSON array of conditions that must match
  • Example: Only process tickets in NOC/Service Desk categories
  • Example: Exclude certain creator users or companies

Test Tab

• Dry-run testing (shows endpoint for now)
• Select a ticket ID
• Run workflow without actually updating Autotask
• See step-by-step results and proposed changes

History Tab

• Execution history for this specific workflow
• Shows recent runs with status (completed, failed, skipped)
• Click to see detailed step-by-step breakdown

---

Tips for Non-Technical Users

You don't need to write code! The JSON is just configuration:

1. To change what a step does:

   • Expand the step
   • Read the blue help box
   • Copy the example JSON
   • Modify the values you need

2. To disable a step temporarily:

   • Just toggle it off (no need to delete)

3. To test changes:

   • Save your changes
   • Go to Test tab
   • Run a dry-run to see what would happen

4. To see if it's working:

   • Go to History tab
   • Look for recent executions
   • Check if status is "completed" (green)

5. Common Changes:

   • Change delay: Edit Step 9, change duration_ms from 30000 to 60000 (60 seconds)
   • Disable AI: Toggle off Steps 7, 8, 11 to use only robotic classification
   • Change default branch: Edit Step 1, change default_value from "service_desk" to "noc"

---

Visual Guide

Collapsed Step:

┌─────────────────────────────────────────┐
│ ↑↓  #1  Branch Routing  [classify]  ✓   │
│                               [Expand]   │
└─────────────────────────────────────────┘

Expanded Step:

┌─────────────────────────────────────────┐
│ ↑↓  #1  Branch Routing  [classify]  ✓   │
│                             [Collapse]   │
├─────────────────────────────────────────┤
│ 📘 What This Step Does                  │
│ Uses keyword-based classification...    │
│                                         │
│ Configuration Fields:                   │
│ • rule_type: branch_routing             │
│ • result_field: branch                  │
│ • default_value: service_desk           │
│                                         │
│ Example: {"rule_type": "branch_r..."}   │
├─────────────────────────────────────────┤
│ Step Name: [Branch Routing______]      │
│                                         │
│ On Failure: [Continue to next step ▼]  │
│                                         │
│ Configuration (JSON):                   │
│ ┌───────────────────────────────────┐  │
│ │ {                                 │  │
│ │   "rule_type": "branch_routing",  │  │
│ │   "result_field": "branch",       │  │
│ │   "default_value": "service_desk" │  │
│ │ }                                 │  │
│ └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

---

Need help? The blue help box in each expanded step explains everything you need to know!