wulf-pulse/docs/addigy-mapping-implementation.md

Addigy Organization Mapping Implementation

Overview

This document describes the implementation of Addigy organization to Autotask company mappings for the Pulse application. This feature allows administrators to map Addigy organizations to Autotask companies, enabling proper device synchronization and management for Apple devices.

Components Created

1. Database Schema

File: /migrations/011_create_addigy_org_mappings.sql

Created the addigy_org_mappings table with the following structure:

• id - Primary key (auto-increment)
• addigy_org_id - Unique identifier for Addigy organization
• addigy_org_name - Display name of the Addigy organization
• autotask_company_id - Foreign key to Autotask company
• autotask_company_name - Cached company name for display
• created_at - Timestamp of mapping creation
• updated_at - Timestamp of last update (auto-updated via trigger)

Indexes:

• idx_addigy_org_id - Fast lookup by Addigy organization ID
• idx_addigy_autotask_company_id - Fast lookup by Autotask company ID

Features:

• Unique constraint on addigy_org_id to prevent duplicate mappings
• Automatic updated_at timestamp via PostgreSQL trigger
• Follows the same pattern as Auvik and RMM mappings

2. TypeScript Types

File: /lib/types/addigy.ts

Added AddigyOrgMapping interface:

export interface AddigyOrgMapping {
  id: number;
  addigyOrgId: string;
  addigyOrgName: string;
  autotaskCompanyId: number;
  autotaskCompanyName: string;
  createdAt: string;
  updatedAt: string;
}

3. API Endpoints

File: /app/api/addigy/org-mappings/route.ts

Implements three REST endpoints:

GET /api/addigy/org-mappings

• Retrieves all organization mappings from the database
• Query parameter includeUnmapped=true fetches unmapped organizations from Addigy API
• Returns mapped and unmapped organizations with statistics

POST /api/addigy/org-mappings

• Creates or updates an organization mapping
• Uses ON CONFLICT to handle upserts
• Validates required fields (addigyOrgId, autotaskCompanyId)

DELETE /api/addigy/org-mappings?id={mappingId}

• Removes a mapping by ID
• Returns success status

4. User Interface

File: /app/addigy-mappings/page.tsx

Full-featured mapping management page with:

Features:

• Stats Dashboard - Shows total, mapped, and unmapped organization counts
• Search & Filter - Real-time search and status filtering (all/mapped/unmapped)
• Mapping Table - Displays all organizations with mapping controls
• Inline Editing - Select company from dropdown, save button appears on change
• Delete Functionality - Remove existing mappings
• Loading States - Skeleton loaders during data fetch
• Error Handling - Toast notifications for success/error states

UI Components Used:

• Card, Table, Select, Input, Button, Badge, Skeleton from shadcn/ui
• Lucide icons (Smartphone, Building2, CheckCircle, XCircle, etc.)
• Responsive layout with Tailwind CSS

5. Navigation Integration

File: /components/navigation/app-navigation.tsx

Already includes Addigy mappings in the Admin menu:

• Title: "Apple RMM Mapping (Addigy)"
• Icon: Smartphone (orange)
• Route: /addigy-mappings
• Description: "Map Addigy devices to companies"

Installation Instructions

1. Apply Database Migration

Run the migration script to create the database table:

# Apply specific migration
./scripts/apply-migrations.sh 011_create_addigy_org_mappings.sql

# Or apply all pending migrations
./scripts/apply-migrations.sh

For Docker environments:

docker exec -i pulse-postgres psql -U pulse_user -d pulse_autotask < /opt/stacks/pulse/migrations/011_create_addigy_org_mappings.sql

2. Verify Addigy Client Configuration

Ensure the Addigy API client is properly configured with:

• ADDIGY_API_URL environment variable
• ADDIGY_API_TOKEN environment variable

The client is accessed via /lib/services/addigy-factory.ts which provides getAddigyClient().

3. Access the Page

Navigate to: http://localhost:3000/addigy-mappings

Or use the navigation menu: Admin → Apple RMM Mapping (Addigy)

Usage Workflow

1. View Organizations - Page loads all Addigy organizations (mapped and unmapped)
2. Create Mapping - Select an Autotask company from the dropdown for an organization
3. Save Mapping - Click the "Save" button that appears after making a change
4. Update Mapping - Change the company selection and save again
5. Delete Mapping - Click the trash icon to remove a mapping
6. Search/Filter - Use search box or filter dropdown to find specific organizations

Architecture Pattern

This implementation follows the established pattern used for:

• Auvik Tenant Mappings (/auvik-mappings)
• RMM Site Mappings (/rmm-mappings)

Benefits of this consistency:

• Familiar UI/UX for administrators
• Reusable code patterns
• Consistent database schema design
• Similar API endpoint structure

Future Enhancements

Potential improvements for future iterations:

1. Device Count Display - Show number of devices per organization
2. Auto-Discovery - Suggest mappings based on name matching
3. Bulk Operations - Map multiple organizations at once
4. Sync Integration - Trigger device sync after mapping changes
5. Audit Trail - Track who created/modified mappings
6. Policy Mapping - Map Addigy policies to Autotask service plans
7. Device Filtering - Filter devices by organization in main device view

Related Files

• Database: /migrations/011_create_addigy_org_mappings.sql
• Types: /lib/types/addigy.ts
• API: /app/api/addigy/org-mappings/route.ts
• UI: /app/addigy-mappings/page.tsx
• Navigation: /components/navigation/app-navigation.tsx
• Client: /lib/services/addigy-client.ts
• Factory: /lib/services/addigy-factory.ts

Testing Checklist

• Database migration applies successfully
• API endpoints return correct data
• Page loads without errors
• Organizations display in table
• Search functionality works
• Filter dropdown works
• Mapping creation succeeds
• Mapping update succeeds
• Mapping deletion succeeds
• Error handling displays appropriate messages
• Loading states display correctly
• Dark mode styling works
• Responsive layout on mobile devices