Before diving into the different models and data types available in Planhat, it’s worth understanding some core concepts that tie together the platform and models:

There are some other important concepts that are particular to certain models. These are mentioned further down - for example, Company group structures are described as part of the Company header under Business models, and some important email logic is mentioned under the Email header.

• Keys (planhatId, sourceId, externalId)

• Paths, permissions, and “links”

• Formulas and Validation

• Logs and Field History

There are a few different keys available to you:

PlanhatId is Planhat’s own UUID, system-generated, immutable.

Most models also support external keys: sourceId, and externalId, to facilitate integrating data from one or more sources. For models which support both, it’s worth noting that sourceId takes precedence over externalId, when both are provided in the payload.

Email can also be used as the key for Endusers. Endusers can be created with only an email, first name, last name, and companyId. They can also be updated using the email as the key. However, this requires the email to be unique in the tenant, something which is not enforced by Planhat across companies. You can read more about keys under the respective endpoints in the API docs.

• planhatId

• sourceId

• externalID

• email

Paths and CompanyIds

As mentioned, most models belong to Companies. There are two ways this is represented - with a companyId field on the model (legacy), or through a “path” object on the model (updated structure). For models that use a companyId field, the hierarchy is simple - a License, for instance, must belong to one and only one Company.

Paths are an endpoint used to represent the position of a record in relation to the Company, in the data hierarchy. For example, you might have a Workflow applied to an Enduser belonging to a Company: “Alphabet”. In this case, the path on the Workflow points first to the Enduser as the direct parent, and then to the Company as the ultimate parent.

Permissions

Company associations and Paths are an important part of Planhat’s permission structure. When setting permissions for a user, you assign roles, and these roles have different CRUD level access to Models and their fields, as well as binary access to certain processes and features in the app. Crucially, permission to access data can be filtered on the Company level, which in turn controls access to models beneath the Company. (Permissions are also assigned to Private Apps AKA Service Accounts). Read more about permissions here.

“Links”

Also known as “soft associations”, these are fields which permit a non-hierarchical, or “lateral” association between two models.

For example, when an email is synced into Planhat, there is a companyId, but there is also a Team Members field (API name: users) and an Involved Contacts field (API name: endusers). These fields respectively point to the PlanhatIds of the team members and endusers linked to the email. In this case, the key used to link the email to users and endusers, is the email addresses of involved Endusers.

Some models have system fields for “Owners” and “Co-owners”, pointing to the user model. The issue model also has a system field pointing to “Companies”, since this model can relate to more than one company. There are also custom fields available to create, of types:

You can read more about custom fields here.

• enduser

• endusers

• team member

• team members

There are many parts of Planhat where custom or system-encoded calculations take place. Some are mentioned elsewhere - for example, there is a separate collection exploring Automations in detail. Below, we will take a look at Filters, Field Rules, Formula Fields, and some System Calculations.

Filters

Filters, also known as Global Filters, are available on most models, and regularly calculate which records to include and exclude, based on custom-created conditions. These conditions can relate to data on the same model, but can also reference across models, via the Company. Read more about filters here.

Field Rules

Field Rules are custom rules, enforcing data validation. They are constructed with conditions referencing fields on the same record, and/or properties of the Actor interacting with the record. They can then enforce either the mandatory state, or locked state, of selected fields. For example, you could say that for users with role “CSM”, and Companies with status “customer”, it is mandatory to have a value for the field “Industry”. Importantly, it is possible to configure whether a Field Rule should be enforced for “All Actors” (Including API and Integration) or only Users. Read more about Field Rules here.

Formula Fields and Other Calculations

Formula Fields are custom fields which regularly run calculations. The formulas can reference other fields on the same record, but Formula Fields on the Company level can also aggregate data from nested models and records. Read more about Formula Fields here.

There are also a number of “system” calculated fields, where jobs ensure that data is aggregated and calculated on a regular basis. Some examples of this are Health Profiles, which give Companies scores based on custom criteria, and Company mrr and arr fields, which aggregate data from the license model. Both of these topics are mentioned in a bit more detail in the Business Models section, but can also be found in this article describing the Company model.

Planhat also has multiple ways of exploring historical events.

There is the Logs Explorer, a filterable and searchable list of events on all Business Models (e.g. Company, Enduser, Asset, Churn, et.c.), displaying the event, the type of change that happened, and the actor. This is described in more detail here.

Then there are logs for various system features - Automations have logs, as do some integrations, such as the Salesforce and Snowflake integrations. Private Apps also have logs.

Finally, there is Field History, a list similar to the Logs Explorer, but displaying a filtered and paginated list of events involving a particular field on a particular record. Read more here.