@simonecoelhosfo/optimizely-mcp-server/dist/resources/docs/entity-relationships.md

Optimizely MCP Server for AI assistants with integrated CLI tools

# Optimizely Entity Relationships Guide

## Platform Comparison Matrix

| Entity Type | Feature Experimentation | Web Experimentation |
|-------------|------------------------|---------------------|
| **Shared Entities** |
| Projects | ✅ | ✅ |
| Environments | ✅ (read-only) | ✅ (full CRUD) |
| Experiments | ✅ | ✅ |
| Audiences | ✅ | ✅ |
| Attributes | ✅ | ✅ |
| Events | ✅ | ✅ |
| Groups | ✅ | ✅ |
| List Attributes | ✅ | ✅ |
| **Feature Experimentation Only** |
| Flags | ✅ | ❌ |
| Variable Definitions | ✅ | ❌ |
| Variations | ✅ | ❌ |
| Rulesets | ✅ | ❌ |
| Rules | ✅ | ❌ |
| Features (legacy) | ✅ | ❌ |
| Feature Variables | ✅ | ❌ |
| **Web Experimentation Only** |
| Campaigns | ❌ | ✅ |
| Pages | ❌ | ✅ |
| Extensions | ❌ | ✅ |
| Segments | ❌ | ✅ |
| Webhooks | ❌ | ✅ |
| Collaborators | ❌ | ✅ |

**Detection Rule**: `is_flags_enabled = true` → Feature Experimentation | `is_flags_enabled = false` → Web Experimentation

## Entity Hierarchies

### Feature Experimentation Hierarchy

```
Project
├── Flags
│   ├── Variable Definitions (Schema)
│   ├── Variations (Values)
│   └── Rulesets (per Environment)
│       └── Rules (Targeting Logic)
├── Experiments (Flag-based)
├── Audiences
├── Attributes
├── Events
└── Groups
```

### Web Experimentation Hierarchy

```
Project
├── Campaigns
│   └── Experiments
│       └── Variations
├── Pages
├── Extensions
├── Audiences
├── Attributes
├── Events
├── Groups
├── Segments
└── Webhooks
```

## Critical Entity Relationships

### Flags and Their Components (Feature Experimentation)

1. **Flag → Variable Definitions**
   - One-to-many relationship
   - Defines the schema/template for variables
   - Access via: `list_entities variable_definition filters={"flag_key": "FLAG_KEY"}`

2. **Flag → Variations**
   - One-to-many relationship
   - Contains actual values for variables
   - Access via: `list_entities variation filters={"flag_key": "FLAG_KEY"}`

3. **Flag → Rulesets**
   - One per environment
   - Not a standalone entity - exists as flag + environment combination
   - Access via: `get_entity_details flag FLAG_KEY` → check `environmentData`

4. **Ruleset → Rules**
   - One-to-many relationship
   - Contains targeting logic
   - Access via: `list_entities rule filters={"flag_key": "FLAG_KEY", "environment_key": "ENV_KEY"}`

### Campaigns and Their Components (Web Experimentation)

1. **Campaign → Experiments**
   - One-to-many relationship
   - Groups related experiments
   - Access via: `list_entities experiment filters={"campaign_id": CAMPAIGN_ID}`

2. **Experiment → Pages**
   - Many-to-many relationship
   - Defines where experiment runs
   - Access via: `list_entities page project_id=PROJECT_ID`

3. **Experiment → Variations**
   - One-to-many relationship
   - Different experiences to test
   - Access via: `list_entities variation filters={"experiment_id": EXPERIMENT_ID}`

## Entity CRUD Operations

### Read-Only Entities
- Environments (in Feature Experimentation)
- Results
- Collaborators (global list)

### Special Access Patterns

1. **Rulesets**
   - Not directly listable
   - Access through flag's environmentData
   - Update via: `update_ruleset` or `manage_entity_lifecycle`

2. **Rules**
   - Require both flag_key and environment_key filters
   - Part of ruleset structure

3. **Variable Definitions**
   - Always require flag_key filter
   - Represent schema, not values

4. **Variations**
   - Context-dependent (flag vs experiment)
   - Always require parent entity filter

## Entity Scope Requirements

### Project-Scoped Entities
All entities except projects themselves require `project_id` parameter.

### Flag-Scoped Entities (Require flag_key filter)
- Variable Definitions
- Variations (in Feature Experimentation)
- Rules
- Rulesets

### Campaign-Scoped Entities
- Experiments (when filtered by campaign)

### Environment-Scoped Entities
- Rulesets (also require flag_key)
- Rules (also require flag_key)

## Experiment Entity Disambiguation

### Two Types of Experiments

1. **Feature Experimentation Experiments**
   - Flag-based experiments
   - Use flag variations for testing
   - Managed through flag rulesets
   - Statistical analysis via `get_experiment_results`
   - Modern approach (recommended)

2. **Web Experimentation Experiments**
   - Traditional A/B tests
   - HTML/CSS/JS modifications
   - Grouped in campaigns
   - Page-based targeting
   - Legacy approach

**Key Point**: Both are called "experiments" but work completely differently!

## Best Practices

1. **Always Check Platform First**
   - Never assume entity availability
   - Use `get_entity_details project PROJECT_ID`
   - Check `is_flags_enabled` property

2. **Use Proper Entity Endpoints**
   - Don't extract nested data
   - Use dedicated `list_entities` calls
   - Provide required filters

3. **Understand Entity Relationships**
   - Know parent-child relationships
   - Understand scope requirements
   - Use correct access patterns

4. **Respect Platform Boundaries**
   - Feature Experimentation has flags
   - Web Experimentation has campaigns
   - Never mix entity types across platforms