@simonecoelhosfo/optimizely-mcp-server
Version:
Optimizely MCP Server for AI assistants with integrated CLI tools
304 lines • 11.7 kB
JavaScript
/**
* Direct Template Architecture Reference
* Complete guide to the new direct template approach (Template Format Version 2)
*
* NOTE: This replaces the old system_template_id architecture
*/
export const entityTypeRegistry = {
// Feature Experimentation Entity Types
'flag': {
entity_type: 'flag',
platform: 'feature',
description: 'Create a basic feature flag',
required_fields: ['project_id', 'key', 'name'],
optional_fields: ['description', 'variables'],
example: {
entity_type: 'flag',
operation: 'create',
mode: 'template',
template_data: {
project_id: '${project_id}',
key: 'new_feature',
name: 'New Feature Flag',
description: 'Controls the new feature rollout'
}
}
},
'rule': {
entity_type: 'rule',
platform: 'feature',
description: 'Create individual targeting rule',
required_fields: ['project_id', 'flag_key', 'environment_key', 'name', 'type'],
optional_fields: ['audience_conditions', 'percentage_included', 'enabled']
},
'ruleset': {
entity_type: 'ruleset',
platform: 'feature',
description: 'Create A/B test or rollout ruleset',
required_fields: ['project_id', 'flag_key', 'environment_key', 'name', 'type', 'variations'],
optional_fields: ['audience_conditions', 'metrics'],
notes: 'Use type: "a/b_test" for experiments'
},
// Web Experimentation Entity Types
'page': {
entity_type: 'page',
platform: 'web',
description: 'Create landing page with URL targeting',
required_fields: ['project_id', 'name', 'key'],
optional_fields: ['conditions', 'activation_type', 'edit_url'],
example: {
entity_type: 'page',
operation: 'create',
mode: 'template',
template_data: {
project_id: '${project_id}',
name: 'Homepage',
key: 'homepage',
conditions: [{
match_type: 'simple',
value: 'https://example.com'
}]
}
}
},
'campaign': {
entity_type: 'campaign',
platform: 'web',
description: 'Create campaign container for experiments',
required_fields: ['project_id', 'name'],
optional_fields: ['status', 'type', 'holdback'],
notes: 'Container for multiple experiments'
},
'experiment': {
entity_type: 'experiment',
platform: 'web',
description: 'Create standard A/B test experiment or personalization experiment',
required_fields: ['project_id', 'name', 'page_ids', 'variations'],
optional_fields: ['campaign_id', 'audience', 'traffic_allocation', 'metrics'],
notes: 'For personalization, use single variation at 100% with audience targeting'
},
'extension': {
entity_type: 'extension',
platform: 'web',
description: 'Create custom code extension',
required_fields: ['project_id', 'name', 'key', 'extension_point'],
optional_fields: ['javascript', 'css', 'html', 'enabled'],
notes: 'Use extension_point: "project_javascript" for global code'
},
// Shared Entity Types (Both Platforms)
'event': {
entity_type: 'event',
platform: 'both',
description: 'Create custom event for tracking',
required_fields: ['project_id', 'name', 'key', 'event_type'],
optional_fields: ['category', 'selector'],
example: {
entity_type: 'event',
operation: 'create',
mode: 'template',
template_data: {
project_id: '${project_id}',
name: 'Purchase Completed',
key: 'purchase_completed',
event_type: 'custom',
category: 'purchase'
}
}
},
'audience': {
entity_type: 'audience',
platform: 'both',
description: 'Create user segment with conditions',
required_fields: ['project_id', 'name', 'key', 'conditions'],
optional_fields: ['description'],
notes: 'Conditions can be array or object with and/or'
},
'attribute': {
entity_type: 'attribute',
platform: 'both',
description: 'Create custom attribute (supports all types including list)',
required_fields: ['project_id', 'key', 'name', 'type'],
optional_fields: ['description', 'list_type', 'values'],
notes: 'Types: string, number, boolean, list. For list type, include list_type and values'
},
'project': {
entity_type: 'project',
platform: 'both',
description: 'Create new project',
required_fields: ['name', 'platform'],
optional_fields: ['description'],
notes: 'Platform must be "web" or "custom" (not "feature_experimentation")'
},
'environment': {
entity_type: 'environment',
platform: 'both',
description: 'Create project environment',
required_fields: ['project_id', 'name', 'key'],
optional_fields: ['is_primary']
},
'variable_definition': {
entity_type: 'variable_definition',
platform: 'feature',
description: 'Create flag variable definition',
required_fields: ['flag_key', 'key', 'type', 'default_value'],
notes: 'Part of flag creation workflow'
}
};
export const directTemplateGuide = {
format_migration: {
old_format: {
system_template_id: 'campaign_create',
operation: 'create',
inputs: {
project_id: '${project_id}',
name: 'My Campaign'
}
},
new_format: {
entity_type: 'campaign',
operation: 'create',
mode: 'template',
template_data: {
project_id: '${project_id}',
name: 'My Campaign'
}
},
changes: [
'system_template_id → entity_type',
'inputs → template_data',
'Added mode: "template"',
'Added template_format_version: 2 to root template'
]
}
};
export const troubleshootingGuide = {
common_errors: [
{
error: 'Entity type not supported',
cause: 'Invalid entity_type specified',
solution: 'Check entityTypeRegistry for valid entity types'
},
{
error: 'Missing dependency: step_name',
cause: 'Typo in depends_on array',
solution: 'Verify step ID spelling matches exactly'
},
{
error: 'Variable ${var} not resolved',
cause: 'JSONPath syntax error or missing parameter',
solution: 'Use ${param} for parameters, ${step.entity_id} for references'
},
{
error: 'Audience defaults to everyone',
cause: 'Missing or incorrect audience reference format',
solution: 'Use {ref: {id: "${step.entity_id}"}} format'
},
{
error: 'Invalid value for field platform',
cause: 'Using "feature_experimentation" instead of "custom"',
solution: 'For Feature Experimentation projects, use platform: "custom"'
},
{
error: 'Unknown template format',
cause: 'Using old system_template_id format',
solution: 'Migrate to Direct Template Architecture with entity_type and template_data'
},
{
error: 'Validation failed for variations',
cause: 'Traffic allocation doesnt sum to 10000',
solution: 'Ensure all variation weights sum to exactly 10000 (100%)'
}
],
validation_checklist: [
'All parameters have type, required, and description',
'All steps have unique IDs',
'Entity types exist in registry',
'Variable syntax uses ${} format',
'Dependencies reference existing step IDs',
'Entity data matches API requirements',
'Audience references use {ref: {id: ...}} format',
'Platform values are "web" or "custom" (not "feature_experimentation")'
],
debugging_tips: [
'Check orchestration execution logs for detailed errors',
'Validate each step independently before full orchestration',
'Use get_entity_templates to see expected formats',
'Test variable resolution with simple values first',
'Enable verbose logging for troubleshooting'
]
};
export const directTemplateConcepts = {
template_structure: {
description: 'Structure of Direct Template Architecture (Template Format Version 2)',
required_fields: {
entity_type: 'Type of entity to create (flag, experiment, campaign, etc.)',
operation: 'Operation to perform (create, update, delete)',
mode: 'Template mode - always "template" for this architecture',
template_data: 'Entity-specific data for creation/update'
},
example: {
entity_type: 'experiment',
operation: 'create',
mode: 'template',
template_data: {
project_id: '${project_id}',
name: 'My Test',
page_ids: ['${create_page.entity_id}'],
variations: [ /* variation objects */]
}
}
}
};
export const orchestrationConcepts = {
variable_resolution: {
description: 'How variables are resolved in orchestration templates',
patterns: {
parameter_reference: {
syntax: '${parameter_name}',
example: '${project_id}',
usage: 'Reference input parameters'
},
step_entity_id: {
syntax: '${step_id.entity_id}',
example: '${create_audience.entity_id}',
usage: 'Reference created entity ID from previous step'
},
step_entity_key: {
syntax: '${step_id.entity_key}',
example: '${create_flag.entity_key}',
usage: 'Reference created entity key from previous step'
},
nested_data: {
syntax: '${step_id.data.field_name}',
example: '${create_campaign.data.status}',
usage: 'Access any field from step response'
},
string_interpolation: {
syntax: 'Text with ${variable}',
example: '${campaign_name} - Mobile',
usage: 'Embed variables within strings'
}
}
},
dependency_management: {
description: 'How to manage step dependencies',
rules: [
'Steps execute in order unless dependencies specified',
'depends_on array lists prerequisite step IDs',
'Circular dependencies will fail',
'Optional steps can fail without stopping orchestration'
],
example: {
depends_on: ['create_campaign', 'create_page', 'create_audience']
}
},
error_handling: {
description: 'How errors are handled during orchestration',
strategies: {
fail: 'Stop orchestration on error (default)',
continue: 'Log error and continue with next step',
rollback: 'Attempt to undo completed steps'
}
}
};
//# sourceMappingURL=SystemTemplateReference.js.map