By default, the Tracking Plan configuration is in JSON format. The Tracking Plan spreadsheet is a no-code, spreadsheet representation of your Tracking Plan configuration. It lets you easily create or use an existing Tracking Plan.

This guide details the various options and spreadsheet settings that let you configure your Tracking Plan.

Spreadsheet overview

The configuration settings for your Tracking Plan are listed in the Homepage and Additional Features tabs of the Tracking Plan spreadsheet. They are linked to the actions listed in the RudderStack Tracking Plan menu in the Google Sheets top bar, as shown:

Creating a Tracking Plan from existing event data

RudderStack lets you create a Tracking Plan from an existing event data source. This option uses the Data Governance API and the Tracking API features to generate an initial plan.

To create a Tracking Plan from an existing RudderStack source, follow these steps:

1. Go to the Additional Features tab of your Tracking Plan spreadsheet.

2. Under Create Tracking Plan from Existing Source, enter the following settings:

   • Data Plane URL: Enter the data plane URL of your workspace or where the data plane is hosted.
   • Write key: Enter the write key for the RudderStack source. You can find it in the Sources page.
   • Username: Enter your admin username.
   • Password: Enter your admin password.
   • Tracking Plan Name: Assign a name to this Tracking Plan.

3. Click the RudderStack Tracking Plan > Create Tracking Plan from Existing Source Events option in the top bar to create a new Tracking Plan.

4. To verify if the Tracking Plan is created, refer to the Getting the Tracking Plans section below.

Getting the Tracking Plans

To get a list of all your existing Tracking Plans, go to RudderStack Tracking Plan > Show All Tracking Plans.

This option lists all your existing Tracking Plans along with their respective Tracking Plan IDs in the List of Tracking Plans sheet.

Downloading existing Tracking Plans from RudderStack

To download existing Tracking Plans from RudderStack, follow these steps:

1. Get a list of all your Tracking Plans by going to RudderStack Tracking Plan > Show All Tracking Plans. Note the Tracking Plan ID.
2. Go to the Download Tracking Plan from RudderStack option in the spreadsheet and enter the Tracking Plan ID, as shown:

3. Click RudderStack Tracking Plan > Download Tracking Plan from RudderStack in the top bar.

This will create a new sheet with your Tracking Plan.

Uploading a Tracking Plan to RudderStack

To upload a Tracking Plan to RudderStack, follow these steps:

1. Go to the Upload Tracking Plan to RudderStack section in the Homepage tab of your spreadsheet.

2. Enter the following settings:

   • Sheet Name (for Upload): Enter the tab name of the sheet containing the Tracking Plan.
   • Tracking Plan name: Enter the name of the Tracking Plan you want to upload to RudderStack.

3. Upload the Tracking Plan by going to RudderStack Tracking Plan > Upload Tracking Plan to RudderStack in the top bar.

Linking Tracking Plan to a source

When you link a Tracking Plan to a source, all the events will be processed in accordance with that plan.

To link a Tracking Plan to a source, follow these steps:

1. In the Additional Features tab, go to the Link Tracking Plan to Source.

2. Then, enter the following settings:

   • Tracking Plan ID: Enter the Tracking Plan ID. Refer to the Getting the Tracking Plans section for more information.
   • Source ID: Enter your source ID. The following image highlights the source ID's location in the RudderStack dashboard:

Global settings

1. Specify the following settings under Global Settings (applicable for all events):

   • Allow unplanned events: This setting has the following options:

   Option	Description
   TRUE	RudderStack will not drop the events not defined in your Tracking Plan
   FALSE	RudderStack will drop the events not defined in the Tracking Plan.

   • Unplanned Properties: This setting has the following options:

   Option	Description
   FORWARD	The event's context field will be updated with the erroneous/unplanned property and forwarded to RudderStack.
   DROP	RudderStack will drop the event containing the unplanned properties.

   • Other Violations: These violations include discrepancies such as type mismatch, missing required properties, etc.

   Option	Description
   FORWARD	The event's context field will be updated with these violations and forwarded to RudderStack.
   DROP	RudderStack will drop the event containing the violations.

   • Propagate Errors: This setting has the following options:

   Option	Description
   TRUE	The validation errors are captured in the event's context and sent downstream (user transformations, destinations)
   FALSE	RudderStack will drop the event containing the validation errors.

2. After finalizing the settings, go to RudderStack Tracking Plan > Link Tracking Plan to Source in the top bar.

Other spreadsheet settings

This section contains the noteworthy spreadsheet settings required to interact with your Tracking Plan.

API key settings (Global)

• API Personal Access Token: Enter your Personal Access Token obtained from the RudderStack dashboard.

• Email: Enter the email ID associated with your RudderStack account.

Advanced settings

These settings define how RudderStack should pick the data (event/property values) from the Tracking Plan.

Google Apps permissions

When you run the RudderStack Tracking Plan menu options for the first time, Google Apps will prompt you to authorize the scripts using the Tracking Plan API.

Click Allow to set the permissions required for the script to work.

Server-side validation

RudderStack uses server-side validation to enforce your Tracking Plans. When you link a Tracking Plan to a source, RudderStack will check all the new events against the Tracking Plan.

The validation adds two new columns for each table and each row that specify:

• Which Tracking Plan was used
• The error message associated with the Plan

These columns will then propagate to both your data warehouse as well as cloud destinations. This lets you monitor the state of your violations and choose to act on them through manual operations or through the transformations.

How RudderStack propagates context related to tracking plan violations

Currently, RudderStack propagates any context related to the tracking plan violations only to the data warehouses but not all the destinations. You can use this context in your Transformations for filtering or modifying the events before they reach the destination.

If you have defined the tracking plan global settings such that Allow unplanned events is set to FALSE, the events that are explicitly dropped via the tracking plan will not reach any destination.