Bulk-Edit & Sync Piwik Pro Custom Dimensions in multiple Sites

Part II of “Scaling with Piwik Pro Manager”

8 min readFeb 1, 2025

This is Part II of a series on scaling your Piwik Pro setup. Feel free to read from Part I for more context.

You can also watch the video to this post! ;) Not all the details in there, but good enough for starters.

After installing Piwik Pro Manager and running the setup (takes only 5 minutes), we can start with the easiest, but most unforgiving part if we were to make an error: Custom Dimensions.

A professional setup cannot live without Custom Dimensions. But the Piwik Pro interface offers no way to create or change Custom Dimensions across multiple Sites. Moreover, Piwik Pro is intricate about how it assigns Custom Dimensions. Especially important:

If you create a new Custom Dimension, it automatically gets assigned to the next numerical Slot and (“Tracking”) ID — you cannot choose neither Slot nor ID. The ID just increases by 1 with every new Dimension. But the “Slot” is unique per Scope (Event or Session). See for example the screenshot below, where, after 21 Event-scoped dimensions, we have the first Session-scoped Dimension (“Google Ads Match Type”). The Tracking ID just continues with 22, but the Slot “restarts” at 1:

This seems like no big deal, but it is. Because you cannot change the scope afterwards! So you have to be extremely cautious when creating Custom Dimensions. If you accidentally create ID 5 as an Event Dimension, but want it to be a Session Dimension after all, there is no way to change that anymore. You need to shred your Site and start from scratch.

Why is this a giant problem? Because it kills scalability. If you want to maintain a centralized standard across Sites, your Custom Dimension Slots absolutely have to be identical across sites.

Take our example again with a client with multiple PP Sites, one each for the EMEA website, APAC, the US, and Africa. And while you need to track into different PP Analytics Sites because your org’s PP users from EMEA should not be allowed to see data from the other regions, the websites are mostly identical from a tracking standpoint: E.g., all websites provide a Data Layer variable pageType. So if you track that Variable into Analytics Custom Dimension Tracking ID 32 on all websites, you can use the same mapping logic in your Piwik Pro Tags for EMEA, APAC, the US, and Africa. You can also use the same segment using Dimension 32 in multiple Sites, the same Custom Report Filters, the same Custom Dashboard widgets in all Sites, and so on. So in summary:

Having the same Custom Dimension Slots and IDs across Sites is the most crucial foundation for scalability!

To help with this, I use a naming convention of “CD{Tracking ID}: Name of Dimension ({Scope})” (see examples in the screenshot above) for Custom Dimensions.

But how can you make sure you don’t mess up …

… when creating Custom Dimension for multiple Sites?
… when trying to keep Custom Dimensions up to date easily across Sites?

Step 1: Create identical Custom Dimensions across Sites (“Cloning”)

In the following I will often refer to the Blueprint Site, meaning the one PP Site which represents the standard you want to replicate in other Sites. These other Sites I call Destination Sites.

“Custom Dimension” will be abbreviated to “CD”.

The prerequisite for everything that comes below is that you have not messed up yet. This means that …

a) You have not set up any CDs in the Destination Site(s) at all yet, OR …

b) You have set up CDs in your Blueprint Site only, OR …

c) You have set up some CDs in Destination Sites already, and those share the same Slots, IDs and Scopes as in your Blueprint Site. For example: The Blueprint Site has Custom Dimension IDs 1–4. Destination Site A has only ID 1–2, but A’s 2 CDs have the same Scope and the same Slots as CDs 1 and 2 in the Blueprint Site.

For example, this is OK. Other Site A has only 2 CDs instead of the 4 CDs in the Blueprint Site, but the Slots, IDs, and Names of the shared 2 CDs are identical.

This is not OK (too late!), because each ID has a different Scope & Slot:

So if your current setup is “OK” as described above, we can continue.

If you haven’t created any Custom Dimensions at all, create them in the Blueprint Site, just as usual from the Piwik Pro interface under Analytics -> Settings -> Custom Dimensions.

Now we want to copy these Custom Dimensions to certain Destination Sites. For that, in your Piwik Pro Manager Google Sheet, navigate to the “Sites” tab and run Sites -> Refresh Sites:

After the “Sites” tab has refreshed, in column “Generate data for these sites”, check all the Sites for which you want Piwik Pro Manager to retrieve data to the sheet. Choose only those you really want to edit at the moment, as each additional Site increases the time needed to load the data into the Google Sheet, and a less crowded Sheet also helps you with your overview. In my example, I have selected my Blueprint Site (www.dim28.ch), “Lukas Testing 2” and “Lukas Testing 3”. In our earlier example, the Blueprint Site could be EMEA, “Lukas Testing 2" could be US and “Lukas Testing 3” could be APAC.

Get Lukas Oldenburg’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Then, in column “Clone Custom Dimensions to”, select the Sites where your Custom Dimensions should match the Blueprint. Again, I select the 2 “Lukas Testing” Sites:

Now, run Sites -> Clone Custom Dimensions and click OK on the popup that follows.

What “Clone Custom Dimensions” does:

It replicates the Blueprint’s CDs in the Destination Sites, using the same Scope, Slot, Name, and other settings (e.g., extraction rules).
If a CD already exists in the Destination, it is left untouched. So this function only creates new CDs, it does not change existing ones! For editing existing CDs, see below.
If a CD with the same Slot and ID already exists in the Destination Site, but has a different Name, the Piwik Pro Manager will stop and not do anything. Likewise, if it sees any mismatch in the Destination Site in terms of Slots and IDs (e.g. CD with ID 3 in Blueprint uses Session Slot 1, but in Destination it uses Session Slot 2), it will also abort and not change anything.

After about a minute (usually less), you should receive a success message in the Status bar:

Now, run Custom Dimensions -> Refresh Custom Dimensions.

After some seconds, you should see that all Sites now share the same Custom Dimensions settings:

Whenever you create a new Custom Dimension in your Blueprint Site in the interface, run “Clone Custom Dimensions” again so your Sites are always in sync. But you never need to edit anything in the Destination Sites anymore from the Piwik Pro interface. That’s what the following functions are for:

Edit Custom Dimensions in Bulk and Sync the changes across Sites

But what if you want to edit a Custom Dimension and then replicate that change in all Destination Sites?

You can edit the Custom Dimension in the Blueprint Site of the Piwik Pro interface (recommended if you change URL extraction rules) and then replicate (“sync”) the changes across Sites with Piwik Pro Manager, or you can directly edit & sync everything from Piwik Pro Manager. If you only need to change the name or the “active/inactive” status or the case sensitivity setting, you should do that directly in Piwik Pro Manager, as it saves you one step.

Simply do your edit in the sheet directly. E.g., here, I added “- new name” to CD8 and CD10. The whole row now also turns yellow and the “EDIT” column should read “edit”. This means: Once you confirm the Edits to Piwik Pro by selecting “Custom Dimensions -> Edit Custom Dimensions”, Piwik Pro Manager will edit these 2 dimensions accordingly.

If you change your mind, simply change “edit” to “empty” again (go to the “edit” cell and press Delete).

But we not only want to edit the Custom Dimension in our Blueprint Site, we also want to edit it in all the Destination Sites.

While you could just do the same edits further up or down in your “CustomDimensions” tab in the other Sites and then run “Custom Dimensions → Edit Custom Dimensions”, there is a more elegant way of doing that: The Sync! The idea is that you should only ever be editing your Blueprint Site.

In the “SYNC IN” column for any of your Blueprint’s Custom Dimensions, select the Destination Sites you want to sync to:

Then copy the value to all the other Custom Dimensions of your Blueprint Site. Your “CustomDimensions” tab should now look like this:

Now, run Edit & Sync Custom Dimensions:

After the synching has completed, you see that:

not only was the name of CD8 and 10 changed to contain “- new name” in the Blueprint Site (www.dim28.ch),
that renaming was also done in the 2 Destination Sites (Lukas Testing 2 and 3):

If you have done the Blueprint Edits in the Piwik Pro interface and simply want to sync, run Custom Dimensions -> Sync Custom Dimensions.

You can reset the yellow color in the rows you edited and the “edit” in the EDIT column now by running “Clear Edit Column”.

Summary

You only work (create, edit) in the Blueprint Site.
When creating new Custom Dimensions, create them in the Piwik Pro interface in the Blueprint Site, then go to Piwik Pro Manager and run Sites -> Clone Custom Dimensions to replicate the new CDs in the Destination Sites.
When editing Custom Dimensions, use Custom Dimensions -> Edit and Sync to make sure your edits are replicated in all Destination Sites.