# SaveClaimType - Advanced Documentation

## Overview
Creates or updates a claim type configuration including staff roles, expected event triggers, and form design hierarchy. For new types, auto-generates intake HTML and duplicates the menu/widget/field structure from a template. For existing types, removes unassigned staff roles from claims. Clears intake designer and claim security caches after save.

## Business Rules
- Claim type Name is required (validated by `ValidateClaimTypes`)
- Claim type Name must be unique per company (enforced by database index `idx_claimtypename`)
- The FirmID is set from the current company at the API layer before reaching the controller
- For existing claim types: staff roles that are no longer in the `StaffRoles` collection are deleted from all claims of this type via `spDeleteMissingClaimTypeRolesFromClaims`
- For new claim types:
  - A placeholder IntakeHTML is set: `<div><p>Please go to the intake designer and build this {claimLabel} type.</p></div>`
  - Expected events are created from the input, each requiring either an AdHocField or SystemField reference
  - Expected event task bundles are synced as subtypes
  - The entire menu/widget/field structure is duplicated from the template via `CopyClaimTypeDesign`
  - Intake widgets are also duplicated
  - Generated forms (HTML) are regenerated via `UpdateClaimTypeGeneratedForms`
- Staff roles are synced to the `CompanyClaimTypeStaffRoles` subtype
- After entity save, `spSaveClaimTypeStaffRoles` is called to propagate staff role changes to claims
- Multiple caches are cleared: intake setup, claim types, and claim security info

## Permissions & Security
- Caller must be logged in (`curPerson.ID >= 1`)
- Caller must have a company selected (`curCompany.ID >= 1`)
- Caller must be a member of the current company
- Caller must have the **ManageFirm** permission

## Data Flow
1. Verify ManageFirm permission
2. Validate claim type name is not empty
3. Begin transaction
4. For existing types: execute `spDeleteMissingClaimTypeRolesFromClaims` to remove unassigned roles
5. Load or create the `CompanyClaimTypes` Aptify entity
6. Set fields: CompanyID, Icon, Name, Abbreviation, UseContingencyBasis
7. For new types: create expected events with system/ad-hoc field references and task bundles
8. For new types: set placeholder IntakeHTML
9. Sync staff roles to `CompanyClaimTypeStaffRoles` subtype
10. Save the claim type entity
11. For new types: call `CopyClaimTypeDesign` which:
    a. Duplicates each menu from the template as new `ClaimTypeMenus` records
    b. For each menu, duplicates widgets as new `ClaimTypeMenuWidgets` records
    c. For each widget, duplicates fields via `CopyClaimTypeFormFields` (resolves ad hoc field references by label)
    d. Duplicates intake widgets as `CompanyClaimTypeIntakeWidgets` records with their fields
    e. Clears intake cache and regenerates forms via `UpdateClaimTypeGeneratedForms`
    f. Saves the claim type entity again to persist generated content
12. Execute `spSaveClaimTypeStaffRoles` to propagate roles to claims
13. Commit transaction
14. Clear intake setup cache, claim types cache, and claim security info cache

## Side Effects
- **Database writes**: CompanyClaimTypes entity created or updated
- **Database writes**: CompanyClaimTypeStaffRoles subtype synced
- **Database writes**: CompanyClaimTypeExpectedEvents and their task bundles created (new types only)
- **Database deletes**: `spDeleteMissingClaimTypeRolesFromClaims` removes unassigned roles from existing claims
- **Database writes**: `spSaveClaimTypeStaffRoles` propagates role assignments
- **Database writes**: ClaimTypeMenus, ClaimTypeMenuWidgets, ClaimTypeMenuWidgetFields duplicated (new types only)
- **Database writes**: CompanyClaimTypeIntakeWidgets and their fields duplicated (new types only)
- **Database writes**: Generated claim forms (HTML) regenerated (new types only)
- **Cache invalidation**: Intake setup cache cleared via `ClearIntakeSetupCache(CompanyID)`
- **Cache invalidation**: Claim types cache cleared via `ClearClaimTypesCache(CompanyID)` (removes both list and individual type cache entries)
- **Cache invalidation**: Claim security info cache cleared for the firm via `ClearSecurityInfoCacheForFirm`

## Error Conditions
- `RadoloException("You must be logged in to perform this action.")` - not authenticated
- `RadoloException("You must have a company selected to perform this action.")` - no company
- `RadoloException("You can only perform this action for a company you are a member of.")` - not in company
- `RadoloException("You do not have permission to save {claimLabel} types...")` - missing ManageFirm
- `RadoloException("All Claim Types must have a name.")` - empty name
- `RadoloException("There is already a @[ClaimLabel] Type with this name!")` - duplicate name (caught at API layer from `idx_claimtypename` constraint)
- `RadoloException("Expected events must have a field selected.")` - expected event without ad hoc or system field
- `RadoloException("There was a problem saving the {claimLabel} Type: {error}")` - entity save failed
- `RadoloException("There was a problem saving this {claimLabel} type menu : {error}")` - menu duplication failed
- `RadoloException("There was a problem saving this {claimLabel} type menu widget : {error}")` - widget duplication failed
- `RadoloException("There was a problem saving this intake widget: {error}")` - intake widget duplication failed

## Usage Notes
- Creating a new claim type is a heavyweight operation that duplicates the entire form design hierarchy (menus, widgets, fields, intake widgets). The input `ClaimType` must include the template's `Menus` and `IntakeWidgets` collections for the copy to work.
- The `@[ClaimLabel]` token in the duplicate name error is a client-side label replacement placeholder, not a server-side template.
- Staff role removal (`spDeleteMissingClaimTypeRolesFromClaims`) affects all existing claims of this type, not just the type definition. Removing a role from a claim type removes it from every claim of that type.
- The ad hoc field resolution during `CopyClaimTypeFormFields` matches by `FieldLabel`, so field labels must be unique within the claim type's ad hoc fields for correct mapping.
- The entire operation runs in a single transaction. If any step fails, all changes are rolled back.