Tracking Plan Spreadsheet
Detailed technical description of the Tracking Plan spreadsheet for configuring your Tracking Plan.
Last updated
Was this helpful?
Detailed technical description of the Tracking Plan spreadsheet for configuring your Tracking Plan.
Last updated
Was this helpful?
By default, the Tracking Plan configuration is in JSON format. The 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.
The Tracking Plan spreadsheet uses the Google Sheets' scripts functionality to integrate with the Rudderstack Tracking Plan API.
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:
The Tracking Plan spreadsheet currently supports only simple datatypes (strings, numbers, Boolean, arrays, and objects).
You can create, delete, or update the events or the properties within these events. Once you upload the changes, RudderStack creates a new version of the Tracking Plan to keep track of your changes.
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.
This is the easiest way to kickstart your Tracking Plan program without having to start from scratch.
To create a Tracking Plan from an existing RudderStack source, follow these steps:
Go to the Additional Features tab of your Tracking Plan spreadsheet.
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.
The Username and Password are your Grafana dashboard credentials and not your RudderStack account credentials. If you are unsure, contact your Account Manager.
Click on the RudderStack Tracking Plan > Create Tracking Plan from Existing Source Events option in the top bar to create a new Tracking Plan.
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.
To download existing Tracking Plans from RudderStack, follow these steps:
Get a list of all your Tracking Plans by going to RudderStack Tracking Plan > Show All Tracking Plans. Note the Tracking Plan ID.
Go to the Download Tracking Plan from RudderStack option in the spreadsheet and enter the Tracking Plan ID, as shown:
Click on RudderStack Tracking Plan > Download Tracking Plan from RudderStack in the top bar.
This will create a new sheet with your Tracking Plan.
You can use this option to create or update a Tracking Plan.
To upload a Tracking Plan to RudderStack, follow these steps:
Go to the Upload Tracking Plan to RudderStack section in the Homepage tab of your spreadsheet.
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.
RudderStack will create a new Tracking Plan if the name does not exist.
Upload the Tracking Plan by going to RudderStack Tracking Plan > Upload Tracking Plan to RudderStack in the top bar.
When you link a Tracking Plan to a source, all the events will be processed in accordance with that plan.
This option lets you define the events that will be allowed to pass through or dropped by RudderStack, and the permissible errors in the event's context field.
To link a Tracking Plan to a source, follow these steps:
In the Additional Features tab, go to the Link Tracking Plan to Source and enter the following settings:
Source ID: Enter your source ID. The following image highlights the source ID's location in the RudderStack dashboard:
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.
Specify the following settings under Global Settings (applicable for all events):
Allow unplanned events: This setting has the following options:
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:
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.
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:
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.
You can use Settings for track to explicitly define the Tracking Plan rules for track events.
After finalizing the settings, go to RudderStack Tracking Plan > Link Tracking Plan to Source in the top bar.
This section contains the noteworthy spreadsheet settings required to interact with your Tracking Plan.
API Personal Access Token: Enter your Personal Access Token obtained from the RudderStack dashboard.
Email: Enter the email ID associated with your RudderStack account.
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.
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 on Allow to set the permissions required for the script to work.
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.
For the first time you use the Tracking Plan spreadsheet, you will be prompted with an approval request. Select Allow to permit Google Apps to execute the scripts. Refer to the section below for more information.
To verify if the Tracking Plan is created, refer to the section below.
Refer to the section below for more information on how RudderStack enforces the Tracking Plans on your source events.
Tracking Plan ID: Enter the Tracking Plan ID. Refer to the section for more information.
For more information, refer to the documentation.
RudderStack uses server-side validation to enforce your Tracking Plans. When you , RudderStack will check all the new events against the Tracking Plan.
For queries on any of the sections covered in this guide, you can or get in touch with your Account Manager.
