💡 Event schemas are important in many layers of your data stack. Keeping schema registries in sync across the stack can be a challenge, especially since stakeholders involved vary from non-technical folks with a preference for human readable tools like spreadsheets, to technical folks with a preference for computer readable schemas like JSON.
Publishing is a way to push your tracking plan specs from Avo into your other schema registries and downstream tools, including analytics platforms like Amplitude or Mixpanel, ingestion time validation tools like Segment Protocols, RudderStack or Snowplow, or connect to any tool or internal system via webhook. See publishing use cases and publishing integrations below.
Avo allows you to maintain a single source of truth for your schemas and keep your schema registries in sync, serving both your technical and non-technical stakeholders.
💡 Push or pull your schemas: To keep your Avo tracking plan in sync with your downstream schema registries you can either push your schema from Avo via Avo Publishing or pull your Avo schema via Avo CLI. We recommend leveraging push since you can configure that to make sure your downstream schema registries get updated when your main Avo schema gets updated.
Push: Publishing your schema: You can set up Publishing integrations where you publish your Avo schema into other schema registries. For example as JSON into a Webhook. We recommend leveraging auto-publishing for those integrations, where your schema will get published upon Avo branch merge (you can also manually publish a schema at any point). See use cases.
Pull: Pull JSON schema via CLI: An alternative to Avo Publishing integrations is pulling a JSON schema via the CLI. This way you can add a schema pull into a CI/CD. See docs to pull schema via CLI.
Available integrations are:
Publishing enables your Tracking Plan to be:
Having the description at hand when navigating your events in your analytics platform, like Mixpanel or Amplitude, helps you more easily identify the events and properties you’re looking for when building charts and looking at dashboards. With an Avo publishing integration you can let Avo automatically push description and other tracking plan details into these tools, so you can have more context at hand when using the data.
Segment Protocols, mParticle Data Master, RudderStack Tracking Plans and Snowplow Iglu are all examples of CDPs with ingestion time validation. It allows you to validate the events as they come in, and for example route the bad events to alternative destinations. With Avo publishing you can make sure the schemas used for this validation are always up to date with your tracking plan in Avo, which increases the quality of your data in all downstream destinations. Being able to integrate with CDPs this way also allows your teams to gradually adopt Avo over time.
The publishing webhook is a building block that allows you to integrate your Avo tracking plan with your other schema registries and internal systems, tools and workflows. What can you build with the webhook? Here are some ideas to get you started:
To create a new publishing integration, find the Publishing part of the tracking plan in the left side navigation bar. From there you can click the "Add Integration" button to create a new publishing integration.
Then you can select the type of integration you want to create and give it a name.
Note that the publishing integrations are independent of the destinations defined in the "Sources" tab. However the publishing integration can use those destinations to filter which events should be included in the publishing integration. See more below in Filtering events for publishing.
When Auto Publishing is enabled all changes made on a branch will be published to the integration when the branch is merged.
You can customize which events in Avo are published to which integrations by using the events filter. Events can be filtered by Sources, Destinations and Tags. For example the following integration will only publish events sent from Web to Amplitude.
How is source specific property presence published?
What does the "lowest common denominator" mean?
You can learn more on configuring when Properties are required or optional here.
The integration to Segment Protocols allows for your Tracking Plan to be published into Segment Protocols whenever branches are merged in your workspace or with a push of a button.
💡 The Protocols integration currently supports the established Config API. If you are only able to use the new Public API, please reach out to us.
To enable the direct integration with Segment Protocols, you need to configure it with the following parameters from Segment.
https://app.segment.com/{Segment workspace slug}/...
or in the workspace settingsrs_
To publish your Avo tracking plan to Protocols, click the "Publish" button in the integration interface, or enable Auto Publishing to publish the events included in the publishing integration whenever a branch has been merged.
Avo will override all events in the Protocols tracking plan that are included in the publish from Avo. Any changes made to an event in Protocols between Avo publish will be overridden on next Avo publish.
Avo will not override any events that are only defined in Protocols, or events that are not included in the Protocols integration in Avo.
Here's how the Avo Tracking Plan is mapped to Protocols:
User Properties in Avo are published as identify traits to Segment Protocols.
By default, all user properties that are attached to events that are sent from at least one source in Avo, are included in the publish. When the publishing integration is filtered by source, only user properties sent with events from those sources will be included. To see exactly which user properties will be published in your integration, expand the "Payload Preview" section below the integration config.
Avo will not override any user properties (identify traits) that are only defined in Protocols, or user properties that are not included in the Protocols integration in Avo.
Currently Avo does not publish properties into Protocols. If you'd like to publish group properties, please let us know, and we'll invite you to the beta when it goes live.
Currently Avo does not publish categories into Protocols. If you'd like to publish categories, please let us know!
The integration to Mixpanel Lexicon allows for your Tracking Plan to be published into Mixpanel Lexicon whenever a branch is merged in your workspace or with a push of a button.
To enable the direct integration with Mixpanel Lexicon, you need to configure it with the following parameters from Mixpanel.
https://mixpanel.com/report/<Mixpanel Project Id>/...
To publish your Avo tracking plan to Lexicon, click the "Publish to Lexicon" button in the integration interface, or enable Auto Publishing to publish the events included in the publishing integration whenever a branch has been merged.
On publish, Avo will merge your Avo tracking plan with any existing events in Lexicon. Any changes made to an event in Lexicon between Avo publish will be overridden on next Avo publish.
Avo will not impact any events that are only defined in Lexicon, or events that have not been added to the Lexicon integration in Avo.
The RudderStack integration enables you to publish your Avo Tracking Plan into RudderStack. You can configure the integration to publish whenever a branch is merged or with a push of a button.
To enable the direct integration with RudderStack Tracking Plans, you need to configure it with the following parameters from RudderStack.
Avo will override all events in the RudderStack Tracking Plan that are being imported from Avo. Any changes made to an event in RudderStack Tracking Plan between Avo publish will be overridden on next Avo publish.
Avo will not override any events that are only defined in RudderStack, or events that have not been excluded from the RudderStack integration in Avo with filters.
The Snowplow integration enables you to publish your Avo Tracking Plan into Snowplow. You can configure the integration to publish whenever a branch is merged or with a push of a button.
To enable the direct integration with Snowplow, you need to configure it with the following parameters.
.com
when visiting the console, e.g. 13bbade6-1eff-42d0-861d-41cd3e52ac41
in https://console.snowplowanalytics.com/13bbade6-1eff-42d0-861d-41cd3e52ac41/contact-us
.Manage data structures
section in the console.API keys
section.Data structures interfaces are only compatible with pipelines that have been upgraded to use Iglu Server registries, rather than static S3 registries. Please check in your Snowplow console, to see if you need an upgrade or if your registries are ready to go.
The Snowplow API enforces a workflow of validating, testing on development and then deploying to production.
Avo publishing integration will take care of validating and deploying your data structures to the development environment, where you take over to test the data structures and promote the tested data structures to production.
Avo will override all events in the Snowplow Tracking Plan that are being imported from Avo. Any changes made to an event in Snowplow Tracking Plan between Avo publish will be overridden on next Avo publish.
Avo will not override any events that are only defined in Snowplow, or events that have not been excluded from the Snowplow integration in Avo with filters.
Note that only Admin users can promote data structures from Dev to Production. Learn more on how to promote the data structures with Snowplow Console here
Avo will create new data structures with version 1-0-0 and will patch the existing data structures in your development environment on the same version as they are.
When promoting the tested data structures to production you will be required update the version. Read more about the versioning here
The mParticle Data Master integration enables you to publish your Avo Tracking Plan into mParticle Data Master. You can configure the integration to publish whenever a branch is merged or with a push of a button.
To enable the direct integration with mParticle Data Master, you need to configure it with the following parameters from mParticle.
Avo will create a new version of your data plan in mParticle every time you publish. When publishing manually you can pick whether you'd like to overwrite existing mParticle data plan version or create a new one. Auto publish will always create a new version of the data plan in mParticle, by incrementing the version number of the most recent plan by one.
Avo will override all events in the mParticle Tracking Plan that are being imported from Avo. Any changes made to an event in an mParticle Tracking Plan between publishing from Avo will be overridden on the next Avo publish.
Avo will not override any events that are only defined in mParticle, or events that have not been excluded from the mParticle integration in Avo with filters.
💡 Amplitude has recently closed it's public API making us unable to offer this option to our users. We will make it available as soon as they offer an API to update Govern.
The integration to Amplitude Govern allows for your Tracking Plan to be published into Amplitude Govern whenever a branch has been merged. You can also manually trigger a publish by clicking the "Publish to Govern" button on the integration screen or download a CSV file on the Amplitude Govern format, which you can manually import into Govern. The events to be published can be filtered by Sources, Destinations and Tags.
To enable the direct integration with Amplitude Govern, you need to configure it with the following parameters from Amplitude. They can be found from the project settings in Amplitude. From the left sidebar in your Amplitude workspace click: Settings > Projects > [Your Project Name]. The URL should look like this: https://analytics.amplitude.com/{org-name}/settings/projects/{project-id}/general
.
To publish your Avo tracking plan to Govern, click the "Publish to Govern" button in the integration interface, or enable Auto Publishing to publish the events included in the publishing integration whenever a branch has been merged.
On publish, Avo will merge your Avo tracking plan with any existing events in Govern. Any changes made to an event in Govern between Avo publish will be overridden on next Avo publish.
Avo will not impact any events or properties that are not defined in Avo, or events that have not been added to the Govern integration in Avo. Avo will not impact any custom events defined in Govern.
Here's how events, properties and categories are mapped from Avo to Govern:
string
, number
, boolean
, enum
or any
true
if the "list" checkbox is checked on the property in Avotrue
if the property is marked as "Always sent" in AvoThe following errors might occur when publishing your tracking to Govern. When publishing errors occur the error message in the Avo UI will contain which items could not be updated along with the error codes.
404 Not Found: This error can be thrown in few scenarios:
408 Timeout: The publishing operation took too long. This can happen when publishing large tracking plans for the first time. Click publish again to resume the publish, it will continue from where it left off.
409 Conflict: We tried to update an item that doesn't exist in your Amplitude Govern Schema. We noticed that this error may happen if the entity has a non-default state in your Govern schema, i.e. it is marked as "Unexpected" or "Blocked". Try setting the state to "Expected" in Govern and unblock erroring entities and publish again. If that does not help this might be caused by an internal error. Please reach out to support so we can help you resolve the issue.
429 Too Many Requests: We've exceeded the number of Govern requests we can make per hour for the provided API credentials or there are too many concurrent requests to the Amplitude Govern API with given credentials. Please wait before trying to publish again and make sure that you are not running multiple publishing at the same time for the same credentials. You can learn more about Amplitude Govern request limits in the Amplitude Govern docs.
Other error codes: Please contact us if you are experiencing other types of errors.
The Webhook integration is a way to get your updated Tracking Plan distributed to an endpoint of your choice. This happens when a branch is merged or when the publish button is clicked in the integration interface.
To enable the Webhook integration you need to configure it with a URL where you want the updated tracking plan to be delivered.
The Tracking Plan will be delivered with a POST
request containing the Tracking Plan on a JSON format. The only requirement for this endpoint is to return a 200
response status code when it has successfully received the tracking plan.
Currently there are three different payload formats you can choose from for the webhook: Snowplow Schemas, Avo Json, and Json Schema (default).
💡 To see a preview of the exact Webhook payload in your Avo workspace choose
Publishing
in the sidebar, then pick your Webhook from the menu and expand thePayload preview
section
Json containing a Snowplow Schema for every event included in the Publishing integration. These schemas can for example be used to integrate Avo with Snowplow Iglu.
You can provide your own vendor value via the "Vendor" input in the publishing integration config.
Attribute | Type | Description |
---|---|---|
eventSchemas | array(Snowplow Event Schema) | Schema for every event in your tracking plan, following the Snowplow Schema format |
contextSchemas | array(Snowplow Context Schema) | Schema for every Snowplow context in your tracking plan, following the Snowplow Schema format |
context | { publishInfo: PublishInfo } | Metadata about the webhook call |
Json representation of the state of your entire Avo workspace. Currently behind a feature flag. Contact us to enable.
Attribute | Type | Description |
---|---|---|
model | Avo Model | Json representation of your entire Avo workspace |
context | { publishInfo: PublishInfo } | Metadata about the webhook call |
Json representation of your tracking plan, following the Json Schema standard. Example payload can be found here
Attribute | Type | Description |
---|---|---|
name | string | The name of your Avo workspace |
events | array(Event) | Array of Tracking Plan events |
metrics | { metricId: Metric ... } | Objet where each Tracking Plan metric is a field, keys are metric ids |
sources | { sourceId: Source ... } | Objet where each Tracking Plan source is a field, keys are source ids |
destinations | { destinationId: Destination ... } | Objet where each Tracking Plan destination is a field, keys are destination ids |
categories | { categoryId: Category ... } | Objet where each Tracking Plan metric is a field, keys are category ids |
context | { publishInfo: PublishInfo } | Metadata about the webhook call |
Attribute | Type | Description |
---|---|---|
name | string | Event name |
description | string | Event description and the list of triggers |
rules | Rules | Event JSON rules |
tags | array(string) | Array of all tags attached to event |
categories | array(string) | Array of category ids this event is attached to |
triggers | array({id, description, sourceIds, link, imageUrl}) | Details about all triggers attached to event |
sources | array({id, name, implementWithCodegen, destinations}) | Details about all sources sending event |
Attribute | Type | Description |
---|---|---|
properties | PropertiesRule | Properties JSON rules |
nameMappings | array(NameMapping) | Name mappings defined for given event |
Attribute | Type | Description |
---|---|---|
properties | array(PropertyRule) | Property JSON rules |
Attribute | Type | Description |
---|---|---|
description | string | Property description |
type | string | Property type |
nameMappings | array(NameMapping) | Name mappings defined for given property |
?const | Depends on the property type | Pinned property value |
?enum | array(string) | Allowed enum values |
?operations | array(string) | Array of property ops, e.g. "SnowplowContext" |
Attribute | Type | Description |
---|---|---|
name | string | New mapped name |
destinationId | string | Either a destination id for which this property mapping applies, or "all", meaning that this property mapping applies to all destinations |
Attribute | Type | Description |
---|---|---|
id | string | Metric id |
name | string | Metric name |
description | string | Metric description |
categories | array(string) | Category ids where this metric is included |
type | string | One of Proportion / EventSegmentation / Funnel / Retention |
items | array of Nested Event | Event descriptions |
Attribute | Type | Description |
---|---|---|
eventId | string | Event id |
where | array(whereFilter) | Array of where filters |
groupBy | array(groupByFilter) | array of objects containing property ids to group by |
Attribute | Type | Description |
---|---|---|
propertyId | string | property Id being used in group filter |
Attribute | Type | Description |
---|---|---|
propertyId | string | property id |
operation | string | binary operation as string |
values | array(t) | array of values of the same type |
Attribute | Type | Description |
---|---|---|
id | string | Source id |
name | string | Source name |
programmingLanguage | string | Name of programming language (e.g. "JavaScript", "Python") |
developmentPlatform | string | Name of development platform (e.g. "Web", "Android") |
destinations | array(string) | Destination ids where this source sends data to |
Attribute | Type | Description |
---|---|---|
id | string | Destination id |
name | string | Destination name |
type | string | Name of the provider (e.g. "Segment", "Mixpanel") where the data is sent to if managed by Avo, "Custom" otherwise. |
Attribute | Type | Description |
---|---|---|
id | string | Category id |
name | string | Category name |
description | string | Category description |
metrics | array(string) | Metric ids belonging this category |
events | array(string) | Event ids belonging this category |
Attribute | Type | Description |
---|---|---|
branchId | id | Branch id |
branchName | string | Branch name |
integrationId | string | Id of the publish integration (consistently the same for this integration) |
integrationName | string | Name of the publish integration (seen in Tracking Plan -> publishing -> 'IntegrationName' |
publishDate | Date string | Timestamp when the webhook was triggered |
publishMethod | { "type": type } | Description of the publish method, type can be "Manual" and "BranchMerge" |