seubert-claims/ondeck/docs/designation-admin-guide.md

Designation Admin Interface - User Guide

Overview

The Designation Admin Interface allows administrators to create and manage client designations with automatic synchronization from AMS360/AFW.

Key Concepts

Designations are Created in Horizon

All designations are created and managed within the Horizon application. They are NOT imported from AFW. Instead:

1. Create a designation in Horizon (e.g., "Shape", "Premium", "VIP")
2. Optionally map it to an AFW ANotId (a GUID that identifies customers in AMS360)
3. Sync to automatically assign clients based on their AFW data

AFW ANotId Mapping

Each designation can have an optional AFW ANotId field:

• This is a GUID from AMS360/AFW (e.g., 13CF7DCB-F6AF-42C2-A7AB-26641A216A81)
• It identifies a group of customers in the AFW database
• When you sync, clients with this ANotId in AFW get assigned to this designation in Horizon

Example Workflow

1. Admin creates "Shape" designation in Horizon
   - Name: Shape
   - Color: Indigo
   - AFW ANotId: 13CF7DCB-F6AF-42C2-A7AB-26641A216A81

2. Admin clicks "Preview" to see which AFW customers match
   - Shows: 150 customers found in AFW with this ANotId

3. Admin saves the designation

4. Admin clicks "Sync" on the Shape designation
   - Horizon queries AFW for customers with ANotId 13CF7DCB-...
   - Finds matching clients in local database
   - Updates their designationId to "Shape"
   - Result: 145 clients updated, 5 skipped (already had Shape)

5. Admin creates "Premium" designation
   - Name: Premium
   - Color: Gold
   - AFW ANotId: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX (different GUID)
   - Syncs separately from Shape

Features

Create/Edit Designations

• Name: Display name (e.g., "Shape", "Premium")
• Description: Purpose of the designation
• Color: Visual identifier in the UI
• Display Order: Sort order in lists
• AFW ANotId: Optional GUID for AFW sync
• Active Status: Enable/disable without deleting

Preview Before Saving

• Enter an AFW ANotId
• Click the eye icon to preview
• See how many customers in AFW match
• View sample customer names
• Helps verify you have the correct GUID

Individual Sync

• Click "Sync" on any designation with an ANotId
• Syncs only that designation
• Shows results: updated, skipped, not found

Bulk Sync

• Click "Sync All Designations"
• Syncs all active designations that have an ANotId configured
• Shows summary results for each designation

Uniqueness Constraints

• Designation names must be unique
• AFW ANotId values must be unique (one designation per ANotId)
• Prevents conflicts and duplicate mappings

API Endpoints

GET /api/admin/designations

List all designations with client counts

POST /api/admin/designations

Create a new designation

GET /api/admin/designations/[id]

Get a specific designation

PATCH /api/admin/designations/[id]

Update a designation

DELETE /api/admin/designations/[id]

Soft delete (deactivate) a designation

POST /api/admin/designations/preview

Preview AFW customers for an ANotId

POST /api/admin/sync-designations

Sync a single designation by ID or type

POST /api/admin/sync-designations/bulk

Sync all active designations with ANotId configured

Database Schema

model Designation {
  id           String   @id @default(cuid())
  name         String   @unique
  description  String?
  color        String
  rules        String?
  displayOrder Int
  isActive     Boolean  @default(true)
  afwAnotId    String?  @unique  // Maps to AFW ANotId
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  clientsDesignation1 Client[] @relation("ClientDesignation1")
  clientsDesignation2 Client[] @relation("ClientDesignation2")
  taskTemplates       TaskTemplate[]
}

Common Questions

Q: Where do I find the AFW ANotId? A: Query the AFW database directly or ask your AMS360 administrator. It's a GUID that identifies customer groups.

Q: Can I have multiple designations with the same ANotId? A: No, each ANotId must be unique to prevent conflicts.

Q: What happens if I sync without an ANotId? A: The sync will fail with an error. ANotId is required for AFW sync.

Q: Can I create designations without AFW sync? A: Yes! Leave the AFW ANotId field empty. You can manually assign clients to these designations.

Q: What's the difference between Shape and other designations? A: Nothing! Shape is just a designation like any other. It happens to map to a specific ANotId in AFW.

Q: Can I change the ANotId after creating a designation? A: Yes, edit the designation and update the ANotId field. Then sync again.

Q: What happens to clients when I delete a designation? A: The designation is deactivated (soft delete). Clients keep their assignment, but the designation won't appear in new assignment lists.