122 lines
4.3 KiB
Markdown
122 lines
4.3 KiB
Markdown
|
# Auvik Tenant Mapping
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
The Auvik Tenant Mapping feature allows administrators to manually map Auvik tenants to Autotask companies. This ensures accurate device matching when company names don't align between systems.
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
### 1. **Tenant Mapping Page** (`/auvik-mappings`)
|
||
|
|
- View all Auvik tenants (mapped and unmapped)
|
||
|
|
- Map tenants to Autotask companies via dropdown selection
|
||
|
|
- Search and filter tenants by status
|
||
|
|
- Real-time statistics dashboard
|
||
|
|
- Save/delete mappings with immediate feedback
|
||
|
|
|
||
|
|
### 2. **Database Storage**
|
||
|
|
- Mappings stored in `auvik_tenant_mappings` table
|
||
|
|
- Unique constraint on `auvik_tenant_id` (one tenant = one company)
|
||
|
|
- Automatic timestamp tracking (created_at, updated_at)
|
||
|
|
- Indexed for fast lookups
|
||
|
|
|
||
|
|
### 3. **API Endpoints**
|
||
|
|
|
||
|
|
#### GET `/api/auvik/tenant-mappings`
|
||
|
|
Fetch all tenant mappings
|
||
|
|
- Query param: `includeUnmapped=true` - includes unmapped tenants from Auvik API
|
||
|
|
- Returns: `{ mappings: AuvikTenantMapping[], totalMapped: number, totalUnmapped: number }`
|
||
|
|
|
||
|
|
#### POST `/api/auvik/tenant-mappings`
|
||
|
|
Create or update a tenant mapping
|
||
|
|
- Body: `{ auvikTenantId, auvikTenantName, autotaskCompanyId, autotaskCompanyName }`
|
||
|
|
- Returns: `{ mapping: AuvikTenantMapping }`
|
||
|
|
|
||
|
|
#### DELETE `/api/auvik/tenant-mappings?id={id}`
|
||
|
|
Delete a tenant mapping
|
||
|
|
- Query param: `id` - mapping ID to delete
|
||
|
|
- Returns: `{ success: true }`
|
||
|
|
|
||
|
|
### 4. **Integration with Device Matching**
|
||
|
|
|
||
|
|
The Auvik client now prioritizes database mappings over fuzzy matching:
|
||
|
|
|
||
|
|
1. **Primary**: Check database for explicit company ID → tenant mapping
|
||
|
|
2. **Fallback**: Use fuzzy name matching (existing logic)
|
||
|
|
|
||
|
|
This ensures:
|
||
|
|
- Accurate matching even when names differ significantly
|
||
|
|
- User control over tenant associations
|
||
|
|
- No breaking changes to existing functionality
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
### Step 1: Access the Mapping Page
|
||
|
|
Navigate to: `https://pulse.wulfconsulting.cloud/auvik-mappings`
|
||
|
|
|
||
|
|
### Step 2: Map Tenants
|
||
|
|
1. Find an unmapped tenant (orange badge)
|
||
|
|
2. Click the dropdown in the "Autotask Company" column
|
||
|
|
3. Select the corresponding company
|
||
|
|
4. Click "Save"
|
||
|
|
|
||
|
|
### Step 3: Verify
|
||
|
|
- The status badge changes to green "Mapped"
|
||
|
|
- Stats update automatically
|
||
|
|
- Configuration items page will now use this mapping
|
||
|
|
|
||
|
|
### Step 4: View Devices
|
||
|
|
Go to `/configuration-items`, select the mapped company, and see Auvik devices appear in the Auvik column and tab.
|
||
|
|
|
||
|
|
## Database Schema
|
||
|
|
|
||
|
|
```sql
|
||
|
|
CREATE TABLE auvik_tenant_mappings (
|
||
|
|
id SERIAL PRIMARY KEY,
|
||
|
|
auvik_tenant_id VARCHAR(255) NOT NULL UNIQUE,
|
||
|
|
auvik_tenant_name VARCHAR(255) NOT NULL,
|
||
|
|
autotask_company_id INTEGER NOT NULL,
|
||
|
|
autotask_company_name VARCHAR(255) NOT NULL,
|
||
|
|
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
|
||
|
|
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
|
||
|
|
);
|
||
|
|
```
|
||
|
|
|
||
|
|
## Migration Applied
|
||
|
|
- **File**: `migrations/009_create_auvik_tenant_mappings.sql`
|
||
|
|
- **Status**: ✅ Applied to database
|
||
|
|
- **Command**: `docker exec pulse-postgres psql -U pulse_user -d pulse_autotask -f /docker-entrypoint-initdb.d/009_create_auvik_tenant_mappings.sql`
|
||
|
|
|
||
|
|
## Files Created/Modified
|
||
|
|
|
||
|
|
### New Files
|
||
|
|
- `/app/auvik-mappings/page.tsx` - Main mapping UI
|
||
|
|
- `/app/api/auvik/tenant-mappings/route.ts` - API endpoints
|
||
|
|
- `/migrations/009_create_auvik_tenant_mappings.sql` - Database schema
|
||
|
|
- `/lib/types/auvik.ts` - Added `AuvikTenantMapping` interface
|
||
|
|
|
||
|
|
### Modified Files
|
||
|
|
- `/lib/services/auvik-client.ts` - Added `findTenantByCompanyId()` method
|
||
|
|
- `/docker-compose.yml` - Added Auvik environment variables
|
||
|
|
|
||
|
|
## Next Steps
|
||
|
|
|
||
|
|
1. **Add Navigation Link**: Add a link to `/auvik-mappings` in the main navigation menu
|
||
|
|
2. **Enhance Toast**: Replace simple alert-based toast with a proper toast component library
|
||
|
|
3. **Bulk Import**: Add ability to import mappings from CSV
|
||
|
|
4. **Auto-Suggest**: Add AI-powered suggestions for likely company matches based on name similarity
|
||
|
|
5. **Audit Log**: Track who created/modified mappings and when
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
### No Tenants Showing
|
||
|
|
- Check Auvik API credentials in `.env.local`
|
||
|
|
- Verify Auvik client initialization in logs: `docker logs pulse-app | grep -i auvik`
|
||
|
|
|
||
|
|
### Mapping Not Working
|
||
|
|
- Verify database migration was applied
|
||
|
|
- Check API endpoint response: `curl http://localhost:3100/api/auvik/tenant-mappings`
|
||
|
|
- Review console logs for errors
|
||
|
|
|
||
|
|
### Companies Not Loading
|
||
|
|
- Ensure Autotask API is accessible
|
||
|
|
- Check `/api/companies` endpoint returns data
|