Working with Custom Fields

Custom Fields in m3ter allow you to store custom data in the form of number or string values against m3ter entities in a way that does not directly affect the normal working operation of the m3ter platform. Having this capability to store data in a free-hand fashion can prove very useful in helping you to meet the specific usage-based pricing and other operational business use cases you want to implement.

You can create Custom Fields for the following m3ter entities:

Organization
Product
Meter
Plan
Plan Template
Account
Account Plan
Aggregation
Compound Aggregation
Contract
Plan Group

However, you can exploit the values you store using Custom Fields in another, more directed, way by referencing them in your Derived Field and Compound Aggregation calculations. When you use Custom Fields for this purpose, and given the key role Derived Fields or Compound Aggregation can play in implementing usage-based pricing schema, they will then affect how the platform behaves. Referencing Custom Field values in your calculations gives you a much wider scope of options when it comes to resolving complex usage-based pricing use cases.

If you plan to use Custom Fields in calculations, there are some key points to note:

You can create Custom Fields you want to reference in your calculations at two levels - at the Organizational-level and at the level of individual entities - for the following:
- Product
- Plan Template
- Plan
- Meter
- Account
- Account Plan
For example, if you want reference a Custom Field for Account, say cfAccount1, in your calculations:
- You must first create an Account Custom Field called cfAccount1 at the Organizational-level to act as a default value for the field. This is designed to ensure that a default value is always available and, for cases where the individual entity - in this case an Account - does not have a Custom Field defined, the calculation will not fail. You cannot simply create a Custom Field at the entity-level.
- If you do not create a Custom Field called cfAccount1 for an individual Account (say for Account 1), then when you reference cfAccount1 in a calculation, the value of the Organization-level field will be used for the calculation.
- If you do create a Custom Field called cfAccount1 for an individual Account (say Account 1), then when you reference cfAccount1 in a calculation, the value of the entity-level field will be used in the calculation.
The general rule when referencing Custom Fields in calculations is: the entity-level field value is used if defined, otherwise the Organization-level value is used.

Important! Exceptions to Rule. There are exceptions to the general rule, so please review the following sections in this topic for Referencing Custom Fields in Derived Field Calculations and Referencing Custom Fields in Compound Aggregation Calculations before you attempt to use them.

Important! What about Custom Fields for Aggregations and Compound Aggregations? You can define Custom Fields for Aggregations and Compound Aggregations at both the Organizational level and the individual entity level. However, these Custom Fields are NOT supported for referencing in Derived Field or Compound Aggregation calculations.

Tip: What about Contracts and Plan Groups? Currently, you cannot create Custom Fields for Contracts or Plan Groups at the Organization-level, and therefore you cannot reference the Custom Fields values for those you create at the entity-level for these entities in your calculations.

Creating Custom Fields

At Organizational-Level

You can create Custom Fields at the Organization-level in the Console when setting up your Organization in m3ter: see Adding and Editing Custom Fields in the Managing your Organization section.

You can also use the Update CustomFields API call to do this.

Tip: Limit on Number of Custom Fields? Yes, a limit is imposed on the number of Custom Fields - you can create up to ten Custom Fields for each entity type at Organization-level.

At Individual Entity-Level

When you create or edit an individual entity that accepts Custom Fields in the Console, you'll be able to add them. For example, when Creating Products.

You can also use an API call to do this. For example, the Create Product API call.

Reviewing Custom Fields

On the Details pages for the main entities in your m3ter Organization, you can quickly review any Custom Fields created for the entity on the metadata panel. Here's an example for an Account:

Any Custom Fields created for the entity are listed, and you can Copy the String or Number value of a Custom Field to your clipboard.

Referencing Custom Fields in Derived Field Calculations

When referencing Custom Fields in your Derived Field calculations, you can use the following format:

organization.<fieldName>
meter.<fieldName>
product.<fieldName>
account.<fieldName>
accountPlan.<fieldName>
plan.<fieldName>
planTemplate.<fieldName>
aggregation.<fieldName>
compoundAggregation.<fieldName>

For example:

plan.cfPlan1
account.cfAccount1

In Derived Field calculations, you can reference all entity types and the general rule of precedence applies: the entity-level value is used if defined, otherwise the Organization-level is used.

Tip: More Details? For more details on referencing Custom Fields in your Derived Field calculations, see Calculation Syntax and Supported Functions/Operators.

Referencing Custom Fields in Compound Aggregation Calculations

When referencing Custom Fields in your Compound Aggregation calculations, you can use the following format:

organization.<fieldName>
meter.<fieldName>
product.<fieldName>
account.<fieldName>
accountPlan.<fieldName>
plan.<fieldName>
planTemplate.<fieldName>
aggregation.<fieldName>
compoundAggregation.<fieldName>

For example:

plan.cfPlan1
account.cfAccount1

In Compound Aggregation calculations, you can reference all entity types except Meter and the general rule or precedence applies: the entity-level value is used if defined, otherwise the Organization-level is used.

Important! Meter is an Exception. If you reference a Meter Custom Field in a Compound Aggregation calculation, the default value set at Organization-level is always used. This is because a Compound Aggregation might reference multiple individual Meters or no individual Meters, which means the specific Meter whose Custom Field value should be used cannot be identified, and therefore the default value is used.

Tip: More Details? For more details on referencing Custom Fields in your Compound Aggregation calculations, see Calculation Syntax and Supported Functions/Operators.

Next: Usage Data: Meters