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.

​

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:

​

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.

​

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.