Publishing

10 minute read

Avo Publishing

Publishing is where you can configure Avo to publish your Tracking Plan to your analytics platform, a production time validation tool or your own custom endpoint via webhook.

Available integrations are:

Publishing enables your Tracking Plan to be:

  • Published whenever a branch is merged with Auto Publishing
  • Published with a push of a button
  • Downloaded from your Avo workspace on relevant format

Setting up and configuring a publishing integration

Create a new publishing integration

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.

Creating a new Publishing Integration

Then you can select the type of integration you want to create and give it a name.

Creating a new Publishing Integration

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.

Configure Auto publishing

When Auto Publishing is enabled all changes made on a branch will be published to the integration when the branch is merged.

Publishing filter to publish only events sent from Web to Amplitude

Filtering events for publishing

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.

Publishing filter to publish only events sent from Web to Amplitude

Filtering and source specific property presence

How is source specific property presence published?

  • If you don't filter the integration by any source, the property presence is set to the "lowest common denominator" for all sources the property is sent from
  • If you filter the integration with one source, the property presence is set to the presence configured for that source on the property
  • If you filter by more than one source, the property presence is set to the "lowest common denominator" for the sources you're filtering by and are sending the property

What does the "lowest common denominator" mean?

  • If the property is "Always sent" on all sources being published, the property presence is set to "Always sent" (required)
  • If the property is "Sometimes sent" on one or more sources being published, the property presence is set to "Sometimes sent" (optional)
  • If property is "Never sent" on all sources being published, the property is not included in the publishing

You can learn more on configuring when Properties are required or optional here.

Integrations

Segment

Segment Protocols

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.

Configure the Protocols integration

To enable the direct integration with Segment Protocols, you need to configure it with the following parameters from Segment.

  • Segment Workspace Name: Found in the URL when logged into Segment: https://app.segment.com/{Segment workspace name}/...
  • Protocols Tracking Plan ID: Found in the URL of the tracking plan page: starts with rs_
  • Segment Access Token: Create new API tokens for Avo and limit the scope of its permissions to ‘Protocol Admin’.

Publishing to Protocols

Avo will override all events in the Protocols tracking plan that are being imported 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 have not been added to the Protocols integration in Avo.

Mixpanel

Mixpanel Lexicon

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.

Configure the Lexicon integration

To enable the direct integration with Mixpanel Lexicon, you need to configure it with the following parameters from Mixpanel.

Publishing to Lexicon

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 Tracking Plan 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.

Amplitude

RudderStack Tracking Plans

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.

Configure the RudderStack integration

To enable the direct integration with RudderStack Tracking Plans, you need to configure it with the following parameters from RudderStack.

  • RudderStack Account Email Address: The email of a RudderStack account with Read-Write access
  • RudderStack Tracking Plan Name: The display name of the RudderStack Tracking Plan you want to publish to
  • RudderStack Access Token: Create new Personal Access Token for the account with the email address you provided above

Publishing to 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.

Amplitude

Amplitude 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. The events to be published can be filtered by Sources, Destinations and Tags.

Configure the Govern integration

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.

  • Amplitude API Key
  • Amplitude Secret Key

Publishing to Govern

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 Tracking Plan 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 only defined in Govern, or events that have not been added to the Govern integration in Avo.

Govern Publishing Warnings

409 Conflict

Some events that are in your Govern Schema are not recognized by the Govern API, for example events that have been merged into other events in Govern or events that are blocked. Events that end up returning 409 error in Amplitude are likely not active. If you'd like to get rid of this warning please double check them and remove them from your Avo tracking plan if they are not active anymore.

Govern Publishing Errors

The 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

We tried to update an event that doesn't exist in your Amplitude Govern Schema. If this error occurs for all of the events you are attempting to publish it might indicate that your Amplitude Govern Schema has not been initialized. Learn more about initializing your Amplitude Govern Schema in the Amplitude Govern docs. After you Govern Schema is initialized usually the API continues to return occasional 404 errors for a few more hours. If your Govern Schema has been initialized more than 6 hours ago and the error persists, please contact support.

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.

Webhook

Webhook

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.

Configure the Webhook integration

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.

Tracking Plan Model

💡 To see your exact Webhook payload in your Avo workspace choose Tracking plan - Publishing in the sidebar, then pick your Webhook from the menu and expand the Payload preview section

Example payload can be found here

AttributeTypeDescription
namestringThe name of your Avo workspace
eventsarray(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

Event Model

AttributeTypeDescription
namestringEvent name
descriptionstringEvent description
rulesRulesEvent JSON rules

Rules Model

AttributeTypeDescription
propertiesarray(PropertyRule)Property JSON rules
nameMappingsarray(NameMapping)Name mappings defined for given event

PropertyRule Model

AttributeTypeDescription
descriptionstringProperty description
typestringProperty type
nameMappingsarray(NameMapping)Name mappings defined for given property
?enumarray(string)Allowed enum values

NameMapping Model

AttributeTypeDescription
namestringNew mapped name
destinationIdstringEither a destination id for which this property mapping applies, or "all", meaning that this property mapping applies to all destinations

Metric Model

AttributeTypeDescription
idstringMetric id
namestringMetric name
descriptionstringMetric description
categoriesarray(string)Category ids where this metric is included
typestringOne of Proportion / EventSegmentation / Funnel / Retention
itemsarray of Nested EventEvent descriptions

Nested Event Model

AttributeTypeDescription
eventIdstringEvent id
wherearray(whereFilter)Array of where filters
groupByarray(groupByFilter)array of objects containing property ids to group by
groupByFilter
AttributeTypeDescription
propertyIdstringproperty Id being used in group filter

Where filter

AttributeTypeDescription
propertyIdstringproperty id
operationstringbinary operation as string
valuesarray(t)array of values of the same type

Source Model

AttributeTypeDescription
idstringSource id
namestringSource name
programmingLanguagestringName of programming language (e.g. "JavaScript", "Python")
developmentPlatformstringName of development platform (e.g. "Web", "Android")
destinationsarray(string)Destination ids where this source sends data to

Destination Model

AttributeTypeDescription
idstringDestination id
namestringDestination name
typestringName of the provider (e.g. "Segment", "Mixpanel") where the data is sent to if managed by Avo, "Custom" otherwise.

Category Model

AttributeTypeDescription
idstringCategory id
namestringCategory name
descriptionstringCategory description
metricsarray(string)Metric ids belonging this category
eventsarray(string)Event ids belonging this category

PublishInfo Model

AttributeTypeDescription
branchIdidBranch id
branchNamestringBranch name
integrationIdstringId of the publish integration (consistently the same for this integration)
integrationNamestringName of the publish integration (seen in Tracking Plan -> publishing -> 'IntegrationName'
publishDateDate stringTimestamp when the webhook was triggered
publishMethod{ "type": type }Description of the publish method, type can be "Manual" and "BranchMerge"