# GetMergeTemplates - Advanced Documentation

## Overview

Returns all merge templates available for the current firm. Use this to discover template IDs and names before calling `GetMergeTemplateByID(id)` for full details.

## Template Types

Templates are grouped by `Type.Name`:

| Type | Use |
|------|-----|
| Claim | Document templates tied to a specific claim (demands, letters, LOPs) |
| Disbursal | Disbursal statement templates |
| Advanced Search | Bulk email/text templates driven by search results |

## Generating Documents from Templates

After discovering a template via `GetMergeTemplates` and inspecting it with `GetMergeTemplateByID`, documents are generated via the `claim.merge` HTTP handler. The merge engine requires a JSON payload with the template ID, a contact ID, and an array of **prompts** that supply data to the template's merge fields.

### claim.merge Request Format

```
GET /claim.merge?json={URL-encoded JSON payload}
```

```json
{
  "TemplateID": 14248,
  "ContactID": 4500920,
  "Prompts": [
    {"Prefix": "Handling Attorney", "RecordType": "Staff",        "RecordID": 22179,   "FillInValue": "Dixon Wiles"},
    {"Prefix": "UM UIM Insurance",  "RecordType": "ClaimContact", "RecordID": 1224875, "FillInValue": "PROGRESSIVE"},
    {"Prefix": "Claim",             "RecordType": "Claim",        "RecordID": 998289},
    {"Prefix": "Claimant",          "RecordType": "Contact",      "RecordID": 4616072}
  ]
}
```

### Required Default Prompts

Every `claim.merge` request **must** include these two prompts, even though they are not listed in the template's prompt definitions:

| Prefix | RecordType | RecordID | How to resolve |
|--------|-----------|----------|----------------|
| `Claim` | `Claim` | The Claim ID | From conversation context |
| `Claimant` | `Contact` | The Claimant's **Contact ID** | `GetClaimWithoutNotes(claimId)` → `Claimant.ID` |

The Claimant prompt uses `RecordType: "Contact"` with the claimant's actual Contact ID - **not** `RecordType: "Claimant"` and **not** the Claim ID.

### RecordType Reference

| RecordType | RecordID points to | Description |
|------------|-------------------|-------------|
| `Claim` | Claim ID | Claim entity fields (dates, status, numbers) |
| `Contact` | Contact ID | Contact entity fields. Used for the **Claimant** prompt only. |
| `ClaimContact` | **ClaimContact join ID** | Contact fields resolved through the claim-contact association. Used for insurance companies, adjusters, medical providers, etc. |
| `Staff` | Person ID | Staff member fields (name, signature, title) |
| `FillIn` | N/A | Free text entered in `FillInValue` |

### Critical: Contact vs ClaimContact

Template prompts stored in the database define insurance company and similar contacts with `RecordType: "Contact"`. However, the merge engine requires `RecordType: "ClaimContact"` with the **ClaimContact join record ID** (from `GetClaimContacts`), not the generic Contact ID.

**Translation rule**: For every template prompt where `RecordType == "Contact"` (except Claimant):
1. Call `GetClaimContacts(claimId)` to get all contacts on the claim
2. Find the `ClaimContactInfo` where `Contact.ID` matches the selected contact
3. Use `ClaimContactInfo.ID` as the `RecordID` and change `RecordType` to `"ClaimContact"`

### Other Merge Handlers

| Handler | Purpose |
|---------|---------|
| `claim.merge` | Claim documents (demands, letters, LOPs) |
| `claimrequest.merge` | Claim request documents |
| `ledger.merge` | Ledger entry documents |
| `invoice.merge` | Invoice documents |
| `disbursal.merge` | Disbursal documents |

## Script Example

```javascript
async () => {
  const templates = await SecureApi.GetMergeTemplates();

  // Group by type
  const byType = {};
  templates.forEach(t => {
    const typeName = t.Type?.Name || 'Unknown';
    (byType[typeName] = byType[typeName] || []).push({ id: t.ID, name: t.Name });
  });

  return byType;
}
```

## Error Conditions

- Not logged in or no company selected - throws RadoloException
- Results are cached per firm; cache invalidated when templates are saved