245 lines
9 KiB
Markdown
245 lines
9 KiB
Markdown
# 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":**
|
|
```json
|
|
{
|
|
"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!
|