[XP-2229] update docs for data structures builder (#713)

* Update data structures with builder details
---------

Co-authored-by: Nick <[email protected]>

docs/feature-comparison/index.md

@@ -47,7 +47,7 @@ To find out more about the support services offered to Snowplow BDP customers se
 | Outage protection | ❌ | ❌ | ✅<br/>_(top tier only)_ |
 | <h3>Collaborate across multiple teams</h3> | [Community Edition](/docs/getting-started-on-community-edition/index.md) | [BDP Cloud](/docs/getting-started-on-snowplow-bdp-cloud/index.md) | [BDP Enterprise](/docs/getting-started-on-snowplow-bdp-enterprise/index.md) |
 | Seats | N/A | unlimited | unlimited |
-| [Data structures tooling & API](/docs/understanding-tracking-design/managing-your-data-structures/ui/index.md) | ❌ | ✅<br/>[_(UI only)_](/docs/understanding-tracking-design/managing-your-data-structures/builder/index.md) | ✅ |
+| [Data structures tooling & API](/docs/understanding-tracking-design/managing-your-data-structures/ui/index.md) | ❌ | ✅<br/>[_(UI only)_](/docs/understanding-tracking-design/managing-your-data-structures/ui/builder/index.md) | ✅ |
 | [Tracking scenarios](/docs/understanding-tracking-design/tracking-plans/index.md) | ❌ | ✅<br/>_(UI only)_ | ✅ |
 | [Data modeling management tooling](/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/index.md) | ❌ | _coming soon_ | ✅ |
 | [Tracking catalog](/docs/discovering-data/tracking-catalog/index.md) | ❌ | ❌ | ✅ |

docs/recipes/custom-events-entities/_index.md

@@ -0,0 +1,5 @@
+Snowplow uses self-describing JSON schemas to structure events and entities so that they can be validated in the pipeline and loaded into tidy tables in the warehouse. You can learn more about these data structures [here](/docs/understanding-your-pipeline/schemas/index.md), and about why we take this approach [here](https://snowplowanalytics.com/blog/2020/01/24/re-thinking-the-structure-of-event-data/).
+
+Snowplow BDP expands its capabilities beyond the pre-designed custom events and entities required for the recipes in Try Snowplow. The platform introduces the [Data Structures UI](/docs/understanding-tracking-design/managing-your-data-structures/ui/index.md), featuring the [Data Structures Builder](/docs/understanding-tracking-design/managing-your-data-structures/ui/builder/index.md). This Builder streamlines the creation process of events and entities with a user-friendly, guided setup and automated versioning. 
+
+For Enterprise customers requiring more control and customization, particularly for intricate data structures, a JSON editor is also available. This editor allows for precise and tailored data structure definitions, ensuring adaptability to complex tracking needs. As well as managing data structures through the Snowplow BDP Console, Enterprise customers can also manage them programmatically through the [Data structures API](docs/understanding-tracking-design/managing-your-data-structures/api/index.md).

docs/recipes/recipe-basic-tracking-design/index.md

@@ -19,7 +19,7 @@ We'll give it the following details:
 
 :::info BDP Cloud
 
-If you are a BDP Cloud customer, use the [data structures builder UI](/docs/understanding-tracking-design/managing-your-data-structures/builder/index.md) to follow along. You will not need the JSON code.
+If you are a BDP Cloud customer, use the [data structures builder UI](/docs/understanding-tracking-design/managing-your-data-structures/ui/builder/index.md) to follow along. You will not need the JSON code.
 
 :::
 
@@ -69,7 +69,7 @@ In the schema for this data structure, we would display these decisions as prope
 
 :::info BDP Cloud
 
-If you are a BDP Cloud customer, you can create an equivalent data structure in the [data structures builder UI](/docs/understanding-tracking-design/managing-your-data-structures/builder/index.md).
+If you are a BDP Cloud customer, you can create an equivalent data structure in the [data structures builder UI](/docs/understanding-tracking-design/managing-your-data-structures/ui/builder/index.md).
 
 :::
 

docs/recipes/recipe-content-analytics/index.md

@@ -25,9 +25,11 @@ For this purpose, you can add a content [entity](/docs/understanding-your-pipeli
 
 We have already created a custom `content` entity for you in [Iglu Central](http://iglucentral.com/).
 
-Snowplow uses self-describing JSON schemas to structure events and entities so that they can be validated in the pipeline and loaded into tidy tables in the warehouse. You can learn more about these data structures [here](/docs/understanding-your-pipeline/schemas/index.md), and about why we take this approach [here](https://snowplowanalytics.com/blog/2020/01/24/re-thinking-the-structure-of-event-data/).
+```mdx-code-block
+import DataStructuresSharedBlock from "@site/docs/recipes/custom-events-entities/_index.md"
 
-While Try Snowplow only ships with a pre-designed set of custom events and entities required for the recipes, Snowplow BDP lets you create an unlimited number of your own via the [Data Structures UI](/docs/understanding-tracking-design/managing-your-data-structures/ui/index.md) (and API) for Enterprise and via [the Data Structures Builder](/docs/understanding-tracking-design/managing-your-data-structures/builder/index.md) for Cloud. 
+<DataStructuresSharedBlock/>
+```
 
 The `content` entity has the following fields:
 

docs/recipes/recipe-ecommerce-analytics/index.md

@@ -38,9 +38,11 @@ You can then run a simple SQL query to model this data into a product table. Thi
 
 We have already created a custom `product` entity for you, and uploaded its data structure to [your Iglu server](/docs/pipeline-components-and-applications/iglu/iglu-resolver/index.md).
 
-Snowplow uses self-describing JSON schemas to structure events and entities so that they can be validated in the pipeline and loaded into tidy tables in the warehouse. You can learn more about these data structures [here](/docs/understanding-your-pipeline/schemas/index.md), and about why we take this approach [here](https://snowplowanalytics.com/blog/2020/01/24/re-thinking-the-structure-of-event-data/).
+```mdx-code-block
+import DataStructuresSharedBlock from "@site/docs/recipes/custom-events-entities/_index.md"
 
-While Try Snowplow only ships with a pre-designed set of custom events and entities required for the recipes, Snowplow BDP lets you create an unlimited number of your own via the [Data Structures UI](/docs/understanding-tracking-design/managing-your-data-structures/ui/index.md) (and API).
+<DataStructuresSharedBlock/>
+```
 
 The `product` entity has the following fields:
 

docs/recipes/recipe-funnel-analysis/index.md

@@ -21,9 +21,11 @@ You will then collect all funnel step interactions (whether they are page views
 
 We have already created a custom `funnel_interaction` event for you in [Iglu Central](http://iglucentral.com/).
 
-Snowplow uses self-describing JSON schemas to structure events and entities so that they can be validated in the pipeline and loaded into tidy tables in the warehouse. You can learn more about these data structures [here](/docs/understanding-your-pipeline/schemas/index.md), and about why we take this approach [here](https://snowplowanalytics.com/blog/2020/01/24/re-thinking-the-structure-of-event-data/).
+```mdx-code-block
+import DataStructuresSharedBlock from "@site/docs/recipes/custom-events-entities/_index.md"
 
-While Try Snowplow only ships with a pre-designed set of custom events and entities required for the recipes, Snowplow BDP lets you create an unlimited number of your own via the [Data Structures UI](/docs/understanding-tracking-design/managing-your-data-structures/ui/index.md) (and API) for Enterprise and via [the Data Structures Builder](/docs/understanding-tracking-design/managing-your-data-structures/builder/index.md) for Cloud. 
+<DataStructuresSharedBlock/>
+```
 
 The `funnel_interaction` event has the following fields:
 

docs/recipes/recipe-marketing-attribution/index.md

@@ -230,9 +230,11 @@ Design and implement a "Conversion" event
 
 We have already created a custom `conversion` event for you in [Iglu Central](http://iglucentral.com/).
 
-Snowplow uses self-describing JSON schemas to structure events and entities so that they can be validated in the pipeline and loaded into tidy tables in the warehouse. You can learn more about these data structures [here](/docs/understanding-your-pipeline/schemas/index.md), and about why we take this approach [here](https://snowplowanalytics.com/blog/2020/01/24/re-thinking-the-structure-of-event-data/).
+```mdx-code-block
+import DataStructuresSharedBlock from "@site/docs/recipes/custom-events-entities/_index.md"
 
-While Try Snowplow only ships with a pre-designed set of custom events and entities required for the recipes, Snowplow BDP lets you create an unlimited number of your own via the [Data Structures UI](/docs/understanding-tracking-design/managing-your-data-structures/ui/index.md) (and API) for Enterprise and via [the Data Structures Builder](/docs/understanding-tracking-design/managing-your-data-structures/builder/index.md) for Cloud.
+<DataStructuresSharedBlock/>
+```
 
 The custom `conversion` event used in this recipe is very flexible so that you can instrument it across as many or as few conversions as possible. Specifically, it has the following fields:
 

docs/understanding-tracking-design/managing-your-data-structures/ui/builder/index.md

@@ -0,0 +1,49 @@
+---
+title: "Managing data structures with the Data Structures Builder"
+description: "The Data Structures Builder is ideal for quickly creating an event or entity with our guided setup and automated versioning."
+sidebar_label: "Using the Data Structures Builder"
+sidebar_position: 1
+---
+
+:::info Supported properties
+The builder only supports the following types:
+
+- string
+- enumerated list
+- integer
+- decimal
+- boolean
+
+For more complex data structures that require heavy nesting and more advanced data types, use the [JSON Editor](../json-editor/index.md).
+:::
+
+***
+
+## Creating a new data structure
+
+Populate the general information, such as Name, and a Description and Vendor. Vendor allows you to organize your data structures, for example, by teams. Snowplow will automatically generate the Tracking Url to be referenced in your tracking code.
+
+![](images/data-structures-1.png)
+
+When creating a new [Data Structure](/docs/understanding-your-pipeline/schemas/index.md), you can add one or multiple properties. For each property, you can set a name, description, its type and a possible enumeration of allowed values (for type `string`). You can also set additional constraints to define if this property should be optional or mandatory, and if `null` values are allowed.
+
+![](images/data-structures-2.png)
+
+Click “Save” on the Property dialog box and this will save your property changes.
+
+Clicking “Save” on the Data Structure page will publish your Data Structure to your Iglu Server.
+
+
+## Editing a data structure
+
+On the edit page, under the General Information panel, you can update the data structure type or its description. To add a new property, cick the "Add Property" button. To edit or delete an existing property, click the three dots next to the property name to open the action menu, and then select the appropriate option.
+
+![](images/edit-data-structure.png)
+
+When you modify the data structure, the builder will mark your changes in yellow and automatically determine the new version of your data structure based on these modifications. You can reset the data structure and erase all changes at any moment by clicking the “Clear Changes” button found in the alert beneath the properties.
+
+If you are satisfied with your changes, click "Save" and make sure to note the newly updated tracking URL.
+
+![](images/data-structure-version.png)
+
+

docs/understanding-tracking-design/managing-your-data-structures/ui/index.md

@@ -6,6 +6,8 @@ sidebar_position: 1
 sidebar_custom_props:
   offerings:
     - enterprise
+    - cloud
+
 ---
 
 ## Creating a new data structure
@@ -14,65 +16,42 @@ To create a new [Data Structure](/docs/understanding-your-pipeline/schemas/index
 
 ![](images/image-1.png)
 
-Now select whether you'd like to create an [Event](/docs/understanding-your-pipeline/events/index.md) or an [Entity](/docs/understanding-your-pipeline/entities/index.md). You can always change this selection at a later date.
+Enterprise customers can select from two options: **Create using builder** or **Create using JSON**. The [Data Structures Builder](/docs/understanding-tracking-design/managing-your-data-structures/ui/builder/index.md) only supports the following types:
 
-![](images/image-2.png)
+- string
+- enumerated list
+- integer
+- decimal
+- boolean
 
-You can now write the first version of your JSON schema for this Data Structure. Some template JSON is provided in the code window to start you off.
+For more complex data structures that require heavy nesting and more advanced data types, use the [JSON Editor](/docs/understanding-tracking-design/managing-your-data-structures/ui/json-editor/index.md). BDP Cloud accounts will be automatically directed to the [Data Structures Builder](/docs/understanding-tracking-design/managing-your-data-structures/ui/builder/index.md).
 
-![](images/image-3.png)
 
-Once you are done, click the **'Validate'** button and we'll validate that your schema is valid JSON markup. Assuming it passes validation the 'Publish' button will activate.
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
 
-Click **'Publish to development environment'** to publish your Data Structure to your development environment. As this is the first version of your data structure it will be created as version `1-0-0`. Click publish again on the modal dialog to confirm the action.
+<DocCardList />
+```
 
-Your new Data Structure will be published to your development environment ready [for you to test](/docs/managing-data-quality/testing-and-qa-workflows/index.md).
 
-* * *
+![](images/builder-or-json.png)
 
 ## Editing a data structure
 
 To edit an existing data structure, navigate to **'Data Structures'** and locate the data structure you wish to edit. You can more easily find your Data Structure by:
 
-- Using the search facility to search by name
+- Using the search facility to search by name or vendor
 - Ordering the Name column alphabetically
 - Filtering the listing by Type and / or Vendor
 
-Once located either click on the name to view the Data Structure and then click the **'Edit'** button, or click the three dots to bring up the action menu where you can select **'Create new version'**.
-
-![](images/image-4.png)
-
-Make the required edits to the JSON schema. You can use the 'Difference' toggle above the editor to see a 'diff' view against the latest Production version of your data structure.
-
-In the example below we have changed the `maxLength` of `example_field_1`.
-
-![](images/image-5.png)
-
-Once you are happy with your changes, click **'Validate'** to ensure you have valid JSON markup. Then click **'Publish to development environment'** to save your changes to your development environment.
-
-![](images/image-7.png)
-
-The versioning modal dialog will appear, at this point you have three options:
-
-- Increment a minor version to indicate a non-breaking change to the schema. In our example, this would increment the schema to from `1-0-1` to `1-0-2`.
-- Increment a major version to indicate a breaking change to the schema. In our example, this would increment the schema from `1-0-1` to `2-0-0`.
-- [Patch the current version](/docs/understanding-tracking-design/versioning-your-data-structures/amending/index.md#patching-the-schema), this will overwrite the existing schema without increasing the version. In our example, this would leave the schema at 1-0-1.
-
-:::caution Selecting the “patch” option
-
-Patching can be useful in development environments, but should be done carefully and should never be done in production. See [amending schemas](/docs/understanding-tracking-design/versioning-your-data-structures/amending/index.md) for an explanation and some suggestions.
+Once located, click on the name to view the Data Structure. You can then select from two options to edit the Data Structure: [**Edit with builder**](./builder/index.md#editing-a-data-structure-with-the-data-structures-builder) or [**Edit with JSON editor**](./json-editor/index.md#editing-a-data-structure-with-the-json-editor).
 
+:::note
+The **Edit with builder** option will be unavailable if the Data Structure you're viewing is not supported. More complex Data Structures must be edited with the **JSON Editor**.
 :::
 
-For more information see [Versioning your data structures](/docs/understanding-tracking-design/versioning-your-data-structures/index.md).
-
-Once you have selected the appropriate version, click **'Publish to development environment'** and your edits will be published to your development environment ready [for you to test](/docs/managing-data-quality/testing-and-qa-workflows/index.md).
-
-You can identify Data Structures where the Development version is ahead of the Production version by the yellow background on the version number. In this example both `user` and `alert` have been edited on development.
-
-![](images/image-10.png)
-
-* * *
+![](images/disabled-builder.png)
+***
 
 ## Promoting a data structure
 
@@ -88,11 +67,11 @@ The action of promoting data structures is only available to Admin users.
 
 Navigate to **Data Structures** and locate the Data Structure you wish to promote. You can more easily find your Data Structure by:
 
-- Using the search facility to search by name
+- Using the search facility to search by name or vendor
 - Ordering the Name column alphabetically
 - Filtering the listing by Type and / or Vendor
 
-Once located either click on the name to view the Data Structure and then click the '**Migrate to production**' button, or click the three dots to bring up the action menu where you can select **'**Migrate to production****'.
+Once located, either click on the name to view the Data Structure and then click the "Migrate to production" button, or click the three dots to bring up the action menu where you can select "Migrate to production".
 
 ![](images/image-8.png)
 
@@ -124,7 +103,7 @@ Follow the modal instructions to confirm the action.
 
 Hiding a Data Structure will not remove it from the registry, it simply hides it from the console listing, this means:
 
-(1) events can still be sent against this structure  
+(1) events can still be sent against this structure
 (2) you cannot create a new structure of the same name
 
 :::