Summary
Custom models let you define your own data models in Planhat, alongside system models (Company, Enduser, License, and so on).
A custom model works like a system model: custom fields, associations to other models, permissions, Profiles, and can sync with external sources
This article covers creating a custom model and setting up its fields, associations, keyables, and profile.
A new model is hidden until you grant a role access to it - the most common setup snag, covered below.
Who is this article for?
Planhat builders/admins who set up the data model for their team (e.g. CS Ops).
Series
This article is part of a series on Custom Models:
Creating and managing custom models · create a model, add fields, set permissions, previews, and profiles ⬅️ You are here
Custom associations · associate records across models, *primary* associations, and many-to-many (junction models)
Salesforce integration for custom models · mirror a Salesforce object into a model
Custom keyables · matching unique records
Joined tables · show an associated model's field as a column
Article Contents
Introduction
Planhat includes a set of system models - Company, Enduser, Conversation, e.t.c - that fit most data needs. When your business has processes or structures those models don't cover (regions, partners, products, and the relationships between them), Custom Models let you represent them directly.
A Custom Model works just like a system model, with their own fields, associations to other models, permissions, profiles - and they connect to the rest of Planhat as first-class data, including integration sync, joined tables, formula fields, and dashboards.
This article covers how to create a custom model and set it up.
Create a Model and its Fields
Go to Data Model → Custom Models and create a new model. Give it an icon, name, plural name, and description (descriptions help both your team and AI agents understand what each model and field is for)
Add the custom fields you need.
Grant the relevant roles access to the model. A new custom model is not visible to anyone (including you) until a role is given access to it in settings.
ℹ️ Info:
New Custom Models are hidden from everyone until you grant a role access. If you can't see your model after creating it, this is why. Go to Data Model → [your model] → Permissions, grant your role access, then refresh.
Association Fields
An association is a field type that links a record to one record on another model. When you add an association field, select the target model and choose whether the association is Primary.
A primary association is the one that anchors a record to a Company. Custom model records don't belong to a Company directly - the primary association is what connects them, through its parent, up to one. That connection does two things: permissions flow from the Company down to the record (anyone who can see the Company can see the record), and every record must have a parent, so records can't end up orphaned. Each custom model can have only one primary association.
An association field points to a single record. To link to many records (many-to-one or many-to-many), use a junction model instead. See Custom associations.
Select "Association" as the field type
Select the Target model
Mark an association Primary when your record belongs to the model it links to — that model is its parent. Leave it non-primary when your record just references another model.
Custom Keyables
A keyable is a field that stores a unique ID, used to match records when syncing data. On system models, sourceId and externalId play this role; on custom models you create and name your own.
You need to define a keyable to sync a custom model with an external source such as Salesforce, BigQuery, or Snowflake. See Salesforce Integration for Custom Models.
Previews and Profiles
Set up previews and profiles for a custom model the same way as for any other model. In addition, you can show a custom model's records on the profile of the model it associates to (its "parent"), so related records appear directly on the parent's profile.
Set up a Custom Model's Profile:
Display related records on the Profile:
Naming Custom Fields in Formulas
Fields on a custom model aren't treated as "custom fields" the way they are on system models. In formulas, reference them by their field name directly — without the custom. prefix that system-model custom fields require.
Importing Records via Spreadsheet
You can populate a custom model's records by importing a spreadsheet, in the same way as other models. Select your custom model from the model dropdown.
Limits
The number of custom models a tenant can create depends on its plan.
Asset, Project, Workspace, Objective, and Campaign data models are treated as custom models and count toward your plan's limit.
Time-series data is only available for Company, End User, Asset and Project. It is not currently available for new Custom Models.