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
• Balance
• Balance Transaction Schedules
• Balance Charge Schedules
• 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
  • Aggregation
  • Compound Aggregation
  • Contract
• 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.

Limits and Constraints:

• Maximum number. The maximum number of Custom Fields you can create for each entity type at Organization-level is 25.
• Duplicate Naming. More that one Custom Field with the same name is not allowed. If you try to add two or more Custom Fields with the same name for an entity type, when you save your changes only the last one you added is saved.

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.
• 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.
• What about the entities you cannot create Custom Fields for at the Organization-level? If you cannot create Custom Fields for an entity at Organization-level and only at individual entity-level, you cannot reference the field values for those you create at the entity-level in your calculations. Currently, these are:
  • Balances
  • Balance Transaction Schedules
  • Balance Charge Schedules
  • Plan Groups

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.

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. 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.

• If the fields have been created only at Organizational-level, then these values will be shown:

• If the fields have also been created for an individual entity, then the values configured for those created at Organizational-level are struck out indicating clearly that the Account level values will be used:

Referencing Custom Fields in Derived Field Calculations

Range of Entities

In Derived Field calculations, the Custom Fields you can reference is restricted to the following entities:

• Organization
• Meter
• Account

If you are using Meters belonging to a specific Product, that is, not Global Meters, you can also reference Custom Fields added to a:

• Product

The following table summarizes the Custom Fields on which entities you can reference in Derived Field calculations:

Entity	Using Global Meters	Using Product Meters
Organization	YES	YES
Meter	YES	YES
Product	NO	YES
Account	YES	YES
Account Plan	NO	NO
Plan	NO	NO
Plan Template	NO	NO

Format

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

• organization.<fieldName>
• meter.<fieldName>
• account.<fieldName>
• product.<fieldName>

For example:

• meter.cfMeter1
• account.cfAccount1

Precedence

In Derived Field calculations the general rule of precedence applies: the entity-level value is used if defined, otherwise the Organization-level value is used.

Important! Aggregation and Compound Aggregation Custom Fields. You can define Custom Fields for Aggregations and Compound Aggregations. However, these Custom Fields are NOT supported for referencing in Derived Field calculations.

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

Range of Entities

• Organization
• Meter
• Product
• Account
• Account Plan
• Plan
• Plan Template

Format

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>

For example:

• plan.cfPlan1
• account.cfAccount1

Precedence

In Compound Aggregation calculations the general rule or precedence applies: the entity-level value is used if defined, otherwise the Organization-level value is used.

Important! Exceptions:

• Meter Custom Fields. 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.
• Aggregation and Compound Aggregation Custom Fields. You can define Custom Fields for Aggregations and Compound Aggregations. However, these Custom Fields are NOT supported for referencing in Compound Aggregation calculations.

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