Tracking plan spreadsheet

The tracking plan spreadsheet is deprecated and will be discontinued soon.

By default, the tracking plan configuration is in JSON format. RudderStack’s 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.

To use the tracking plan spreadsheet, go to the spreadsheet and click File > Make a copy in the Google Sheets menu.

This guide details the various options and spreadsheet settings to configure your tracking plan.

Spreadsheet overview

The tracking plan spreadsheet uses the Google Sheets’ scripts functionality to integrate with the Tracking plan API.

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

Note that:

• The tracking plan spreadsheet supports the Null, String, Number, Integer, Boolean, Array, and Object data types.
• You can create, delete, or update the events and the associated properties. Once you upload the changes, RudderStack creates a new version of the tracking plan to keep track of your changes.

Create tracking plan from scratch

1. Enter the sheet name containing the tracking plan to upload.

You can replicate the sheet in Example Tracking Plan tab and make necessary changes to it. Then, rename this tab and specify the name above.

2. Assign a name for this tracking plan. RudderStack creates a new tracking plan if a plan with this name does not exist.
3. Under API Key Settings (Global), set your API Personal Access Token.
4. Specify the Email associated with your RudderStack workspace.
5. Click RudderStack Tracking Plan > Upload Tracking Plan to RudderStack in the top bar.
6. Verify if the tracking plan is created. See Get all tracking plans for more information.

Create tracking plan from existing event data

This is the easiest way to kickstart your tracking plan program without having to start from scratch.

RudderStack lets you create a tracking plan from an existing event data source. This option leverages the Event Audit API and Tracking plan API features to generate an initial plan.

Before you proceed, make sure the Event Audit API setting is turned on in your RudderStack dashboard.

Go to Settings > Workspace and click the Data Management tab. Scroll down to the Data governance section and turn on the Event Audit API toggle.

See Enable Event Audit API section for more information.

To create a tracking plan from an existing RudderStack source, follow these steps:

1. Make a copy of the Tracking Plan Sheet.

2. Under API Key Settings (Global), enter the following settings:

   • API Personal Access Token: Generate and enter your personal access token.
   • Email: Enter the email ID associated with your RudderStack account.

3. Go to the Additional Features tab of your tracking plan spreadsheet. Enter the following settings:
   • Write Key: Enter the write key for the source with which you want to link the tracking plan.
   • Tracking plan name: Enter the name for the new tracking plan.

4. Click RudderStack Tracking Plan > Create Tracking Plan from Existing Source Events in the top bar to create a new tracking plan.

For the first time you use the spreadsheet, you will be prompted with an approval request. Select Allow to permit Google Apps to execute the scripts. See Google Apps Permissions for more information.

5. Verify if the tracking plan is created. See Get all tracking plans for more information.

Upload tracking plan

You can use this option to create or update a tracking plan in RudderStack.

To upload a tracking plan to RudderStack, follow these steps:

1. Go to Upload Tracking Plan to RudderStack section of your spreadsheet’s Homepage tab.

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.

Note that:

• RudderStack creates a new tracking plan if the name does not exist.
• If you have instrumented your identify events such that the user traits are captured in the traits object of the events, make sure you select traits as shown, before creating or updating the tracking plan.

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

Download existing tracking plans

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 Download Tracking Plan from RudderStack in the spreadsheet and enter the Tracking Plan ID:

3. Click RudderStack Tracking Plan > Download Tracking Plan from RudderStack in the top bar. This creates a new sheet with your tracking plan.

Get all 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 IDs in the List of Tracking Plans sheet.

Link tracking plan to source

When you link a tracking plan to a source, all events are processed in accordance with that plan.

This option lets you define the events that RudderStack will drop or allow to pass through, and the permissible errors in the event’s context field.

See Server-side validation for more information on how RudderStack enforces the tracking plans on your source events.

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 section.

2. Then, enter the following settings:

   • Tracking Plan ID: Enter the tracking plan ID. See Get all tracking plans section for more information.
   • Source ID: Enter your source ID. You can find it by going to the Settings tab of your source.

A source ID uniquely identifies a RudderStack source. It is different to the source write key which is used by RudderStack to send events from the source to your specified destinations.

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

Event settings

• Allow unplanned events: This setting is exclusive to track events and has the following options:

• Unplanned Properties: This setting has the following options:

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

• Propagate Errors: This setting has the following options:

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.

Do not change these settings unless absolutely necessary as it may impact the entire tracking plan workflow.

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

FAQ

What does the Format Excess Rows (>1500) option do?

For the downloaded tracking plans, the formatting and dropdown selection for rule types and data types applies only to the first 1500 rows, as that is the number of rows the sheet displays initially.

In case the tracking plan rules spill over to more than 1500 rows, you can use the Format Excess Rows (>1500) button to reformat the excess rows.

How does the RudderStack tracking plan spreadsheet apply the validations for different event types?

By default, RudderStack applies the tracking plan validation on the supported event types as follows:

• context.traits object for identify events.
• traits for group events.
• properties for track, page, and screen events.

If you have instrumented your identify events such that the user traits are captured in the traits object of the events, make sure you select traits as shown, before creating or updating the tracking plan.

Questions? Contact us by email or on Slack