Skip to content
  • Home
  • University
  • Developers
  • API
  • Releases
  • Status
  • Home
  • University
  • Developers
  • API
  • Releases
  • Status
Home Administration Data Governance Categories & Naming Conventions
Getting Started Installation Administration Define & Analyze Analysis Examples Heap Plays Success Guides Integrations Heap Connect Data Privacy

Read in Order

  1. Data Governance: Overview
  2. Categories & Naming Conventions
  3. Definition Verification
  4. Event Repair Flow
  5. Dataset Cleanup
  6. Definition History
  7. Managing Events, Segments, Properties, & Reports
  8. Ongoing Maintenance

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

Categories & Naming Conventions

In this article you'll learn:

  • How to create, manage, and remove categories
  • Recommended naming conventions for events, segments, and reports
  • How to enable and customize a naming convention for events (Admins & Architects only)
  • What the user experience looks like when using the naming convention after it's been enabled
View instructions for: 

You can use categories to organize your events, segments, properties, and reports, which makes it easier for your team to find what they need in Heap.

Managing Categories

You can only create new categories while saving or editing a report, event, or segment. Check the steps below for complete steps on how to create a category while creating or updating a report, event, or segment.

Creating Report Categories

When creating a new report, on the Save as Report pop-up, simply type the name of the new Category into the ‘Select category’ box.

The 'save as new report' pop-up with the category name 'app - reads docs' added

To learn more about creating and managing reports, see our article on Reports.

Creating Event Categories

You can create new events in the Event Visualizer or from the Events tab in your Heap dashboard.

From the Event Visualizer

When creating a new event in the Event Visualizer, you can add a new event category by simply typing the new category name in the categories field while creating the event.

An event being created in the Event Visualizer with the name 'click login' and category 'app - login'

From the Events tab

You can also create a new event category while creating an event on the events tab. Simply type the new category into the categories field while creating the event.

The category 'Chrome Users' being added to an 'EV Chrome Users' event

Once the event is saved, the new category will be available in your Heap dashboard.

For more information on and best practices for defining events, see Events.

Creating Segment Categories

To create a new segment category from the Segments page, simply type the new category into the categories field while creating the segment.

The category '2019' being added to a 'New Users 2019' event

To learn more about managing segments, see Segments.

Updating Categories / Moving Things Between Categories

To change the category of an existing report, event, or segment, navigate to the page it’s listed on, click on it to open up the details, then click on it’s current category name as listed at the top of the page. A drop-down will appear where you can select a different category.

The 'App' category being added to the 'View - Updates Page' event

Move Multiple Things Between Categories At Once

You can also move multiple reports, events, or segments into a category at once. From the Reports page, the Define > Events page, or the Define > Segments page, open the category of the report, event, or segment, click the checkbox next to the item, then click the move category icon next to “x (reports / events / segments) selected”.

Removing Categories

The only way to remove a category in Heap is to remove all of the reports, events, or segments within that category. Read the section below for steps to do this.

Removing Reports, Events, or Segments from a Category

To remove a report, event, or segment from a category, navigate to the page it’s listed on, click on it to open up the details, click on its current category name as listed at the top of the page, then update the category to ‘uncategorized’.

The 'New Users 2019' event being moved from '2019' to 'Uncategorized'

The report, event, or segment will return to being uncategorized, and will appear in the ‘Uncategorized’ category on that page.

Known Limitations

You cannot batch categorize in Heap – please reach out to support@heap.io if you have a large amount of definitions that you need migrated into categories and we’ll help you out!

Managing Naming Conventions

Naming Conventions is only available for customers on the Business plan. To upgrade, contact your Customer Success Manager or sales@heap.io.

Naming Conventions lets Admins and Architects establish a consistent naming convention for new events. This allows you to keep your growing dataset organized by enforcing an accurate naming convention and makes it faster and easier for team members to find the exact event they need.

When the naming convention is active, team members creating shared events will have to follow the naming convention set up in their account. For example, if you set up a Location – Action – Object naming convention, then the event name field will be completed like this:

The title 'Website - Click - Sign up' being added to an event per the naming convention

Set Up Naming Conventions

Before we jump in, here are a couple of important things to know about how naming conventions work:

  • Naming conventions are applied per project: to apply the same naming convention across multiple projects, you will need to manually update this setting for each project.
  • Naming conventions are not retroactive: events created prior to your naming convention being set up will need to be manually updated to match the naming convention. This also applies when the naming convention is updated; those updates will not be applied retroactively.
  • Naming conventions will not apply when an event is being renamed: the structure is only enforced when an event is being named for the first time.

Admins and Architects can enable and disable the naming conventions feature by navigating to Account > Manage > Data Governance. Click the Set Up button to get started.

The Data Governance page with an arrow pointing to the 'Set Up' button for event naming conventions

You’ll be prompted to configure the prefixes, which are the building blocks of your names, for your naming convention. The default (recommended) approach is to use a Location – Action convention.

The 'Configure Prefixes' section of the naming conventions setup flow with 'Location - Action' defined

When you click on the elements in the text field (in this case, Location or Action), you’ll be prompted to define a list of values for this prefix. Following our example, for the Location prefix, we may define website (our marketing site), app (in-app pages), and help center (our documentation hub) values for Location.

The 'Edit Values' drop-down for the Location prefix with 'Website', 'Homepage', and 'Help Center' added as values

For Action, we’ll follow Heap’s event property types: view, click, submit, and change.

The 'Edit Values' drop-down for the Action prefix with 'View', 'Click', 'Submit' and 'Change' added as values

Click the + button to add an additional prefix. After the third prefix, you’ll be able to populate the rest of the event description when creating it.

To allow team members to enter unique values for any given prefix, we can update their role to grant them the ability to add new values. To grant team members the ability to add new values, navigate to Account > Manage > Roles, select the role you wish to provide these permissions for, and check the box next to Add New Values to Naming Conventions.

The definitions section of the role details page with 'Add New Values to Naming Conventions' highlighted

Once the new naming convention is set up, it will apply to all new events created via the Definitions page in this project. This allows you to establish different naming conventions for each of your projects. Review the next section to see what this looks like for team members.

Naming conventions cannot be applied to events retroactively to events that were created before the naming convention was set up.

Using Naming Conventions 

After your naming convention has been set up, when team members are creating new shared events from the New Definitions drop-down on the Definitions page, they will only be able to use the defined naming convention. If permission has been granted, they can also add values to certain prefixes, such as the Object prefix below.

The name 'Website - Click - Signup' being added to a new event using the naming convention feature

This naming convention will not apply to personal events, though users will see a prompt to structure their personal event like a shared event.

A personal event with the title 'My Personal Event' which does not follow the naming convention feature

This naming convention will only apply to events created via the Events page. Events created via Live View and the Users View will not have this naming convention enforced. Support for the Event Visualizer is coming soon!

Recommended Naming Conventions for Categories

Categories and naming conventions work best when used together, which is we cover both in one guide! Below we’ve provided a set of recommendations for using these effectively to manage your dataset.

Events

The category name for your events should be based off your site’s architecture. Depending on the size of your application, a category should be either a product, feature or page, and the event name should be the action.

For example:

Category: Cart | Event: Submit Purchase Form
Category: Dashboard – Account Settings | Event: Click Edit Profile

Segments

Within Heap, you can segment users by their properties, such as geographic location, as well as by their behavioral activity, such as the number of orders. A segment’s category name should be based on the type of properties or actions used to define each cohort of users. Additionally, you may choose to group segments that correspond with key metrics (e.g. DAUs) or specific business units.

For example:

Attribution Channels

Category: Attribution | Segment: Social Traffic
Category: Attribution | Segment: Direct Traffic
Category: Attribution | Segment: Organic Search Traffic

Key Metrics

Category: KPI | Segment: MAU
Category: KPI | Segment: DAU

Activity (Should be in reference to the module)

Category: Blog | Segment: Blog readers
Category: Checkout | Segment: Frequent Purchasers
Category: Checkout | Segment: Added to cart → did not complete order

Teams
Category: Sales | Segment: Bill’s Open Opportunities
Category: Customer Success | Segment: Carly’s Active Accounts

Reports

Whenever you’re performing analysis in Heap, you’re asking specific questions about your business, such as: What is my conversion rate? How many people are using this feature?

We recommend that all of your reports adhere to a naming convention based around these business questions to help inform teammates the question you’re trying to answer in Heap.

The report’s category should reflect the subject of the report, which can be based on the type of the analysis you’re performing (Attribution), the portion of the application you’re analyzing (Sign Up) or the team that the report is associated with (Customer Success).

For Example:

Category: Attribution | Question: What are the top 10 referrers?
Category: Sign Up | Question: Where do users drop off in the sign up flow?
Category: Customer Success | Question: When should we re-engage with customers?

For more best practices and an example of how Heap uses naming conventions, see Step 4: Establish Naming Conventions.

Was this article helpful?

Yes No

Thank you for your feedback!

Last updated April 19, 2020.

categoriesevent categoriesevent naming conventionsnaming conventionsproperty categoriesreport categoriessegment categoriesusing categories
  • Blog
  • Partners
  • Security
  • Terms
  • About
  • Careers
  • Privacy
  • Contact Us

© 2021 Heap, Inc.