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?

docker exec pulse-postgres psql -U pulse_user -d pulse_autotask -c "SELECT * FROM auvik_tenant_mappings;"

Check 2: Are devices being fetched?

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

# 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:

docker exec pulse-postgres psql -U pulse_user -d pulse_autotask -c "SELECT version();"

Check API logs:

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:

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

{
  "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.)