151 lines
4.8 KiB
Markdown
151 lines
4.8 KiB
Markdown
|
# 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 OnDeck
|
||
|
|
|
||
|
|
**All designations are created and managed within the OnDeck application.** They are NOT imported from AFW. Instead:
|
||
|
|
|
||
|
|
1. **Create a designation** in OnDeck (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 OnDeck
|
||
|
|
|
||
|
|
### Example Workflow
|
||
|
|
|
||
|
|
```
|
||
|
|
1. Admin creates "Shape" designation in OnDeck
|
||
|
|
- 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
|
||
|
|
- OnDeck 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
|
||
|
|
|
||
|
|
```prisma
|
||
|
|
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.
|