Customer-Specific Variables

A customer entity is an object representing a customer at any level of the customer hierarchy. Customer entities can be referenced as a variable in:

• Dataset queries
• Text components
• Chart titles
• Goal lines
• Progress goal totals

Customer entity specific variables that are created on the Customers page or via the API can be referenced. These variables are all automatically set based on the customer entity viewing the data.

​

Archetype Variables

In order to filter down data to a specific customer entity, a few variables are provided depending on where the customer exists within the hierarchy. We call these archetype variables, and they must be defined in order to be used in a query. If an archetype variable is referenced in a query and is not defined, the data panel will error out.

By default, your team will have two hierarchy levels. The top level will be named Customer and the bottom level will be named User. You will receive archetype variables that correspond to these hierarchy level names, and they are detailed in the section below. You can view and change the hierarchy level and parent configuration for each customer entity on the Customers page. You can also view customer entity archetype variables on the Customers page.

If you’d like a different hierarchy setup or archetype variable configuration than the default, please reach out to customer support.

​

Default Archetype Variables

If the customer entity belongs to the top-level of the hierarchy (Customer level):

• customer_id : This is the given provided_id for this customer entity when you create a customer.

• customer_name : This is the name provided for this customer entity when the customer is created.

If the customer entity belongs to the bottom-level of the hierarchy (User level):

• user_id : This is the given provided_id for this customer entity.

• user_name : This is the name provided for this customer entity.

• [inherited] customer_id : If this customer entity has a parent set, this field will be inherited from its parent. So, it will be the provided_id of the parent customer entity. If this customer entity does not have a parent, customer_id will be null, and you will not be able to use it in a query. This means your data panel will error out.

• [inherited] customer_name : If this customer entity has a parent set, this field will be inherited from its parent. So, it will be the name of the parent customer entity. If this customer entity does not have a parent, customer_name will be null, and you will not be able to use it in a query. This means your data panel will error out.

​

Custom Properties

In addition to the archetype variables, you may also add your own, custom properties on the Customers page. When setting up your own properties, you may not overwrite any of the archetype variables.

Customer entities at any hierarchy level will have access to:

• properties.* : All variables passed in the properties object when the customer entity is created are accessed through this format. So for example if you have a key in the properties object called filter_value then you can access that value by using properties.filter_value. This will include any properties a customer entity has inherited from a set parent. You can see which properties have been inherited versus which have been set on the Customers page when editing a customer entity.

​

Summary Table

Here is a summary of which variables are available for a customer entity at each hierarchy level with the default archetype configuration:

To learn more about how to set these variables when creating the customers, reference our customer API docs here.