Skip to main content

Product & activity models

FunnelStory distinguishes several activity-shaped models. All describe something that happened at a point in time, usually tied to an account and often a user. They differ by semantic use in the product (for example product usage vs invitations vs generic events).

This page covers:

  1. Activity (generic)
  2. Product activity
  3. Product feature activity
  4. Invite

Shared concepts​

  • Model key: activity_id + account_id identify a row for activity, product activity, product feature activity, and non-invite activity types.
  • Invite uses user_id + account_id + invitee_email as its composite key (see below).
  • Each row produces Activity occurred (or invite-specific) timeline events when configured.
  • Prerequisites: Accounts model. Users model is required when your events are user-scoped and you map user_id.

For timestamp and JSON types, see the account field reference.

1. Activity (generic)​

Use the Activity model type when you have a single stream of in-product or application events and do not need the separate product vs product feature semantics.

Field reference​

PropertyTypeKey?Description
activity_idstringyesUnique id for the event.
account_idstringyesOwning account; must exist in the accounts model.
user_idstringno*User who performed the action, if applicable.
timestamptimestampnoWhen the event occurred.

*Required for a correct user association when the event is user-driven; omit only for account-level events.

2. Product activity​

Product activity captures usage inside your product (logins, actions, API calls, etc.). Use this when events represent general product engagement.

Field reference​

Same shape as generic Activity:

PropertyTypeKey?Description
activity_idstringyesUnique id for the event.
account_idstringyesOwning account.
user_idstringno*User associated with the event.
timestamptimestampnoEvent time.

Product feature activity​

Product feature activity uses the same required fields as product activity. Configure it when events should feed feature adoption metrics and reporting. Technically the mapping and query are the same shape; choose the model type that matches how FunnelStory should treat the stream.

3. Invite model​

The invite model tracks invitations: who was invited, by whom, to which account, and whether the invite was accepted. It is configured as its own model type (not as product activity), but is documented here alongside other user- and account-scoped events.

Model keys​

PropertyTypeKey?Description
invitee_emailstringyesEmail of the invited person.
user_idstringyesInviter (or primary actor) user id in your system.
account_idstringyesAccount context for the invite.

Default properties​

PropertyTypeDescription
acceptedbooleanWhether the invite was accepted.
created_attimestampWhen the invite was sent or created.

Activities​

Invite models drive Created invite and Updated invite style activities on timelines when rules are enabled.

Configure (query-based connections)​

  1. Ensure Accounts (and usually Users) are configured.
  2. Configuration → Data models → Add model and choose Activity, Product activity, Product feature activity, or Invite.
  3. Pick a connection (database, warehouse, HubSpot, Salesforce, Segment, Mixpanel, etc., depending on what your workspace supports).
  4. Write a query that returns one row per event (or invite) with stable ids.
  5. Map columns to properties, validate, quick test, save.
  6. Refresh and confirm events on an account timeline.

HubSpot and other CRM sources​

When HubSpot (or Salesforce) is your connection, you typically express the query using the connection’s native query format (for HubSpot, HS blocks in the query step—see Writing queries). Map HubSpot properties into the same FunnelStory property names as in the tables above.

Ensure contact or user identifiers align with your users model if you map user_id.

Segment, Mixpanel, Pendo​

These integrations support activity-shaped models per your workspace’s connection capabilities. Use Product activity or Product feature activity for in-product analytics streams, and map provider fields to activity_id, account_id, user_id, and timestamp (or equivalent) per your pipeline.