In this article:
Custom Account Dimensions
There are two options to update a custom dimension for your accounts:
1. Add a custom dimension to your account overview layout or a custom account view and directly edit the dimension values there.
First, you need to define your new custom account dimensions with a name and type in the “Dimensions” page in the Management Center, select "Custom account dimensions" from the drop-down menu and click "New Dimension" on the top right.
- Name – The name of the custom dimension as it will appear on the Natero platform.
- Description - An optional description of this custom account dimension
- Dimension Type – One of the following: Textual, Numeric or Date-based dimension.
To add a pick-list dimension, select “Textual dimension” type and enable the “Dropdown list” option.
You can also edit the picklist values for the below Natero native fields under the “Other picklists” option.
- Support priority
- Support type
- Interaction type
- User role
2. Using the Natero Account API or API upload feature to upload custom dimensions to accounts.
You can send custom account dimensions from your implementation using the Natero Account API or upload them using the API upload feature via the UI.
Note that when sending/uploading the custom dimensions, use the below names under the Accounts endpoint for each type so that the custom dimensions can be used properly in Natero rules and reports.
- Textual: custom_label_dimensions
- Numeric: custom_value_dimensions
- Date-based: custom_event_dimensions
Your data will then be processed immediately using your custom dimension definitions. We'll capture the names of the custom dimensions you send automatically in any account dimensions dropdown.
Custom Account Metrics
While custom dimensions can be defined and updated directly via the UI. Custom metrics need to be created and updated through the Natero Account API or using the API upload feature.
Since custom metrics are time series data, they need to be sent with timestamp information for each data point. Timestamps can be provided as either a number representing epoch milliseconds or as an ISO8601 timestamp. E.g.: 'YYYY-MM-DD HH:MM' or 'YYYY/MM/DD'. All timestamps are assumed to be in the UTC timezone.
Your data will then be processed immediately using your custom metric definitions. We'll capture the names of the custom metrics you send automatically in any account metrics dropdown.
Custom User Dimensions
There are two options to update a custom dimension for your users:
1. Using the “Contacts & Users” section in the Account Details page
First, you need to define your custom user dimensions with a name and type in the “Dimensions” page in the Management Center, select "Custom user dimensions" from the drop-down and click "New Dimension" on the top right.
- Name – The name of the custom dimension as it will appear on the Natero platform.
- Description - An optional description of this custom user dimension
- Dimension Type – One of the following: Textual, Numeric or Date-based dimension.
Then you can update custom dimension values at the Account Details, Contacts & Users page for each individual user.
2. Using the Natero Account API or API upload feature to populate custom dimensions to users.
You can send custom user dimensions to be associated with either CRM contacts or product users using the Natero Account API or upload them to the contacts or product users using the API upload feature via the UI.
Note that when sending/uploading the custom user dimensions, use the below names under either the Account product users or the Account contacts endpoint for each type so that the custom dimensions can be used properly in Natero rules and reports.
- Textual: custom_label_dimensions
- Numeric: custom_value_dimensions
- Date-based: custom_event_dimensions
Your data will then be processed immediately using your custom dimension definitions. We'll capture the names of the custom dimensions you send automatically in any user dimensions dropdown.
Limits and Caveats
1. Once a custom dimension or metric is created, you can only modify its name but not its type. Once the name is changed, you will need to start sending data with the new name and we'll update the name for all the old data.
2. Deletion of any custom dimensions or metrics is permanent and unrecoverable. Deleting a metric or dimension via the “Account Settings” page also deletes the data associated with that setting.
3. Value of custom dimensions and metrics will be stored as a "Double", allowing for fractional numbers.
4. There is a maximum number of characters (255 characters) allowed for string based dimensions. In other words, both the name and values of a specific dimension need to be within the maximum number of characters.
5. When naming the custom dimension and metric, each name needs to be globally unique.
6. When sending the custom dimension and metric, the name for the same dimension/metric needs to be consistent (exact match), otherwise it'll be captured as a separate custom dimension/metric.
7. If the value of a custom metric and/or value dimension does not exist for an account, we'll set it to be zero for that account. For accounts that do not have value for a custom text dimension, you can filter these accounts in the List Explorer by constructing a condition that says "Name of custom text dimension" "is not defined".
8. Natero currently supports both custom dimensions and metrics for accounts but only custom dimensions for users.
Learn more about reporting of the custom dimensions and metrics.