diff --git a/docs/data-product-studio/data-products/ui/index.md b/docs/data-product-studio/data-products/ui/index.md index b7bc2ac94..8eb25cb61 100644 --- a/docs/data-product-studio/data-products/ui/index.md +++ b/docs/data-product-studio/data-products/ui/index.md @@ -19,7 +19,7 @@ After selecting "Create from scratch" a form will appear on the page. Enter your :::note _The name of your data product must be unique to ensure proper identification and avoid conflicts._ -:::note +::: ![Event specifications](images/event-specifications.png) @@ -104,3 +104,4 @@ If the new version of the Data Structure introduces incompatibilities with the e ![Conflict resolution Event Specification](images/conflict_resolution.png) This mechanism ensures that teams can benefit from updated Data Structures while maintaining the integrity and accuracy of their Event Specifications. Users are empowered to make informed decisions during the upgrade process, with clear visual cues and options to handle conflicts effectively. + diff --git a/docs/data-product-studio/event-specifications/api/index.md b/docs/data-product-studio/event-specifications/api/index.md index 9795ea75d..f9720bbaf 100644 --- a/docs/data-product-studio/event-specifications/api/index.md +++ b/docs/data-product-studio/event-specifications/api/index.md @@ -1,7 +1,7 @@ --- title: "Managing Event Specifications via the API" sidebar_label: "Using the API" -sidebar_position: 1 +sidebar_position: 3 --- With the [**Event Specifications API**](https://console.snowplowanalytics.com/api/msc/v1/docs), you can efficiently manage event specifications programmatically. Whether you want to retrieve, create, edit, publish, deprecate, or delete event specifications, the API provides the necessary endpoints and functionalities. diff --git a/docs/data-product-studio/event-specifications/index.md b/docs/data-product-studio/event-specifications/index.md index 945af88f2..5cecb8ba3 100644 --- a/docs/data-product-studio/event-specifications/index.md +++ b/docs/data-product-studio/event-specifications/index.md @@ -1,83 +1,28 @@ --- -title: "Managing Event Specifications in the Console" +title: "Event specifications" sidebar_label: "Event specifications" sidebar_position: 4 +date: "2025-11-14" --- -## Creating a new Event Specification through Console +Event specifications define the complete structure and requirements for [events](/docs/fundamentals/events/index.md) in your behavioral data pipeline. They serve as the single source of truth for what data should be collected, how it should be structured, and what business meaning it carries. -Event specifications serve as direct counterparts to [data structures](/docs/data-product-studio/data-structures/manage/index.md) and encapsulate the documented events within a data product. +## What are event specifications? -:::info -Please note that the creation of event specifications is exclusive to data products. -::: +An event specification is a collection of [schemas](/docs/fundamentals/schemas/index.md) (also called data structures) that describes everything about a specific event you want to track. Each specification includes: -Create event specifications in tandem with the latest deployed data structure version in development. This ensures tracking implementation instructions align with the validation criteria in the event specification. +- **Event schema**: defines the core properties specific to this event type +- **Entity schemas**: defines any additional context data that is sent with the event +- **Business metadata**: captures the purpose, ownership, and implementation requirements +- **Triggers**: documents when and where the event should be collected -Your event specification guarantees compatibility with the associated data structure version, being a specialization of it. This ensures events tracked using specified instructions pass validation for the associated data structure. +Event specifications act as data contracts between teams. When you create an event specification, you are defining exactly what data your applications should send, what your data warehouse will receive, and what your downstream consumers can rely on. -## Creating and Editing Event Specifications +## How event specifications work -To create a new event specification, follow these steps: +Event specifications bridge the gap between tracking design and data collection: -1. Select a data product -2. Click the "Create event" button -3. A dialog will appear, prompting you to enter a name for your event specification and click "Save and continue" -4. Your first event specification will be displayed on the page - -![Create an Event Specification](images/create-event-specification.png) - -To add more information or modify an existing event specification, follow these steps: - -1. Navigate to the appropriate data product -2. Select the desired event specification -3. This action will open on overview of the selected event specification containing the details that have been added to date - -This interface is divided into focused sections; explore each section below for more details. - -![Example of an Event Specification Overview](images/event-specification-overview.png) - -### Event Information - -This section provides essential meta-information for your event specification, including the event name, description, and the applications in which this event is tracked. - -### Event Data Structure - -This section defines the event data structure that this event will validate against as it is processed by your pipeline. - -You can choose from two types of data structures: - -- **Standard**; Provided by the Snowplow tracker by default -- **Custom**; Provided by your organization - -![Event Data Structure](images/event-data-structure.png) - -## Entity Data Structures - -Within this section, you have the flexibility to define the entities that should be associated with the event when it is triggered. - -To facilitate making an informed selection of your entities, you can view a detailed breakdown of the properties associated with the chosen entities (and its version) by a specific version. - -![Entity Data Structures](images/entity-data-structures.png) - -### Event Triggers - -This section defines the locations and circumstances under which this event is triggered. - -To create your first trigger, simply select the "Add trigger" button. You can edit or delete an existing trigger by clicking the dedicated buttons beside each entry in the triggers list. - -A dialog will appear, allowing you to upload an image and provide additional context, such as the URL to the page on which this trigger applies. - -![Event Triggers](images/event-triggers.png) - -### Properties - -This section allows you to specify how each property for a selected event or entity data structure should be populated. - -The dialog displays the list of properties for the selected data structure will be listed here, with the ability to provide the exact value/s or a description of how to populate these properties when the event is triggered. - -You can configure detailed instructions for any of the properties shown in the list by clicking the "Add instruction" or "Edit" buttons. Once you have selected the type of instruction you wish to add/edit and have filled in the required input fields, you are then able to click "Save and update instruction" and return to the properties list. - -*Notes: instructions for required properties are added by default and can be edited but they cannot be deleted.* - -![Implementation Instructions](images/implementation-instructions.png) +- **Design phase**: you document your tracking requirements by creating event specifications that capture both technical structure and business context +- **Implementation phase**: developers use these specifications to instrument tracking code, either manually or through code generation within the Snowplow Console or using tools like Snowtype. Snowtype generated code ensures type-safety and alignment with specifications, reducing implementation errors and accelerating development time +- **Observability phase**: monitor event specification usage directly in the Console. See the total number of events collected for each specification and when each was last seen. This visibility helps you confirm implementations are live, identify unused specifications, and understand event volume patterns across your tracking plan +- **Data modeling phase**: event specifications enable automatically generated dbt models that transform atomic events into analysis-ready tables. These models understand the structure defined in your specifications, creating consistent table schemas and joining related [entities](/docs/fundamentals/entities/index.md). As you update specifications, corresponding data models can be regenerated, keeping your warehouse transformations synchronized with your tracking design \ No newline at end of file diff --git a/docs/data-product-studio/event-specifications/ui/images/code-snippets.png b/docs/data-product-studio/event-specifications/ui/images/code-snippets.png new file mode 100644 index 000000000..e290f1c1a Binary files /dev/null and b/docs/data-product-studio/event-specifications/ui/images/code-snippets.png differ diff --git a/docs/data-product-studio/event-specifications/images/create-event-specification.png b/docs/data-product-studio/event-specifications/ui/images/create-event-specification.png similarity index 100% rename from docs/data-product-studio/event-specifications/images/create-event-specification.png rename to docs/data-product-studio/event-specifications/ui/images/create-event-specification.png diff --git a/docs/data-product-studio/event-specifications/images/entity-data-structures.png b/docs/data-product-studio/event-specifications/ui/images/entity-data-structures.png similarity index 100% rename from docs/data-product-studio/event-specifications/images/entity-data-structures.png rename to docs/data-product-studio/event-specifications/ui/images/entity-data-structures.png diff --git a/docs/data-product-studio/event-specifications/images/event-data-structure.png b/docs/data-product-studio/event-specifications/ui/images/event-data-structure.png similarity index 100% rename from docs/data-product-studio/event-specifications/images/event-data-structure.png rename to docs/data-product-studio/event-specifications/ui/images/event-data-structure.png diff --git a/docs/data-product-studio/event-specifications/images/event-specification-overview.png b/docs/data-product-studio/event-specifications/ui/images/event-specification-overview.png similarity index 100% rename from docs/data-product-studio/event-specifications/images/event-specification-overview.png rename to docs/data-product-studio/event-specifications/ui/images/event-specification-overview.png diff --git a/docs/data-product-studio/event-specifications/images/event-triggers.png b/docs/data-product-studio/event-specifications/ui/images/event-triggers.png similarity index 100% rename from docs/data-product-studio/event-specifications/images/event-triggers.png rename to docs/data-product-studio/event-specifications/ui/images/event-triggers.png diff --git a/docs/data-product-studio/event-specifications/images/implementation-instructions.png b/docs/data-product-studio/event-specifications/ui/images/implementation-instructions.png similarity index 100% rename from docs/data-product-studio/event-specifications/images/implementation-instructions.png rename to docs/data-product-studio/event-specifications/ui/images/implementation-instructions.png diff --git a/docs/data-product-studio/event-specifications/ui/images/sql-example.png b/docs/data-product-studio/event-specifications/ui/images/sql-example.png new file mode 100644 index 000000000..ee034741c Binary files /dev/null and b/docs/data-product-studio/event-specifications/ui/images/sql-example.png differ diff --git a/docs/data-product-studio/event-specifications/ui/index.md b/docs/data-product-studio/event-specifications/ui/index.md new file mode 100644 index 000000000..41c81c800 --- /dev/null +++ b/docs/data-product-studio/event-specifications/ui/index.md @@ -0,0 +1,122 @@ +--- +title: "Managing event specifications using Console" +sidebar_label: "Using the UI" +sidebar_position: 1 +--- + +## Creating a new event specification through Console + +Event specifications serve as direct counterparts to [data structures](/docs/data-product-studio/data-structures/manage/index.md) and encapsulate the documented events within a data product. + +:::info +Please note that the creation of event specifications is exclusive to data products. +::: + +Create event specifications in tandem with the latest deployed data structure version in development. This ensures tracking implementation instructions align with the validation criteria in the event specification. + +Your event specification guarantees compatibility with the associated data structure version, being a specialization of it. This ensures events tracked using specified instructions pass validation for the associated data structure. + +## Creating and editing event specifications + +To create a new event specification, follow these steps: + +1. Select a data product +2. Click the **Create event** button +3. A dialog will appear, prompting you to enter a name for your event specification and click **Save and continue** +4. Your first event specification will be displayed on the page + +![Create an event specification](images/create-event-specification.png) + +To add more information or modify an existing event specification, follow these steps: + +1. Navigate to the appropriate data product +2. Select the desired event specification +3. This action will open on overview of the selected event specification containing the details that have been added to date + +This interface is divided into focused sections; explore each section below for more details. + +![Example of an event specification overview](images/event-specification-overview.png) + +### Event information + +This section provides essential meta-information for your event specification, including the event name, description, and the applications in which this event is tracked. + +### Event data structure + +This section defines the event data structure that this event will validate against as it is processed by your pipeline. + +You can choose from two types of data structures: + +- **Standard**: provided by the Snowplow tracker by default +- **Custom**: provided by your organization + +![Event data structure](images/event-data-structure.png) + +### Entity data structures + +Within this section, you have the flexibility to define the entities that should be associated with the event when it is triggered. + +To facilitate making an informed selection of your entities, you can view a detailed breakdown of the properties associated with the chosen entities (and its version) by a specific version. + +![Entity data structures](images/entity-data-structures.png) + +### Event triggers + +This section defines the locations and circumstances under which this event is triggered. + +To create your first trigger, simply select the **Add trigger** button. You can edit or delete an existing trigger by clicking the dedicated buttons beside each entry in the triggers list. + +A dialog will appear, allowing you to upload an image and provide additional context, such as the URL to the page on which this trigger applies. + +![Event triggers](images/event-triggers.png) + +### Properties + +This section allows you to specify how each property for a selected event or entity data structure should be populated. + +The dialog displays the list of properties for the selected data structure will be listed here, with the ability to provide the exact value/s or a description of how to populate these properties when the event is triggered. + +You can configure detailed instructions for any of the properties shown in the list by clicking the **Add instruction** or **Edit** buttons. Once you have selected the type of instruction you wish to add/edit and have filled in the required input fields, you are then able to click **Save and update instruction** and return to the properties list. + +*Notes: instructions for required properties are added by default and can be edited but they cannot be deleted.* + +![Implementation instructions](images/implementation-instructions.png) + + +## Event specification code generation + +To accelerate your implementation of event tracking, Snowplow Console includes pre-generated code snippets specifically for custom self-describing events. These snippets can be accessed directly within the Console interface to significantly reduce the time and effort required for integrating event tracking functionality into your applications. + +### Working with event specifications + +When viewing an event specification, the **Working with this event** section provides two key tabs: + +- **Implementation**: access ready-to-use tracking code for your event +- **Querying**: view example SQL queries to retrieve your event data from the warehouse + +:::note +For standard Snowplow events (page views, screen views, page pings, and self-describing events), tracking code is available out of the box without requiring any additional configuration. +::: + +### Implementation - Code snippets + +The Implementation tab generates tracking code snippets tailored to your event specification. You can: + +- **Select your tracker type**: choose between JavaScript tracker options (tag-based or npm-based) +- **Copy code directly**: use the generated code snippets immediately in your application + +:::note +Draft data structures can't be used for event validation during testing or production since they aren't loaded into Iglu. Validation will fail without schemas in an Iglu registry, though you can configure a custom registry if needed. Deploy your draft to the development environment when you're ready to test. +::: + +![Implementation code snippets](images/code-snippets.png) + +### Querying - SQL examples + +The Querying tab provides example SQL queries to help you retrieve and analyze your event data. You can: + +- **Select your warehouse**: choose from Snowflake, BigQuery, Redshift, Databricks, and other supported warehouses +- **View tailored queries**: see SQL examples optimized for your selected warehouse +- **Access event data**: query both the event properties and attached entities + +![Querying SQL examples](images/sql-example.png)