Merge pull request #3912 from braze-inc/BD-1494

_docs/_user_guide/data_and_analytics/custom_data/custom_events.md

@@ -111,15 +111,34 @@ When making API calls and using the "is blank" filter, a specific custom event p
 
 In regards to subscription usage, custom event properties enabled for segmentation with the filters `X Custom Event Property in Y Days` or `X Purchase Property in Y Days` are all counted as separate data points in addition to the data point counted by the custom event itself.
 
-### Canvas guidelines
+### Canvas entry properties and event properties
 
-#### Original workflow
+You can leverage `canvas_entry_properties` and `event_properties` in your Canvas user journeys. Check out [Canvas entry properties and event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/) for more information and examples.
 
-Event properties can only be used in an action-based Canvas step using the original workflow. 
+{% tabs local %}
+{% tab Canvas Entry Properties %}
+
+[Canvas entry properties]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object/) are the properties you map for Canvases that are action-based or API-triggered. Note that the `canvas_entry_properties` object has a maximum size limit of 50 KB. 
 
-#### Canvas Flow
+For Canvas Flow messaging, `canvas_entry_properties` can be used in Liquid in any Message step. Use this Liquid when referencing these properties: ``{% raw %} canvas_entry_properties${property_name} {% endraw %}``. Note that the events must be custom events or purchase events to be used this way. 
 
-Custom event and purchase event properties can be used in Liquid in any [Message]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/) step that follows an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) step. Make sure to use `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` if referencing these event properties in Canvas Flow. For more details, check out [Event properties in Message steps]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/#event-properties).
+{% raw %}
+For example, consider the following request: `\"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. You could add the word "shoes" to a message with the Liquid `{{canvas_entry_properties.${product_name}}}`.
+{% endraw %}
+
+For the Canvases built with the original editor, `canvas_entry_properties` can be referenced only in the first full step of a Canvas.
+
+{% endtab %}
+
+{% tab Event Properties %}
+Event properties refer to the properties that you set for custom events and purchases. These `event_properties` can be used in campaigns with action-based delivery as well as Canvases. 
+
+In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an Action Paths step. For Canvas Flow, make sure to use {% raw %} ``{{event_properties.${property_name}}}``{% endraw %} if referencing these `event_properties`. These events must be custom events or purchase events to be used this way in the Message component.
+
+In the first Message step following an Action Path, you can use `event_properties` related to the event referenced in that Action Path. These `event_properties` can only be used if the user actually took the action (didn’t go to the Everyone Else group). You can have other steps (that are not another Action Paths or Message step) in between this Action Paths and the Message step.
+
+{% endtab %}
+{% endtabs %}
 
 ### Nested objects {#nested-objects}
 

_docs/_user_guide/data_and_analytics/custom_data/purchase_events.md

@@ -91,26 +91,37 @@ These segmentation filters include:
 
 Unlike with [segment extensions]({{site.baseurl}}/user_guide/engagement_tools/segments/segment_extension/), segments used are updated in real-time, support an unlimited amount of segments, offer a look back history of at most 30 days, and incur data points. Because of the additional data point charge, you must reach out to your CSM to get event properties turned on for your custom events. Once approved, additional properties can be added in the dashboard under **Manage Settings > Custom Events > Mangage Properties** and used in the target step of the campaign or Canvas builder.
 
-### Referencing purchase event properties with Liquid
+### Canvas entry properties and event properties
 
-When you send through purchase data that includes purchase properties, you can use the `event_properties` tag to reference the purchase properties in your channel messaging.
+You can leverage `canvas_entry_properties` and `event_properties` in your Canvas user journeys. Check out [Canvas entry properties and event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/) for more information and examples.
 
-{% raw %}
+{% tabs local %}
+{% tab Canvas Entry Properties %}
+
+[Canvas entry properties]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object/) are the properties you map for Canvases that are action-based or API-triggered. Note that the `canvas_entry_properties` object has a maximum size limit of 50 KB. 
 
-```liquid
-{{event_properties.${your_custom_event_property}}}
-```
+For Canvas Flow messaging, `canvas_entry_properties` can be used in Liquid in any Message step. Use this Liquid when referencing these properties: ``{% raw %} canvas_entry_properties${property_name} {% endraw %}``. Note that the events must be custom events or purchase events to be used this way. 
 
+{% raw %}
+For example, consider the following request: `\"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. You could add the word "shoes" to a message with the Liquid `{{canvas_entry_properties.${product_name}}}`.
 {% endraw %}
 
-For example, to reference the name of a product, replace `your_custom_event_property` with the `product_id`.
+For the Canvases built with the original editor, `canvas_entry_properties` can be referenced only in the first full step of a Canvas.
 
-### Log purchases at the order level
-If you would like to log purchases at the order level instead of the product level, you can use order name or order category as the `product_id`. Refer to our [purchase object specification]({{site.baseurl}}/api/objects_filters/purchase_object/#product-id-naming-conventions) to learn more. 
+{% endtab %}
 
-#### Canvas Flow
+{% tab Event Properties %}
+Event properties refer to the properties that you set for custom events and purchases. These `event_properties` can be used in campaigns with action-based delivery as well as Canvases. 
 
-Custom event and purchase event properties can be used in Liquid in any [Message]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/) step that follows an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) step. Make sure to use `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` if referencing these event properties in Canvas Flow. For more details, check out [Event properties in Message steps]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/#event-properties).
+In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an Action Paths step. For Canvas Flow, make sure to use {% raw %} ``{{event_properties.${property_name}}}``{% endraw %} if referencing these `event_properties`. These events must be custom events or purchase events to be used this way in the Message component.
+
+In the first Message step following an Action Path, you can use `event_properties` related to the event referenced in that Action Path. These `event_properties` can only be used if the user actually took the action (didn’t go to the Everyone Else group). You can have other steps (that are not another Action Paths or Message step) in between this Action Paths and the Message step.
+
+{% endtab %}
+{% endtabs %}
+
+### Log purchases at the order level
+If you would like to log purchases at the order level instead of the product level, you can use order name or order category as the `product_id`. Refer to our [purchase object specification]({{site.baseurl}}/api/objects_filters/purchase_object/#product-id-naming-conventions) to learn more. 
 
 [1]: {% image_buster /assets/img/purchase1.png %}
 [2]: {% image_buster /assets/img/purchase2.png %}

_docs/_user_guide/engagement_tools/canvas/canvas_components/message_step.md

@@ -41,25 +41,41 @@ Delivery validations provide an additional check to confirm your audience meets
 
 ### Canvas entry properties
 
-Canvas entry properties are properties from the event that triggered the Canvas. These entry properties can only be used in the first full step of a Canvas using the original workflow. 
+Canvas entry properties are configured in the Entry Schedule step of creating a Canvas and will indicate the trigger that enters a user into a Canvas. These properties can also access the properties of entry payloads in API-triggered Canvases. Note that the `canvas_entry_properties` object has a maximum size limit of 50 KB. 
 
-Conversely, in Canvas Flow, you can leverage [persistent entry properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_persistent_entry_properties/) in any Message step to guide your users through personalized steps throughout your Canvas workflow.
+#### Original workflow
+
+For the Canvases built with the original editor, `canvas_entry_properties` can be referenced only in the first Full Step of a Canvas.
+
+#### Canvas Flow
+
+For Canvas Flow messaging, `canvas_entry_properties` can be used in Liquid in any Message step. Use this Liquid if referencing these properties: ``{% raw %} canvas_entry_properties${property_name} {% endraw %}``. Note that the events must be custom events or purchase events to be used this way. 
+
+{% raw %}
+For example, consider the following request: `\"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. You could add the word "shoes" to a message with the Liquid `{{canvas_entry_properties.${product_name}}}`.
+{% endraw %}
+
+You can also leverage [persistent entry properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_persistent_entry_properties/) in any Message step to guide your users through personalized steps throughout your Canvas workflow.
 
 ### Event properties
 
+Event properties refer to the properties that you set for custom events and purchases. These `event_properties` can be used in campaigns with action-based delivery as well as Canvases. 
+
 #### Original workflow
 
-Event properties can only be used in any action-based Canvas step using the original workflow. 
+`event_properties` can only be used in any action-based Canvas step using the original workflow. 
 
 #### Canvas Flow
 
 {% alert important %}
-Event properties cannot be used independently of Action Paths for Canvas Flow.
+`event_properties` cannot be used independently of Action Paths for Canvas Flow.
 {% endalert %}
 
-In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) step. For Canvas Flow, make sure to use `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` if referencing these event properties. These events must be custom events or purchase events to be used this way in the Message component.
+In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) step. For Canvas Flow, use this Liquid `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` when referencing these `event_properties`. These events must be custom events or purchase events to be used this way in the Message component.
+
+In the first Message step following an Action Path, you can use `event_properties` related to the event referenced in that Action Path. You can have other steps (that are not another Action Paths or Message step) in between this Action Paths step and the Message step. Note that you’ll only have access to `event_properties` if your Message step can be traced back to a non-Everyone Else path in an Action Path step.
 
-In the first Message step following an Action Path, you can use event properties related to the event referenced in that Action Path. These event properties can only be used if the user actually took the action (didn't go to the Everyone Else group). You can have other steps (that are not another Action Paths or Message step) in between this Action Paths and the Message step. 
+For more information and examples, check out [Canvas entry properties and event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/).
 
 ## Analytics
 

_docs/_user_guide/engagement_tools/canvas/create_a_canvas.md

@@ -27,6 +27,9 @@ guide_featured_list:
   - name: Exception Events
     link: /docs/user_guide/engagement_tools/canvas/create_a_canvas/exception_events/
     fa_icon: fas fa-exchange-alt
+  - name: Canvas Entry Properties and Event Properties
+    link: /docs/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/
+    fa_icon: fas fa-user-check
   - name: Persistent Entry Properties
     link: /docs/user_guide/engagement_tools/canvas/create_a_canvas/canvas_persistent_entry_properties/
     fa_icon: fas fa-project-diagram

_docs/_user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties.md

@@ -0,0 +1,50 @@
+---
+nav_title: Canvas Entry Properties and Event Properties
+article_title: Canvas Entry Properties and Event Properties
+page_type: reference
+description: "This reference article describes the differences between Canvas entry properties and event properties, and when to use each property."
+tool: Canvas
+page_order: 8
+---
+
+# Canvas entry properties and event properties
+
+> This reference article covers information about `canvas_entry_properties` and `event_properties`, including when to use each property and the differences in behavior.
+
+Though similar in name, Canvas entry properties and event properties function differently within your Canvas workflows. Properties of events or API calls that trigger a user's entry into a Canvas are known as `canvas_entry_properties`. Properties of events that occur as a user moves through a Canvas journey are known as `event_properties`. The key difference here is `canvas_entry_properties` focuses on more than just events by also accessing the properties of entry payloads in API-triggered Canvases.
+
+Behavior can vary between workflows built with the original Canvas editor versus Canvas Flow. For example, in the original Canvas editor, you can use `event_properties` in the first Full Step if it's an action-based step. In Canvas Flow, Full Steps aren't supported, so this does not apply. 
+
+Check out this table for a summary of differences between `canvas_entry_properties` and `event_properties`.
+
+| | Canvas Entry Properties | Event Properties
+|----|----|----|
+| **Liquid** | `canvas_entry_properties` | `event_properties` |
+| **Persistence** | Can be referenced by all [Message][1] steps for the duration of a Canvas for Canvas Flow only. | - Can only be referenced once. <br> - Cannot be referenced by any subsequent Message steps. |
+| **Original Canvas behavior** | Can only reference `canvas_entry_properties` in the first Full Step of a Canvas. The Canvas must be action-based or API triggered. | You can reference `event_properties` in any Full Step that uses action-based delivery in a Canvas. However, if a user is using a [Canvas component][2] in the original Canvas editor, the behavior follows the Canvas Flow rules for `event_properties`. |
+| **Canvas Flow behavior** | Can reference `canvas_entry_properties` in any step of a Canvas. | - Can reference `event_properties` in the first Message step **after** an [Action Paths][3] step where the action taken is a custom event or purchase event. <br> - Cannot be after the Everyone Else path of the Action Paths step. <br> - Can have other non-Message Canvas components in between the Action Path and Message Step. If one of these non-Message Canvas components is an Action Paths step, the user can go through that Action Paths' Everyone Else path. | 
+{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3}
+
+## Example
+
+![][7]{: style="float:right;max-width:30%;margin-left:15px;"}
+
+Here's an example that explains behavior for `canvas_entry_properties` and `event_properties` in Canvas Flow. Let's say we have an action-based Canvas. In this scenario, users will enter this Canvas if they perform the custom event "add item to wishlist". 
+
+The `canvas_entry_properties` are configured in the [Entry Schedule][4] step of creating a Canvas and will correspond to when a user enters a Canvas. These `canvas_entry_properties` can also be referenced in any Message Step in Canvas Flow since Canvas Flow supports [persistent entry properties][5]. 
+
+In this Canvas, we have a user journey that begins at an Action Paths step to determine if a user has added an item to their wishlist. From here, if the user has added an item, then they will experience a delay before receiving a message "New item in your wishlist!" from the Message step. The first Message step in a user journey will have access to the custom `event_properties` from your Action Paths step, so in this case, we're able to include `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` here in this Message step as part of our message content. 
+
+If a user doesn't add an item to their wishlist, they go through the Everyone Else path, so the `event_properties` can't be referenced and will reflect an invalid settings error.
+
+Note that you’ll only have access to `event_properties` if your Message Step can be traced back to a non-Everyone Else path in an Action Path step. If the Message Step is connected to an Everyone Else path but can be traced back to an Action Paths step in the user journey, then you will also still have access to `event_properties`. For more information on these behaviors, check out [Message][8].
+
+Note that you’ll only have access to event_properties if your Message Step can be traced back to a non-Everyone Else path in an Action Path step.
+
+[1]: {{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/
+[2]: {{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/
+[3]: {{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/
+[4]: ({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/create_a_canvas/#step-2b-set-your-canvas-entry-schedule)
+[5]: ({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_persistent_entry_properties/
+[7]: {% image_buster /assets/img_archive/canvas_entry_properties1.png %}
+[8]: {{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/