Models and Fields
You can think of Planhat as having 3 types of model, with some subtypes:
Business Models
Opinionated Models
Flexible Models
Content Models
Other
Opinionated models
Created with a particular purpose in mind, and have tailored system fields and processes to support this. An example of this is the License model, which tracks subscription data, and has custom functionality for auto-renewals and forecasting.
Flexible models
Often regarded as “extra” models to support the customer’s internal data structure. Some support Time Series data, and are often used to track product usage and similar important event-based information. Others do not, and are therefore often used simply to expand the data structure, sometimes to facilitate integrations. All Business Models can be renamed.
Content models
Come in many forms. Workflow templates are templatised workflows, which in turn serve to group tasks and email sequences. Global Filters are rules-based collections of records, often used to trigger automations or notifications (e.g. “when a Company enters churn risk filter, send a notification to the Company owner”).
“Other”
comprises various system models, or otherwise “behind the scenes” models that need not be described in detail here. Also in this category, you could include the “User” model, representing the individual person using the app.
You can think of Planhat as having 3 types of model, with some subtypes:
Business Models
Opinionated Models
Flexible Models
Content Models
Other
Opinionated models
Created with a particular purpose in mind, and have tailored system fields and processes to support this. An example of this is the License model, which tracks subscription data, and has custom functionality for auto-renewals and forecasting.
Flexible models
Often regarded as “extra” models to support the customer’s internal data structure. Some support Time Series data, and are often used to track product usage and similar important event-based information. Others do not, and are therefore often used simply to expand the data structure, sometimes to facilitate integrations. All Business Models can be renamed.
Content models
Come in many forms. Workflow templates are templatised workflows, which in turn serve to group tasks and email sequences. Global Filters are rules-based collections of records, often used to trigger automations or notifications (e.g. “when a Company enters churn risk filter, send a notification to the Company owner”).
“Other”
comprises various system models, or otherwise “behind the scenes” models that need not be described in detail here. Also in this category, you could include the “User” model, representing the individual person using the app.
You can think of Planhat as having 3 types of model, with some subtypes:
Business Models
Opinionated Models
Flexible Models
Content Models
Other
Opinionated models
Created with a particular purpose in mind, and have tailored system fields and processes to support this. An example of this is the License model, which tracks subscription data, and has custom functionality for auto-renewals and forecasting.
Flexible models
Often regarded as “extra” models to support the customer’s internal data structure. Some support Time Series data, and are often used to track product usage and similar important event-based information. Others do not, and are therefore often used simply to expand the data structure, sometimes to facilitate integrations. All Business Models can be renamed.
Content models
Come in many forms. Workflow templates are templatised workflows, which in turn serve to group tasks and email sequences. Global Filters are rules-based collections of records, often used to trigger automations or notifications (e.g. “when a Company enters churn risk filter, send a notification to the Company owner”).
“Other”
comprises various system models, or otherwise “behind the scenes” models that need not be described in detail here. Also in this category, you could include the “User” model, representing the individual person using the app.
A Deeper look at the Business Models
Opinionated Models
These are models created for a distinct purpose, with special features or system fields available to them. Below you will first find a general list of the Opinionated Models, followed by a deeper dive into a selection of models and their particular logic.
To provide some examples of how these models are unique, and “opinionated”:
Licenses represent subscriptions purchased by the customer, and can be open-ended or fixed term, and can also be set to auto-renew within a specified notice period. Licenses are also crucial inputs to a lot of system revenue reports.
Endusers, of course, represent contacts, and are linked to conversations and tasks along with the Company. They can be linked to User Activities (Time Series data) to track things like product usage.
Tasks and Workflows: Tasks have a status, and a done date. Workflows can be sequences of Tasks, but also of Emails, and can be set up to be manually completed (or sent, in the case of emails), or automated.
Conversations: Notes and custom conversations can be logged manually in the app, or automatically as a result of tasks being completed.
Emails, Tickets, and Chats are all internal collections generated by integrations, which are displayed as threads on the Conversation model. For example, if you exchange multiple emails with an enduser, each individual email is stored as a thread on a single conversation record of type email (with the exception of Marketing emails). Email syncing logic has some peculiarities and can be studied in more detail here.
Tickets and Chats work in a similar way, with Tickets being created by certain support tool integrations, and Chats being created by the Intercom integration.
Companies are at the centre of the data structure. In short, almost all data ultimately relates to the Company model. Be it emails shared between multiple endusers and team members, but displayed in the Company Profile, or Assets which represent products sold to the Company, with usage data stored as time series data on the Asset. All of this data has a relationship to the Company.
Below are listed some concepts or features available (uniquely, for the most part) on the Company model:
Health Profiles. This is a central concept, allowing you to calculate a score from 0-10 based on custom criteria, evaluating the strength of a Company’s status as your customer. The Score’s development over time is tracked as Time Series, mentioned in more detail further down. Read more about Health Scores here.
Group structures. The Company model has an orgPath allowing companies to relate to each other in a hierarchy. This is to reflect real-world relationships, where different countries, or products, or other segments, are technically separate legal entities from the parent organisation. Read more about group structures here.
Owners and Portfolio Permissions. Fields on the Company level can denote the relationship between the Company and the User, which in turn can control data permissions - mentioned in more detail here.
Revenue Calculations. The Company model aggregates revenue data from the License model, calculating the current amount of active ARR for the Company, as well as the accumulated amount, and other data. Furthermore, Company and License data is aggregated in system revenue reports, to calculate Net Revenue Retention and other metrics. Read more about revenue reports here.
Portals. The Planhat environment can be share with customers who don’t have a Planhat license. they are created as external users, and have roles and permissions of their own. Following from this, they can access data relating to their Company in Planhat. Read more about portals here.
Calculated Metrics, User Activities and Custom Metrics. The Company model supports all of these concepts, along with a handful of other models (Enduser, Asset, Project).
There are many other things that are particular to the Company model. Read more here.
Flexible Models
A number of models are available (depending on the package you have purchased) with a less intentional data structure:
Assets and Projects
These are two models which support user activities, custom metrics, calculated metrics, as well as custom fields. They relate to the Company model, and there can be multiple records per Company. The intention is to provide flexible models, which are often renamed, to represent data structures particular to the customer. The default names represent two frequent use cases. The “Asset” name, for example, was chosen because these models often represent individual products sold to a customer, with associated user activities and custom metrics tracking product usage and aggregated time series data, respectively. You can read more about this here.
Campaigns, Objectives, and Workspaces
These models are the same as the above, with the exception that they do not support time series data. While the above, therefore, might be used to analyse the development over time of product usage, or perhaps marketing projects, these models are more “flat”, and are often renamed and used to store additional data models particular to the customer. Sometimes customers with a complex data structure in Salesforce, Hubspot, or in a Data Warehouse, utilise these models. Read more here.
A Deeper look at the Business Models
Opinionated Models
These are models created for a distinct purpose, with special features or system fields available to them. Below you will first find a general list of the Opinionated Models, followed by a deeper dive into a selection of models and their particular logic.
To provide some examples of how these models are unique, and “opinionated”:
Licenses represent subscriptions purchased by the customer, and can be open-ended or fixed term, and can also be set to auto-renew within a specified notice period. Licenses are also crucial inputs to a lot of system revenue reports.
Endusers, of course, represent contacts, and are linked to conversations and tasks along with the Company. They can be linked to User Activities (Time Series data) to track things like product usage.
Tasks and Workflows: Tasks have a status, and a done date. Workflows can be sequences of Tasks, but also of Emails, and can be set up to be manually completed (or sent, in the case of emails), or automated.
Conversations: Notes and custom conversations can be logged manually in the app, or automatically as a result of tasks being completed.
Emails, Tickets, and Chats are all internal collections generated by integrations, which are displayed as threads on the Conversation model. For example, if you exchange multiple emails with an enduser, each individual email is stored as a thread on a single conversation record of type email (with the exception of Marketing emails). Email syncing logic has some peculiarities and can be studied in more detail here.
Tickets and Chats work in a similar way, with Tickets being created by certain support tool integrations, and Chats being created by the Intercom integration.
Companies are at the centre of the data structure. In short, almost all data ultimately relates to the Company model. Be it emails shared between multiple endusers and team members, but displayed in the Company Profile, or Assets which represent products sold to the Company, with usage data stored as time series data on the Asset. All of this data has a relationship to the Company.
Below are listed some concepts or features available (uniquely, for the most part) on the Company model:
Health Profiles. This is a central concept, allowing you to calculate a score from 0-10 based on custom criteria, evaluating the strength of a Company’s status as your customer. The Score’s development over time is tracked as Time Series, mentioned in more detail further down. Read more about Health Scores here.
Group structures. The Company model has an orgPath allowing companies to relate to each other in a hierarchy. This is to reflect real-world relationships, where different countries, or products, or other segments, are technically separate legal entities from the parent organisation. Read more about group structures here.
Owners and Portfolio Permissions. Fields on the Company level can denote the relationship between the Company and the User, which in turn can control data permissions - mentioned in more detail here.
Revenue Calculations. The Company model aggregates revenue data from the License model, calculating the current amount of active ARR for the Company, as well as the accumulated amount, and other data. Furthermore, Company and License data is aggregated in system revenue reports, to calculate Net Revenue Retention and other metrics. Read more about revenue reports here.
Portals. The Planhat environment can be share with customers who don’t have a Planhat license. they are created as external users, and have roles and permissions of their own. Following from this, they can access data relating to their Company in Planhat. Read more about portals here.
Calculated Metrics, User Activities and Custom Metrics. The Company model supports all of these concepts, along with a handful of other models (Enduser, Asset, Project).
There are many other things that are particular to the Company model. Read more here.
Flexible Models
A number of models are available (depending on the package you have purchased) with a less intentional data structure:
Assets and Projects
These are two models which support user activities, custom metrics, calculated metrics, as well as custom fields. They relate to the Company model, and there can be multiple records per Company. The intention is to provide flexible models, which are often renamed, to represent data structures particular to the customer. The default names represent two frequent use cases. The “Asset” name, for example, was chosen because these models often represent individual products sold to a customer, with associated user activities and custom metrics tracking product usage and aggregated time series data, respectively. You can read more about this here.
Campaigns, Objectives, and Workspaces
These models are the same as the above, with the exception that they do not support time series data. While the above, therefore, might be used to analyse the development over time of product usage, or perhaps marketing projects, these models are more “flat”, and are often renamed and used to store additional data models particular to the customer. Sometimes customers with a complex data structure in Salesforce, Hubspot, or in a Data Warehouse, utilise these models. Read more here.
A Deeper look at the Business Models
Opinionated Models
These are models created for a distinct purpose, with special features or system fields available to them. Below you will first find a general list of the Opinionated Models, followed by a deeper dive into a selection of models and their particular logic.
To provide some examples of how these models are unique, and “opinionated”:
Licenses represent subscriptions purchased by the customer, and can be open-ended or fixed term, and can also be set to auto-renew within a specified notice period. Licenses are also crucial inputs to a lot of system revenue reports.
Endusers, of course, represent contacts, and are linked to conversations and tasks along with the Company. They can be linked to User Activities (Time Series data) to track things like product usage.
Tasks and Workflows: Tasks have a status, and a done date. Workflows can be sequences of Tasks, but also of Emails, and can be set up to be manually completed (or sent, in the case of emails), or automated.
Conversations: Notes and custom conversations can be logged manually in the app, or automatically as a result of tasks being completed.
Emails, Tickets, and Chats are all internal collections generated by integrations, which are displayed as threads on the Conversation model. For example, if you exchange multiple emails with an enduser, each individual email is stored as a thread on a single conversation record of type email (with the exception of Marketing emails). Email syncing logic has some peculiarities and can be studied in more detail here.
Tickets and Chats work in a similar way, with Tickets being created by certain support tool integrations, and Chats being created by the Intercom integration.
Companies are at the centre of the data structure. In short, almost all data ultimately relates to the Company model. Be it emails shared between multiple endusers and team members, but displayed in the Company Profile, or Assets which represent products sold to the Company, with usage data stored as time series data on the Asset. All of this data has a relationship to the Company.
Below are listed some concepts or features available (uniquely, for the most part) on the Company model:
Health Profiles. This is a central concept, allowing you to calculate a score from 0-10 based on custom criteria, evaluating the strength of a Company’s status as your customer. The Score’s development over time is tracked as Time Series, mentioned in more detail further down. Read more about Health Scores here.
Group structures. The Company model has an orgPath allowing companies to relate to each other in a hierarchy. This is to reflect real-world relationships, where different countries, or products, or other segments, are technically separate legal entities from the parent organisation. Read more about group structures here.
Owners and Portfolio Permissions. Fields on the Company level can denote the relationship between the Company and the User, which in turn can control data permissions - mentioned in more detail here.
Revenue Calculations. The Company model aggregates revenue data from the License model, calculating the current amount of active ARR for the Company, as well as the accumulated amount, and other data. Furthermore, Company and License data is aggregated in system revenue reports, to calculate Net Revenue Retention and other metrics. Read more about revenue reports here.
Portals. The Planhat environment can be share with customers who don’t have a Planhat license. they are created as external users, and have roles and permissions of their own. Following from this, they can access data relating to their Company in Planhat. Read more about portals here.
Calculated Metrics, User Activities and Custom Metrics. The Company model supports all of these concepts, along with a handful of other models (Enduser, Asset, Project).
There are many other things that are particular to the Company model. Read more here.
Flexible Models
A number of models are available (depending on the package you have purchased) with a less intentional data structure:
Assets and Projects
These are two models which support user activities, custom metrics, calculated metrics, as well as custom fields. They relate to the Company model, and there can be multiple records per Company. The intention is to provide flexible models, which are often renamed, to represent data structures particular to the customer. The default names represent two frequent use cases. The “Asset” name, for example, was chosen because these models often represent individual products sold to a customer, with associated user activities and custom metrics tracking product usage and aggregated time series data, respectively. You can read more about this here.
Campaigns, Objectives, and Workspaces
These models are the same as the above, with the exception that they do not support time series data. While the above, therefore, might be used to analyse the development over time of product usage, or perhaps marketing projects, these models are more “flat”, and are often renamed and used to store additional data models particular to the customer. Sometimes customers with a complex data structure in Salesforce, Hubspot, or in a Data Warehouse, utilise these models. Read more here.
Fields
Each Business Model has some system fields as well as supporting custom fields. As mentioned, the “opinionated” models have a number of system fields intended for a particular use case, e.g. the ARR field on the License model, or the email field on the Enduser model. The more “flexible” models generally have fewer system fields, as they are intended to be populated with the fields and data particular to the customer’s business.
Planhat supports the following field types:
Text
Rich text
Rating
Number
Toggle
List
Multi-pick list
Team member
Team members
Enduser
Endusers
URL
Phone
Email
Day
Date
Date Time
Fields
Each Business Model has some system fields as well as supporting custom fields. As mentioned, the “opinionated” models have a number of system fields intended for a particular use case, e.g. the ARR field on the License model, or the email field on the Enduser model. The more “flexible” models generally have fewer system fields, as they are intended to be populated with the fields and data particular to the customer’s business.
Planhat supports the following field types:
Text
Rich text
Rating
Number
Toggle
List
Multi-pick list
Team member
Team members
Enduser
Endusers
URL
Phone
Email
Day
Date
Date Time
Fields
Each Business Model has some system fields as well as supporting custom fields. As mentioned, the “opinionated” models have a number of system fields intended for a particular use case, e.g. the ARR field on the License model, or the email field on the Enduser model. The more “flexible” models generally have fewer system fields, as they are intended to be populated with the fields and data particular to the customer’s business.
Planhat supports the following field types:
Text
Rich text
Rating
Number
Toggle
List
Multi-pick list
Team member
Team members
Enduser
Endusers
URL
Phone
Email
Day
Date
Date Time
Data Standards
In order to maintain consistency and make data the most reliable as possible, the API relies on a set of standards and rules to normalize data it takes in.
Some data a client sends can either be invalid or transformed to be accommodated and stored in a better shape.
All time-related data will be stored in UTC (offset 0) and API can tolerate non UTC values when handling Date Time fields but they'll be represented in UTC time.
We provide three data types to work with dates:
Day
Date
Date Time
Day
When a field has day type API expect it to be a number also known as UNIX Epoch, the value of it should be: the amount of days that have passed since Jan 1, 1970. For example, 19508 would represent the date May 31, 2023. This type of data can't tolerate time.
API can receive and handle ISO 8601 strings with or without time and timezone for day fields, although the end result will always be the number of days as explained above.
The following date strings are valid and will be converted correctly to the epoch representation.
Input | Result |
|---|---|
2023-05-01T00:00:00.000Z | 19478 |
2023-05-02 | 19479 |
2023-05-03T05:00:00.000+02:00 | 19480 |
custom |
Date
Date type fields are stored as ISO 8601 date strings with zeroed time (T00:00.000Z). For example: 2023-05-01T00:00:00.000Z. When a time part is provided for this type of field it will be ignored.
The following date strings are valid and will have time zeroed when it's the case:
Input | Result |
|---|---|
2023-05-31T15:21:19.144Z | 2023-05-31T00:00:00.000Z |
2023-05-31T15:21:19.000+02:00 | 2023-05-31T00:00:00.000Z |
2023-05-31 | 2023-05-31T00:00:00.000Z |
Date Time
Date Time fields are stored as ISO 8601 date strings with time in UTC. For example: 2023-05-01T21:53:22.634Z will be saved exactly like that. When timezone is provided we save the UTC representation of it
The following date strings are valid and will have time zeroed when it's the case:
Header 1 | Header 2 |
|---|---|
2023-05-31T15:21:19.144Z | 2023-05-31T15:21:19.144Z |
2023-05-31T15:21:19.000+02:00 | 2023-05-31T13:21:19.000Z |
2023-05-31 | 2023-05-31T00:00:00.000Z |
Data Standards
In order to maintain consistency and make data the most reliable as possible, the API relies on a set of standards and rules to normalize data it takes in.
Some data a client sends can either be invalid or transformed to be accommodated and stored in a better shape.
All time-related data will be stored in UTC (offset 0) and API can tolerate non UTC values when handling Date Time fields but they'll be represented in UTC time.
We provide three data types to work with dates:
Day
Date
Date Time
Day
When a field has day type API expect it to be a number also known as UNIX Epoch, the value of it should be: the amount of days that have passed since Jan 1, 1970. For example, 19508 would represent the date May 31, 2023. This type of data can't tolerate time.
API can receive and handle ISO 8601 strings with or without time and timezone for day fields, although the end result will always be the number of days as explained above.
The following date strings are valid and will be converted correctly to the epoch representation.
Input | Result |
|---|---|
2023-05-01T00:00:00.000Z | 19478 |
2023-05-02 | 19479 |
2023-05-03T05:00:00.000+02:00 | 19480 |
custom |
Date
Date type fields are stored as ISO 8601 date strings with zeroed time (T00:00.000Z). For example: 2023-05-01T00:00:00.000Z. When a time part is provided for this type of field it will be ignored.
The following date strings are valid and will have time zeroed when it's the case:
Input | Result |
|---|---|
2023-05-31T15:21:19.144Z | 2023-05-31T00:00:00.000Z |
2023-05-31T15:21:19.000+02:00 | 2023-05-31T00:00:00.000Z |
2023-05-31 | 2023-05-31T00:00:00.000Z |
Date Time
Date Time fields are stored as ISO 8601 date strings with time in UTC. For example: 2023-05-01T21:53:22.634Z will be saved exactly like that. When timezone is provided we save the UTC representation of it
The following date strings are valid and will have time zeroed when it's the case:
Header 1 | Header 2 |
|---|---|
2023-05-31T15:21:19.144Z | 2023-05-31T15:21:19.144Z |
2023-05-31T15:21:19.000+02:00 | 2023-05-31T13:21:19.000Z |
2023-05-31 | 2023-05-31T00:00:00.000Z |
Data Standards
In order to maintain consistency and make data the most reliable as possible, the API relies on a set of standards and rules to normalize data it takes in.
Some data a client sends can either be invalid or transformed to be accommodated and stored in a better shape.
All time-related data will be stored in UTC (offset 0) and API can tolerate non UTC values when handling Date Time fields but they'll be represented in UTC time.
We provide three data types to work with dates:
Day
Date
Date Time
Day
When a field has day type API expect it to be a number also known as UNIX Epoch, the value of it should be: the amount of days that have passed since Jan 1, 1970. For example, 19508 would represent the date May 31, 2023. This type of data can't tolerate time.
API can receive and handle ISO 8601 strings with or without time and timezone for day fields, although the end result will always be the number of days as explained above.
The following date strings are valid and will be converted correctly to the epoch representation.
Input | Result |
|---|---|
2023-05-01T00:00:00.000Z | 19478 |
2023-05-02 | 19479 |
2023-05-03T05:00:00.000+02:00 | 19480 |
custom |
Date
Date type fields are stored as ISO 8601 date strings with zeroed time (T00:00.000Z). For example: 2023-05-01T00:00:00.000Z. When a time part is provided for this type of field it will be ignored.
The following date strings are valid and will have time zeroed when it's the case:
Input | Result |
|---|---|
2023-05-31T15:21:19.144Z | 2023-05-31T00:00:00.000Z |
2023-05-31T15:21:19.000+02:00 | 2023-05-31T00:00:00.000Z |
2023-05-31 | 2023-05-31T00:00:00.000Z |
Date Time
Date Time fields are stored as ISO 8601 date strings with time in UTC. For example: 2023-05-01T21:53:22.634Z will be saved exactly like that. When timezone is provided we save the UTC representation of it
The following date strings are valid and will have time zeroed when it's the case:
Header 1 | Header 2 |
|---|---|
2023-05-31T15:21:19.144Z | 2023-05-31T15:21:19.144Z |
2023-05-31T15:21:19.000+02:00 | 2023-05-31T13:21:19.000Z |
2023-05-31 | 2023-05-31T00:00:00.000Z |