# GetAdvancedSearchResultString - Advanced Notes

## When to Use

Use this for firm-level queries where you need to **process data in a script** - aggregating, filtering, joining, or transforming results. Returns rows as JSON key/value objects (easier to work with than array-based `GetAdvancedSearchResults`).

## Workflow: Find → Execute → Process

```javascript
async () => {
  // Step 1: Find the right search
  const searches = await SecureApi.GetFirmAdvancedSearchesClaim(
    "open cases",  // keyword filter
    { take: 20, skip: 0, page: 1, pageSize: 20 }
  );

  // Step 2: Pick the best match by name/description
  const search = searches.Data.find(s => s.Name.includes('Total Open'));
  if (!search) return { error: 'No matching search found' };

  // Step 3: Execute and parse
  const raw = await SecureApi.GetAdvancedSearchResultString(search.ID, "");
  const rows = JSON.parse(raw);

  // Step 4: Aggregate in script (_ is lodash, available as global)
  const byType = _.groupBy(rows, 'Claim Type');
  const summary = Object.entries(byType).map(([type, claims]) => ({
    type,
    count: claims.length,
    totalValue: _.sumBy(claims, c => parseFloat(c['Estimated Value'] || '0'))
  }));

  return { searchName: search.Name, totalRows: rows.length, summary: _.orderBy(summary, 'count', 'desc') };
}
```

## Parameter Overrides

Override search filters at runtime using `ParametersJson`. Each override matches a filter field by `ParameterName` (discoverable via `GetAdvancedSearchFilters(searchId)` - it returns each filter's `ParameterName`, `Operator`, and current value slots; copy the filter, replace the populated slot, and pass a flat JSON array as ParametersJson) and sets a typed value property:

```javascript
// Override filters - use ParameterName (not FieldName) and typed value properties (not Value)
const params = JSON.stringify([
  { ParameterName: "Status", ValueString: "Won" },
  { ParameterName: "IncidentDate", BetweenValueDate: { StartValue: "2024-01-01", EndValue: "2024-12-31" } }
]);
const raw = await SecureApi.GetAdvancedSearchResultString(searchId, params);
```

See `GetAdvancedSearchResults` advanced documentation for the full DataType-to-property mapping table and details on discovering available parameter names.

## Key Differences from GetAdvancedSearchResults

| Feature | GetAdvancedSearchResultString | GetAdvancedSearchResults |
|---------|------------------------------|------------------------|
| Return format | JSON string of key/value objects | Columns + DataJson arrays |
| Best for | Script processing (filter, group, join) | Display in grids |
| Time zone | Converts to local | No conversion |
| Parsing | `JSON.parse(result)` → array of objects | Parse DataJson per row |

## Combining Multiple Searches

```javascript
async () => {
  // Run multiple searches in parallel
  const [openClaims, closedClaims] = await Promise.all([
    SecureApi.GetAdvancedSearchResultString(openSearchId, ""),
    SecureApi.GetAdvancedSearchResultString(closedSearchId, "")
  ]);

  const open = JSON.parse(openClaims);
  const closed = JSON.parse(closedClaims);

  return {
    open: { count: open.length, byType: _.countBy(open, 'Claim Type') },
    closed: { count: closed.length, byType: _.countBy(closed, 'Claim Type') },
    total: open.length + closed.length
  };
}
```