Skip to content

UTM tracking inventory

What it does

The UTM tracking inventory shows which UTM tracking combinations are defined in the Easy8 source code. It helps product owners and developers understand:

  • which product areas and user actions are tracked;
  • which plugin owns the tracking;
  • what a particular UTM combination is intended to measure;
  • which plugins currently have no detectable UTM tracking.

The inventory is not an analytics report. It does not show how often an action was used. It only lists tracking that the scanner finds in the source code.

Running the scanner

The modification_easysoftware plugin must be present because it holds the generated inventory used by the page. Run the scanner from the repository root:

ruby .opencode/scripts/generate_utm_inventory.rb

The scanner searches Ruby and frontend source files, collects the UTM campaign, content and term combinations it can detect, removes duplicates and updates the generated inventory file (plugins/easyproject/easy_plugins/modification_easysoftware/config/analytics/utm_tracking_inventory.generated.json, or the path in UTM_INVENTORY_PATH).

Review the diff after running it. Do not edit the generated JSON; fix the tracking source or the scanner instead.

If modification_easysoftware or its inventory target directory is not present, the command prints a warning and exits successfully without creating files.

Descriptions

Tracking declarations can include an optional plain-language description. Descriptions should explain the specific action and its entry point, for example:

// utm-inventory-description: Creates a product backlog item from the product backlog board action.

Use a description only when the surrounding code makes the tracked behavior reasonably clear. Generic helpers and dynamically assembled tracking may cover several different flows; in those cases, leaving the description empty is better than guessing.

The scanner supports these immediately preceding comment forms:

  • // utm-inventory-description: ... in JavaScript and TypeScript;
  • # utm-inventory-description: ... in Ruby;
  • <%# utm-inventory-description: ... %> in ERB views.

Viewing the inventory

Administrators can open /utm_tracking_inventory to view the generated inventory. The page provides filters for plugin, campaign, content, and term. Lower-level filter choices automatically follow the selected higher-level values.

Entries without a reliable source description show "Not available".

Scanner limitations

The scanner works from source code and can reliably include only values it can determine without running the application. Dynamic values, uncommon tracking patterns, and indirectly assembled parameters may be missing. Conversely, commented-out or unusually structured code can occasionally be detected incorrectly.

The inventory is an overview, not a guarantee of complete runtime coverage. When you add or change a UTM campaign, follow the UTM tracking standard and add a new utm_campaign to the EWA export whitelist, otherwise its usage is not exported as an EWA feature metric.