wulf-pulse/docs/AUVIK_TESTING_GUIDE.md

# Auvik Integration Testing Guide

## Quick Start

### Step 1: Map Auvik Tenants
1. Navigate to: `https://pulse.wulfconsulting.cloud/auvik-mappings`
2. You'll see all Auvik tenants (17 total based on logs)
3. For each tenant you want to use, select the matching Autotask company from the dropdown
4. Click "Save"

### Step 2: Verify Mapping
- Status badge should change from orange "Unmapped" to green "Mapped"
- Stats at the top should update

### Step 3: View Auvik Data
1. Go to: `https://pulse.wulfconsulting.cloud/configuration-items`
2. Select a company that you just mapped
3. You should now see:
   - ✅ Checkmarks in the "Auvik" column for matched devices
   - Auvik tab in the device detail modal with full device information

## How the Matching Works

### Priority Order:
1. **Database Mapping** (NEW) - Uses explicit tenant-to-company mappings
   - Most accurate
   - User-controlled
   - Recommended approach

2. **Fuzzy Name Matching** (Fallback) - Automatic matching by name similarity
   - Less reliable
   - Used when no mapping exists
   - May miss matches if names differ

### Matching Flow:
```
User selects company → 
  Check database for mapping → 
    If found: Use mapped tenant → Fetch devices → Match by serial/hostname/MAC
    If not found: Try fuzzy name match → Fetch devices → Match by serial/hostname/MAC
```

## Example Test Case

### Test with "Wulf Consulting"

1. **Map the tenant:**
   - Go to `/auvik-mappings`
   - Find tenant "wulfconsulting" 
   - Select "Wulf Consulting" from company dropdown
   - Click Save

2. **View devices:**
   - Go to `/configuration-items`
   - Select "Wulf Consulting" from company dropdown
   - Look for devices with Auvik checkmarks

3. **View details:**
   - Click on a device with an Auvik checkmark
   - Click the "Auvik Data" tab
   - You should see:
     - Device name
     - Serial number
     - Online/offline status
     - IP addresses
     - MAC addresses
     - Network interfaces
     - Firmware version

## Troubleshooting

### No Auvik Data Showing

**Check 1: Is the tenant mapped?**
```bash
docker exec pulse-postgres psql -U pulse_user -d pulse_autotask -c "SELECT * FROM auvik_tenant_mappings;"
```

**Check 2: Are devices being fetched?**
```bash
docker logs pulse-app --tail 100 | grep -i auvik
```

You should see:
- "Found Auvik tenant via mapping: [tenant] for company ID: [id]"
- "Fetched X Auvik devices"
- "Matched Auvik device by [serial/hostname/MAC]"

**Check 3: Test the API directly**
```bash
# Test tenant mappings endpoint
curl http://localhost:3100/api/auvik/tenant-mappings

# Test devices endpoint (replace with your company ID)
curl "http://localhost:3100/api/rmm-devices?companyId=29682574&companyName=Wulf%20Consulting"
```

### Mapping Not Saving

**Check database connection:**
```bash
docker exec pulse-postgres psql -U pulse_user -d pulse_autotask -c "SELECT version();"
```

**Check API logs:**
```bash
docker logs pulse-app --tail 50
```

### Devices Not Matching

**Check matching logic:**
The system matches devices in this priority:
1. Serial number (exact match)
2. Hostname (exact match)
3. MAC address (normalized)

**View matching logs:**
```bash
docker logs pulse-app --tail 200 | grep -E "(Matched|No match)"
```

## Expected Behavior

### When Mapping Exists:
```
✅ Fast lookup (database query)
✅ Accurate tenant selection
✅ Consistent results
✅ User-controlled
```

### When No Mapping:
```
⚠️ Slower (fuzzy matching)
⚠️ May miss matches
⚠️ Depends on name similarity
⚠️ Automatic (no control)
```

## Recommended Workflow

1. **Initial Setup:**
   - Map all active Auvik tenants to their corresponding companies
   - Test with 2-3 companies to verify

2. **Ongoing:**
   - When adding a new company to Auvik, add the mapping
   - Review unmapped tenants monthly

3. **Maintenance:**
   - Check logs for "No mapping found" messages
   - Add mappings as needed

## API Endpoints Reference

### GET `/api/auvik/tenant-mappings`
Fetch all mappings
- Query: `?includeUnmapped=true` - includes unmapped tenants

### POST `/api/auvik/tenant-mappings`
Create/update mapping
```json
{
  "auvikTenantId": "123abc",
  "auvikTenantName": "wulfconsulting",
  "autotaskCompanyId": 29682574,
  "autotaskCompanyName": "Wulf Consulting"
}
```

### DELETE `/api/auvik/tenant-mappings?id={id}`
Remove mapping

### GET `/api/rmm-devices?companyId={id}&companyName={name}`
Fetch devices (includes Auvik)
- Now uses mapping first, then falls back to name matching

### GET `/api/configuration-items/{id}?type=autotask`
Fetch device details (includes Auvik)
- Now uses mapping first, then falls back to name matching

## Success Metrics

After mapping tenants, you should see:
- ✅ Green checkmarks in Auvik column
- ✅ "Auvik Data" tab populated in device modals
- ✅ Logs showing "Found tenant via mapping"
- ✅ Device counts matching between Auvik and Autotask

## Next Steps

1. Map all 17 Auvik tenants to their companies
2. Verify device data appears correctly
3. Report any issues with matching logic
4. Consider adding more matching fields if needed (IP address, etc.)