Working with Custom Fields - m3ter Documentation

Custom Fields in m3ter

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. This capability can help you meet specific usage-based pricing and other operational business use cases. 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

Using Custom Fields

You can reference the values you store using Custom Fields in Derived Field and Compound Aggregation calculations. This will affect how the platform behaves and gives you a wider scope for resolving complex usage-based pricing use cases. Here are some key points to note:

• You can create Custom Fields at two levels
  • Organizational-level
  • Individual entities

For example, if you want to 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.
• If you do not create a Custom Field for an individual Account, the value of the Organization-level field will be used.
• If you do create a Custom Field for an individual Account, then that value will be referenced in the calculation.

Limits and Constraints

• Maximum number. The maximum number of Custom Fields at Organization-level is 25.
• Duplicate Naming. More than one Custom Field with the same name is not allowed.

Important Exceptions

• Custom Fields for Aggregations and Compound Aggregations at both Organizational and individual entity levels are NOT supported for referencing in Derived Field or Compound Aggregation calculations.
• You cannot create Custom Fields for Balances, Balance Transaction Schedules, Balance Charge Schedules, and Plan Groups at the Organization-level.

Creating Custom Fields

At Organizational-Level

You can create Custom Fields at the Organization-level in the Console. For more information, see the section on Adding and Editing Custom Fields.

At Individual Entity-Level

When creating or editing an individual entity that accepts Custom Fields in the Console, you’ll be able to add them. See the Create Product API call as an example.

Reviewing Custom Fields

You can review any Custom Fields created for the entity on the metadata panel in your m3ter Organization. The Custom Fields will be listed, and you can Copy the String or Number value of a Custom Field to your clipboard.

Custom Fields in Derived Field Calculations

In Derived Field calculations, the Custom Fields you can reference are:

• Organization
• Meter
• Account

If using Meters belonging to a specific Product, you can also reference Custom Fields added to a Product.

Format

When referencing Custom Fields in your Derived Field calculations, you can use formats like:

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

Precedence

In Derived Field calculations, 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

For Compound Aggregation calculations, use:

• organization.<fieldName>
• meter.<fieldName>
• product.<fieldName>
• account.<fieldName>
• accountPlan.<fieldName>
• plan.<fieldName>
• planTemplate.<fieldName>

Precedence

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

Important Exceptions

• If you reference a Meter Custom Field in a Compound Aggregation calculation, the default value at the Organization-level is always used.