Managing changes impacting multiple stakeholders
When a large organization is sharing a single tracking plan, it’s not unlikely that changes to the tracking plan will impact multiple stakeholder teams within your organization. To prevent users from unknowingly making changes that may disrupt the events other teams rely on, Avo offers tools to surface this potential impact and mitigate it.
A stakeholder team refers to a certain function or area within your organization. It could be a product area (Search, Checkout, etc), an entire app for specific personas (Drivers, Riders, etc) or a business function independent of the product (Marketing, Sales, Finance, etc.). Learn more
In Avo you can assign stakeholder teams as stakeholders on tracking plan items (events, event variants and properties) in your tracking plan, to ensure that anyone making changes in Avo is aware of who those changes will impact. With this awareness, they can choose to tweak the changes to reduce the scope, or loop in the relevant stakeholders.
Impacted stakeholders
When a user in your workspace drafts changes on a branch in Avo, the “Impacted stakeholders” indicator in the branch header keeps track of how many stakeholder teams will be impacted by the suggested changes.
When you click the indicator it will expand to show the following:
- Which stakeholder teams are impacted by the changes on your branch. The stakeholder teams you are not a member of will be surfaced at the top of the list and indicated with a pink dot.
- A preview of the members of each stakeholder team – you can also click the stakeholder team name to see more details on the stakeholder team name and its members
- For each stakeholder team a list of the tracking plan items you have changed that they are marked as stakeholders of.
Note that the full Impacted Stakeholders functionality is only available on our Enterprise Plan.
What counts as an impacting change?
Avo calculates impact from a behavioral diff of your branch against main – it compares how each event will be sent, per source, before and after your changes. Event variants are diffed as events of their own, and properties are compared as they resolve onto each event (including properties that come in through property bundles).
A stakeholder team is marked impacted when an item they are a stakeholder or owner of shows up in that diff. Changes that only affect how an item is documented – not how it is sent – do not mark anyone as impacted.
Changes that impact stakeholders
On an event or event variant
| Change | Breaking? |
|---|---|
| Adding a new event or event variant | Breaking |
| Removing (archiving) an event or event variant | Breaking |
| Renaming an event or event variant | Breaking |
| Changing an event’s name mapping | Breaking |
| Adding or removing a source on the event | Breaking |
| Turning “Include in code generation” on or off for a source | Breaking |
| Changing the event’s actions (log event, update user properties, etc.) | Breaking |
| Changing which destinations the event is sent to | Non-breaking |
| Changing the event’s group types (event groups or user groups) | Non-breaking |
| Changing the property whitelist for an analytics tool | Non-breaking |
On a property, as it is sent with an event
| Change | Breaking? |
|---|---|
| Adding a property to an event, or removing it | Breaking |
| Renaming a property | Breaking |
| Changing a property’s type, or making it a list | Breaking |
| Changing a property’s presence (required, sometimes sent, never sent) | Breaking |
| Changing a property’s name mapping | Breaking |
| Removing an allowed value, or adding the first regex / min / max rule | Breaking |
| Adding an allowed value to a property that already has allowed values | Non-breaking |
| Changing a pinned value | Breaking |
| Changing nested properties on an object property | Breaking |
| Changing the property operation (for example set vs. increment) | Non-breaking |
Because properties are compared per event, editing a property that is sent with many events marks the stakeholders of every one of those events as impacted. See Minimizing stakeholder impact for how to scope a property change to just the events that need it.
Changes that do not impact stakeholders
These changes appear in your branch’s diff and activity log, but they do not add anyone to the impacted stakeholders list:
- Descriptions on events, event variants and properties
- Tags on events and properties
- Custom field values on events and properties
- Event triggers – screenshots, trigger descriptions and user journeys
- Category and metric membership – adding an event to a category, or editing a category or metric
- Assigning or removing stakeholder teams and owners on an item
- Source and destination settings themselves, such as renaming a source
- Changes to an event that has no sources attached – with no source to send it, there is no sent shape to change
- Adding or removing a property that is never sent for that source
Edited a description and saw no impacted stakeholders? That is expected. Descriptions, tags, custom fields and triggers are documentation: they change how an item is understood, not how it is implemented or sent. Impacted stakeholders exists to warn you before you disrupt data other teams rely on, so it only counts changes that alter the data itself. Your description change is still on the branch, still shows up in the diff, and still goes through the normal review and merge flow.
Settings that change what counts
Three stakeholder team settings adjust the rules above. They are available on the Enterprise Plan and are configured per stakeholder team in stakeholder team settings.
- Only impacted by breaking changes – the team is left out of the impacted list for anything marked Non-breaking in the tables above, and is not required to review it.
- Impacted by new items and Impacted by PII changes – these work in the opposite direction: the team is marked impacted whenever the branch adds a new event or property, or changes a PII declaration, anywhere in the tracking plan – even on items they are not a stakeholder or owner of. Note that a PII declaration change on its own does not otherwise count as an impacting change.
Minimizing stakeholder impact
While there are fundamental data structures that need to be consistent across multiple teams and platforms, stakeholder teams frequently need to expand on them and add nuances that don’t need to apply to every single place these events and properties are tracked.
The Avo tracking plan has tools to provide this flexibility, allowing stakeholder teams to more granularly define their data based on their needs and reduce unnecessary impact across other stakeholder teams.
Event-specific property constraints
For generic properties that are sent with multiple events across your product, the constraints of the property (such as allowed values or regex) are commonly different depending on which event or variant the property is being sent with. Example: If a social media app is introducing a “Stories” feature. To track users commenting on stories, only the “Comment Added” event will need to include the allowed value “Story” for the “Item Type” property.
If this allowed value is introduced to the property without specifically defining which event(s) it should apply to, this will generate a change to all events and event variants using this property in Avo – meaning all stakeholders of those events and variants will be marked as impacted by the branch changes.
To avoid this, you can simply specify the new value as only applying to the event where you need it. Same applies when modifying the regex constraints, instead of modifying the regex on all events and variants that have the property, you apply event or variant specific regex rules.
Learn how to set event specific property constraints
Event variants
For events that are used in multiple places and scenarios across a product, some of these scenarios may call for the event to be sent with certain properties or property values that don’t apply to every instance of the event.
Example:
An “add_to_cart” event may be used by both the Checkout and Search teams. The Checkout team owns the event and relies on certain properties like “cart_product_origin” that must be consistent across all products.
The Search team needs a specific variation of this event for when it’s triggered on their Search Results page. In this scenario, this event needs to be sent with the property “search_term” and the pinned value for “cart_product_origin” should be “Search Result Page”.
Event Variants provide a way to document variations of an event to account for different scenarios. Event variants inherit its definition from a base event, but you can add overrides on top of them.
That way, you can define variant-specific properties, property presence and value rules, without needing to roll out those changes to every instance of this event across your organization.
Learn how to create Event Variants
Aligning on cross-stakeholder changes
In cases where a cross-stakeholder change is required, the visibility of the impacted stakeholder teams allows you to understand who you will need to loop in to align on the suggested changes, where these changes will need to be implemented across your organization and by who.
- From the impacted stakeholders indicator, you see a preview of the members of the stakeholder team.
- On the Enterprise plan, impacted owners can be automatically added as required reviewers based on their stakeholder settings.
- Other stakeholder teams, including impacted owners on the Team plan, can also be added as reviewers manually.
Managing stakeholder-impacted branches
To help stakeholder teams stay on top of branches that impact their domain, Avo provides filtering capabilities in both the events and branches views:
- Events filtering: Filter events by stakeholders and owners to focus on relevant events
- Branch filtering: Filter branches by impacted stakeholders and owners to see branches affecting your team’s domain
These filters are particularly useful for stakeholder team leads who need to track branches requiring their team’s review or approval.
Automatic reviewer assignment
Automatic reviewer assignment and required reviews from stakeholder teams is only available on the enterprise plan.
Stakeholder teams can be automatically added as required reviewers when branches impact their stakeholder events. This happens through two different mechanisms:
Workspace-level requirement:
- When “Require approval from owning stakeholders” is enabled in workspace settings
- All stakeholder teams that own events being modified are automatically added as required reviewers
- Applies to all impacted owner teams regardless of their individual settings
Individual stakeholder settings:
- Each stakeholder team can configure how they want to be involved when impacted
- Separate configurations for when they’re owners vs stakeholders of impacted events
- Teams can choose: automatic required reviewer assignment, Slack notifications only, or no automatic action
When a stakeholder team is assigned as a reviewer—either manually or automatically—a random team member with approval privileges will be assigned to review and approve on the team’s behalf.