---
name: jmeter-correlation-naming
description: >-
  Review, adjust, or generate JMeter correlation variable names from
  correlation_spec.json files. Use when working with correlation_naming.json,
  correlation specs, JMeter variable naming, or when the user mentions
  correlation naming, variable mapping, or correlation review.
---

# JMeter Correlation Naming

## Overview

The `correlation_naming.json` file maps each `correlation_id` from a `correlation_spec.json`
to a meaningful JMeter variable name, extractor type, and extractor expression. It is consumed
by `generate_jmeter_script` to produce the parameterized JMX.

### Auto-Generated by Default

The `analyze_network_traffic` MCP tool **automatically generates** `correlation_naming.json`
as Phase 4 of the correlation analysis pipeline. The algorithmic naming engine
(`services/correlations/naming.py`) applies deterministic rules:

1. **Custom mappings** from `correlation_config.yaml` (highest priority)
2. **OAuth parameter lookups** (e.g., `state` -> `oauth_state`)
3. **OAuth token field lookups** (e.g., `cdssotoken` -> `cdsso_token`)
4. **Timestamp URL-pattern matching** (e.g., SignalR URLs -> `signalr_timestamp_N`)
5. **Algorithmic camelCase -> snake_case conversion** (e.g., `entityGuid` -> `entity_guid`)
6. **De-duplication suffixes** when the same base name is assigned to multiple correlations

### Configuration: `correlation_config.yaml`

The naming engine reads customizable mappings from `jmeter-mcp/correlation_config.yaml`.
Falls back to `jmeter-mcp/correlation_config.example.yaml` if the local file does not exist.

To customize naming for your application:

1. Copy `correlation_config.example.yaml` to `correlation_config.yaml`
2. Add entries under `naming.custom_mappings` for application-specific field names
3. The local file is git-ignored

```yaml
naming:
  custom_mappings:
    entityGuid: "product_guid"
    productDataSourceId: "data_source_id"
```

---

## When to Use This Skill

- **Reviewing** the auto-generated `correlation_naming.json` for clarity and accuracy
- **Adjusting** variable names after auto-generation (manual overrides)
- **Generating** `correlation_naming.json` from scratch for older correlation specs
  that were produced before algorithmic naming was added

---

## Scenario A: Reviewing Auto-Generated Output

When `analyze_network_traffic` has already produced `correlation_naming.json`:

1. Read both `correlation_naming.json` and the corresponding `correlation_spec.json`
2. Review each variable name:
   - Does the name reflect the domain entity? (e.g., `entity_guid` for an entity GUID)
   - Are OAuth parameters using the standard names? (see [naming-conventions.md](naming-conventions.md))
   - Are orphan variables descriptively named (not generic like `corr_var`)?
3. If adjustments are needed, update `correlation_naming.json` directly
4. If the same pattern will recur, suggest adding a `custom_mappings` entry to
   `correlation_config.yaml` so the engine handles it automatically next time

## Scenario B: Generating from Scratch

When no `correlation_naming.json` exists (e.g., older correlation specs):

1. Read the entire `correlation_spec.json`
2. For each correlation with `correlation_found: true`:
   - Infer the resource/purpose from `source_key`, `source_json_path`, URLs, and step labels
   - Generate a descriptive `variable_name` following the naming conventions
   - Set `jmeter_extractor_type` based on `source_location`
   - Generate `jmeter_extractor_expression` (JSONPath or regex)
3. For each correlation with `correlation_found: false`:
   - Place in `orphan_variables` array
   - Suggest parameterization strategy based on `parameterization_hint`
4. Return valid JSON matching the output schema (see [naming-conventions.md](naming-conventions.md))

---

## Validation Rules (Mandatory — Both Scenarios)

### Uniqueness

- Every `variable_name` across both `variables` and `orphan_variables` MUST be unique
- If duplicates exist, rename using more specific context (`source_key`, `location_key`,
  or numeric suffix as last resort)

### Name Quality

Variable names MUST NOT be:

- Empty or blank
- Just a number suffix (e.g., `_22`, `_23`)
- Overly generic (e.g., `value`, `value_19`, `id`)

If any fail validation, re-derive using the orphan naming rules in [naming-conventions.md](naming-conventions.md).

---

## Quick Reference: Naming Rules

### General

- Use `snake_case` for all variable names
- Use singular nouns for IDs (`product_id` not `products_id`)
- Do not embed literal values in variable names

### By Correlation Type

| Type | Pattern | Examples |
|------|---------|----------|
| `business_id` | `<resource>_id` | `product_id`, `order_id`, `customer_id` |
| `correlation_id` | `<purpose>_id` | `request_id`, `trace_id`, `session_id` |
| `oauth_param` | Standard OAuth names | `oauth_state`, `oauth_nonce`, `oauth_client_id` |

### Extractor Type Selection

| source_location | Extractor Type |
|-----------------|---------------|
| `response_json` | `json_extractor` |
| `response_header` | `regex_extractor` |
| `response_redirect_url` | `regex_extractor` |
| `response_set_cookie` | `regex_extractor` |
| `response_html_form` | `regex_extractor` |

### Context-Based Naming (Inference Order)

1. `source.source_key` — the JSON field name (e.g., `productId` -> `product_id`)
2. `source.source_json_path` — path context (e.g., `$.items[0].orderId` -> `order_id`)
3. `source.request_url` — API endpoint (e.g., `/products/` -> `product_id`)
4. `usages[*].request_url` — where it's used
5. `source.step_label` — business context from step description

---

## Additional Resources

For detailed schemas, full naming tables, OAuth parameter mappings, orphan naming rules,
SignalR patterns, and input/output examples, see [naming-conventions.md](naming-conventions.md).
