triggers_create
Create triggers in Piwik PRO Tag Manager to define when tags fire based on user actions like page views, clicks, or form submissions using JSON attributes and supported trigger types.
Instructions
Create a new trigger in Piwik PRO Tag Manager using JSON attributes.
Only trigger types listed by `templates_list_triggers()` are supported. Any other type will be refused.
💡 TIP: Use these tools to discover available trigger templates and their requirements:
- templates_list_triggers() - List all available trigger templates
- templates_get_trigger(template_name='page_view') - Get detailed requirements
This tool uses a simplified interface with 2 parameters: app_id and attributes.
Use tools_parameters_get("triggers_create") to get the complete JSON schema
with all available fields, types, and validation rules.
Args:
app_id: UUID of the app
attributes: Dictionary containing trigger attributes for creation. Required fields vary by trigger type:
- name: Trigger name (always required)
- trigger_type: Trigger type (e.g., 'page_view', 'click', 'form_submission')
- conditions: Array of condition objects that define when trigger fires
- Additional fields may be required depending on trigger type
Returns:
Dictionary containing created trigger information including:
- data: Created trigger object with id, name, trigger_type, and attributes
- Trigger conditions and configuration
Template Discovery:
Use templates_list_triggers() to see all available trigger templates, or
templates_get_trigger(template_name='TEMPLATE') for specific requirements.
Parameter Discovery:
Use tools_parameters_get("triggers_create") to get the complete JSON schema
for all available fields. This returns validation rules, field types, and examples.
Examples:
# Get available trigger templates first
templates = templates_list_triggers()
# Get specific template requirements
page_view_info = templates_get_trigger(template_name='page_view')
# Create page view trigger
attributes = {
"name": "Homepage Page View",
"trigger_type": "page_view",
"conditions": [
{
"condition_id": "9efa6364-8982-45c5-a288-cdabdf7a4001",
"variable_id": "page-path-variable-uuid",
"condition_type": "equals",
"value": "/",
"options": {}
}
]
}
# Create click trigger
attributes = {
"name": "CTA Button Click",
"trigger_type": "click",
"conditions": [
{
"condition_id": "8efa6364-8982-45c5-a288-cdabdf7a4002",
"variable_id": "click-element-variable-uuid",
"condition_type": "equals",
"value": "#cta-primary",
"options": {"selector_type": "css"}
}
]
}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app_id | Yes | ||
| attributes | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes |
Implementation Reference
- The MCP tool handler for 'triggers_create', decorated with @mcp.tool, provides documentation, and delegates to the internal create_trigger function after validation.
@mcp.tool(annotations={"title": "Piwik PRO: Create Trigger"}) def triggers_create(app_id: str, attributes: dict) -> TagManagerSingleResponse: """Create a new trigger in Piwik PRO Tag Manager using JSON attributes. Only trigger types listed by `templates_list_triggers()` are supported. Any other type will be refused. 💡 TIP: Use these tools to discover available trigger templates and their requirements: - templates_list_triggers() - List all available trigger templates - templates_get_trigger(template_name='page_view') - Get detailed requirements This tool uses a simplified interface with 2 parameters: app_id and attributes. Use tools_parameters_get("triggers_create") to get the complete JSON schema with all available fields, types, and validation rules. Args: app_id: UUID of the app attributes: Dictionary containing trigger attributes for creation. Required fields vary by trigger type: - name: Trigger name (always required) - trigger_type: Trigger type (e.g., 'page_view', 'click', 'form_submission') - conditions: Array of condition objects that define when trigger fires - Additional fields may be required depending on trigger type Returns: Dictionary containing created trigger information including: - data: Created trigger object with id, name, trigger_type, and attributes - Trigger conditions and configuration Template Discovery: Use templates_list_triggers() to see all available trigger templates, or templates_get_trigger(template_name='TEMPLATE') for specific requirements. Parameter Discovery: Use tools_parameters_get("triggers_create") to get the complete JSON schema for all available fields. This returns validation rules, field types, and examples. Examples: # Get available trigger templates first templates = templates_list_triggers() # Get specific template requirements page_view_info = templates_get_trigger(template_name='page_view') # Create page view trigger attributes = { "name": "Homepage Page View", "trigger_type": "page_view", "conditions": [ { "condition_id": "9efa6364-8982-45c5-a288-cdabdf7a4001", "variable_id": "page-path-variable-uuid", "condition_type": "equals", "value": "/", "options": {} } ] } # Create click trigger attributes = { "name": "CTA Button Click", "trigger_type": "click", "conditions": [ { "condition_id": "8efa6364-8982-45c5-a288-cdabdf7a4002", "variable_id": "click-element-variable-uuid", "condition_type": "equals", "value": "#cta-primary", "options": {"selector_type": "css"} } ] } """ return create_trigger(app_id, attributes) - Pydantic model TriggerCreateAttributes used for input validation in the triggers_create handler via validate_data_against_model.
class TriggerCreateAttributes(BaseModel): """Attributes for creating triggers with assets-based allowlist enforcement.""" model_config = {"extra": "allow"} name: str = Field(..., description="Trigger name") trigger_type: str = Field(..., description="Trigger type (must match assets)") is_active: Optional[bool] = Field(None, description="Whether trigger is active") @field_validator("trigger_type") @classmethod def _validate_trigger_type(cls, v: str) -> str: allowed = set(list_template_names("tag_manager/triggers")) if v not in allowed: raise ValueError(f"Unsupported trigger type '{v}'. Use templates_list_triggers() to discover options.") return v - Helper function that performs the actual Piwik PRO API call to create the trigger after validation.
def create_trigger(app_id: str, attributes: dict) -> TagManagerSingleResponse: try: client = create_piwik_client() # Validate and enforce allowlist through TriggerCreateAttributes validated_attrs = validate_data_against_model(attributes, TriggerCreateAttributes) # Convert to dictionary and filter out None values create_kwargs = {k: v for k, v in validated_attrs.model_dump(exclude_none=True).items()} # Extract required fields name = create_kwargs.pop("name") trigger_type = create_kwargs.pop("trigger_type") response = client.tag_manager.create_trigger( app_id=app_id, name=name, trigger_type=trigger_type, **create_kwargs ) return TagManagerSingleResponse(**response) except BadRequestError as e: raise RuntimeError(f"Failed to create trigger: {e.message}") except Exception as e: raise RuntimeError(f"Failed to create trigger: {str(e)}") - src/piwik_pro_mcp/tools/__init__.py:35-39 (registration)Registration point where register_trigger_tools(mcp) is called, which defines and registers the triggers_create tool among others.
register_tag_tools(mcp) register_trigger_tools(mcp) register_variable_tools(mcp) register_version_tools(mcp) register_template_tools(mcp) - Tool schema registry mapping 'triggers_create' to TriggerAttributes model for dynamic schema retrieval via tools_parameters_get.
TOOL_PARAMETER_MODELS: Dict[str, Type[BaseModel]] = { "apps_create": NewAppAttributes, "apps_update": AppEditableAttributes, "audiences_create": NewAudienceAttributes, "audiences_update": EditableAudienceAttributes, "tracker_settings_app_update": AppTrackerSettings, "tracker_settings_global_update": GlobalTrackerSettings, "tags_create": TagManagerCreateAttributes, "tags_update": TagManagerUpdateAttributes, "tags_list": TagFilters, "triggers_create": TriggerAttributes, "triggers_list": TriggerFilters, "variables_create": VariableCreateAttributes, "variables_update": VariableUpdateAttributes, "variables_list": VariableFilters, }